docs: document agent bundle runtimes

steipete · steipete · commit f2d8facb4876 · 2026-06-04T05:34:48.000-04:00
diff --git a/src/agents/agent-bundle-lsp-runtime.test.ts b/src/agents/agent-bundle-lsp-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests embedded LSP runtime JSON-RPC, tool behavior, and cleanup. */
 import { EventEmitter } from "node:events";
 import { PassThrough, Writable } from "node:stream";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/agents/agent-bundle-lsp-runtime.ts b/src/agents/agent-bundle-lsp-runtime.ts
@@ -1,3 +1,4 @@
+/** Session-scoped embedded LSP runtime and tool materialization for agent bundles. */
 import { spawn, type ChildProcess } from "node:child_process";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -46,6 +47,7 @@ type LspServerCapabilities = {
   [key: string]: unknown;
 };
 
+/** Materialized LSP tools plus session capabilities and cleanup handle. */
 export type BundleLspToolRuntime = {
   tools: AnyAgentTool[];
   sessions: Array<{ serverName: string; capabilities: LspServerCapabilities }>;
@@ -69,6 +71,7 @@ function delay(ms: number): Promise<void> {
   });
 }
 
+/** Spawns one LSP server process using sanitized host env and Windows shim handling. */
 export function spawnLspServerProcess(config: StdioMcpServerLaunchConfig): ChildProcess {
   const mergedEnv = sanitizeHostExecEnv({ baseEnv: process.env, overrides: config.env ?? null });
   const program = resolveWindowsSpawnProgram({
diff --git a/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts b/src/agents/agent-bundle-lsp-runtime.windows-spawn.test.ts
@@ -1,3 +1,4 @@
+/** Tests LSP server spawning with Windows shim and sanitized env handling. */
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { spawnLspServerProcess } from "./agent-bundle-lsp-runtime.js";
 
diff --git a/src/agents/agent-bundle-mcp-materialize.ts b/src/agents/agent-bundle-mcp-materialize.ts
@@ -1,3 +1,4 @@
+/** Materializes configured MCP catalog entries into agent tools and runtime helpers. */
 import crypto from "node:crypto";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/agents/agent-bundle-mcp-names.test.ts b/src/agents/agent-bundle-mcp-names.test.ts
@@ -1,3 +1,4 @@
+/** Tests MCP server/tool name sanitization, truncation, and collision handling. */
 import { describe, expect, it } from "vitest";
 import {
   buildSafeToolName,
diff --git a/src/agents/agent-bundle-mcp-names.ts b/src/agents/agent-bundle-mcp-names.ts
@@ -1,3 +1,4 @@
+/** Sanitizes MCP server/tool names into stable model-facing tool ids. */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -38,6 +39,7 @@ function sanitizeToolName(raw: string): string {
   return sanitizeToolFragment(raw, "tool");
 }
 
+/** Normalizes reserved tool names for collision checks. */
 export function normalizeReservedToolNames(names?: Iterable<string>): Set<string> {
   return new Set(
     Array.from(names ?? [], (name) => normalizeOptionalLowercaseString(name)).filter(
diff --git a/src/agents/agent-bundle-mcp-runtime.test.ts b/src/agents/agent-bundle-mcp-runtime.test.ts
@@ -1,3 +1,4 @@
+/** Tests session-scoped MCP runtime catalog, transport, validation, and lifecycle behavior. */
 import fs from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
diff --git a/src/agents/agent-bundle-mcp-runtime.ts b/src/agents/agent-bundle-mcp-runtime.ts
@@ -1,3 +1,4 @@
+/** Session-scoped MCP runtime manager, catalog loader, and transport lifecycle. */
 import crypto from "node:crypto";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
diff --git a/src/agents/agent-bundle-mcp-test-harness.ts b/src/agents/agent-bundle-mcp-test-harness.ts
@@ -1,4 +1,4 @@
-// Test helper for resetting bundle MCP runtime state between harness tests.
+/** Test helper for resetting bundle MCP runtime state between harness tests. */
 /** Reset session-scoped bundle MCP runtime manager state. */
 export async function cleanupBundleMcpHarness(): Promise<void> {
   const { testing } = await import("./agent-bundle-mcp-tools.js");
diff --git a/src/agents/agent-bundle-mcp-tools.materialize.test.ts b/src/agents/agent-bundle-mcp-tools.materialize.test.ts
@@ -1,3 +1,4 @@
+/** Tests materializing MCP catalog tools into agent tool definitions and results. */
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { validateToolArguments } from "openclaw/plugin-sdk/llm";
 import { describe, expect, it } from "vitest";
diff --git a/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts b/src/agents/agent-bundle-mcp-tools.request-boundary.test.ts
@@ -1,3 +1,4 @@
+/** Tests configured MCP tools survive policy/splitting to the outbound request boundary. */
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
diff --git a/src/agents/agent-bundle-mcp-tools.ts b/src/agents/agent-bundle-mcp-tools.ts
@@ -1,5 +1,4 @@
-// Public barrel for bundle MCP tool materialization and session-scoped runtime
-// management. Keep callers on this facade instead of importing runtime internals.
+/** Public facade for bundle MCP tool materialization and session-scoped runtime management. */
 export type {
   BundleMcpToolRuntime,
   McpCatalogTool,
diff --git a/src/agents/agent-bundle-mcp-types.ts b/src/agents/agent-bundle-mcp-types.ts
@@ -1,14 +1,17 @@
+/** Shared bundle MCP catalog, runtime, and manager types. */
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { TSchema } from "typebox";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { AnyAgentTool } from "./tools/common.js";
 
+/** Materialized MCP tools plus diagnostics and cleanup handle for one run. */
 export type BundleMcpToolRuntime = {
   tools: AnyAgentTool[];
   diagnostics?: readonly McpToolCatalogDiagnostic[];
   dispose: () => Promise<void>;
 };
 
+/** Catalog metadata for one configured MCP server. */
 export type McpServerCatalog = {
   serverName: string;
   safeServerName?: string;
@@ -32,6 +35,7 @@ export type McpServerCatalog = {
   };
 };
 
+/** MCP tool entry after server-name sanitization and schema normalization. */
 export type McpCatalogTool = {
   serverName: string;
   safeServerName: string;
@@ -42,6 +46,7 @@ export type McpCatalogTool = {
   fallbackDescription: string;
 };
 
+/** Complete tool catalog for a session-scoped MCP runtime. */
 export type McpToolCatalog = {
   version: number;
   generatedAt: number;
@@ -57,6 +62,7 @@ export type McpToolCatalogDiagnostic = {
   message: string;
 };
 
+/** Live MCP runtime bound to one session/workspace. */
 export type SessionMcpRuntime = {
   sessionId: string;
   sessionKey?: string;
@@ -79,6 +85,7 @@ export type SessionMcpRuntime = {
   dispose: () => Promise<void>;
 };
 
+/** Manager for session-scoped MCP runtimes and their idle lifecycle. */
 export type SessionMcpRuntimeManager = {
   getOrCreate: (params: {
     sessionId: string;

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests embedded LSP runtime JSON-RPC, tool behavior, and cleanup. */`
`1`	`2`	`import { EventEmitter } from "node:events";`
`2`	`3`	`import { PassThrough, Writable } from "node:stream";`
`3`	`4`	`import { afterEach, describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests LSP server spawning with Windows shim and sanitized env handling. */`
`1`	`2`	`import { describe, expect, it, vi, beforeEach } from "vitest";`
`2`	`3`	`import { spawnLspServerProcess } from "./agent-bundle-lsp-runtime.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Materializes configured MCP catalog entries into agent tools and runtime helpers. */`
`1`	`2`	`import crypto from "node:crypto";`
`2`	`3`	`import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";`
`3`	`4`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests MCP server/tool name sanitization, truncation, and collision handling. */`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`buildSafeToolName,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests session-scoped MCP runtime catalog, transport, validation, and lifecycle behavior. */`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import http from "node:http";`
`3`	`4`	`import os from "node:os";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Session-scoped MCP runtime manager, catalog loader, and transport lifecycle. */`
`1`	`2`	`import crypto from "node:crypto";`
`2`	`3`	`import { Client } from "@modelcontextprotocol/sdk/client/index.js";`
`3`	`4`	`import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// Test helper for resetting bundle MCP runtime state between harness tests.`
	`1`	`+/** Test helper for resetting bundle MCP runtime state between harness tests. */`
`2`	`2`	`/** Reset session-scoped bundle MCP runtime manager state. */`
`3`	`3`	`export async function cleanupBundleMcpHarness(): Promise<void> {`
`4`	`4`	`const { testing } = await import("./agent-bundle-mcp-tools.js");`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+/** Tests materializing MCP catalog tools into agent tool definitions and results. */`
`1`	`2`	`import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";`
`2`	`3`	`import { validateToolArguments } from "openclaw/plugin-sdk/llm";`
`3`	`4`	`import { describe, expect, it } from "vitest";`