@senpi/runtime 3.0.180 → 3.0.182

package/dist/tool-surface/crib-sheet.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The crib sheet: the `senpi__*` tool names, with their required arguments,
+ * for an OpenClaw 10.x agent in tool-search directory mode (R3).
+ *
+ * In directory mode OpenClaw lists only `source === "openclaw"` tools in the
+ * deferred-tool directory and folds every MCP tool into one generic sentence
+ * (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/tool-search-directory.ts:127-221`),
+ * so no `senpi__*` name reaches the model, while skills and guides keep naming
+ * them. The sheet puts the names back, as text the hook returns in
+ * `prependSystemContext`, ahead of the stable system-prompt prefix. It is
+ * cache-stable only while its bytes do not change, so the builder is pure and
+ * deterministic: the same set of tools in any order renders the same string.
+ *
+ * Every entry is the full catalog name (`senpi__create_position`), the exact
+ * text the dispatcher accepts as `id`; the model never assembles a name.
+ */
+/** One MCP tool as the crib needs it. */
+export interface McpToolSummary {
+    /** Bare MCP name, as `tools/list` returns it (`create_position`). */
+    name: string;
+    /** `inputSchema.required ?? []`, sorted. */
+    required: string[];
+    /** `Object.keys(inputSchema.properties ?? {})`, sorted. */
+    properties: string[];
+}
+/** Options for {@link buildCribSheet}. */
+export interface BuildCribSheetOptions {
+    /** Cap on the whole sheet, header included. Default {@link CRIB_SHEET_MAX_CHARS}. */
+    maxChars?: number;
+    /** The gateway's MCP server name, the catalog prefix. Default `senpi`. */
+    serverName?: string;
+    /**
+     * Optional arguments worth naming, by bare tool name. One renders as `arg?`
+     * only when the tool's `properties` has it, so a stale hint never names a
+     * missing argument. Default `{}` (open decision D11 decides whether any ship).
+     */
+    optionalHints?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The tool-search dispatcher's name as the host lists it (`dispatch_action`
+     * on 10.10; read from the host's tool list by the hook). Default
+     * {@link DEFAULT_DISPATCHER_NAME}.
+     */
+    dispatcherName?: string;
+}
+/** Default cap. The 59-tool MCP catalog renders in under 4,000 chars with arguments. */
+export declare const CRIB_SHEET_MAX_CHARS = 6000;
+/** The dispatcher name on the pinned host (`TOOL_CALL_RAW_TOOL_NAME`, 10.10 `src/agents/tool-search-types.ts:12`). */
+export declare const DEFAULT_DISPATCHER_NAME = "dispatch_action";
+/**
+ * Builds the sheet, or `null` when there is no tool to name.
+ *
+ * Over `maxChars` it first drops the argument lists; if the names alone still
+ * do not fit, it keeps whole groups in order and ends with `+N more`.
+ */
+export declare function buildCribSheet(tools: readonly McpToolSummary[], opts?: BuildCribSheetOptions): string | null;
+//# sourceMappingURL=crib-sheet.d.ts.map

package/dist/tool-surface/crib-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crib-sheet.d.ts","sourceRoot":"","sources":["../../src/tool-surface/crib-sheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,sHAAsH;AACtH,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAYzD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,IAAI,GAAE,qBAA0B,GAC/B,MAAM,GAAG,IAAI,CAmCf"}

package/dist/tool-surface/crib-sheet.js

@@ -0,0 +1,129 @@
+/**
+ * The crib sheet: the `senpi__*` tool names, with their required arguments,
+ * for an OpenClaw 10.x agent in tool-search directory mode (R3).
+ *
+ * In directory mode OpenClaw lists only `source === "openclaw"` tools in the
+ * deferred-tool directory and folds every MCP tool into one generic sentence
+ * (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/tool-search-directory.ts:127-221`),
+ * so no `senpi__*` name reaches the model, while skills and guides keep naming
+ * them. The sheet puts the names back, as text the hook returns in
+ * `prependSystemContext`, ahead of the stable system-prompt prefix. It is
+ * cache-stable only while its bytes do not change, so the builder is pure and
+ * deterministic: the same set of tools in any order renders the same string.
+ *
+ * Every entry is the full catalog name (`senpi__create_position`), the exact
+ * text the dispatcher accepts as `id`; the model never assembles a name.
+ */
+/** Default cap. The 59-tool MCP catalog renders in under 4,000 chars with arguments. */
+export const CRIB_SHEET_MAX_CHARS = 6_000;
+/** The dispatcher name on the pinned host (`TOOL_CALL_RAW_TOOL_NAME`, 10.10 `src/agents/tool-search-types.ts:12`). */
+export const DEFAULT_DISPATCHER_NAME = "dispatch_action";
+/** The schema tool on 10.x (`TOOL_DESCRIBE_RAW_TOOL_NAME`). */
+const DESCRIBE_TOOL_NAME = "tool_describe";
+/** The search tool on 10.x (`TOOL_SEARCH_RAW_TOOL_NAME`). */
+const SEARCH_TOOL_NAME = "tool_search";
+/**
+ * Builds the sheet, or `null` when there is no tool to name.
+ *
+ * Over `maxChars` it first drops the argument lists; if the names alone still
+ * do not fit, it keeps whole groups in order and ends with `+N more`.
+ */
+export function buildCribSheet(tools, opts = {}) {
+    const maxChars = opts.maxChars ?? CRIB_SHEET_MAX_CHARS;
+    const server = opts.serverName ?? "senpi";
+    const dispatcher = opts.dispatcherName ?? DEFAULT_DISPATCHER_NAME;
+    const hints = opts.optionalHints ?? {};
+    const byName = new Map();
+    for (const tool of tools) {
+        if (typeof tool?.name === "string" && tool.name.length > 0 && !byName.has(tool.name))
+            byName.set(tool.name, tool);
+    }
+    if (byName.size === 0)
+        return null;
+    const groups = groupByPrefix([...byName.values()]);
+    const example = byName.has("create_position") ? "create_position" : [...byName.keys()].sort()[0];
+    const withArgs = render(groups, header(server, dispatcher, example, true), (t) => entry(server, t, hints));
+    if (withArgs.length <= maxChars)
+        return withArgs;
+    const namesHeader = header(server, dispatcher, example, false);
+    const namesOnly = render(groups, namesHeader, (t) => `${server}__${t.name}`);
+    if (namesOnly.length <= maxChars)
+        return namesOnly;
+    const total = byName.size;
+    const lines = [];
+    let used = namesHeader.length;
+    let shown = 0;
+    for (const group of groups) {
+        const line = groupLine(group, (t) => `${server}__${t.name}`);
+        const remainingAfter = total - shown - group.tools.length;
+        const markerAfter = remainingAfter > 0 ? 1 + moreLine(remainingAfter).length : 0;
+        if (used + 1 + line.length + markerAfter > maxChars)
+            break;
+        lines.push(line);
+        used += 1 + line.length;
+        shown += group.tools.length;
+    }
+    lines.push(moreLine(total - shown));
+    return [namesHeader, ...lines].join("\n");
+}
+/**
+ * The sheet's opening lines. They carry the four facts the model needs: the
+ * tools are absent from the tool list and the directory; they are called
+ * through the dispatcher with the full name as `id`; skills drop the prefix;
+ * `tool_describe` gives the full schema.
+ */
+function header(server, dispatcher, example, withArgs) {
+    return [
+        "## Senpi tools",
+        `The Senpi tools below are not in your tool list and not in the deferred-tool directory. ` +
+            `To call one, use ${dispatcher} with {"id": "${server}__<name>", "args": {...}}. ` +
+            `Skills and guides name these tools without the ${server}__ prefix (${example}); add it (${server}__${example}). ` +
+            (withArgs
+                ? `Required arguments are in parentheses; run ${DESCRIBE_TOOL_NAME} on a name for its full argument schema.`
+                : `Run ${DESCRIBE_TOOL_NAME} on a name for its argument schema.`),
+    ].join("\n");
+}
+function render(groups, head, fmt) {
+    return [head, ...groups.map((g) => groupLine(g, fmt))].join("\n");
+}
+function groupLine(group, fmt) {
+    return `${group.prefix}: ${group.tools.map(fmt).join(", ")}`;
+}
+function moreLine(n) {
+    return `+${n} more Senpi tools: find them with ${SEARCH_TOOL_NAME}.`;
+}
+/**
+ * `senpi__name(req1, req2, opt?)`; required args sorted, hints in the order
+ * given. A tool that takes no arguments renders `senpi__name()`; one whose
+ * arguments are all optional (and unhinted) renders the bare name, so it does
+ * not read as taking none.
+ */
+function entry(server, tool, hints) {
+    const required = [...new Set(tool.required ?? [])].sort();
+    const properties = new Set(tool.properties ?? []);
+    const optional = (hints[tool.name] ?? []).filter((arg) => properties.has(arg) && !required.includes(arg));
+    const args = [...required, ...[...new Set(optional)].map((arg) => `${arg}?`)];
+    if (args.length === 0 && properties.size > 0)
+        return `${server}__${tool.name}`;
+    return `${server}__${tool.name}(${args.join(", ")})`;
+}
+/**
+ * Groups tools by their first `_` segment (the MCP server namespaces its tools
+ * that way: `market`, `strategy`, …), groups and names sorted by code unit so
+ * the order does not depend on the locale.
+ */
+function groupByPrefix(tools) {
+    const groups = new Map();
+    for (const tool of tools) {
+        const cut = tool.name.indexOf("_");
+        const prefix = cut > 0 ? tool.name.slice(0, cut) : tool.name;
+        const list = groups.get(prefix) ?? [];
+        list.push(tool);
+        groups.set(prefix, list);
+    }
+    const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return [...groups.entries()]
+        .sort(([a], [b]) => byCodeUnit(a, b))
+        .map(([prefix, list]) => ({ prefix, tools: list.sort((a, b) => byCodeUnit(a.name, b.name)) }));
+}
+//# sourceMappingURL=crib-sheet.js.map

package/dist/tool-surface/crib-sheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crib-sheet.js","sourceRoot":"","sources":["../../src/tool-surface/crib-sheet.ts"],"names":[],"mappings":"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"}

package/dist/tool-surface/mcp-tool-source.d.ts

@@ -0,0 +1,64 @@
+import type { McpToolSummary } from "./crib-sheet.js";
+/** OpenClaw `toolFilter` (`McpServerToolFilterConfig`): include then exclude, exact text or `*` globs. */
+export interface McpToolFilter {
+    include?: string[];
+    exclude?: string[];
+}
+/** The parts of a gateway MCP server entry the lister needs. */
+export interface GatewayMcpEntry {
+    url: string;
+    headers: Record<string, string>;
+    toolFilter?: McpToolFilter;
+}
+/**
+ * Reads `mcp.servers.<serverName>` from a whole OpenClaw config.
+ *
+ * @returns `null` when the entry is missing, `enabled: false`, has no http(s)
+ *   `url`, or is not streamable HTTP. OpenClaw runs an entry with a `command`
+ *   over stdio, and an http entry over SSE unless its canonical `transport`
+ *   (trimmed, lowercased) is `streamable-http`, so an entry with no transport
+ *   is SSE too (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/mcp-transport-config.ts:115-138`,
+ *   `src/config/mcp-config-normalize.ts:16-21`). This lister speaks only
+ *   streamable HTTP. senpi-agent writes `transport: "streamable-http"`.
+ *   Number and boolean header values are stringified, as OpenClaw's schema
+ *   allows them. The `toolFilter` is returned for the caller to apply.
+ */
+export declare function readGatewayMcpEntry(config: unknown, serverName?: string): GatewayMcpEntry | null;
+/**
+ * OpenClaw's include-then-exclude policy on a bare MCP tool name
+ * (`isMcpToolAllowed`, `src/agents/mcp-tool-filter.ts:55-64`, same on 10.4 and 10.10).
+ */
+export declare function isMcpToolAllowed(toolFilter: McpToolFilter | undefined, toolName: string): boolean;
+/** The slice of an MCP client the lister uses (the SDK `Client`, or a test double). */
+export interface McpListClient {
+    listTools(params?: {
+        cursor?: string;
+    }, options?: {
+        timeout?: number;
+    }): Promise<{
+        tools: Array<{
+            name: string;
+            inputSchema?: unknown;
+        }>;
+        nextCursor?: string;
+    }>;
+    close(): Promise<void>;
+}
+/** Options for {@link listMcpTools}. */
+export interface ListMcpToolsOptions {
+    /** Deadline for the whole listing, connect included. */
+    timeoutMs: number;
+    /** Test seam: opens the client. Defaults to the SDK streamable-HTTP client. */
+    connect?: (entry: GatewayMcpEntry, timeoutMs: number) => Promise<McpListClient>;
+}
+/**
+ * Lists the entry's tools through `tools/list`, following `nextCursor`, then
+ * applies the entry's `toolFilter` and maps each tool to an
+ * {@link McpToolSummary}. The client is always closed. `SenpiClient` is not
+ * used: the crib must see the gateway's server entry, not the runtime's.
+ *
+ * @throws On a connect or page failure, a repeated cursor, too many pages, or
+ *   when the whole listing outlives `timeoutMs`.
+ */
+export declare function listMcpTools(entry: GatewayMcpEntry, opts: ListMcpToolsOptions): Promise<McpToolSummary[]>;
+//# sourceMappingURL=mcp-tool-source.d.ts.map

package/dist/tool-surface/mcp-tool-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-source.d.ts","sourceRoot":"","sources":["../../src/tool-surface/mcp-tool-source.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,aAAa,CAAC;CAC5B;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,SAAU,GAAG,eAAe,GAAG,IAAI,CA4BjG;AAwCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,aAAa,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMjG;AAED,uFAAuF;AACvF,MAAM,WAAW,aAAa;IAC5B,SAAS,CACP,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACjF;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA+C/G"}

package/dist/tool-surface/mcp-tool-source.js

@@ -0,0 +1,189 @@
+/**
+ * Where the crib's tool names come from: the gateway's own `mcp.servers.<name>`
+ * entry, not the runtime's `SENPI_MCP_URL` (R3). The crib lists tools from that
+ * entry's `url` with its `headers` and applies its `toolFilter` with
+ * OpenClaw's semantics, so it names exactly what the gateway's catalog holds,
+ * including under a per-profile URL or filter.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function rec(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function stringEntries(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/**
+ * Reads `mcp.servers.<serverName>` from a whole OpenClaw config.
+ *
+ * @returns `null` when the entry is missing, `enabled: false`, has no http(s)
+ *   `url`, or is not streamable HTTP. OpenClaw runs an entry with a `command`
+ *   over stdio, and an http entry over SSE unless its canonical `transport`
+ *   (trimmed, lowercased) is `streamable-http`, so an entry with no transport
+ *   is SSE too (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/mcp-transport-config.ts:115-138`,
+ *   `src/config/mcp-config-normalize.ts:16-21`). This lister speaks only
+ *   streamable HTTP. senpi-agent writes `transport: "streamable-http"`.
+ *   Number and boolean header values are stringified, as OpenClaw's schema
+ *   allows them. The `toolFilter` is returned for the caller to apply.
+ */
+export function readGatewayMcpEntry(config, serverName = "senpi") {
+    const entry = rec(rec(rec(config)?.mcp)?.servers)?.[serverName];
+    const e = rec(entry);
+    if (!e || e.enabled === false)
+        return null;
+    if (typeof e.command === "string")
+        return null;
+    if (typeof e.transport !== "string" || e.transport.trim().toLowerCase() !== "streamable-http")
+        return null;
+    if (typeof e.url !== "string")
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(e.url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return null;
+    const headers = {};
+    for (const [key, value] of Object.entries(rec(e.headers) ?? {})) {
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+            headers[key] = String(value);
+    }
+    const result = { url: e.url, headers };
+    const filter = rec(e.toolFilter);
+    if (filter) {
+        const include = stringEntries(filter.include);
+        const exclude = stringEntries(filter.exclude);
+        if (include.length > 0 || exclude.length > 0) {
+            result.toolFilter = { ...(include.length > 0 ? { include } : {}), ...(exclude.length > 0 ? { exclude } : {}) };
+        }
+    }
+    return result;
+}
+/**
+ * Line-for-line port of OpenClaw `matchesMcpToolFilterPattern`
+ * (`openclaw-worktrees/v2026.10.10-beta.3/src/agents/mcp-tool-filter.ts:6-38`).
+ */
+function matchesMcpToolFilterPattern(pattern, value) {
+    const trimmed = pattern.trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (!trimmed.includes("*")) {
+        return trimmed === value;
+    }
+    const parts = trimmed.split("*");
+    const first = parts[0] ?? "";
+    const last = parts.at(-1) ?? "";
+    if (first && !value.startsWith(first)) {
+        return false;
+    }
+    let cursor = first.length;
+    const endBound = last ? value.length - last.length : value.length;
+    if (last && (!value.endsWith(last) || endBound < cursor)) {
+        return false;
+    }
+    for (const part of parts.slice(1, -1)) {
+        if (!part) {
+            continue;
+        }
+        const index = value.indexOf(part, cursor);
+        if (index === -1 || index + part.length > endBound) {
+            return false;
+        }
+        cursor = index + part.length;
+    }
+    return true;
+}
+/**
+ * OpenClaw's include-then-exclude policy on a bare MCP tool name
+ * (`isMcpToolAllowed`, `src/agents/mcp-tool-filter.ts:55-64`, same on 10.4 and 10.10).
+ */
+export function isMcpToolAllowed(toolFilter, toolName) {
+    const matches = (pattern) => matchesMcpToolFilterPattern(pattern, toolName);
+    return ((!toolFilter?.include?.length || toolFilter.include.some(matches)) &&
+        !toolFilter?.exclude?.some(matches));
+}
+/** Upper bound on pages, so a server that never ends its cursor chain cannot spin the refresh. */
+const MAX_PAGES = 50;
+async function connectSdkClient(entry) {
+    const transport = new StreamableHTTPClientTransport(new URL(entry.url), {
+        requestInit: { headers: entry.headers },
+    });
+    const client = new Client({ name: "senpi-runtime-tool-surface", version: "1.0.0" });
+    await client.connect(transport);
+    return client;
+}
+function toSummary(tool) {
+    const schema = rec(tool.inputSchema);
+    return {
+        name: tool.name,
+        required: [...new Set(stringEntries(schema?.required))].sort(),
+        properties: Object.keys(rec(schema?.properties) ?? {}).sort(),
+    };
+}
+/**
+ * Lists the entry's tools through `tools/list`, following `nextCursor`, then
+ * applies the entry's `toolFilter` and maps each tool to an
+ * {@link McpToolSummary}. The client is always closed. `SenpiClient` is not
+ * used: the crib must see the gateway's server entry, not the runtime's.
+ *
+ * @throws On a connect or page failure, a repeated cursor, too many pages, or
+ *   when the whole listing outlives `timeoutMs`.
+ */
+export async function listMcpTools(entry, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let timer;
+    let expired = false;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            expired = true;
+            reject(new Error(`tools/list timed out after ${opts.timeoutMs} ms`));
+        }, opts.timeoutMs);
+        timer.unref?.();
+    });
+    let client;
+    try {
+        const connect = opts.connect ?? ((e) => connectSdkClient(e));
+        const connecting = connect(entry, opts.timeoutMs);
+        // A connect that lands after the deadline still gets closed.
+        connecting.then((c) => {
+            if (expired)
+                void c.close().catch(() => undefined);
+        }, () => undefined);
+        client = await Promise.race([connecting, timeout]);
+        const out = [];
+        const seen = new Set();
+        let cursor;
+        for (let page = 0;; page += 1) {
+            if (page >= MAX_PAGES)
+                throw new Error(`tools/list returned more than ${MAX_PAGES} pages`);
+            const remaining = Math.max(1, deadline - Date.now());
+            const result = await Promise.race([
+                client.listTools(cursor === undefined ? undefined : { cursor }, { timeout: remaining }),
+                timeout,
+            ]);
+            for (const tool of result.tools ?? []) {
+                if (typeof tool?.name === "string" && isMcpToolAllowed(entry.toolFilter, tool.name))
+                    out.push(toSummary(tool));
+            }
+            const next = typeof result.nextCursor === "string" && result.nextCursor.length > 0 ? result.nextCursor : undefined;
+            if (next === undefined)
+                break;
+            if (seen.has(next))
+                throw new Error(`tools/list repeated cursor ${JSON.stringify(next)}`);
+            seen.add(next);
+            cursor = next;
+        }
+        return out;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        if (client)
+            await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=mcp-tool-source.js.map

package/dist/tool-surface/mcp-tool-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-source.js","sourceRoot":"","sources":["../../src/tool-surface/mcp-tool-source.ts"],"names":[],"mappings":"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"}

package/dist/utils/event-catalog.d.ts

@@ -81,6 +81,10 @@ export declare const EVENT_NAME: {
     readonly autoUpdateInstallFailed: "auto_update.install_failed";
     readonly autoUpdateRestartFailed: "auto_update.restart_failed";
     readonly autoUpdateDegraded: "auto_update.degraded";
+    readonly autoUpdateRestartRequested: "auto_update.restart_requested";
+    readonly autoUpdateApplyFailed: "auto_update.apply_failed";
+    readonly autoUpdateInstallResult: "auto_update.install_result";
+    readonly autoUpdateDeferred: "auto_update.deferred";
     readonly skillRouterDecision: "skill_router.decision";
     readonly skillRouterError: "skill_router.error";
     readonly skillsCheckCompleted: "skills.check_completed";
@@ -232,6 +236,10 @@ export interface EventAttributes {
     "auto_update.install_failed": AutoUpdateInstallFailedAttrs;
     "auto_update.restart_failed": AutoUpdateRestartFailedAttrs;
     "auto_update.degraded": AutoUpdateDegradedAttrs;
+    "auto_update.restart_requested": AutoUpdateRestartRequestedAttrs;
+    "auto_update.apply_failed": AutoUpdateApplyFailedAttrs;
+    "auto_update.install_result": AutoUpdateInstallResultAttrs;
+    "auto_update.deferred": AutoUpdateDeferredAttrs;
     "skill_router.decision": SkillRouterDecisionAttrs;
     "skill_router.error": SkillRouterErrorAttrs;
     "skills.check_completed": SkillsCheckCompletedAttrs;
@@ -759,20 +767,45 @@ export interface ToolCalledAttrs {
     "senpi.tool.outcome": string;
     /** Low-cardinality error class on an abnormal outcome (`errorTypeOf`, or `user_denied`/`approval_timeout` for a `denied` outcome). */
     "error.type"?: string;
+    /**
+     * `true` when the name is what the model asked an OpenClaw 10.x tool-search dispatcher for
+     * (`dispatch_action` / `tool_call` params `id`) and no inner call ran, e.g. `Unknown tool id`.
+     */
+    "senpi.tool.bridge"?: boolean;
 }
 /**
  * One MCP tool approval-gate decision — the audit trail of what the user chose and why. Fires on
- * EVERY terminal resolution: `allow-once` / `allow-always` (info) and `deny` / `timeout` (escalated
- * to warn). Complements `tool.called{denied}` (the execution-outcome plane): this is the
+ * EVERY terminal resolution: `allow-once` / `allow-always` (info) and `deny` / `timeout` /
+ * `cancelled` (escalated to warn). `cancelled` is a run abort with the prompt open, a host with no
+ * route or surface to ask (10.x), or the gate's own scheduled-turn block (`cancel_reason`). Complements `tool.called{denied}` (the execution-outcome plane): this is the
  * gate-decision plane, and the only place the approve path (`allow-once` vs `allow-always`) is
  * recorded — so allow-always adoption is queryable.
  */
 export interface ToolApprovalResolvedAttrs {
     "gen_ai.tool.name": string;
-    /** `allow-once` | `allow-always` | `deny` | `timeout`. */
+    /** `allow-once` | `allow-always` | `deny` | `timeout` | `cancelled`. */
     "senpi.tool_approval.decision": string;
     /** `"true"` for a state-changing tool; `"false"` for a read gated only in `all` mode. */
     "senpi.tool.is_trade": string;
+    /**
+     * Milliseconds from the gate's `requireApproval` to the resolution; 0 when
+     * the gate cancelled the call itself. A no-route or no-surface `cancelled`
+     * lands within milliseconds, a user abort after the user's wait.
+     */
+    "senpi.tool_approval.wait_ms"?: number;
+    /** The turn's session key (the span convention for a session). Absent when the hook gave none. */
+    "gen_ai.conversation.id"?: string;
+    /**
+     * The turn's kind, from the run's host trigger: `chat` (trigger `user`),
+     * `cron`, `heartbeat`, `other` (`memory`, `manual`, `overflow`) or
+     * `unknown` (the run was not seen at prompt build).
+     */
+    "senpi.turn.kind"?: string;
+    /**
+     * Set when the runtime cancelled the call itself, before asking:
+     * `scheduled_turn` (a gated call in a cron or heartbeat turn on 10.x, D13).
+     */
+    "senpi.tool_approval.cancel_reason"?: string;
 }
 /**
  * The MCP tool approval gate's fail-open catch fired — a money-safety gate momentarily disengaged and
@@ -785,7 +818,7 @@ export interface ToolApprovalGateErrorAttrs {
     "error.type"?: string;
 }
 /**
- * Shared shape for the eight `auto_update.*` plugin self-update lifecycle events — one poll's version
+ * Shared shape for the twelve `auto_update.*` plugin self-update lifecycle events — one poll's version
  * check, the resulting notify/apply/restart transitions, and their failure modes. Fired by
  * {@link AutoUpdateCoordinator}, outside any signal/trading flow, so these carry no `senpi.strategy.*`
  * identity (the plugin process, not a strategy, is the subject). Free-text (a thrown error's message
@@ -807,11 +840,24 @@ export interface AutoUpdateAvailableAttrs {
     "senpi.auto_update.latest_version": string;
     "senpi.auto_update.update_type": string;
 }
-/** The package install succeeded and a gateway restart was requested. */
+/**
+ * The update took effect. On an OpenClaw 5.x host this fires when the in-process install succeeded
+ * and the restart was requested (the historical meaning). On a 10.x host it fires on the first boot
+ * whose loaded version reaches the target, since nothing is installed until the wrapper consumes
+ * the marker; `restart_mode` is then `restart-to-apply`.
+ */
 export interface AutoUpdateAppliedAttrs {
     "senpi.auto_update.from_version": string;
     "senpi.auto_update.to_version": string;
     "senpi.auto_update.restart_mode": string;
+    /** 10.x only: ISO time the restart that applied the update was requested. */
+    "senpi.auto_update.requested_at"?: string;
+    /** 10.x only, when known: ISO time the target version was first seen in this pending episode. */
+    "senpi.auto_update.first_seen_at"?: string;
+    /** 10.x only: ms from the restart request to this boot's reconcile (stop + wrapper install + start). */
+    "senpi.auto_update.apply_ms"?: number;
+    /** 10.x only, when known: ms from first seen to this boot's reconcile (spread + idle wait + apply). */
+    "senpi.auto_update.pending_ms"?: number;
 }
 /** An already-applied version is still waiting on the gateway restart that was requested for it. */
 export interface AutoUpdateAwaitingRestartAttrs {
@@ -841,6 +887,72 @@ export interface AutoUpdateRestartFailedAttrs {
 export interface AutoUpdateDegradedAttrs {
     "senpi.auto_update.reason": string;
 }
+/**
+ * OpenClaw 10.x only: the install marker for `to_version` was written and the gateway restart was
+ * requested through `mutateConfigFile`. The wrapper installs the version before the next gateway
+ * spawn; `auto_update.applied` follows on that boot.
+ */
+export interface AutoUpdateRestartRequestedAttrs {
+    "senpi.auto_update.from_version": string;
+    "senpi.auto_update.to_version": string;
+    /** Always `restart-to-apply`. */
+    "senpi.auto_update.restart_mode": string;
+    /** True when the box was busy and the 24 h deferral cap forced the restart in the quiet window. */
+    "senpi.auto_update.forced": boolean;
+    /** Only when `forced`: the idle-gate blockers the forced restart overrode, sorted, comma-joined. */
+    "senpi.auto_update.blockers"?: string;
+}
+/**
+ * A requested update did not load: more than 30 min after the restart request (or with no request
+ * time on record) the loaded version is still below `to_version`. The awaiting-restart state is
+ * dropped and the next tick starts over, instead of trusting the persisted applied version forever.
+ */
+export interface AutoUpdateApplyFailedAttrs {
+    "senpi.auto_update.to_version": string;
+    "senpi.auto_update.loaded_version": string;
+}
+/**
+ * OpenClaw 10.x only: one runtime install outcome the senpi-agent wrapper recorded in
+ * `senpi-state/runtime-update-results.json` (`install-results.ts`), reported by the gateway that
+ * starts next. Each attribute mirrors one entry field and is absent when the entry had none.
+ */
+export interface AutoUpdateInstallResultAttrs {
+    /** `marker` (the install before a gateway spawn) or `floor` (the boot-time `SENPI_RUNTIME_MIN_VERSION` check). */
+    "senpi.auto_update.source"?: string;
+    /** `updated` | `failed` | `timeout` | `not-newer` | `invalid` | `lease-skip` | `still-below`. */
+    "senpi.auto_update.outcome": string;
+    /** The npm spec the wrapper installed or refused to install. */
+    "senpi.auto_update.spec"?: string;
+    /** Installed version before the step. */
+    "senpi.auto_update.from_version"?: string;
+    /** Installed version read back after the install. */
+    "senpi.auto_update.to_version"?: string;
+    /** The marker's target version, or the floor minimum. */
+    "senpi.auto_update.target_version"?: string;
+    /** Run time of the `openclaw plugins update` CLI call; absent when none ran. */
+    "senpi.auto_update.duration_ms"?: number;
+    /** Why the step did not update: the first line, at most 300 chars. Absent on success. */
+    "senpi.auto_update.reason"?: string;
+    /** ISO time the wrapper's step ended (the entry's `at`). */
+    "senpi.auto_update.ended_at"?: string;
+    /** The entry id, the de-duplication key. */
+    "senpi.auto_update.result_id"?: string;
+    /** OpenClaw version of the image the wrapper ran. */
+    "senpi.auto_update.openclaw_version"?: string;
+}
+/**
+ * OpenClaw 10.x only: a newer version is waiting (`pending-idle:<v>`). Fired when the box enters
+ * the wait and again only when the target or the blocker set changes, not on every re-check.
+ */
+export interface AutoUpdateDeferredAttrs {
+    "senpi.auto_update.to_version": string;
+    /** Sorted, comma-joined: `spread` (waiting for `eligible_at`), else the idle-gate blockers. */
+    "senpi.auto_update.blockers": string;
+    /** ISO time the box may first apply (first seen + spread offset + jitter). */
+    "senpi.auto_update.eligible_at"?: string;
+    /** ISO time the version was first seen in this pending episode. */
+    "senpi.auto_update.first_seen_at"?: string;
+}
 /**
  * What the skill router did with one eligible user turn (`skill_router.decision.outcome`):
  * - `classified`: the endpoint answered; `injected` says whether a pointer went in.