feat(tasks): non-terminal task/interrupt + INTERRUPTED status (AGX1-391)

[declan-scale]

Summary

Platform half of AGX1-391 (stop an agent run mid-stream). Adds a non-terminal INTERRUPTED task status and a task/interrupt operation so a running turn can be stopped without terminating the task or locking the chat.

Ownership model (important)

Interrupt is cooperative, not control-plane-authoritative like cancel:

• task/interrupt RPC = courier only. It is forwarded to the agent (exactly like event/send) and writes no status. Only the agent can actually stop an in-flight turn.
• The agent records INTERRUPTED. After stopping its turn, the agent calls the REST POST /tasks/{task_id}/interrupt route (like the other task-state routes: complete/fail/cancel/timeout) to set its status. An agent that does not implement interrupt simply stays RUNNING, so status stays honest.
• The control plane owns RUNNING. It sets RUNNING on task creation and auto-resumes INTERRUPTED -> RUNNING on the next turn (_get_or_create_task).

Contrast with cancel, which is authoritative: the control plane sets CANCELED itself (and the RPC cancel_task also CAS-writes CANCELED), because cancel does not depend on the agent cooperating.

What's included

• task/interrupt RPC method (forward-only) + REST POST /tasks/{task_id}/interrupt (authorized update, the agent's write path). Allowed for SYNC / ASYNC / AGENTIC.
• New non-terminal INTERRUPTED status + alembic migration; terminal transitions accept INTERRUPTED as a valid source (so an interrupted task can still be canceled/completed).
• Auto-resume INTERRUPTED -> RUNNING on the next turn; if that CAS loses to a concurrent terminal transition, the turn is rejected instead of running against a terminal task.
• Regenerated openapi.yaml (drives SDK regeneration).
• Unit + integration tests mirroring the task/cancel suite.

Review follow-ups (in this PR)

• task/interrupt RPC reworked to forward-only per design discussion (agent owns INTERRUPTED); control plane keeps ownership of RUNNING/auto-resume.
• Auto-resume rejects with ClientError if the resume CAS lost to a concurrent cancel/complete (@smoreinis).
• cancel_task (RPC path) hardened with a compare-and-swap so it cannot clobber a task the agent terminated during the ACP call (independent correctness fix; @greptile).
• Restored x-acting-user-authorization to BLOCKED_HEADERS (had been dropped inadvertently).
• Corrected the _transition_to_terminal error text now that INTERRUPTED is a valid source.

Not in this PR (tracked separately)

• Agent-side behavior: golden agent on_interrupt (stops the turn and calls the REST interrupt route to record INTERRUPTED) and the agentex SDK interrupt hook (interrupt_turn signal / on_interrupt base workflow method).
• SDK regeneration (scale-agentex-python / agentex-typescript) once this openapi.yaml lands in Stainless — this includes adding the task/interrupt path to the Stainless config so tasks.interrupt is generated (per @smoreinis).
• Golden-agent Stop + queue-at-boundary UI (scaleapi egp-annotation). The generic agentex-ui Stop button was intentionally dropped: a generic Stop is misleading for agents that do not implement self-interruption.

Testing

Unit + integration tests pass (authz mapping, non-terminal interrupt via REST, INTERRUPTED -> RUNNING resume, terminal-from-INTERRUPTED, SYNC now permits the method, fail-closed unchanged).

🤖 Generated with Claude Code

Greptile Summary

This PR introduces a non-terminal task/interrupt operation and an INTERRUPTED task status as a structural sibling of task/cancel. It allows a running turn to be stopped without terminating the task, enabling the user to resume via the next message or event.

• Adds INTERRUPTED enum value with a guarded Alembic migration, state machine transitions (RUNNING → INTERRUPTED, INTERRUPTED → RUNNING, and terminal transitions from INTERRUPTED), and compare-and-swap logic throughout to prevent concurrent-status clobbering.
• Exposes a REST POST /tasks/{task_id}/interrupt endpoint (authorized as update) and a task/interrupt RPC method (allowed for SYNC, ASYNC, and AGENTIC agents), with matching unit and integration tests.
• Aligns cancel_task in AgentTaskService to the same CAS pattern for consistency, and restores x-acting-user-authorization to BLOCKED_HEADERS.

Confidence Score: 5/5

Safe to merge; the CAS-based state transitions are correct, the authorization mapping is consistent, and the migration is guarded with IF NOT EXISTS.

The INTERRUPTED state machine is cleanly implemented with compare-and-swap throughout — no path can overwrite a terminal status. Authorization for interrupt correctly maps to the less-privileged update operation. The one notable issue is a docstring on _handle_task_interrupt that claims the returned task carries INTERRUPTED status when the cooperative design intentionally leaves the task RUNNING until the agent acknowledges; this does not affect runtime correctness.

agentex/src/domain/use_cases/agents_acp_use_case.py — the _handle_task_interrupt return-value docstring should be corrected to reflect that the returned task retains RUNNING status until the agent-side callback writes INTERRUPTED.

Important Files Changed

Filename	Overview
agentex/database/migrations/alembic/versions/2026_07_16_1200_add_interrupted_task_status_a1b2c3d4e5f6.py	Adds INTERRUPTED enum value with IF NOT EXISTS guard; downgrade is a documented no-op consistent with prior enum migrations.
agentex/src/domain/services/task_service.py	Adds cooperative interrupt_task (courier-only, no DB write) and resume_interrupted_task (CAS INTERRUPTED→RUNNING); cancel_task aligned to same CAS guard pattern.
agentex/src/domain/use_cases/tasks_use_case.py	New interrupt_task method with CAS RUNNING→INTERRUPTED; _transition_to_terminal expanded to accept INTERRUPTED as a valid source status.
agentex/src/domain/use_cases/agents_acp_use_case.py	_handle_task_interrupt wired correctly; INTERRUPTED→RUNNING resume in _get_or_create_task is sound; docstring on return type of _handle_task_interrupt is inaccurate (returns RUNNING, not INTERRUPTED).
agentex/src/api/routes/tasks.py	New interrupt_task REST endpoint authorized as update (not cancel); delegates to use-case CAS correctly.
agentex/src/domain/entities/agents_rpc.py	InterruptTaskParams, InterruptTaskRequestEntity, and ACP_TYPE_TO_ALLOWED_RPC_METHODS all updated consistently; SYNC now permits task/interrupt.
agentex/tests/unit/use_cases/test_tasks_use_case.py	Comprehensive tests for interrupt/resume/terminal-from-INTERRUPTED paths; error message match strings updated to reflect new wording.
agentex/tests/integration/api/tasks/test_tasks_api.py	Integration tests cover interrupt, default reason, terminal-from-INTERRUPTED, and rejection of interrupt on completed task.
agentex/tests/unit/api/test_tasks_authz.py	Authorization tests confirm interrupt maps to update (not cancel) for both task_id and task_name resolution paths, and SYNC/ASYNC/AGENTIC allowlists.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant UI as Client / UI
    participant TasksRoute as REST /tasks/{id}/interrupt
    participant AgentsRoute as RPC task/interrupt
    participant UseCase as TasksUseCase
    participant ACPUseCase as AgentsACPUseCase
    participant TaskSvc as AgentTaskService
    participant DB as Task Repository
    participant Agent as Agent Pod

    note over UI,Agent: Path A — REST endpoint (direct status write)
    UI->>TasksRoute: "POST /tasks/{id}/interrupt"
    TasksRoute->>UseCase: interrupt_task(id, reason)
    UseCase->>DB: CAS RUNNING → INTERRUPTED
    DB-->>UseCase: TaskEntity (INTERRUPTED)
    TasksRoute-->>UI: "200 OK — Task{status: INTERRUPTED}"

    note over UI,Agent: Path B — RPC endpoint (agent signal, no status write)
    UI->>AgentsRoute: "POST /agents/{id}/rpc method=task/interrupt"
    AgentsRoute->>ACPUseCase: _handle_task_interrupt
    ACPUseCase->>TaskSvc: interrupt_task(agent, task, url)
    TaskSvc->>Agent: JSON-RPC task/interrupt (best-effort)
    TaskSvc->>DB: get task (no write)
    ACPUseCase-->>UI: "200 OK — Task{status: RUNNING}"

    note over UI,DB: Resume on next turn
    UI->>AgentsRoute: message/send or task/create
    AgentsRoute->>ACPUseCase: _get_or_create_task
    ACPUseCase->>TaskSvc: resume_interrupted_task (CAS INTERRUPTED→RUNNING)
    TaskSvc-->>ACPUseCase: TaskEntity (RUNNING)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant UI as Client / UI
    participant TasksRoute as REST /tasks/{id}/interrupt
    participant AgentsRoute as RPC task/interrupt
    participant UseCase as TasksUseCase
    participant ACPUseCase as AgentsACPUseCase
    participant TaskSvc as AgentTaskService
    participant DB as Task Repository
    participant Agent as Agent Pod

    note over UI,Agent: Path A — REST endpoint (direct status write)
    UI->>TasksRoute: "POST /tasks/{id}/interrupt"
    TasksRoute->>UseCase: interrupt_task(id, reason)
    UseCase->>DB: CAS RUNNING → INTERRUPTED
    DB-->>UseCase: TaskEntity (INTERRUPTED)
    TasksRoute-->>UI: "200 OK — Task{status: INTERRUPTED}"

    note over UI,Agent: Path B — RPC endpoint (agent signal, no status write)
    UI->>AgentsRoute: "POST /agents/{id}/rpc method=task/interrupt"
    AgentsRoute->>ACPUseCase: _handle_task_interrupt
    ACPUseCase->>TaskSvc: interrupt_task(agent, task, url)
    TaskSvc->>Agent: JSON-RPC task/interrupt (best-effort)
    TaskSvc->>DB: get task (no write)
    ACPUseCase-->>UI: "200 OK — Task{status: RUNNING}"

    note over UI,DB: Resume on next turn
    UI->>AgentsRoute: message/send or task/create
    AgentsRoute->>ACPUseCase: _get_or_create_task
    ACPUseCase->>TaskSvc: resume_interrupted_task (CAS INTERRUPTED→RUNNING)
    TaskSvc-->>ACPUseCase: TaskEntity (RUNNING)

Loading

_{Reviews (5): Last reviewed commit: "refactor(tasks): make task/interrupt RPC..." | Re-trigger Greptile}

[github-actions]

✱ Stainless preview builds

This PR will update the agentex-sdk SDKs with the following commit messages.

openapi

feat(api): add interrupt endpoint, InterruptTaskRequest model, INTERRUPTED status to tasks

python

feat(api): add task/interrupt method and INTERRUPTED status to agents/tasks

typescript

feat(api): add task/interrupt method and INTERRUPTED status to agents/tasks

✅ agentex-sdk-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ agentex-sdk-typescript studio · code

Your SDK build had a failure in the build CI job, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ✅

⚠️ agentex-sdk-python studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️ → build ✅ → lint ✅ → test ✅

pip install https://pkg.stainless.com/s/agentex-sdk-python/4f1c09348c2ddffeb8c78738fb9b7aa14ed4b752/agentex_client-0.19.0-py3-none-any.whl

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-16 19:19:02 UTC

[smoreinis]

is it worth have the acp_client.interrupt_task happen after this CAS since right now a second RPC interrupt sees INTERRUPTED, but still forwards another interrupt before its CAS misses?

[smoreinis]

it also looks like the stainless diagnostic reports the new interrupt endpoint is not configured so just leaving this as a reminder to make sure the code for it gets generated

[smoreinis]

small race, but if resumed is None here it might be because the CAS lost to an e.g. concurrent cancel or complete so I think it would make sense to refetch the task and reject if the latest status is terminal

[smoreinis]

just a couple comments on the code here plus a reminder to add the new path to the stainless config, everything else LGTM! i think this will be a great help for folks working on voice too since they (will) want to interrupt a turn when a user barges in