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

{qoder_agent_sdk-1.0.14 → qoder_agent_sdk-1.0.16}/.gitignore

@@ -27,6 +27,7 @@ ENV/
 env/
 .venv
 .venv-release/
+.venv-e2e-build/
 .tmp-brand-packages/
 .tmp-qoder-python-release-plan.json
 uv.lock

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qoder-agent-sdk
-Version: 1.0.14
+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
@@ -405,6 +433,10 @@ against shared storage operated by your application, then validate its
 append/load ordering, project isolation, subkey handling, and deletion behavior
 with `run_session_store_conformance`.
 
+## Memory
+
+Configure native or custom memory with `QoderAgentOptions(memory=...)`. Interactive clients expose `flush_memory()` and `refresh_memory()`. See [Memory](doc/memory.md) for configuration, generation callbacks, and lifecycle behavior.
+
 ## Custom Tools
 
 You can expose Python functions to Qoder Agent as in-process SDK MCP servers.

{qoder_agent_sdk-1.0.14 → 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
@@ -363,6 +391,10 @@ against shared storage operated by your application, then validate its
 append/load ordering, project isolation, subkey handling, and deletion behavior
 with `run_session_store_conformance`.
 
+## Memory
+
+Configure native or custom memory with `QoderAgentOptions(memory=...)`. Interactive clients expose `flush_memory()` and `refresh_memory()`. See [Memory](doc/memory.md) for configuration, generation callbacks, and lifecycle behavior.
+
 ## Custom Tools
 
 You can expose Python functions to Qoder Agent as in-process SDK MCP servers.

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

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

{qoder_agent_sdk-1.0.14 → 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,
@@ -78,6 +79,29 @@ from .auth import (
     service_account_from_env,
 )
 from .client import QoderSDKClient
+from .memory import (
+    EffectiveMemoryConfig,
+    EffectiveMemoryRoot,
+    MemoryConsumptionCallback,
+    MemoryConsumptionFile,
+    MemoryConsumptionFileResult,
+    MemoryConsumptionOptions,
+    MemoryConsumptionResult,
+    MemoryGateContext,
+    MemoryGenerationCallback,
+    MemoryGenerationFailedFile,
+    MemoryGenerationGateInput,
+    MemoryGenerationGateResult,
+    MemoryGenerationOptions,
+    MemoryGenerationResult,
+    MemoryMode,
+    MemoryOptions,
+    MemoryRoot,
+    MemoryRootAccess,
+    MemoryShouldGenerate,
+    MemoryTurnCompleteOptions,
+    MemoryWrittenFile,
+)
 from .plugins import (
     PluginError,
     disable_plugin,
@@ -106,10 +130,14 @@ from .types import (
     MAX_SKILL_EVOLUTION_REVIEW_THRESHOLD,
     AgentCreateParams,
     AgentDefinition,
+    AgentToolBackgroundLaunchResult,
     AssistantMessage,
     AssistantMessageWithRequestId,
     AsyncHookJSONOutput,
+    BackgroundTask,
+    BackgroundTasksChangedMessage,
     BaseHookInput,
+    BashToolBackgroundLaunchResult,
     BetaManagedAgentsAgentToolName,
     BetaManagedAgentsAgentToolset20260401Params,
     BetaManagedAgentsCustomSkillParams,
@@ -186,6 +214,8 @@ from .types import (
     McpStatusResponse,
     McpToolAnnotations,
     McpToolInfo,
+    MemoryConsumptionMessage,
+    MemoryGenerationMessage,
     Message,
     ModelContextConfig,
     ModelContextWindowEntry,
@@ -306,6 +336,9 @@ from .types import (
     TaskNotificationStatus,
     TaskProgressMessage,
     TaskStartedMessage,
+    TaskStatus,
+    TaskUpdatedMessage,
+    TaskUpdatePatch,
     TaskUsage,
     TextBlock,
     ThinkingBlock,
@@ -844,6 +877,29 @@ def create_sdk_mcp_server(
 
 
 __all__ = [
+    "EffectiveMemoryConfig",
+    "EffectiveMemoryRoot",
+    "MemoryMode",
+    "MemoryRootAccess",
+    "MemoryRoot",
+    "MemoryConsumptionFile",
+    "MemoryGenerationGateInput",
+    "MemoryGenerationGateResult",
+    "MemoryGateContext",
+    "MemoryWrittenFile",
+    "MemoryGenerationFailedFile",
+    "MemoryGenerationResult",
+    "MemoryConsumptionFileResult",
+    "MemoryConsumptionResult",
+    "MemoryShouldGenerate",
+    "MemoryGenerationCallback",
+    "MemoryConsumptionCallback",
+    "MemoryTurnCompleteOptions",
+    "MemoryGenerationOptions",
+    "MemoryConsumptionOptions",
+    "MemoryOptions",
+    "MemoryGenerationMessage",
+    "MemoryConsumptionMessage",
     "GoalClearedMessage",
     "GoalSnapshot",
     "GoalStatus",
@@ -935,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.14 → 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.38"
+__cli_version__ = "1.1.76"

{qoder_agent_sdk-1.0.14 → qoder_agent_sdk-1.0.16}/src/qoder_agent_sdk/_internal/client.py

@@ -16,6 +16,7 @@ from .auth_helpers import (
     get_fetch_service_account_token,
     once_callback,
 )
+from .memory import prepare_memory_options
 from .message_parser import parse_message
 from .query import Query, resolve_initialize_timeout
 from .session_storage import (
@@ -101,6 +102,7 @@ class InternalClient:
                 configured_options, on_auth_expired=on_auth_expired
             )
 
+        prepared_memory = prepare_memory_options(configured_options.memory)
         requires_store_resume = configured_options.session_store is not None and (
             configured_options.resume is not None
             or configured_options.continue_conversation
@@ -170,6 +172,7 @@ class InternalClient:
         try:
             query = Query(
                 transport=chosen_transport,
+                memory=prepared_memory,
                 is_streaming_mode=True,  # Always streaming internally
                 can_use_tool=configured_options.can_use_tool,
                 hooks=convert_hooks_to_internal_format(configured_options.hooks)

qoder_agent_sdk-1.0.16/src/qoder_agent_sdk/_internal/memory.py

@@ -0,0 +1,186 @@
+"""Validate memory options before starting the CLI; never serialize callbacks."""
+
+import math
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath, PureWindowsPath
+from typing import Any, cast
+
+from ..memory import (
+    MemoryConsumptionCallback,
+    MemoryGenerationCallback,
+    MemoryOptions,
+    MemoryShouldGenerate,
+)
+
+
+@dataclass
+class PreparedMemoryOptions:
+    config: dict[str, Any] | None = None
+    gates: dict[str, MemoryShouldGenerate] = field(default_factory=dict)
+    on_generation: MemoryGenerationCallback | None = None
+    on_consumption: MemoryConsumptionCallback | None = None
+
+
+def _object(value: Any, name: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise TypeError(f"{name} must be an object")
+    return cast(dict[str, Any], value)
+
+
+def _string(value: Any, name: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(f"{name} must be a non-empty string")
+
+
+def _boolean(data: dict[str, Any], key: str, name: str) -> None:
+    if key in data and not isinstance(data[key], bool):
+        raise TypeError(f"{name}.{key} must be a boolean")
+
+
+def _callback(data: dict[str, Any], key: str, name: str) -> None:
+    if key in data and not callable(data[key]):
+        raise TypeError(f"{name}.{key} must be callable")
+
+
+def _choice(
+    data: dict[str, Any], key: str, choices: tuple[str, ...], name: str
+) -> None:
+    if key in data and data[key] not in choices:
+        raise TypeError(f"{name}.{key} must be one of {choices}")
+
+
+def _files(value: Any, name: str, *, roots: bool) -> list[dict[str, Any]]:
+    if not isinstance(value, list) or not value:
+        raise TypeError(f"{name} must be a non-empty list")
+    ids: set[str] = set()
+    result = []
+    for index, raw in enumerate(value):
+        label = f"{name}[{index}]"
+        item = _object(raw, label)
+        for key in ("id", "path"):
+            _string(item.get(key), f"{label}.{key}")
+        if item["id"] in ids:
+            raise TypeError(f'{name} contains duplicate id "{item["id"]}"')
+        ids.add(item["id"])
+        output = {"id": item["id"], "path": item["path"]}
+        if roots:
+            _choice(item, "access", ("read", "read-write"), label)
+            if "access" in item:
+                output["access"] = item["access"]
+            if "index_file" in item:
+                path = item["index_file"]
+                _string(path, f"{label}.index_file")
+                normalized = path.replace("\\", "/")
+                if (
+                    PurePosixPath(normalized).is_absolute()
+                    or PureWindowsPath(path).root
+                    or ".." in normalized.split("/")
+                ):
+                    raise TypeError(f"{label}.index_file must stay within its root")
+                output["indexFile"] = path
+        else:
+            _boolean(item, "required", label)
+            output["required"] = item.get("required", False)
+        result.append(output)
+    return result
+
+
+def prepare_memory_options(memory: MemoryOptions | None) -> PreparedMemoryOptions:
+    prepared = PreparedMemoryOptions()
+    if memory is None:
+        return prepared
+    data = _object(memory, "options.memory")
+    if not data:
+        return prepared
+    if data.get("mode") not in ("native", "custom"):
+        raise TypeError('options.memory.mode must be "native" or "custom"')
+    config: dict[str, Any] = {"requester": "sdk", "mode": data["mode"]}
+    for key, wire in (("project_scope", "projectScope"), ("user_scope", "userScope")):
+        _boolean(data, key, "options.memory")
+        if key in data:
+            config[wire] = data[key]
+    if (
+        data["mode"] == "native"
+        and data.get("project_scope") is False
+        and data.get("user_scope") is False
+    ):
+        raise TypeError(
+            "native memory requires at least one enabled scope; use memory={} to disable"
+        )
+    for section in ("generation", "consumption"):
+        if section not in data:
+            continue
+        name = f"options.memory.{section}"
+        options = _object(data[section], name)
+        _callback(options, "on_result", name)
+        if section == "generation":
+            prepared.on_generation = options.get("on_result")
+        else:
+            prepared.on_consumption = options.get("on_result")
+        if data["mode"] == "native":
+            if options.keys() - {"on_result"}:
+                raise TypeError(
+                    "native mode only accepts generation.on_result and consumption.on_result"
+                )
+            continue
+        _boolean(options, "enabled", name)
+        output: dict[str, Any] = {"enabled": options.get("enabled", True)}
+        if section == "generation":
+            if "roots" in options:
+                output["roots"] = _files(options["roots"], f"{name}.roots", roots=True)
+            if "prompt" in options:
+                _string(options["prompt"], f"{name}.prompt")
+                output["prompt"] = options["prompt"]
+            if "turn_complete" in options:
+                turn = _object(options["turn_complete"], f"{name}.turn_complete")
+                label = f"{name}.turn_complete"
+                _boolean(turn, "enabled", label)
+                _callback(turn, "should_generate", label)
+                _choice(turn, "on_gate_error", ("skip", "report_failed"), label)
+                tc: dict[str, Any] = {"enabled": turn.get("enabled", True)}
+                if "timeout_ms" in turn:
+                    timeout = turn["timeout_ms"]
+                    if (
+                        isinstance(timeout, bool)
+                        or not isinstance(timeout, (int, float))
+                        or not math.isfinite(timeout)
+                        or timeout <= 0
+                    ):
+                        raise TypeError(
+                            f"{label}.timeout_ms must be a positive finite number"
+                        )
+                    tc["timeoutMs"] = timeout
+                if "on_gate_error" in turn:
+                    tc["onGateError"] = turn["on_gate_error"]
+                if "should_generate" in turn:
+                    callback_id = "memory_should_generate_0"
+                    prepared.gates[callback_id] = turn["should_generate"]
+                    tc["shouldGenerateCallbackId"] = callback_id
+                if turn.get("enabled") is True and options.get("enabled") is False:
+                    raise TypeError(
+                        "turn_complete cannot be enabled when generation.enabled is false"
+                    )
+                output["turnComplete"] = tc
+        else:
+            if "files" in options:
+                output["files"] = _files(options["files"], f"{name}.files", roots=False)
+            if "max_tokens" in options:
+                budget = options["max_tokens"]
+                if (
+                    isinstance(budget, bool)
+                    or not isinstance(budget, int)
+                    or budget <= 0
+                ):
+                    raise TypeError(f"{name}.max_tokens must be a positive integer")
+                output["maxTokens"] = budget
+            _choice(options, "overflow", ("truncate", "fail_query"), name)
+            _choice(options, "failure_mode", ("best_effort", "fail_query"), name)
+            for key, wire in (
+                ("overflow", "overflow"),
+                ("failure_mode", "failureMode"),
+            ):
+                if key in options:
+                    output[wire] = options[key]
+        config[section] = output
+    prepared.config = config
+    return prepared

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

@@ -7,10 +7,13 @@ from .._errors import MessageParseError
 from ..types import (
     AssistantMessage,
     AssistantMessageWithRequestId,
+    BackgroundTasksChangedMessage,
     CloudAgentEventMessage,
     ContentBlock,
     GoalClearedMessage,
     GoalUpdatedMessage,
+    MemoryConsumptionMessage,
+    MemoryGenerationMessage,
     Message,
     PlanModeChangedMessage,
     ResultMessage,
@@ -22,6 +25,7 @@ from ..types import (
     TaskNotificationMessage,
     TaskProgressMessage,
     TaskStartedMessage,
+    TaskUpdatedMessage,
     TextBlock,
     ThinkingBlock,
     ToolResultBlock,
@@ -166,6 +170,14 @@ def parse_message(data: dict[str, Any]) -> Message | None:
             try:
                 subtype = data["subtype"]
                 match subtype:
+                    case "memory_generation":
+                        return MemoryGenerationMessage(
+                            subtype=subtype, data=data, result=data["result"]
+                        )
+                    case "memory_consumption":
+                        return MemoryConsumptionMessage(
+                            subtype=subtype, data=data, result=data["result"]
+                        )
                     case "permission_denied":
                         return SDKPermissionDeniedMessage(
                             subtype=subtype,
@@ -189,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(
@@ -196,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(
@@ -222,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,