docs: document gateway tool methods

steipete · steipete · commit a8154f425c0c · 2026-06-04T18:28:04.000-04:00
diff --git a/src/gateway/server-methods.ts b/src/gateway/server-methods.ts
@@ -1,3 +1,5 @@
+// Gateway method registry aggregator wires core and plugin RPC descriptors to
+// lazy-loaded handler families, role checks, scopes, and control-plane budgets.
 import { ErrorCodes, errorShape } from "../../packages/gateway-protocol/src/index.js";
 import {
   gatewayStartupUnavailableDetails,
diff --git a/src/gateway/server-methods/tasks.ts b/src/gateway/server-methods/tasks.ts
@@ -1,3 +1,5 @@
+// Task gateway methods expose detached task list/get/cancel operations with
+// bounded public summaries over the runtime task registry.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   ErrorCodes,
diff --git a/src/gateway/server-methods/tools-effective.test.ts b/src/gateway/server-methods/tools-effective.test.ts
@@ -1,3 +1,5 @@
+// Effective tools tests cover session-scoped tool inventory, MCP catalog state,
+// caching behavior, delivery context, and policy filtering.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { ErrorCodes } from "../../../packages/gateway-protocol/src/index.js";
 import type { McpToolCatalog, SessionMcpRuntime } from "../../agents/agent-bundle-mcp-types.js";
diff --git a/src/gateway/server-methods/tools-effective.ts b/src/gateway/server-methods/tools-effective.ts
@@ -1,3 +1,5 @@
+// Effective tools methods resolve the tools available to a session by combining
+// bundled tools, MCP tools, plugin policy, model context, and cache state.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   ErrorCodes,
diff --git a/src/gateway/server-methods/tools-invoke.ts b/src/gateway/server-methods/tools-invoke.ts
@@ -1,3 +1,5 @@
+// Tool invocation methods adapt gateway-visible tools to RPC callers with
+// protocol-shaped success, approval-required, validation, and error payloads.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   ErrorCodes,
diff --git a/src/gateway/server-methods/update-managed-service-handoff.ts b/src/gateway/server-methods/update-managed-service-handoff.ts
@@ -1,3 +1,5 @@
+// Managed-service update handoff starts a detached process that can finish an
+// update after the gateway exits under launchd/systemd-style supervisors.
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
diff --git a/src/gateway/server-methods/update.test.ts b/src/gateway/server-methods/update.test.ts
@@ -1,3 +1,5 @@
+// Update method tests cover update.run/status, restart sentinel metadata,
+// managed-service handoff, restart scheduling, and delivery context preservation.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { RestartSentinelPayload } from "../../infra/restart-sentinel.js";
 import type { RespawnSupervisor } from "../../infra/supervisor-markers.js";
diff --git a/src/gateway/server-methods/update.ts b/src/gateway/server-methods/update.ts
@@ -1,3 +1,5 @@
+// Update gateway methods run self-update flows, report status, write restart
+// sentinels, and hand off managed-service restarts when needed.
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import {
diff --git a/src/gateway/server-methods/usage.sessions-usage.test.ts b/src/gateway/server-methods/usage.sessions-usage.test.ts
@@ -1,3 +1,5 @@
+// Session usage tests cover aggregate cost/token usage across configured and
+// discovered agent session logs.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts
@@ -1,3 +1,5 @@
+// Usage gateway methods aggregate provider and session cost/token metrics from
+// caches, logs, session stores, and discovered transcript files.
 import fs from "node:fs";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/gateway/server-methods/validation.ts b/src/gateway/server-methods/validation.ts
@@ -1,3 +1,5 @@
+// Validation helpers adapt gateway-protocol validators to standard method
+// INVALID_REQUEST responses.
 import {
   ErrorCodes,
   errorShape,
diff --git a/src/gateway/server-methods/web.ts b/src/gateway/server-methods/web.ts
@@ -1,3 +1,5 @@
+// Web login methods delegate QR-login start/wait requests to the active channel
+// plugin that owns web login gateway methods.
 import {
   ErrorCodes,
   errorShape,
diff --git a/src/gateway/server-methods/wizard.ts b/src/gateway/server-methods/wizard.ts
@@ -1,3 +1,5 @@
+// Wizard gateway methods manage interactive setup wizard sessions and route
+// start/next/status/cancel RPCs through the wizard runtime.
 import { randomUUID } from "node:crypto";
 import { readStringValue } from "@openclaw/normalization-core/string-coerce";
 import {

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Gateway method registry aggregator wires core and plugin RPC descriptors to`
	`2`	`+// lazy-loaded handler families, role checks, scopes, and control-plane budgets.`
`1`	`3`	`import { ErrorCodes, errorShape } from "../../packages/gateway-protocol/src/index.js";`
`2`	`4`	`import {`
`3`	`5`	`gatewayStartupUnavailableDetails,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Task gateway methods expose detached task list/get/cancel operations with`
	`2`	`+// bounded public summaries over the runtime task registry.`
`1`	`3`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`4`	`import {`
`3`	`5`	`ErrorCodes,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Effective tools tests cover session-scoped tool inventory, MCP catalog state,`
	`2`	`+// caching behavior, delivery context, and policy filtering.`
`1`	`3`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`4`	`import { ErrorCodes } from "../../../packages/gateway-protocol/src/index.js";`
`3`	`5`	`import type { McpToolCatalog, SessionMcpRuntime } from "../../agents/agent-bundle-mcp-types.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Effective tools methods resolve the tools available to a session by combining`
	`2`	`+// bundled tools, MCP tools, plugin policy, model context, and cache state.`
`1`	`3`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`4`	`import {`
`3`	`5`	`ErrorCodes,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Tool invocation methods adapt gateway-visible tools to RPC callers with`
	`2`	`+// protocol-shaped success, approval-required, validation, and error payloads.`
`1`	`3`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`2`	`4`	`import {`
`3`	`5`	`ErrorCodes,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Managed-service update handoff starts a detached process that can finish an`
	`2`	`+// update after the gateway exits under launchd/systemd-style supervisors.`
`1`	`3`	`import { spawn } from "node:child_process";`
`2`	`4`	`import fs from "node:fs/promises";`
`3`	`5`	`import os from "node:os";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Update method tests cover update.run/status, restart sentinel metadata,`
	`2`	`+// managed-service handoff, restart scheduling, and delivery context preservation.`
`1`	`3`	`import { beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`4`	`import type { RestartSentinelPayload } from "../../infra/restart-sentinel.js";`
`3`	`5`	`import type { RespawnSupervisor } from "../../infra/supervisor-markers.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Update gateway methods run self-update flows, report status, write restart`
	`2`	`+// sentinels, and hand off managed-service restarts when needed.`
`1`	`3`	`import { randomUUID } from "node:crypto";`
`2`	`4`	`import os from "node:os";`
`3`	`5`	`import {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Session usage tests cover aggregate cost/token usage across configured and`
	`2`	`+// discovered agent session logs.`
`1`	`3`	`import fs from "node:fs";`
`2`	`4`	`import os from "node:os";`
`3`	`5`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Usage gateway methods aggregate provider and session cost/token metrics from`
	`2`	`+// caches, logs, session stores, and discovered transcript files.`
`1`	`3`	`import fs from "node:fs";`
`2`	`4`	`import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";`
`3`	`5`	`import {`