qoder-agent-sdk 1.0.15__tar.gz → 1.0.16__tar.gz

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qoder-agent-sdk
-Version: 1.0.15
+Version: 1.0.16
 Summary: Python SDK for Qoder Agent
 Author: Qoder
 License: Copyright (c) 2026 Qoder
@@ -315,6 +315,34 @@ cancellation, and do not reuse UUIDs within a session.
 `await client.cancel_async_message(message_uuid)` returns `True` when the
 queued message is cancelled and `False` when it can no longer be cancelled.
 
+Manage background tasks from a connected `QoderSDKClient`:
+
+```python
+await client.background_tasks(tool_use_id)  # ToolUseBlock.id; omit for bulk conversion
+await client.stop_task(task_id)  # TaskStartedMessage.task_id
+```
+
+`background_tasks()` moves running foreground Bash / Agent executions into the
+background; it does not list tasks. A targeted call returns whether the execution
+moved; bulk `True` acknowledges the request without guaranteeing a transition.
+`stop_task()` returns `None` and leaves the main turn and other independent tasks
+running. Unknown IDs and repeated stops are safe no-ops. Both methods require the
+CLI capability `background_tasks_v1` (otherwise `UnsupportedCliCapabilityError`)
+and are unavailable in Cloud Agent sessions.
+
+`interrupt()` does not stop existing background tasks. To clean them up, continue
+consuming `receive_messages()` after the main `ResultMessage`, replace the roster
+on each `BackgroundTasksChangedMessage`, and stop each task separately. Bulk
+conversion can detach an Agent's Bash execution as an independent task.
+
+Use `AgentDefinition(background=True, ...)` to launch delegated agents in the
+background. Merge `TaskUpdatedMessage.patch` into stored task state. Task events
+retain raw `data`; optional metadata depends on the CLI. Missing progress `usage`
+is `None`, and `total_tokens` can be absent within usage.
+
+For event fields, launch result types, the Bash result guard, and examples, see
+[Python SDK Reference](https://docs.qoder.com/cli/sdk/references-python#clientstop-task).
+
 ## External Session Storage
 
 Use `session_store` when a host needs durable transcripts outside the local

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/README.md

@@ -273,6 +273,34 @@ cancellation, and do not reuse UUIDs within a session.
 `await client.cancel_async_message(message_uuid)` returns `True` when the
 queued message is cancelled and `False` when it can no longer be cancelled.
 
+Manage background tasks from a connected `QoderSDKClient`:
+
+```python
+await client.background_tasks(tool_use_id)  # ToolUseBlock.id; omit for bulk conversion
+await client.stop_task(task_id)  # TaskStartedMessage.task_id
+```
+
+`background_tasks()` moves running foreground Bash / Agent executions into the
+background; it does not list tasks. A targeted call returns whether the execution
+moved; bulk `True` acknowledges the request without guaranteeing a transition.
+`stop_task()` returns `None` and leaves the main turn and other independent tasks
+running. Unknown IDs and repeated stops are safe no-ops. Both methods require the
+CLI capability `background_tasks_v1` (otherwise `UnsupportedCliCapabilityError`)
+and are unavailable in Cloud Agent sessions.
+
+`interrupt()` does not stop existing background tasks. To clean them up, continue
+consuming `receive_messages()` after the main `ResultMessage`, replace the roster
+on each `BackgroundTasksChangedMessage`, and stop each task separately. Bulk
+conversion can detach an Agent's Bash execution as an independent task.
+
+Use `AgentDefinition(background=True, ...)` to launch delegated agents in the
+background. Merge `TaskUpdatedMessage.patch` into stored task state. Task events
+retain raw `data`; optional metadata depends on the CLI. Missing progress `usage`
+is `None`, and `total_tokens` can be absent within usage.
+
+For event fields, launch result types, the Bash result guard, and examples, see
+[Python SDK Reference](https://docs.qoder.com/cli/sdk/references-python#clientstop-task).
+
 ## External Session Storage
 
 Use `session_store` when a host needs durable transcripts outside the local

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qoder-agent-sdk"
-version = "1.0.15"
+version = "1.0.16"
 description = "Python SDK for Qoder Agent"
 readme = "README.md"
 requires-python = ">=3.10"

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/__init__.py

@@ -50,6 +50,7 @@ from ._internal.sessions import (
     project_key_for_directory,
 )
 from ._internal.transport import Transport
+from ._tool_results import is_bash_tool_background_launch_result
 from ._version import __version__
 from .auth import (
     DEFAULT_ACCESS_TOKEN_ENV_VAR,
@@ -129,10 +130,14 @@ from .types import (
     MAX_SKILL_EVOLUTION_REVIEW_THRESHOLD,
     AgentCreateParams,
     AgentDefinition,
+    AgentToolBackgroundLaunchResult,
     AssistantMessage,
     AssistantMessageWithRequestId,
     AsyncHookJSONOutput,
+    BackgroundTask,
+    BackgroundTasksChangedMessage,
     BaseHookInput,
+    BashToolBackgroundLaunchResult,
     BetaManagedAgentsAgentToolName,
     BetaManagedAgentsAgentToolset20260401Params,
     BetaManagedAgentsCustomSkillParams,
@@ -331,6 +336,9 @@ from .types import (
     TaskNotificationStatus,
     TaskProgressMessage,
     TaskStartedMessage,
+    TaskStatus,
+    TaskUpdatedMessage,
+    TaskUpdatePatch,
     TaskUsage,
     TextBlock,
     ThinkingBlock,
@@ -983,6 +991,14 @@ __all__ = [
     "TaskNotificationMessage",
     "TaskNotificationStatus",
     "TaskUsage",
+    "TaskStatus",
+    "TaskUpdatePatch",
+    "TaskUpdatedMessage",
+    "BackgroundTask",
+    "BackgroundTasksChangedMessage",
+    "BashToolBackgroundLaunchResult",
+    "AgentToolBackgroundLaunchResult",
+    "is_bash_tool_background_launch_result",
     "ResultMessage",
     "StreamEvent",
     "CloudAgentEventMessage",

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/_cli_version.py

@@ -1,3 +1,3 @@
 """Bundled runtime CLI version."""
 
-__cli_version__ = "1.1.61"
+__cli_version__ = "1.1.76"

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/_internal/message_parser.py

@@ -7,6 +7,7 @@ from .._errors import MessageParseError
 from ..types import (
     AssistantMessage,
     AssistantMessageWithRequestId,
+    BackgroundTasksChangedMessage,
     CloudAgentEventMessage,
     ContentBlock,
     GoalClearedMessage,
@@ -24,6 +25,7 @@ from ..types import (
     TaskNotificationMessage,
     TaskProgressMessage,
     TaskStartedMessage,
+    TaskUpdatedMessage,
     TextBlock,
     ThinkingBlock,
     ToolResultBlock,
@@ -199,6 +201,10 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                             session_id=data["session_id"],
                             tool_use_id=data.get("tool_use_id"),
                             task_type=data.get("task_type"),
+                            subagent_type=data.get("subagent_type"),
+                            workflow_name=data.get("workflow_name"),
+                            prompt=data.get("prompt"),
+                            tools=data.get("tools"),
                         )
                     case "task_progress":
                         return TaskProgressMessage(
@@ -206,18 +212,13 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                             data=data,
                             task_id=data["task_id"],
                             description=data["description"],
-                            usage=data.get(
-                                "usage",
-                                {
-                                    "total_tokens": 0,
-                                    "tool_uses": 0,
-                                    "duration_ms": 0,
-                                },
-                            ),
+                            usage=data.get("usage"),
                             uuid=data["uuid"],
                             session_id=data["session_id"],
                             tool_use_id=data.get("tool_use_id"),
                             last_tool_name=data.get("last_tool_name"),
+                            subagent_type=data.get("subagent_type"),
+                            summary=data.get("summary"),
                         )
                     case "task_notification":
                         return TaskNotificationMessage(
@@ -232,6 +233,23 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                             tool_use_id=data.get("tool_use_id"),
                             usage=data.get("usage"),
                         )
+                    case "task_updated":
+                        return TaskUpdatedMessage(
+                            subtype=subtype,
+                            data=data,
+                            task_id=data["task_id"],
+                            patch=data["patch"],
+                            uuid=data["uuid"],
+                            session_id=data["session_id"],
+                        )
+                    case "background_tasks_changed":
+                        return BackgroundTasksChangedMessage(
+                            subtype=subtype,
+                            data=data,
+                            tasks=data["tasks"],
+                            uuid=data["uuid"],
+                            session_id=data["session_id"],
+                        )
                     case "goal_updated":
                         return GoalUpdatedMessage(
                             subtype=subtype,

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/_internal/query.py

@@ -585,6 +585,7 @@ class Query:
     SIDE_QUESTION_CAPABILITY = "side_question_v1"
     SKILL_EVOLUTION_CAPABILITY = "skill_evolution_v1"
     PLAN_MODE_CAPABILITY = "plan_mode_v1"
+    BACKGROUND_TASKS_CAPABILITY = "background_tasks_v1"
 
     def __init__(
         self,
@@ -1966,6 +1967,21 @@ class Query:
         """Interrupt the active turn."""
         await self._send_control_request({"subtype": "interrupt"})
 
+    async def stop_task(self, task_id: str) -> None:
+        """Stop exactly one task without aborting the active main-session turn."""
+        await self._require_cli_capability(self.BACKGROUND_TASKS_CAPABILITY)
+        await self._send_control_request({"subtype": "stop_task", "task_id": task_id})
+
+    async def background_tasks(self, tool_use_id: str | None = None) -> bool:
+        """Background one or all eligible foreground executions in this session."""
+        await self._require_cli_capability(self.BACKGROUND_TASKS_CAPABILITY)
+        request: dict[str, Any] = {"subtype": "background_tasks"}
+        if tool_use_id is not None:
+            request["tool_use_id"] = tool_use_id
+        response = await self._send_control_request(request)
+        backgrounded = response.get("backgrounded")
+        return backgrounded if isinstance(backgrounded, bool) else True
+
     async def cancel_async_message(self, message_uuid: str) -> bool:
         """Request cancellation and return whether the queue entry was removed."""
         response = cast(

qoder_agent_sdk-1.0.16/src/qoder_agent_sdk/_tool_results.py

@@ -0,0 +1,38 @@
+"""Runtime guards for typed tool results without changing their wire shape."""
+
+from typing import TypeGuard
+
+from .types import BashToolBackgroundLaunchResult
+
+
+def is_bash_tool_background_launch_result(
+    value: object,
+) -> TypeGuard[BashToolBackgroundLaunchResult]:
+    """Recognize a background Bash launch result using the TypeScript contract."""
+    if not isinstance(value, dict):
+        return False
+
+    def is_integer(number: object) -> bool:
+        # JSON numbers can decode as floats; booleans are not wire numbers.
+        return type(number) is int or (type(number) is float and number.is_integer())
+
+    return (
+        value.get("kind") == "backgrounded"
+        and is_integer(value.get("pid"))
+        and value["pid"] > 0
+        and isinstance(value.get("taskId"), str)
+        and isinstance(value.get("command"), str)
+        and isinstance(value.get("initialOutput"), str)
+        and all(
+            key not in value or isinstance(value[key], str)
+            for key in ("outputFile", "stdout", "telemetryExecutionId")
+        )
+        and all(
+            key not in value or (is_integer(value[key]) and value[key] >= 0)
+            for key in ("totalLines", "totalBytes")
+        )
+        and (
+            "backgroundReason" not in value
+            or value["backgroundReason"] in ("user", "model", "timeout", "auto")
+        )
+    )

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/_version.py

@@ -1,3 +1,3 @@
 """Version information for qoder-agent-sdk."""
 
-__version__ = "1.0.15"
+__version__ = "1.0.16"

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/client.py

@@ -445,6 +445,46 @@ class QoderSDKClient:
             raise CLIConnectionError("Not connected. Call connect() first.")
         await self._query.interrupt()
 
+    async def stop_task(self, task_id: str) -> None:
+        """Stop one running task without interrupting the main session turn.
+
+        Use the task ID from ``TaskStartedMessage.task_id``. The connected
+        CLI must advertise ``background_tasks_v1``; older CLIs raise
+        ``UnsupportedCliCapabilityError``. Stopping an unknown or already
+        finished task succeeds without affecting other tasks.
+
+        This operation is not supported by the experimental Cloud Agent runtime.
+        """
+        if not self._query:
+            raise CLIConnectionError("Not connected. Call connect() first.")
+        if self.options.experimental_cloud_agent is not None:
+            raise NotImplementedError(
+                "stop_task is not supported by the experimental Cloud Agent runtime"
+            )
+        await self._query.stop_task(task_id)
+
+    async def background_tasks(self, tool_use_id: str | None = None) -> bool:
+        """Move running foreground Bash/Agent executions into the background.
+
+        Pass a tool use ID to target one execution, or omit it to target all
+        eligible foreground executions in this session. This does not list
+        tasks; consume ``BackgroundTasksChangedMessage`` for the current roster.
+
+        Requires the CLI's ``background_tasks_v1`` capability. A targeted
+        request returns whether the execution moved into the background.
+        A successful bulk request may have no response body and returns True,
+        which acknowledges the request rather than guaranteeing a transition.
+        Cloud Agent sessions do not support this operation.
+        """
+        if not self._query:
+            raise CLIConnectionError("Not connected. Call connect() first.")
+        if self.options.experimental_cloud_agent is not None:
+            raise NotImplementedError(
+                "background_tasks is not supported by the experimental Cloud Agent runtime"
+            )
+        result: bool = await self._query.background_tasks(tool_use_id)
+        return result
+
     async def ask_side_question(
         self,
         question: str,

{qoder_agent_sdk-1.0.15 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/types.py

@@ -317,6 +317,8 @@ class AgentDefinition:
     maxTurns: int | None = None  # noqa: N815
     effort: Literal["low", "medium", "high", "max"] | None = None
     permissionMode: PermissionMode | None = None  # noqa: N815
+    # Run this agent asynchronously whenever it is invoked.
+    background: bool | None = None
 
 
 # Cloud Agent experimental runtime types.
@@ -2000,6 +2002,36 @@ class ToolResultBlock:
 ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
 
 
+class BashToolBackgroundLaunchResult(TypedDict):
+    """Background Bash launch result; keys preserve the CLI wire spelling."""
+
+    kind: Literal["backgrounded"]
+    # The wire guard accepts integral JSON numbers, including 123.0.
+    pid: int | float
+    taskId: str
+    command: str
+    initialOutput: str
+    outputFile: NotRequired[str]
+    stdout: NotRequired[str]
+    backgroundReason: NotRequired[Literal["user", "model", "timeout", "auto"]]
+    telemetryExecutionId: NotRequired[str]
+    totalLines: NotRequired[int | float]
+    totalBytes: NotRequired[int | float]
+
+
+class AgentToolBackgroundLaunchResult(TypedDict):
+    """Background Agent launch result, available in ``tool_use_result``."""
+
+    isAsync: Literal[True]
+    status: Literal["async_launched"]
+    agentId: str
+    description: str
+    prompt: str
+    outputFile: str
+    resolvedModel: NotRequired[str]
+    canReadOutputFile: NotRequired[bool]
+
+
 # Message types
 AssistantMessageError = Literal[
     "authentication_failed",
@@ -2144,7 +2176,7 @@ class SDKPermissionDenial(TypedDict):
 class TaskUsage(TypedDict):
     """Usage statistics reported in task_progress and task_notification messages."""
 
-    total_tokens: int
+    total_tokens: NotRequired[int]
     tool_uses: int
     duration_ms: int
 
@@ -2168,6 +2200,10 @@ class TaskStartedMessage(SystemMessage):
     session_id: str
     tool_use_id: str | None = None
     task_type: str | None = None
+    subagent_type: str | None = None
+    workflow_name: str | None = None
+    prompt: str | None = None
+    tools: list[str] | None = None
 
 
 @dataclass
@@ -2181,11 +2217,13 @@ class TaskProgressMessage(SystemMessage):
 
     task_id: str
     description: str
-    usage: TaskUsage
+    usage: TaskUsage | None
     uuid: str
     session_id: str
     tool_use_id: str | None = None
     last_tool_name: str | None = None
+    subagent_type: str | None = None
+    summary: str | None = None
 
 
 @dataclass
@@ -2207,6 +2245,47 @@ class TaskNotificationMessage(SystemMessage):
     usage: TaskUsage | None = None
 
 
+TaskStatus = Literal["pending", "running", "completed", "failed", "killed", "paused"]
+
+
+class TaskUpdatePatch(TypedDict, total=False):
+    """Partial task update. Merge these fields into the stored task state."""
+
+    status: TaskStatus
+    description: str
+    end_time: int
+    total_paused_ms: int
+    error: str
+    is_backgrounded: bool
+
+
+@dataclass
+class TaskUpdatedMessage(SystemMessage):
+    """A task state patch, with the original wire message preserved in data."""
+
+    task_id: str
+    patch: TaskUpdatePatch
+    uuid: str
+    session_id: str
+
+
+class BackgroundTask(TypedDict):
+    """One live entry in a background task roster."""
+
+    task_id: str
+    task_type: str
+    description: str
+
+
+@dataclass
+class BackgroundTasksChangedMessage(SystemMessage):
+    """Full live background task roster. Replace the previous roster with tasks."""
+
+    tasks: list[BackgroundTask]
+    uuid: str
+    session_id: str
+
+
 @dataclass
 class ResultMessage:
     """Result message with cost and usage information."""
@@ -2908,6 +2987,16 @@ class SDKControlInterruptRequest(TypedDict):
     subtype: Literal["interrupt"]
 
 
+class SDKControlStopTaskRequest(TypedDict):
+    subtype: Literal["stop_task"]
+    task_id: str
+
+
+class SDKControlBackgroundTasksRequest(TypedDict):
+    subtype: Literal["background_tasks"]
+    tool_use_id: NotRequired[str]
+
+
 class SDKControlPermissionRequest(TypedDict):
     subtype: Literal["can_use_tool"]
     tool_name: str
@@ -3119,6 +3208,8 @@ class SDKControlRequest(TypedDict):
     request_id: str
     request: (
         SDKControlInterruptRequest
+        | SDKControlStopTaskRequest
+        | SDKControlBackgroundTasksRequest
         | SDKControlPermissionRequest
         | SDKControlInitializeRequest
         | SDKControlSetPermissionModeRequest