wave-agent-sdk 1.2.0 → 1.3.0

package/dist/exec/catalog.js

@@ -0,0 +1,470 @@
+import { EXEC_RESERVED_NAMESPACE } from "./constants.js";
+/**
+ * Recursion ceiling for signature rendering. Object, array and union recursion all
+ * increment depth, so this bounds every path: a pathological or structurally cyclic
+ * schema degrades to `unknown` instead of overflowing the stack. Rendering must
+ * never throw.
+ *
+ * This is the *only* silent reduction left in the renderer — there is deliberately
+ * no cap on properties per level or on enum variants. A wide schema or a long enum
+ * is decision-relevant text, and truncating it is how the model ends up guessing
+ * which parameter or which variant to use. Depth 8 and `unknown` are opencode's
+ * values (`tool-schema.ts`, `MAX_RENDER_DEPTH`).
+ */
+const MAX_SIGNATURE_DEPTH = 8;
+/** Cap a rendered *tool* description at one line of this length. */
+const MAX_DESCRIPTION_CHARS = 120;
+/** A property name that can be written bare in TypeScript. */
+const IDENTIFIER_SEGMENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+ * Budget accounting for the catalog, in estimated tokens.
+ *
+ * Applied to a whole catalog entry, which is a multi-line block: its newlines
+ * and indentation are part of `text.length`, so `chars / 4` already covers them.
+ *
+ * A plain `chars / 4`, same basis as opencode's `catalogBudget`. Deliberately
+ * not the CJK-aware `utils/tokenEstimate`: MCP tool descriptions are
+ * overwhelmingly English, so telling CJK from Latin text would not move the
+ * result in practice.
+ */
+const estimateCatalogTokens = (text) => Math.round(text.length / 4);
+/**
+ * Every MCP tool the current agent may call, in catalog form.
+ *
+ * Derived from `getMcpToolsConfig()` — the exact source that produces the flat
+ * `tools[]` declarations when the pool is not collapsed, and the one whose
+ * connected/reconnecting filtering already keeps a transient disconnect from
+ * churning the tool list. So "the catalog equals what would have been declared"
+ * holds structurally, not by parallel construction.
+ */
+export function buildExecPool(mcpManager, permissionManager) {
+    const outputSchemas = mcpManager.getMcpToolOutputSchemas();
+    const entries = [];
+    for (const tool of mcpManager.getMcpToolsConfig()) {
+        if (permissionManager?.isToolDenied(tool.function.name))
+            continue;
+        entries.push({
+            name: tool.function.name,
+            description: tool.function.description,
+            inputSchema: tool.function.parameters,
+            outputSchema: outputSchemas.get(tool.function.name),
+        });
+    }
+    return entries;
+}
+/** Render an object key, quoting names that are not valid identifiers. */
+function renderKey(name) {
+    return IDENTIFIER_SEGMENT.test(name) ? name : JSON.stringify(name);
+}
+/**
+ * The property path the sandbox exposes a tool under. Non-identifier names use
+ * bracket form because `tools.mcp__my-srv__x` would parse as a subtraction.
+ */
+function toolExpression(name) {
+    return IDENTIFIER_SEGMENT.test(name)
+        ? `tools.${name}`
+        : `tools[${JSON.stringify(name)}]`;
+}
+/**
+ * Trim a *tool* description to its first line and cap its length.
+ *
+ * Only tool-level prose is compressed here: it is padding that the model does not
+ * need to act, and the full text stays reachable through search. Field descriptions
+ * are never clamped (see `jsdoc`) — those carry the decision guidance.
+ */
+function clampDescription(text) {
+    const first = text.split("\n")[0].trim();
+    return first.length > MAX_DESCRIPTION_CHARS
+        ? `${first.slice(0, MAX_DESCRIPTION_CHARS - 3)}...`
+        : first;
+}
+/**
+ * JSDoc tags for a field. Only keywords that survive `cleanSchema` are
+ * supported; anything else (`minimum`, `pattern`, `title`, ...) is dropped.
+ */
+function docTags(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return [];
+    const typed = schema;
+    const tags = [];
+    if (typed.deprecated === true)
+        tags.push("@deprecated");
+    if (typed.default !== undefined) {
+        const rendered = JSON.stringify(typed.default);
+        if (rendered !== undefined)
+            tags.push(`@default ${rendered}`);
+    }
+    if (typeof typed.format === "string")
+        tags.push(`@format ${typed.format}`);
+    if (typeof typed.minItems === "number") {
+        tags.push(`@minItems ${typed.minItems}`);
+    }
+    if (typeof typed.maxItems === "number") {
+        tags.push(`@maxItems ${typed.maxItems}`);
+    }
+    return tags;
+}
+/**
+ * The JSDoc block rendered above one field, indented to `pad`. Emits nothing
+ * when the field has neither a description nor a tag, so plain fields stay
+ * unadorned.
+ *
+ * The description is kept verbatim — multi-line included, no width cap. A field
+ * description says what to put in the field ("which of these variants, and why"),
+ * so cutting it at a fixed column cuts the guidance and keeps the preamble. Only
+ * the tool's own description is clamped (see `clampDescription`); when a model
+ * needs that one in full it searches the pool by name.
+ */
+function jsdoc(schema, pad) {
+    const description = schema && typeof schema === "object" && !Array.isArray(schema)
+        ? schema.description
+        : undefined;
+    const raw = [
+        ...(typeof description === "string" ? description.split("\n") : []),
+        ...docTags(schema),
+    ]
+        // A `*/` inside third-party text would close the comment early. Split/join
+        // rather than `replaceAll`: these packages compile against lib ES2020.
+        .map((line) => line.split("*/").join("* /").replace(/\s+$/, ""));
+    while (raw.length > 0 && raw[0].trim() === "")
+        raw.shift();
+    while (raw.length > 0 && raw[raw.length - 1].trim() === "")
+        raw.pop();
+    if (raw.length === 0)
+        return "";
+    if (raw.length === 1)
+        return `${pad}/** ${raw[0]} */\n`;
+    const body = raw
+        .map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`)
+        .join("\n");
+    return `${pad}/**\n${body}\n${pad} */\n`;
+}
+/**
+ * Render a JSON Schema as TypeScript: a multi-line block whose fields each carry
+ * their own JSDoc. Only recursion depth is capped; properties and enum variants
+ * are rendered in full.
+ */
+function renderType(schema, depth) {
+    if (depth > MAX_SIGNATURE_DEPTH)
+        return "unknown";
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return "unknown";
+    }
+    const typed = schema;
+    if (Array.isArray(typed.enum)) {
+        return typed.enum
+            .map((value) => JSON.stringify(value) ?? "null")
+            .join(" | ");
+    }
+    const union = Array.isArray(typed.anyOf)
+        ? typed.anyOf
+        : Array.isArray(typed.oneOf)
+            ? typed.oneOf
+            : undefined;
+    if (union) {
+        // No cap on branches, for the reason there is none on properties or enum
+        // variants: a union is a list of choices, and showing the first few is how
+        // the model ends up using a branch that does not exist. opencode's renderer,
+        // whose depth ceiling this one borrows, renders every member too.
+        return union.map((variant) => renderType(variant, depth + 1)).join(" | ");
+    }
+    if (Array.isArray(typed.type)) {
+        const names = typed.type.filter((value) => typeof value === "string");
+        if (names.length > 0)
+            return names.join(" | ");
+        return "unknown";
+    }
+    if (typed.type === "array" || typed.items) {
+        return `Array<${renderType(typed.items, depth + 1)}>`;
+    }
+    if (typed.type === "object" || typed.properties) {
+        const properties = (typed.properties ?? {});
+        const required = new Set(Array.isArray(typed.required) ? typed.required : []);
+        const keys = Object.keys(properties);
+        if (keys.length === 0)
+            return "{}";
+        const pad = "  ".repeat(depth + 1);
+        const close = "  ".repeat(depth);
+        const lines = keys.map((key) => `${jsdoc(properties[key], pad)}${pad}${renderKey(key)}${required.has(key) ? "" : "?"}: ${renderType(properties[key], depth + 1)},`);
+        return `{\n${lines.join("\n")}\n${close}}`;
+    }
+    return typeof typed.type === "string" ? typed.type : "unknown";
+}
+/**
+ * The callable signature for one tool: parameters and return type. The catalog and
+ * search results share it, so the model can copy either one verbatim.
+ *
+ * The return type comes from the schema the server declared for its output, and a
+ * tool that declared none still gets `Promise<unknown>` rather than no return type
+ * at all: the sandbox resolves every call to the tool's output (its structured
+ * content, else its text, else `null`), and a signature ending at the parameters
+ * would read as "calls this, get nothing". Rendering it from the same rule the
+ * runtime applies is what keeps the catalog from teaching a shape the host will
+ * not deliver.
+ */
+export function renderToolSignature(entry) {
+    return `${toolExpression(entry.name)}(${renderType(entry.inputSchema, 0)}): Promise<${renderType(entry.outputSchema, 0)}>`;
+}
+/**
+ * The path the sandbox exposes search under. Built from the reserved namespace
+ * (the sandbox builds it the same way), so prose and runtime cannot drift.
+ */
+const SEARCH_EXPRESSION = `tools[${JSON.stringify(EXEC_RESERVED_NAMESPACE)}].search`;
+/**
+ * Input schema of the sandbox's `search` entry point.
+ *
+ * Load-bearing: the call form in the tool description, the call form in error
+ * messages and the validation `resolveSearchQuery` runs all come from this object.
+ * The description asked for the object form while the host only accepted a
+ * positional string, and nothing in the code tied the two together — one object
+ * makes that class of drift impossible rather than unlikely.
+ */
+const SEARCH_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Substring matched against tool names and descriptions, case-insensitively. Omit it (or pass an empty string) to list the entire pool.",
+        },
+    },
+};
+/**
+ * Output schema of the sandbox's `search` entry point.
+ *
+ * The same role `SEARCH_INPUT_SCHEMA` plays at the other end of the call: the
+ * return type in the rendered signature and the value the host actually hands back
+ * both come from this one object, so "what a hit looks like" cannot drift between
+ * the prose and the runtime. It also keeps the sandbox API uniform — every call
+ * resolves to its output, so nothing hands back a JSON *string* to parse.
+ */
+const SEARCH_OUTPUT_SCHEMA = {
+    type: "array",
+    items: {
+        type: "object",
+        properties: {
+            name: { type: "string" },
+            description: { type: "string" },
+            signature: { type: "string" },
+        },
+        required: ["name", "signature"],
+    },
+};
+const SEARCH_INPUT_KEYS = Object.keys(SEARCH_INPUT_SCHEMA.properties);
+/** A type-shaped placeholder for a field, used by the one-line call form. */
+function placeholderFor(schema) {
+    const type = schema && typeof schema === "object" && !Array.isArray(schema)
+        ? schema.type
+        : undefined;
+    switch (type) {
+        case "string":
+            return '"..."';
+        case "number":
+        case "integer":
+            return "0";
+        case "boolean":
+            return "false";
+        case "array":
+            return "[]";
+        case "object":
+            return "{}";
+        default:
+            return "...";
+    }
+}
+/**
+ * The callable signature of search, rendered by the very function that renders
+ * every catalog entry, so its shape cannot drift from what the host accepts or
+ * returns. Multi-line, for the sandbox API blurb where there is room to show the
+ * field docs.
+ */
+export function renderSearchSignature() {
+    return `${SEARCH_EXPRESSION}(${renderType(SEARCH_INPUT_SCHEMA, 0)}): Promise<${renderType(SEARCH_OUTPUT_SCHEMA, 0)}>`;
+}
+/**
+ * The one-line call form of search: the path plus a placeholder per field, all
+ * derived from `SEARCH_INPUT_SCHEMA`. For prose that cannot afford the multi-line
+ * block — the catalog's `PARTIAL` notice and error messages, which must still name
+ * a shape the host accepts.
+ */
+export function renderSearchCallForm() {
+    const properties = SEARCH_INPUT_SCHEMA.properties;
+    const fields = Object.keys(properties)
+        .map((key) => `${renderKey(key)}: ${placeholderFor(properties[key])}`)
+        .join(", ");
+    return `${SEARCH_EXPRESSION}({ ${fields} })`;
+}
+/**
+ * Validate a search call's arguments against `SEARCH_INPUT_SCHEMA` and return the
+ * query to match on.
+ *
+ * The sandbox only guarantees a plain object (see `callHost`); it knows nothing
+ * about this schema, so a call naming a field the schema does not have must fail
+ * loudly here. Treating `{ q: "..." }` as an empty query would answer "here is the
+ * whole pool" and dress a typo up as a successful search.
+ */
+export function resolveSearchQuery(args) {
+    const unexpected = Object.keys(args).find((key) => !SEARCH_INPUT_KEYS.includes(key));
+    if (unexpected !== undefined) {
+        throw new Error(`search() does not take "${unexpected}". Expected ${renderSearchCallForm()}`);
+    }
+    const query = args.query;
+    if (query === undefined)
+        return "";
+    if (typeof query !== "string") {
+        throw new Error(`search() expects "query" to be a string, got ${typeof query}. Expected ${renderSearchCallForm()}`);
+    }
+    return query.trim().toLowerCase();
+}
+/**
+ * A single catalog entry: its signature (possibly several lines) followed by the
+ * first line of its description.
+ */
+export function renderCatalogEntry(entry) {
+    const signature = renderToolSignature(entry);
+    const description = clampDescription(entry.description ?? "");
+    return description ? `${signature} // ${description}` : signature;
+}
+/**
+ * The one-line index of a server: `- mcp__github (40 tools, 13 shown)`. The tail
+ * is dropped when the server is fully shown, and reads `none shown` when it got
+ * no seat at all.
+ *
+ * The prefix is the flattened name's, not the routing key alone, so the line is a
+ * substring of every tool name it covers (and of what search matches on). For a
+ * server whose name itself contains `__` the key is only the first segment — the
+ * same pre-existing ambiguity the grouping key has (see `execNamespace`).
+ *
+ * Exported for the announcement's per-namespace delta lines: the same renderer for
+ * the same counts, so a summary line and a delta line cannot drift apart.
+ */
+export function summarizeNamespace(name, count, shownCount) {
+    const label = `${count} tool${count === 1 ? "" : "s"}`;
+    const detail = shownCount === count
+        ? ""
+        : shownCount === 0
+            ? ", none shown"
+            : `, ${shownCount} shown`;
+    return `- mcp__${name} (${label}${detail})`;
+}
+/**
+ * The server a flat MCP tool name routes to. Mirrors the split `executeMcpTool`
+ * does on the way back (`parts[1]`), so a group key always agrees with where a
+ * call would actually go — including its behaviour for server names that
+ * themselves contain `__`.
+ */
+function execNamespace(name) {
+    return name.split("__")[1] ?? name;
+}
+/**
+ * Cheapest rendered block first, ties broken by tool name.
+ *
+ * The rotation takes each server's next unshown entry every round, so this order
+ * *is* the seat order: cheapest-first means one budget buys the most entries, and
+ * the tie-break keeps the result a pure function of the entries themselves — the
+ * order `tools/list` happened to return is not a reason to seat one tool first.
+ * opencode ranks its listings the same way (`rankListings`: cost, then path).
+ */
+function orderByCost(group) {
+    return [...group].sort((left, right) => {
+        const delta = estimateCatalogTokens(renderCatalogEntry(left)) -
+            estimateCatalogTokens(renderCatalogEntry(right));
+        if (delta !== 0)
+            return delta;
+        return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+    });
+}
+/** Groups in order of first appearance; within a group, cheapest block first. */
+function groupByNamespace(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const namespace = execNamespace(entry.name);
+        const group = groups.get(namespace);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            groups.set(namespace, [entry]);
+        }
+    }
+    return [...groups.values()].map(orderByCost);
+}
+/**
+ * Render the catalog within an estimated-token budget.
+ *
+ * Selection round-robins across servers: one entry per server per round, so
+ * every server gets a seat before any server gets its second. A plain first-N
+ * cut would drop whole servers that happen to be connected later, and the model
+ * reads a missing server as "those tools do not exist" — the failure mode this
+ * whole feature has to avoid.
+ *
+ * An entry is a whole multi-line block and is budgeted and placed atomically: a
+ * server either gets the block this round or sits the round out, never half a
+ * signature.
+ *
+ * A truncated catalog additionally prints one summary line per server (see
+ * `summarizeNamespace`), before that server's blocks and outside the budget.
+ *
+ * The truncation notice deliberately carries no budget number: the budget is a
+ * tuning knob, and rendering it would make an unchanged tool pool produce
+ * different model-visible text after a config change.
+ */
+export function renderCatalog(entries, budgetTokens) {
+    const groups = groupByNamespace(entries);
+    const picked = groups.map(() => []);
+    let used = 0;
+    let shown = 0;
+    let active = groups.map((_, index) => index);
+    while (active.length > 0) {
+        const stillActive = [];
+        for (const index of active) {
+            const group = groups[index];
+            const entry = group[picked[index].length];
+            if (entry === undefined)
+                continue;
+            const block = renderCatalogEntry(entry);
+            const cost = estimateCatalogTokens(block) + 1;
+            // The very first entry is always shown even if it alone is over budget:
+            // an empty catalog would be worse than an over-budget one.
+            if (shown > 0 && used + cost > budgetTokens)
+                continue;
+            picked[index].push(block);
+            used += cost;
+            shown += 1;
+            if (picked[index].length < group.length)
+                stillActive.push(index);
+        }
+        active = stillActive;
+    }
+    const truncated = shown < entries.length;
+    // Rotation alone cannot promise any server a seat — a group whose block does
+    // not fit the remaining budget sits the round out for good — so a truncated
+    // catalog also names every server, one line each, outside the budget. Without
+    // that line a server nobody picked is invisible, and "not in the catalog" is
+    // read as "that capability does not exist". An untruncated catalog skips them:
+    // the entries are already the index.
+    const lines = [];
+    for (let index = 0; index < groups.length; index += 1) {
+        if (truncated) {
+            const group = groups[index];
+            lines.push(summarizeNamespace(execNamespace(group[0].name), group.length, picked[index].length));
+        }
+        lines.push(...picked[index]);
+    }
+    if (truncated) {
+        // Counts only: the call form that reaches the rest is taught once, in the
+        // announcement's search section, which exists in exactly this state. Writing it
+        // here as well would give the same call two spellings to drift between.
+        lines.push(`PARTIAL — ${shown} of ${entries.length} tools shown.`);
+    }
+    return {
+        text: lines.join("\n"),
+        shown,
+        total: entries.length,
+        truncated,
+        namespaces: groups.map((group, index) => ({
+            name: execNamespace(group[0].name),
+            count: group.length,
+            shown: picked[index].length,
+        })),
+    };
+}

package/dist/exec/catalogAnnouncement.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The MCP catalog, announced in the conversation instead of the `Exec` tool
+ * description. opencode only made this move on its v2 line (v1 shipped the catalog
+ * inside `execute`'s description, which is what this repo did until now).
+ *
+ * Why it cannot stay in the description: `tools[]` sits inside the cached prefix,
+ * and the catalog is a function of the pool. Every server that connects, drops, or
+ * changes its `tools/list` would rewrite the declaration and take the whole cached
+ * prefix with it. The description is a pool-independent constant now; the catalog is
+ * appended at the tail, where an addition invalidates nothing that already went out.
+ *
+ * State lives in the history, not in the process (same rule as
+ * `utils/mcpInstructions.ts`): each announcement leads with a marker line carrying
+ * the hash of a full catalog body. Three consequences, all deliberate:
+ *  - Once the marker is gone (compaction, rewind), the next turn announces the full
+ *    catalog again. A duplicate is better than a loss.
+ *  - A delta is only emitted while the full catalog it is relative to is still in
+ *    the history. The marker carries that baseline's hash (`bh`) so the check stays
+ *    local: a delta is relative, and without its basis it says nothing.
+ *  - The hash covers rendered text, so editing the renderer re-announces the catalog
+ *    once for existing sessions. That is what buys the invariant "same hash ⇒ the
+ *    same bytes the model read". It is also why a full catalog carries no "this
+ *    supersedes the previous one" preamble: such a line would depend on history, and
+ *    a history-dependent body can never compare equal to a freshly rendered one —
+ *    the session would re-announce on every single turn.
+ */
+import type { Message } from "../types/messaging.js";
+import type { RenderedCatalog } from "./catalog.js";
+/** Marks an announcement so the history scan can find it. */
+export declare const EXEC_CATALOG_MARKER_PREFIX = "<!-- exec-catalog ";
+export declare const EXEC_CATALOG_MARKER_SUFFIX = " -->";
+/** Which body a marker leads. */
+type ExecCatalogAnnouncementKind = "full" | "delta" | "removed";
+/**
+ * A marker's payload: what a later turn needs to *compare* against, never the body
+ * itself. The body is the message the marker leads.
+ */
+export interface ExecCatalogMarker {
+    kind: ExecCatalogAnnouncementKind;
+    /**
+     * Hash of the full catalog body as of this announcement — for a delta too, where
+     * it is the hash of what a full catalog would say right now. That is what lets the
+     * next turn (whose pool has not moved on since) recognise the delta as current and
+     * stay silent.
+     */
+    hash?: string;
+    /** 1 when the catalog was truncated at that moment. */
+    truncated?: number;
+    /** Namespace → how many tools it held. The only material a delta can be built from. */
+    namespaces?: Record<string, number>;
+    /** Delta only: the hash of the full catalog this delta is relative to. */
+    base?: string;
+}
+/** What the history says: its last announcement, and every full catalog hash in it. */
+export interface ExecCatalogState {
+    last: ExecCatalogMarker | null;
+    fullHashes: Set<string>;
+}
+/**
+ * A full catalog body: the header, the rendered entries, and — only when the budget
+ * truncated them — how to reach the rest.
+ *
+ * The search section is the single place the call form is taught (the entry point
+ * stays registered either way, it is merely not advertised). Making it conditional
+ * is what keeps the two statements from drifting: while the catalog is complete,
+ * nothing anywhere claims a search is needed.
+ */
+export declare function renderFullCatalogNote(catalog: RenderedCatalog): string;
+/**
+ * Read the announcement state out of the history.
+ *
+ * Only this module's own messages are read: a marker quoted anywhere else — a reply
+ * explaining the mechanism, a hook echoing one — is prose *about* a marker, not a
+ * statement about the pool. Counting it would invent an announcement, and the
+ * invented state then misleads every later turn. A marker that cannot be parsed is
+ * skipped for the same reason (worst case: one duplicate announcement).
+ */
+export declare function collectExecCatalogState(messages: Message[]): ExecCatalogState;
+/**
+ * The next announcement for this turn, or null when there is nothing to say.
+ *
+ * The decision table, in order: a channel that was never open says nothing; a closed
+ * channel is announced once; a session that has announced nothing (or whose last word
+ * was the closing notice) gets the full catalog; an unchanged hash says nothing; a
+ * changed pool with its basis still present may go out as a namespace-level delta;
+ * anything else is the full catalog.
+ */
+export declare function buildExecCatalogAnnouncement(state: ExecCatalogState, current: RenderedCatalog | undefined): string | null;
+export {};