diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index f2d64b9bd..2ba515440 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "0c3d1892cd5ad60fa5a5b703edb62168522140ff", - "syncedAt": "2026-05-01T08:01:58.279Z" + "sha": "ef0eb126159f1e6d28024a63fe847f0ce15cabfa", + "syncedAt": "2026-05-01T08:18:06.127Z" } diff --git a/docs/concepts/openclaw-sdk.md b/docs/concepts/openclaw-sdk.md index 499f2ddd6..ad8d58c23 100644 --- a/docs/concepts/openclaw-sdk.md +++ b/docs/concepts/openclaw-sdk.md @@ -25,24 +25,24 @@ resources. `@openclaw/sdk` ships with: -| Surface | Status | What it does | -| ------------------------- | ------- | ---------------------------------------------------------------------------- | -| `OpenClaw` | Ready | Main client entry point. Owns transport, connection, requests, and events. | -| `GatewayClientTransport` | Ready | WebSocket transport backed by the Gateway client. | -| `oc.agents` | Ready | Lists, creates, updates, deletes, and gets agent handles. | -| `Agent.run()` | Ready | Starts a Gateway `agent` run and returns a `Run`. | -| `oc.runs` | Ready | Creates, gets, waits for, cancels, and streams runs. | -| `Run.events()` | Ready | Streams normalized per-run events with replay for fast runs. | -| `Run.wait()` | Ready | Calls `agent.wait` and returns a stable `RunResult`. | -| `Run.cancel()` | Ready | Calls `sessions.abort` by run id, with session key when available. | -| `oc.sessions` | Ready | Creates, resolves, sends to, patches, compacts, and gets session handles. | -| `Session.send()` | Ready | Calls `sessions.send` and returns a `Run`. | -| `oc.models` | Ready | Calls `models.list` and the current `models.authStatus` status RPC. | -| `oc.tools` | Partial | Lists tool catalog and effective tools; direct tool invocation is not wired. | -| `oc.artifacts` | Ready | Lists, gets, and downloads Gateway transcript artifacts. | -| `oc.approvals` | Ready | Lists and resolves exec approvals through Gateway approval RPCs. | -| `oc.rawEvents()` | Ready | Exposes raw Gateway events for advanced consumers. | -| `normalizeGatewayEvent()` | Ready | Converts raw Gateway events into the stable SDK event shape. | +| Surface | Status | What it does | +| ------------------------- | ------ | -------------------------------------------------------------------------- | +| `OpenClaw` | Ready | Main client entry point. Owns transport, connection, requests, and events. | +| `GatewayClientTransport` | Ready | WebSocket transport backed by the Gateway client. | +| `oc.agents` | Ready | Lists, creates, updates, deletes, and gets agent handles. | +| `Agent.run()` | Ready | Starts a Gateway `agent` run and returns a `Run`. | +| `oc.runs` | Ready | Creates, gets, waits for, cancels, and streams runs. | +| `Run.events()` | Ready | Streams normalized per-run events with replay for fast runs. | +| `Run.wait()` | Ready | Calls `agent.wait` and returns a stable `RunResult`. | +| `Run.cancel()` | Ready | Calls `sessions.abort` by run id, with session key when available. | +| `oc.sessions` | Ready | Creates, resolves, sends to, patches, compacts, and gets session handles. | +| `Session.send()` | Ready | Calls `sessions.send` and returns a `Run`. | +| `oc.models` | Ready | Calls `models.list` and the current `models.authStatus` status RPC. | +| `oc.tools` | Ready | Lists, scopes, and invokes Gateway tools through the policy pipeline. | +| `oc.artifacts` | Ready | Lists, gets, and downloads Gateway transcript artifacts. | +| `oc.approvals` | Ready | Lists and resolves exec approvals through Gateway approval RPCs. | +| `oc.rawEvents()` | Ready | Exposes raw Gateway events for advanced consumers. | +| `normalizeGatewayEvent()` | Ready | Converts raw Gateway events into the stable SDK event shape. | The SDK also exports the core types used by those surfaces: `AgentRunParams`, `RunResult`, `RunStatus`, `OpenClawEvent`, @@ -216,11 +216,19 @@ await oc.models.list(); await oc.models.status({ probe: false }); // calls models.authStatus ``` -Tool helpers expose the Gateway catalog and effective tool view: +Tool helpers expose the Gateway catalog, effective tool view, and direct +Gateway tool invocation. `oc.tools.invoke()` returns a typed envelope instead +of throwing for policy or approval refusals. ```typescript await oc.tools.list(); await oc.tools.effective({ sessionKey: "main" }); +await oc.tools.invoke("tool-name", { + args: { input: "value" }, + sessionKey: "main", + confirm: false, + idempotencyKey: "tool-call-1", +}); ``` Artifact helpers expose the Gateway artifact projection for session, run, or @@ -256,8 +264,6 @@ await oc.tasks.list(); await oc.tasks.get("task-id"); await oc.tasks.cancel("task-id"); -await oc.tools.invoke("tool-name", {}); - await oc.environments.list(); await oc.environments.create({}); await oc.environments.status("environment-id"); diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 2f572f677..e243f2509 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -443,7 +443,7 @@ enumeration of `src/gateway/server-methods/*.ts`. - Automation: `wake` schedules an immediate or next-heartbeat wake text injection; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` manage scheduled work. - - Skills and tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`. + - Skills and tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`, `tools.invoke`. @@ -501,6 +501,15 @@ enumeration of `src/gateway/server-methods/*.ts`. caller-supplied auth or delivery context. - The response is session-scoped and reflects what the active conversation can use right now, including core, plugin, and channel tools. +- Operators may call `tools.invoke` (`operator.write`) to invoke one available tool through the + same gateway policy path as `/tools/invoke`. + - `name` is required. `args`, `sessionKey`, `agentId`, `confirm`, and + `idempotencyKey` are optional. + - If both `sessionKey` and `agentId` are present, the resolved session agent must match + `agentId`. + - The response is an SDK-facing envelope with `ok`, `toolName`, optional `output`, and typed + `error` fields. Approval or policy refusals return `ok:false` in the payload rather than + bypassing the gateway tool policy pipeline. - Operators may call `skills.status` (`operator.read`) to fetch the visible skill inventory for an agent. - `agentId` is optional; omit it to read the default agent workspace.