fix(gateway): document task ledger SDK surface

BunsDev · BunsDev · commit 42d73001ae80 · 2026-05-09T00:43:07.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ Docs: https://docs.openclaw.ai
 - Telegram/Feishu: honor configured per-agent and global `reasoningDefault` values when deciding whether channel reasoning previews should stream or stay hidden, addressing the preview-default part of #73182. Thanks @anagnorisis2peripeteia.
 - Docker: run the runtime image under `tini` so long-lived containers reap orphaned child processes and forward signals correctly. (#77885) Thanks @VintageAyu.
 - Logging/redaction: redact quoted HTTP client secret fields and auth/cookie headers in shared log and formatted error output. Related #71211 and #65623. (#75033) Thanks @liaoandi.
+- Gateway/SDK: document and stabilize the task ledger RPC surface for `tasks.list`, `tasks.get`, and `tasks.cancel`, including generated Swift model typing for optional task summaries. Thanks @BunsDev.
 - Google/Gemini: normalize retired `google/gemini-3-pro-preview` and `google-gemini-cli/gemini-3-pro-preview` selections to `google/gemini-3.1-pro-preview` before they are written to model config.
 - Google/Gemini: emit canonical `google/gemini-3.1-pro-preview` ids from configured provider catalog rows so model list and selection paths can test Gemini 3.1 instead of retired Gemini 3 Pro.
 - Google/Gemini: normalize nested proxy-provider catalog ids like `google/gemini-3-pro-preview` to `google/gemini-3.1-pro-preview`, so Kilo-style configured catalogs test Gemini 3.1 instead of the retired Gemini 3 Pro id.
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -165,14 +165,14 @@ public struct ResponseFrame: Codable, Sendable {
     public let id: String
     public let ok: Bool
     public let payload: AnyCodable?
-    public let error: [String: AnyCodable]?
+    public let error: ErrorShape?
 
     public init(
         type: String,
         id: String,
         ok: Bool,
         payload: AnyCodable?,
-        error: [String: AnyCodable]?)
+        error: ErrorShape?)
     {
         self.type = type
         self.id = id
@@ -195,14 +195,14 @@ public struct EventFrame: Codable, Sendable {
     public let event: String
     public let payload: AnyCodable?
     public let seq: Int?
-    public let stateversion: [String: AnyCodable]?
+    public let stateversion: StateVersion?
 
     public init(
         type: String,
         event: String,
         payload: AnyCodable?,
         seq: Int?,
-        stateversion: [String: AnyCodable]?)
+        stateversion: StateVersion?)
     {
         self.type = type
         self.event = event
@@ -2778,13 +2778,13 @@ public struct WizardStep: Codable, Sendable {
 
 public struct WizardNextResult: Codable, Sendable {
     public let done: Bool
-    public let step: [String: AnyCodable]?
+    public let step: WizardStep?
     public let status: AnyCodable?
     public let error: String?
 
     public init(
         done: Bool,
-        step: [String: AnyCodable]?,
+        step: WizardStep?,
         status: AnyCodable?,
         error: String?)
     {
@@ -2805,14 +2805,14 @@ public struct WizardNextResult: Codable, Sendable {
 public struct WizardStartResult: Codable, Sendable {
     public let sessionid: String
     public let done: Bool
-    public let step: [String: AnyCodable]?
+    public let step: WizardStep?
     public let status: AnyCodable?
     public let error: String?
 
     public init(
         sessionid: String,
         done: Bool,
-        step: [String: AnyCodable]?,
+        step: WizardStep?,
         status: AnyCodable?,
         error: String?)
     {
@@ -4755,7 +4755,7 @@ public struct ToolsInvokeResult: Codable, Sendable {
     public let requiresapproval: Bool?
     public let approvalid: String?
     public let source: AnyCodable?
-    public let error: [String: AnyCodable]?
+    public let error: ToolsInvokeError?
 
     public init(
         ok: Bool,
@@ -4764,7 +4764,7 @@ public struct ToolsInvokeResult: Codable, Sendable {
         requiresapproval: Bool?,
         approvalid: String?,
         source: AnyCodable?,
-        error: [String: AnyCodable]?)
+        error: ToolsInvokeError?)
     {
         self.ok = ok
         self.toolname = toolname
diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
@@ -411,6 +411,7 @@ enumeration of `src/gateway/server-methods/*.ts`.
     - `agents.list` returns configured agent entries, including effective model and runtime metadata.
     - `agents.create`, `agents.update`, and `agents.delete` manage agent records and workspace wiring.
     - `agents.files.list`, `agents.files.get`, and `agents.files.set` manage the bootstrap workspace files exposed for an agent.
+    - `tasks.list`, `tasks.get`, and `tasks.cancel` expose the Gateway task ledger to SDK and operator clients.
     - `artifacts.list`, `artifacts.get`, and `artifacts.download` expose transcript-derived artifact summaries and downloads for an explicit `sessionKey`, `runId`, or `taskId` scope. Run and task queries resolve the owning session server-side and only return transcript media with matching provenance; unsafe or local URL sources return unsupported downloads instead of fetching server-side.
     - `environments.list` and `environments.status` expose read-only Gateway-local and node environment discovery for SDK clients.
     - `agent.identity.get` returns the effective assistant identity for an agent or session.
@@ -499,6 +500,34 @@ enumeration of `src/gateway/server-methods/*.ts`.
 - Nodes may call `skills.bins` to fetch the current list of skill executables
   for auto-allow checks.
 
+### Task ledger RPCs
+
+Operator clients may inspect and cancel Gateway background task records through
+the task ledger RPCs. These methods return sanitized task summaries, not raw
+runtime state.
+
+- `tasks.list` requires `operator.read`.
+  - Params: optional `status` (`"queued"`, `"running"`, `"completed"`,
+    `"failed"`, `"cancelled"`, or `"timed_out"`) or an array of those statuses,
+    optional `agentId`, optional `sessionKey`, optional `limit` from `1` to
+    `500`, and optional string `cursor`.
+  - Result: `{ "tasks": TaskSummary[], "nextCursor"?: string }`.
+- `tasks.get` requires `operator.read`.
+  - Params: `{ "taskId": string }`.
+  - Result: `{ "task": TaskSummary }`.
+  - Missing task ids return the Gateway not-found error shape.
+- `tasks.cancel` requires `operator.write`.
+  - Params: `{ "taskId": string, "reason"?: string }`.
+  - Result:
+    `{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }`.
+  - `found` reports whether the ledger had a matching task. `cancelled`
+    reports whether the runtime accepted or recorded cancellation.
+
+`TaskSummary` includes `id`, `status`, and optional metadata such as `kind`,
+`runtime`, `title`, `agentId`, `sessionKey`, `childSessionKey`, `ownerKey`,
+`runId`, `taskId`, `flowId`, `parentTaskId`, `sourceId`, timestamps, progress,
+terminal summary, and sanitized error text.
+
 ### Operator helper methods
 
 - Operators may call `commands.list` (`operator.read`) to fetch the runtime
diff --git a/docs/reference/openclaw-sdk-api-design.md b/docs/reference/openclaw-sdk-api-design.md
@@ -49,9 +49,9 @@ oc.runs.events(runId, { after });
 oc.runs.wait(runId);
 oc.runs.cancel(runId);
 
-oc.tasks.list(); // future API: current SDK throws unsupported
-oc.tasks.get(taskId); // future API: current SDK throws unsupported
-oc.tasks.cancel(taskId); // future API: current SDK throws unsupported
+oc.tasks.list({ status: "running" });
+oc.tasks.get(taskId);
+oc.tasks.cancel(taskId, { reason });
 oc.tasks.events(taskId, { after }); // future API
 
 oc.models.list();
diff --git a/scripts/protocol-gen-swift.ts b/scripts/protocol-gen-swift.ts
@@ -175,7 +175,7 @@ function emitStruct(name: string, schema: JsonSchema): string {
   const codingKeys: string[] = [];
   for (const [key, propSchema] of Object.entries(props)) {
     const propName = safeName(key);
-    const propType = swiftType(propSchema, required.has(key));
+    const propType = swiftType(propSchema, required.has(key), true);
     lines.push(`    public let ${propName}: ${propType}`);
     if (propName !== key) {
       codingKeys.push(`        case ${propName} = "${key}"`);
@@ -189,7 +189,7 @@ function emitStruct(name: string, schema: JsonSchema): string {
         .map(([key, prop]) => {
           const propName = safeName(key);
           const req = required.has(key);
-          return `        ${propName}: ${swiftType(prop, true)}${req ? "" : "?"}`;
+          return `        ${propName}: ${swiftType(prop, true, true)}${req ? "" : "?"}`;
         })
         .join(",\n") +
       ")\n" +
