autourgos-hcix

Human Cognitive Interrupt (HCIx) middleware for Autourgos agents. Press a global shortcut during a long-running agent task, type a high-priority instruction, and the middleware injects it so the next reasoning step is steered by the human operator.

from autourgos_hcix import HcixInterruptMiddleware
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

middleware = HcixInterruptMiddleware(shortcut="ctrl+shift+h")
agent = Agent(llm=OpenAIChatModel(model="gpt-4o-mini"), middleware=[middleware], verbose=True)
result = agent.invoke("Research this task and keep working until you have a final answer.")

Features

• Global-hotkey live steering — interrupt a running agent, type a correction, and the next reasoning step picks it up
• Programmatic interrupts — submit an instruction without a keyboard, for tests, APIs, dashboards, notebooks
• Human approval primitives — HumanInterrupt, HumanInterruptHandler, HumanStateEditor for worker-thread-blocks-until-a-human-decides workflows
• Native on Windows (RegisterHotKey), pynput optional extra for Linux/macOS
• Cleanup guaranteed — hotkey listeners unregister on run end or error
• Safe to share across agents — one HcixInterruptMiddleware instance can serve multiple concurrent Agents; per-agent injected-override state is isolated (autourgos-core's PerAgentRegistry)

Table of Contents

• Why Use This?
• Install
• Quick Start
• Async Usage
• Programmatic Interrupts
• Human Approval Primitives
• Agent Hooks
• Constructor Parameters
• License

Why Use This?

Long-running agents sometimes need live human steering:

• Stop drift — redirect an agent when its current plan is no longer useful
• Inject new context — add fresh information without restarting the run
• Pause for operator input — wait while a person writes a corrective instruction
• Keep cleanup reliable — unregister hotkey listeners when the run ends or errors

HcixInterruptMiddleware depends on autourgos-agent (for the shared CallbackHandler interface).

Install

pip install autourgos-hcix

For global hotkey support on Linux/macOS, install the optional pynput extra:

pip install 'autourgos-hcix[hcix]'

Windows uses the native RegisterHotKey API. Tkinter is used for the desktop prompt when available; otherwise HCIx falls back to a console prompt.

Quick Start

my_llm is any chat-model instance, e.g. OpenAIChatModel from autourgos-openaichat (needs OPENAI_API_KEY set). my_tool is any plain callable used as an agent tool.

from autourgos_hcix import HcixInterruptMiddleware
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")

def my_tool(query: str) -> str:
    return f"Result for: {query}"

middleware = HcixInterruptMiddleware(shortcut="ctrl+shift+h")

agent = Agent(
    llm=my_llm,
    tools=[my_tool],
    middleware=[middleware],
    verbose=True,
)

result = agent.invoke("Research this task and keep working until you have a final answer.")
print(result)

During the run, press ctrl+shift+h, type the new instruction, then send it. HCIx injects an authoritative override block into the agent context. With verbose=True, HCIx also narrates the injection into the agent's verbose trace:

[HCIx] Human override injected: 'Stop researching and summarize what you have so far.'

Async Usage

import asyncio

from autourgos_hcix import HcixInterruptMiddleware
from autourgos_agent import Agent

agent = Agent(
    llm=my_llm,
    tools=[my_tool],
    middleware=[HcixInterruptMiddleware(shortcut="ctrl+alt+k")],
)

async def main() -> None:
    result = await agent.ainvoke("Prepare a detailed cloud service comparison.")
    print(result)

asyncio.run(main())

HCIx uses the same lifecycle hooks in sync and async agent runs. When the user is actively writing an interrupt, the hook waits until the instruction is submitted or cancelled.

Programmatic Interrupts

Submit an interrupt without using a keyboard shortcut — useful for tests, APIs, dashboards, and notebooks.

from autourgos_hcix import CognitiveInterruptManager, HcixInterruptMiddleware

manager = CognitiveInterruptManager(enable_hotkey=False)
middleware = HcixInterruptMiddleware(manager=manager)

manager.submit_instruction("Stop searching. Summarize only the sources already collected.")

At the next supported middleware hook, the instruction is consumed and injected once.

Autonomous / Headless Agents

Global hotkeys and desktop prompts assume a human is sitting at a keyboard. An autonomous agent running on a server, in a container, or in the cloud has neither — there's no DISPLAY for pynput to bind to, and no one to press ctrl+shift+h.

For these deployments, skip the hotkey listener entirely and drive HCIx from your own control plane (an API endpoint, a queue consumer, a supervisor process) instead:

from autourgos_hcix import CognitiveInterruptManager, HcixInterruptMiddleware

manager = CognitiveInterruptManager.headless()
middleware = HcixInterruptMiddleware(manager=manager)

# elsewhere -- an API handler, a queue consumer, an operator dashboard:
manager.submit_instruction("Stop researching. Summarize what you have.")

CognitiveInterruptManager.headless() is shorthand for enable_hotkey=False. On a headless box, enable_hotkey=True (the default) also degrades safely on its own -- no DISPLAY/ WAYLAND_DISPLAY means HCIx skips the hotkey listener without attempting to import pynput -- but for an autonomous deployment, being explicit is clearer than relying on that fallback.

Human Approval Primitives

from autourgos_hcix import HumanInterrupt, HumanInterruptHandler, HumanStateEditor

state = {"step": "delete_files", "count": 3}
edited = HumanStateEditor.edit(state, {"count": 2})

handler = HumanInterruptHandler()

# Worker thread:
# action, edits = handler.wait_for_human(timeout=60.0)

# UI/API thread later:
# handler.submit("approve", edited)

Agent Hooks

HCIx uses standard Autourgos middleware hooks:

agent.scratchpad is a real, live instance attribute on autourgos-agent, so HCIx injects the override directly into it (in addition to agent.system_prompt) and the running agent picks it up on its very next LLM call.

Constructor Parameters

Requirements

• Python 3.9+
• Optional: pynput for non-Windows global hotkeys
• Optional: Tkinter for the desktop prompt UI

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar