feat(adk): add adk.tasks.interrupt for agents to record INTERRUPTED (AGX1-391)

Agents call adk.tasks.interrupt(task_id=...) from their interrupt handler, after stopping the in-flight turn, to record the non-terminal INTERRUPTED status (the control plane forwards task/interrupt but no longer writes status). Mirrors adk.tasks.cancel across the facade / activity / service layers and registers the interrupt-task activity. The service uses a generic POST /tasks/{id}/interrupt for now; switches to client.tasks.interrupt once Stainless regenerates the typed method.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: declan-scale

src/agentex/lib/adk/_modules/tasks.py

@@ -174,6 +174,53 @@ async def cancel(
                 parent_span_id=parent_span_id,
             )
 
+    async def interrupt(
+        self,
+        *,
+        task_id: str,
+        reason: str | None = None,
+        trace_id: str | None = None,
+        parent_span_id: str | None = None,
+        start_to_close_timeout: timedelta = timedelta(seconds=5),
+        heartbeat_timeout: timedelta = timedelta(seconds=5),
+        retry_policy: RetryPolicy = DEFAULT_RETRY_POLICY,
+    ) -> Task:
+        """
+        Mark a running task as interrupted (non-terminal).
+
+        Interrupt is cooperative: an agent calls this from its interrupt handler,
+        after it has actually stopped its in-flight turn, to record INTERRUPTED.
+        The task stays continuable; the control plane resumes it to RUNNING on the
+        next turn.
+        Args:
+            task_id: The ID of the task to interrupt.
+            reason: Optional reason for the interrupt.
+        Returns:
+            The updated task entry.
+        """
+        params = TaskStatusTransitionParams(
+            task_id=task_id,
+            reason=reason,
+            trace_id=trace_id,
+            parent_span_id=parent_span_id,
+        )
+        if in_temporal_workflow():
+            return await ActivityHelpers.execute_activity(
+                activity_name=TasksActivityName.INTERRUPT_TASK,
+                request=params,
+                response_type=Task,
+                start_to_close_timeout=start_to_close_timeout,
+                retry_policy=retry_policy,
+                heartbeat_timeout=heartbeat_timeout,
+            )
+        else:
+            return await self._tasks_service.interrupt_task(
+                task_id=task_id,
+                reason=reason,
+                trace_id=trace_id,
+                parent_span_id=parent_span_id,
+            )
+
     async def complete(
         self,
         *,

src/agentex/lib/core/services/adk/tasks.py

@@ -98,6 +98,32 @@ async def cancel_task(
                 span.output = task_model.model_dump()
             return task_model
 
+    async def interrupt_task(
+        self,
+        task_id: str,
+        reason: str | None = None,
+        trace_id: str | None = None,
+        parent_span_id: str | None = None,
+    ) -> Task:
+        trace = self._tracer.trace(trace_id)
+        async with trace.span(
+            parent_id=parent_span_id,
+            name="interrupt_task",
+            input={"task_id": task_id, "reason": reason},
+        ) as span:
+            heartbeat_if_in_workflow("interrupt task")
+            # TODO(AGX1-391): switch to self._agentex_client.tasks.interrupt(...) once the
+            # POST /tasks/{id}/interrupt endpoint is added to the Stainless config and
+            # regenerated. Using the generic post keeps this working before regeneration.
+            task_model = await self._agentex_client.post(
+                f"/tasks/{task_id}/interrupt",
+                cast_to=Task,
+                body={"reason": reason},
+            )
+            if span:
+                span.output = task_model.model_dump()
+            return task_model
+
     async def complete_task(
         self,
         task_id: str,

src/agentex/lib/core/temporal/activities/__init__.py

@@ -181,6 +181,7 @@ def get_all_activities(sgp_client=None):
         tasks_activities.get_task,
         tasks_activities.delete_task,
         tasks_activities.cancel_task,
+        tasks_activities.interrupt_task,
         tasks_activities.complete_task,
         tasks_activities.fail_task,
         tasks_activities.terminate_task,

src/agentex/lib/core/temporal/activities/adk/tasks_activities.py

@@ -18,6 +18,7 @@ class TasksActivityName(str, Enum):
     GET_TASK = "get-task"
     DELETE_TASK = "delete-task"
     CANCEL_TASK = "cancel-task"
+    INTERRUPT_TASK = "interrupt-task"
     COMPLETE_TASK = "complete-task"
     FAIL_TASK = "fail-task"
     TERMINATE_TASK = "terminate-task"
@@ -83,6 +84,15 @@ async def cancel_task(self, params: TaskStatusTransitionParams) -> Task:
             parent_span_id=params.parent_span_id,
         )
 
+    @activity.defn(name=TasksActivityName.INTERRUPT_TASK)
+    async def interrupt_task(self, params: TaskStatusTransitionParams) -> Task:
+        return await self._tasks_service.interrupt_task(
+            task_id=params.task_id,
+            reason=params.reason,
+            trace_id=params.trace_id,
+            parent_span_id=params.parent_span_id,
+        )
+
     @activity.defn(name=TasksActivityName.COMPLETE_TASK)
     async def complete_task(self, params: TaskStatusTransitionParams) -> Task:
         return await self._tasks_service.complete_task(