@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/codemode/index.js

@@ -0,0 +1,31 @@
+/**
+ * The `codemode` tool as an extension. The CLI loads it as a built-in extension; SDK users
+ * add `createCodemodeExtension()` to their extension factories.
+ *
+ * `codemode` is registered inactive. Activate it with `--tools`, the `defaultTools` setting, or
+ * `setActiveTools()`; the MCP extension activates it when MCP tools are only reachable from scripts.
+ */
+import { createCodemodeToolDefinition } from "./tool.js";
+function readMode(pi) {
+    return pi.getSettings().codemode?.mode === "only" ? "only" : "on";
+}
+function readInlineBudget(pi) {
+    const budget = pi.getSettings().codemode?.inlineBudget;
+    return typeof budget === "number" && Number.isFinite(budget) && budget >= 0 ? budget : undefined;
+}
+export function createCodemodeExtension(options = {}) {
+    return (pi) => {
+        pi.registerTool({
+            ...createCodemodeToolDefinition({
+                appendEntry: (customType, data) => pi.appendEntry(customType, data),
+                models: options.models ?? true,
+                getToolNamespace: (name) => pi.getAllTools().find((tool) => tool.name === name)?.namespace,
+                getToolGuidelines: () => new Map(pi.getAllTools().map((tool) => [tool.name, tool.promptGuidelines ?? []])),
+                getMode: () => options.mode ?? readMode(pi),
+                getInlineBudget: () => options.inlineBudget ?? readInlineBudget(pi),
+            }),
+            defaultActive: false,
+        });
+    };
+}
+export default createCodemodeExtension();

package/dist/extensions/codemode/renderer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Presentation for the codemode tool.
+ *
+ * The call shows the script; the result lists the nested tool calls with their status as they
+ * run and the cost of its model calls, followed by the script output without the "Script completed"
+ * header. Nested calls are not
+ * separate tool rows because they never reach the model as tool calls.
+ */
+import type { ToolDefinition } from "../../core/extensions/types.ts";
+import type { CodemodeToolDetails } from "./tool.ts";
+export declare const codemodeRenderers: Pick<ToolDefinition<any, CodemodeToolDetails | undefined>, "renderCall" | "renderResult">;

package/dist/extensions/codemode/renderer.js

@@ -0,0 +1,136 @@
+/**
+ * Presentation for the codemode tool.
+ *
+ * The call shows the script; the result lists the nested tool calls with their status as they
+ * run and the cost of its model calls, followed by the script output without the "Script completed"
+ * header. Nested calls are not
+ * separate tool rows because they never reach the model as tool calls.
+ */
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { getTextOutput, replaceTabs, str } from "../../core/tools/render-utils.js";
+import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
+import { VisualLinePreview } from "../../modes/interactive/components/visual-truncate.js";
+import { highlightCode } from "../../modes/interactive/theme/theme.js";
+const CODE_PREVIEW_LINES = 10;
+const CALL_PREVIEW_COUNT = 8;
+const OUTPUT_PREVIEW_LINES = 5;
+const COLLAPSED_ARGS_CHARS = 80;
+const SCRIPT_HEADER = /^Script (completed|failed)\nWall time [\d.]+ seconds\nOutput:\n$/;
+function expandHint(theme, hidden, noun) {
+    return `${theme.fg("muted", `... (${hidden} more ${noun},`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+}
+function formatDuration(ms) {
+    if (ms === undefined)
+        return "";
+    return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/** Cents for larger amounts, two significant digits for the fractions of a cent classifier calls cost. */
+function formatCost(cost) {
+    return `$${cost >= 0.01 ? cost.toFixed(2) : cost.toPrecision(2)}`;
+}
+function statusIcon(call, theme) {
+    switch (call.status) {
+        case "running":
+            return theme.fg("warning", "…");
+        case "ok":
+            return theme.fg("success", "✓");
+        case "error":
+            return theme.fg("error", "✗");
+        case "cancelled":
+            return theme.fg("muted", "⊘");
+    }
+}
+function formatCall(call, theme, expanded) {
+    const args = !expanded && call.args.length > COLLAPSED_ARGS_CHARS
+        ? `${call.args.slice(0, COLLAPSED_ARGS_CHARS - 3)}...`
+        : call.args;
+    const duration = formatDuration(call.durationMs);
+    let line = `${statusIcon(call, theme)} ${theme.fg("toolTitle", call.name)}`;
+    if (args)
+        line += ` ${theme.fg("muted", args)}`;
+    if (duration)
+        line += ` ${theme.fg("dim", duration)}`;
+    if (call.cost)
+        line += ` ${theme.fg("dim", formatCost(call.cost))}`;
+    if (expanded && call.error)
+        line += `\n    ${theme.fg("error", call.error.split("\n").join("\n    "))}`;
+    return line;
+}
+export const codemodeRenderers = {
+    renderCall(args, theme, context) {
+        // The code includes the `// @options:` line, so options show as part of the script.
+        const code = str(args?.code);
+        const title = theme.fg("toolTitle", theme.bold("codemode"));
+        const component = context.lastComponent ?? new Container();
+        component.clear();
+        if (code === null) {
+            component.addChild(new Text(`${title} ${theme.fg("error", "[invalid arg]")}`, 0, 0));
+            return component;
+        }
+        component.addChild(new Text(title, 0, 0));
+        if (code) {
+            const highlighted = highlightCode(replaceTabs(code.replace(/\r/g, "").trimEnd()), "javascript").join("\n");
+            component.addChild(context.expanded
+                ? new Text(highlighted, 0, 0)
+                : new VisualLinePreview({
+                    text: highlighted,
+                    maxVisualLines: CODE_PREVIEW_LINES,
+                    keep: "start",
+                    formatHint: (hidden) => expandHint(theme, hidden, "lines"),
+                }));
+        }
+        return component;
+    },
+    renderResult(result, options, theme, context) {
+        const component = context.lastComponent ?? new Container();
+        component.clear();
+        const calls = result.details?.calls ?? [];
+        if (calls.length > 0) {
+            const shown = options.expanded ? calls : calls.slice(-CALL_PREVIEW_COUNT);
+            const lines = shown.map((call) => formatCall(call, theme, options.expanded));
+            if (shown.length < calls.length) {
+                lines.unshift(`${theme.fg("muted", `... (${calls.length - shown.length} earlier calls,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`);
+            }
+            // Collapsed rows hide earlier calls, so the total covers every call.
+            const priced = calls.filter((call) => call.cost);
+            if (priced.length > 1) {
+                const total = priced.reduce((sum, call) => sum + (call.cost ?? 0), 0);
+                lines.push(theme.fg("muted", `Model calls: ${formatCost(total)}`));
+            }
+            component.addChild(new Spacer(1));
+            component.addChild(new Text(lines.join("\n"), 0, 0));
+        }
+        // Drop the "Script completed\nWall time ...\nOutput:\n" header. Rejected input (invalid options)
+        // has no header.
+        const [first, ...rest] = result.content;
+        const hasHeader = first?.type === "text" && SCRIPT_HEADER.test(first.text);
+        const output = options.isPartial
+            ? ""
+            : getTextOutput({ ...result, content: hasHeader ? rest : result.content }, context.showImages).trim();
+        if (output) {
+            const color = context.isError ? "error" : "toolOutput";
+            const styled = replaceTabs(output)
+                .split("\n")
+                .map((line) => theme.fg(color, line))
+                .join("\n");
+            component.addChild(new Spacer(1));
+            if (options.expanded) {
+                component.addChild(new Text(styled, 0, 0));
+            }
+            else {
+                // Limit wrapped lines, not logical ones: script output is often one long JSON line.
+                component.addChild(new VisualLinePreview({
+                    text: styled,
+                    maxVisualLines: OUTPUT_PREVIEW_LINES,
+                    keep: "start",
+                    formatHint: (hidden) => expandHint(theme, hidden, "lines"),
+                }));
+                // The collapsed preview hides the truncation notice at the end, so name the file here.
+                const fullOutputPath = result.details?.fullOutputPath;
+                if (fullOutputPath)
+                    component.addChild(new Text(theme.fg("muted", `Full output: ${fullOutputPath}`), 0, 0));
+            }
+        }
+        return component;
+    },
+};

package/dist/extensions/codemode/tool.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The `codemode` tool: the model writes JavaScript that calls other tools. Scripts use `tools`,
+ * `ALL_TOOLS`, `text()`, `image()`, `exit()`, `store()`/`load()`, `console.*`, and `return <value>`,
+ * may start with a `// @options:` line, and reach the model catalog, classifiers, and image models
+ * through `models.*`. Results start with a "Script completed" or "Script failed" header.
+ *
+ * Scripts can call the agent loop's nested tools: active `direct` tools and every `codemode` or
+ * `deferred` tool. Nested calls run through the agent loop's tool pipeline (`ctx.executeTool`), so
+ * validation, `tool_call`/`tool_result` hooks, and permission checks apply exactly as for direct
+ * calls. Only the script's output reaches the model; nested results do not.
+ *
+ * Nested results are handed to the script as follows:
+ * - A tool that declares `outputSchema` resolves to its `structuredContent`, also for error
+ *   results that carry one (MCP tools resolve to their `CallToolResult`, including `isError`).
+ * - Any other tool resolves to its text content as one string.
+ * - A failed, blocked, or invalid call rejects with an Error carrying the tool's error text.
+ *
+ * A script that fails returns a normal error result that keeps its partial output, followed by
+ * "Script error:" and the error. `store(key, value)` and `load(key)` keep JSON values across
+ * calls; successful scripts append their writes to the session as `codemode-store` custom entries,
+ * so each branch sees the values written on its own path.
+ */
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { CodemodeTool } from "@earendil-works/pi-codemode";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition, ToolInfo, ToolNamespace } from "../../core/extensions/types.ts";
+import type { ModelRegistry } from "../../core/model-registry.ts";
+import type { CodemodeMode } from "../../core/settings-manager.ts";
+export declare const CODEMODE_TOOL_NAME = "codemode";
+/** Custom entry type holding one script's `store()` writes: {@link CodemodeStoreEntryData}. */
+export declare const CODEMODE_STORE_ENTRY_TYPE = "codemode-store";
+export interface CodemodeStoreEntryData {
+    set: Record<string, unknown>;
+    delete: string[];
+}
+/** The part of the model registry that scripts reach through `models`. */
+export type CodemodeModelRuntime = Pick<ModelRegistry, "getModelsOfType" | "getAvailableOfType" | "getModelOfType" | "classify" | "generateImages">;
+export interface CodemodeToolOptions {
+    /** Namespace of a tool, for `searchTools()` ranking and its `namespace` filter. */
+    getToolNamespace?: (toolName: string) => ToolNamespace | undefined;
+    /** Prompt guidelines of every tool, by tool name, shown with declarations by `describeTool()` and `ALL_TOOLS`. */
+    getToolGuidelines?: () => ReadonlyMap<string, readonly string[]>;
+    /**
+     * Expose the `models` namespace to scripts, backed by the session's model registry
+     * (`ctx.modelRegistry`). Without it, `models` is not declared.
+     */
+    models?: boolean;
+    /**
+     * Persists `store()` writes as a session custom entry. Without it, writes last only for the
+     * current script; `load()` still reads entries already on the branch.
+     */
+    appendEntry?: (customType: string, data: CodemodeStoreEntryData) => void;
+    /** How the tool presents the loadout while active (the `codemode.mode` setting). Default: `on`. */
+    getMode?: () => CodemodeMode;
+    /** Token budget for tool declarations in the description. Default: {@link DEFAULT_CODEMODE_INLINE_BUDGET}. */
+    getInlineBudget?: () => number | undefined;
+}
+export declare const codemodeSchema: Type.TObject<{
+    code: Type.TString;
+}>;
+export type CodemodeToolInput = Static<typeof codemodeSchema>;
+/**
+ * Whether a registered tool is this package's `codemode` tool rather than another extension's tool
+ * with the same name. Compares the parameter schema, which the definition passes through by reference.
+ */
+export declare function isCodemodeTool(tool: Pick<ToolInfo, "name" | "parameters">): boolean;
+export type CodemodeNestedCallStatus = "running" | "ok" | "error" | "cancelled";
+export interface CodemodeNestedCall {
+    /** Tool call id of the nested call, `<codemode call id>/<n>`. */
+    id: string;
+    name: string;
+    /** Compact JSON of the arguments, truncated for display. */
+    args: string;
+    status: CodemodeNestedCallStatus;
+    durationMs?: number;
+    /** Error text, truncated for display. */
+    error?: string;
+    /** Cost in USD of a `models.*` call that reported usage. */
+    cost?: number;
+}
+export interface CodemodeToolDetails {
+    calls: CodemodeNestedCall[];
+    /** Temp file with the full text output, when the output was truncated. */
+    fullOutputPath?: string;
+}
+export declare const codemodeToolSystemPromptContribution: {
+    readonly snippet: "Run JavaScript that calls other tools";
+    readonly guidelines: readonly ["Use codemode to batch independent tool calls (Promise.allSettled), chain them, or filter large output, instead of many separate calls."];
+};
+/** The reference for scripts: globals, tool results, `store()`, the `models` API, and limits. */
+export declare const CODEMODE_DOCS_PATH: string;
+/** Default for {@link CodemodeDescriptionOptions.inlineBudget}, in estimated tokens. */
+export declare const DEFAULT_CODEMODE_INLINE_BUDGET = 3000;
+/**
+ * What a script sees of a tool: its description followed by its prompt guidelines, which the system
+ * prompt only has for declared tools. Tools without an output schema resolve to their text output.
+ */
+export declare function toCodemodeDeclaration(tool: AgentTool<any>, guidelines?: readonly string[]): Omit<CodemodeTool, "execute">;
+/** Tools a script may call: every given tool except the codemode tool itself. */
+export declare function getCodemodeCallableTools(tools: readonly AgentTool<any>[]): AgentTool<any>[];
+export interface CodemodeDescriptionOptions {
+    /** Declare the `models` namespace; only for tools created with model access. */
+    models?: boolean;
+    /** Namespace of each tool, by tool name. Tools of one namespace are listed under one heading. */
+    namespaces?: ReadonlyMap<string, ToolNamespace>;
+    /** Tools that are callable but never listed with their declaration (`deferred` exposure). */
+    deferred?: ReadonlySet<string>;
+    /** Prompt guidelines of each tool, by tool name, listed after its description. */
+    guidelines?: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Estimated tokens (characters / 4) the tool sections may use. Tools that do not fit are left
+     * out, like deferred tools. Unset lists every tool that is not deferred.
+     */
+    inlineBudget?: number;
+}
+/**
+ * Model-facing description: the helper list, guidance for finding tools that are not listed, the
+ * shared MCP types when listed tools need them, the `models` API, and one section per listed tool,
+ * grouped by namespace. Deferred tools are never listed and do not affect the description at all, so
+ * it stays the same while MCP servers connect or change their tools. Tool sections are limited to
+ * `inlineBudget`.
+ */
+export declare function createCodemodeDescription(tools: readonly AgentTool<any>[], options?: CodemodeDescriptionOptions): string;
+export declare function createCodemodeToolDefinition(options?: CodemodeToolOptions): ToolDefinition<typeof codemodeSchema, CodemodeToolDetails | undefined>;
+/**
+ * Create the codemode tool as an AgentTool. The description lists the given tools; the script can
+ * call whatever tools the agent loop provides at execution time.
+ */
+export declare function createCodemodeTool(tools?: readonly AgentTool<any>[], options?: CodemodeToolOptions): AgentTool<typeof codemodeSchema>;

package/dist/extensions/codemode/tool.js

@@ -0,0 +1,275 @@
+/**
+ * The `codemode` tool: the model writes JavaScript that calls other tools. Scripts use `tools`,
+ * `ALL_TOOLS`, `text()`, `image()`, `exit()`, `store()`/`load()`, `console.*`, and `return <value>`,
+ * may start with a `// @options:` line, and reach the model catalog, classifiers, and image models
+ * through `models.*`. Results start with a "Script completed" or "Script failed" header.
+ *
+ * Scripts can call the agent loop's nested tools: active `direct` tools and every `codemode` or
+ * `deferred` tool. Nested calls run through the agent loop's tool pipeline (`ctx.executeTool`), so
+ * validation, `tool_call`/`tool_result` hooks, and permission checks apply exactly as for direct
+ * calls. Only the script's output reaches the model; nested results do not.
+ *
+ * Nested results are handed to the script as follows:
+ * - A tool that declares `outputSchema` resolves to its `structuredContent`, also for error
+ *   results that carry one (MCP tools resolve to their `CallToolResult`, including `isError`).
+ * - Any other tool resolves to its text content as one string.
+ * - A failed, blocked, or invalid call rejects with an Error carrying the tool's error text.
+ *
+ * A script that fails returns a normal error result that keeps its partial output, followed by
+ * "Script error:" and the error. `store(key, value)` and `load(key)` keep JSON values across
+ * calls; successful scripts append their writes to the session as `codemode-store` custom entries,
+ * so each branch sees the values written on its own path.
+ */
+import { join } from "node:path";
+import { MCP_TYPESCRIPT_PREAMBLE, mcpStructuredContentSchema, renderToolOutputType, renderToolSample, toCodemodeIdentifier, } from "@earendil-works/pi-codemode/declarations";
+import { CODEMODE_SOURCE_GRAMMAR } from "@earendil-works/pi-codemode/source";
+import { Type } from "typebox";
+import { getDocsPath } from "../../config.js";
+import { wrapToolDefinition } from "../../core/tools/tool-definition-wrapper.js";
+import { loadCodemodeExecutor } from "./execute.lazy.js";
+import { codemodeRenderers } from "./renderer.js";
+export const CODEMODE_TOOL_NAME = "codemode";
+/** Custom entry type holding one script's `store()` writes: {@link CodemodeStoreEntryData}. */
+export const CODEMODE_STORE_ENTRY_TYPE = "codemode-store";
+const TEXT_OUTPUT_SCHEMA = { type: "string" };
+export const codemodeSchema = Type.Object({
+    code: Type.String({
+        description: "Raw JavaScript source.",
+    }),
+});
+/**
+ * Whether a registered tool is this package's `codemode` tool rather than another extension's tool
+ * with the same name. Compares the parameter schema, which the definition passes through by reference.
+ */
+export function isCodemodeTool(tool) {
+    return tool.name === CODEMODE_TOOL_NAME && tool.parameters === codemodeSchema;
+}
+export const codemodeToolSystemPromptContribution = {
+    snippet: "Run JavaScript that calls other tools",
+    guidelines: [
+        "Use codemode to batch independent tool calls (Promise.allSettled), chain them, or filter large output, instead of many separate calls.",
+    ],
+};
+/** The reference for scripts: globals, tool results, `store()`, the `models` API, and limits. */
+export const CODEMODE_DOCS_PATH = join(getDocsPath(), "codemode.md");
+const DESCRIPTION_INTRO = `Run JavaScript that calls other tools. The input is raw JavaScript (not JSON, no code fence), run as an async function body in a QuickJS sandbox: top-level \`await\` and \`return\` work. No Node, file system, network, or timers.
+- \`await tools.<name>({ ...args })\` resolves to a string, or an object if the tool's declaration says so, and rejects with an Error on failure. Calls still running when the script ends are cancelled.
+- Optional first line: \`// @options: {"max_output_tokens": 10000, "timeout_ms": 60000}\``;
+/** One line per global. The details live in {@link CODEMODE_DOCS_PATH}. */
+function describeGlobals(models) {
+    const lines = [
+        "Globals:",
+        "- `text(value)`, `image(dataUrlOrImageBlock)`, `console.log(...)`, and top-level `return` add output; `exit()` ends the script. With several text items, each starts with a `==> text N/M <==` line, and `console` lines follow the other output in one `<console_output>` block. `image()` also saves the image to a temp file and the result names its path.",
+        "- `store(key, value)` and `load(key)` keep JSON values across codemode calls.",
+        "- `ALL_TOOLS`, `await searchTools(query, { limit?, namespace? })`, `await describeTool(name)`, `await describeNamespace(name)`: find unlisted tools, such as MCP tools.",
+    ];
+    if (models) {
+        lines.push(`- \`models\`: classifiers and image generation. Read ${CODEMODE_DOCS_PATH} first.`);
+    }
+    return lines.join("\n");
+}
+/** Default for {@link CodemodeDescriptionOptions.inlineBudget}, in estimated tokens. */
+export const DEFAULT_CODEMODE_INLINE_BUDGET = 3000;
+/** Characters per token when estimating the cost of a tool section. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * What a script sees of a tool: its description followed by its prompt guidelines, which the system
+ * prompt only has for declared tools. Tools without an output schema resolve to their text output.
+ */
+export function toCodemodeDeclaration(tool, guidelines = []) {
+    const bullets = guidelines.flatMap((guideline) => (guideline.trim() ? [`- ${guideline.trim()}`] : []));
+    return {
+        name: tool.name,
+        description: bullets.length > 0 ? `${tool.description.trim()}\n\n${bullets.join("\n")}` : tool.description,
+        inputSchema: tool.parameters,
+        outputSchema: tool.outputSchema ?? TEXT_OUTPUT_SCHEMA,
+    };
+}
+/** Tools a script may call: every given tool except the codemode tool itself. */
+export function getCodemodeCallableTools(tools) {
+    return tools.filter((tool) => tool.name !== CODEMODE_TOOL_NAME);
+}
+/** `### \`id\` (\`raw name\`)` followed by the tool's description and declaration. */
+function renderToolSection(declaration) {
+    const id = toCodemodeIdentifier(declaration.name);
+    const heading = id === declaration.name ? `### \`${id}\`` : `### \`${id}\` (\`${declaration.name}\`)`;
+    return `${heading}\n${renderToolSample(declaration).trim()}`;
+}
+/**
+ * Pick the tool sections that fit the budget, like OpenCode's catalog: in each round every group
+ * (tools without a namespace first, then namespaces by name) places its cheapest remaining tool; a
+ * group whose next tool does not fit drops out while the others continue. Every namespace is
+ * represented before any namespace is complete.
+ */
+function selectCatalog(groups, budget) {
+    if (budget === undefined)
+        return new Set(groups.flatMap((group) => group.entries.map((entry) => entry.name)));
+    const queues = groups.map((group) => [...group.entries].sort((a, b) => a.cost - b.cost));
+    const shown = new Set();
+    let remaining = budget;
+    let active = queues.filter((queue) => queue.length > 0);
+    while (active.length > 0) {
+        active = active.filter((queue) => {
+            const next = queue[0];
+            if (next.cost > remaining)
+                return false;
+            remaining -= next.cost;
+            shown.add(next.name);
+            queue.shift();
+            return queue.length > 0;
+        });
+    }
+    return shown;
+}
+/**
+ * Model-facing description: the helper list, guidance for finding tools that are not listed, the
+ * shared MCP types when listed tools need them, the `models` API, and one section per listed tool,
+ * grouped by namespace. Deferred tools are never listed and do not affect the description at all, so
+ * it stays the same while MCP servers connect or change their tools. Tool sections are limited to
+ * `inlineBudget`.
+ */
+export function createCodemodeDescription(tools, options = {}) {
+    const declarations = getCodemodeCallableTools(tools)
+        .filter((tool) => !options.deferred?.has(tool.name))
+        .map((tool) => toCodemodeDeclaration(tool, options.guidelines?.get(tool.name)));
+    const groups = new Map([["", { namespace: undefined, entries: [] }]]);
+    for (const declaration of declarations) {
+        const namespace = options.namespaces?.get(declaration.name);
+        const key = namespace ? `ns:${namespace.name}` : "";
+        const group = groups.get(key) ?? { namespace, entries: [] };
+        groups.set(key, group);
+        const section = renderToolSection(declaration);
+        group.entries.push({ name: declaration.name, section, cost: Math.ceil(section.length / CHARS_PER_TOKEN) });
+    }
+    const ordered = [...groups.values()].sort((a, b) => a.namespace === undefined ? -1 : b.namespace === undefined ? 1 : a.namespace.name.localeCompare(b.namespace.name));
+    const shown = selectCatalog(ordered, options.inlineBudget);
+    const sections = [DESCRIPTION_INTRO, describeGlobals(options.models === true)];
+    if (declarations.some((declaration) => shown.has(declaration.name) && mcpStructuredContentSchema(declaration.outputSchema) !== undefined)) {
+        sections.push(`Shared MCP Types:\n\`\`\`ts\n${MCP_TYPESCRIPT_PREAMBLE}\n\`\`\``);
+    }
+    if (declarations.length === 0)
+        return sections.join("\n\n");
+    const toolSections = ["Nested tools:"];
+    for (const { namespace, entries } of ordered) {
+        const visible = entries.filter((entry) => shown.has(entry.name));
+        if (namespace) {
+            // Only tools that did not fit the budget are counted as not listed here.
+            const listing = visible.length === entries.length
+                ? ""
+                : visible.length === 0
+                    ? " (tools not listed)"
+                    : " (some tools not listed)";
+            const description = namespace.description?.trim();
+            toolSections.push(`## ${namespace.name}${listing}${description ? `\n${description}` : ""}`);
+        }
+        for (const entry of visible)
+            toolSections.push(entry.section);
+    }
+    sections.push(toolSections.join("\n\n"));
+    return sections.join("\n\n");
+}
+/**
+ * What a script call resolves to, in one line: `a string`, the field names of an object
+ * (`{ output, exit_code, full_output_path? }`), or the rendered type for anything else.
+ */
+function describeOutput(schema) {
+    const type = renderToolOutputType(schema);
+    if (type === "string")
+        return "a string";
+    const object = typeof schema === "object" ? schema : undefined;
+    const properties = object?.properties;
+    if (object?.type === "object" &&
+        typeof properties === "object" &&
+        properties !== null &&
+        mcpStructuredContentSchema(schema) === undefined) {
+        const required = new Set(Array.isArray(object.required) ? object.required : []);
+        const fields = Object.keys(properties).map((name) => (required.has(name) ? name : `${name}?`));
+        return `\`{ ${fields.join(", ")} }\``;
+    }
+    return `\`${type.replace(/\s+/g, " ")}\``;
+}
+/**
+ * A declared tool's description followed by how scripts call it and what the call resolves to. The
+ * arguments are the tool's declared parameters, so they are not repeated.
+ */
+function describeScriptCall(tool) {
+    return `${tool.description.trim()}\n\nCodemode: \`tools.${toCodemodeIdentifier(tool.name)}(args)\` resolves to ${describeOutput(toCodemodeDeclaration(tool).outputSchema)}.`;
+}
+/**
+ * How the codemode tool presents tools that are both declared and callable from scripts:
+ * - `on`: their descriptions say how scripts call them, and the codemode description
+ *   lists only the callable tools without `direct` exposure.
+ * - `only`: the codemode description lists every callable tool, and requests leave out the
+ *   declarations of active `direct` tools.
+ *
+ * Listed tools carry their prompt guidelines, which the system prompt only has for declared tools.
+ *
+ * Listing by exposure, not by the active set, keeps the codemode description unchanged when
+ * `tool_search` loads a tool, so loads do not redeclare codemode.
+ */
+function prepareCodemodeLoadout(loadout, options) {
+    const mode = options.getMode?.() ?? "on";
+    const isDirect = (tool) => loadout.getExposure(tool.name) === "direct";
+    const callable = getCodemodeCallableTools(loadout.callable);
+    const callableNames = new Set(callable.map((tool) => tool.name));
+    const descriptions = {};
+    if (mode === "on") {
+        for (const tool of loadout.declared) {
+            if (callableNames.has(tool.name))
+                descriptions[tool.name] = describeScriptCall(tool);
+        }
+    }
+    const listed = mode === "only" ? callable : callable.filter((tool) => !isDirect(tool));
+    const namespaces = new Map(listed.flatMap((tool) => {
+        const namespace = loadout.getNamespace(tool.name);
+        return namespace ? [[tool.name, namespace]] : [];
+    }));
+    const guidelines = new Map(listed.map((tool) => [tool.name, loadout.getPromptGuidelines(tool.name)]));
+    descriptions[CODEMODE_TOOL_NAME] = createCodemodeDescription(listed, {
+        models: options.models === true,
+        namespaces,
+        guidelines,
+        deferred: new Set(listed.filter((tool) => loadout.getExposure(tool.name) === "deferred").map((tool) => tool.name)),
+        inlineBudget: options.getInlineBudget?.() ?? DEFAULT_CODEMODE_INLINE_BUDGET,
+    });
+    const declaredNames = new Set(loadout.declared.map((tool) => tool.name));
+    return {
+        descriptions,
+        hiddenDeclarations: mode === "only"
+            ? callable.filter((tool) => isDirect(tool) && declaredNames.has(tool.name)).map((tool) => tool.name)
+            : [],
+    };
+}
+export function createCodemodeToolDefinition(options = {}) {
+    return {
+        name: CODEMODE_TOOL_NAME,
+        label: CODEMODE_TOOL_NAME,
+        // Replaced with the declarations of the callable tools when the tool is activated.
+        description: createCodemodeDescription([], { models: options.models === true }),
+        promptSnippet: codemodeToolSystemPromptContribution.snippet,
+        promptGuidelines: [...codemodeToolSystemPromptContribution.guidelines],
+        parameters: codemodeSchema,
+        // Scripts must not start other scripts.
+        exposure: "model-only",
+        prepareLoadout: (loadout) => prepareCodemodeLoadout(loadout, options),
+        // Capable models write the script as raw text instead of a JSON-escaped string.
+        constrainedSampling: { type: "grammar", variants: { openai_lark: CODEMODE_SOURCE_GRAMMAR } },
+        // The sandbox (worker, QuickJS wasm) loads on the first call, not at startup.
+        execute: async (toolCallId, params, signal, onUpdate, ctx) => (await loadCodemodeExecutor()).executeCodemode(toolCallId, params, signal, onUpdate, ctx, options),
+        ...codemodeRenderers,
+    };
+}
+/**
+ * Create the codemode tool as an AgentTool. The description lists the given tools; the script can
+ * call whatever tools the agent loop provides at execution time.
+ */
+export function createCodemodeTool(tools = [], options = {}) {
+    const definition = createCodemodeToolDefinition(options);
+    const tool = wrapToolDefinition(definition);
+    Object.assign(tool, {
+        description: createCodemodeDescription(tools, { models: options.models === true }),
+        promptSnippet: definition.promptSnippet,
+        promptGuidelines: definition.promptGuidelines,
+    });
+    return tool;
+}

package/dist/extensions/context-compaction-reminder.ts

@@ -2,7 +2,7 @@ import type { ExtensionAPI } from "@selesai/code";
 
 export const CONTEXT_COMPACTION_REMINDER_THRESHOLD = 128_000;
 export const CONTEXT_COMPACTION_REMINDER_MESSAGE =
-	`Conversation context has reached ${CONTEXT_COMPACTION_REMINDER_THRESHOLD.toLocaleString()} tokens. Run /handoff-new to summarize into a new chat, or enable Auto Handoff in Settings to do this automatically. Bigger context windows eat up tokens quickly and degrade AI quality.`;
+	`Conversation context has reached ${CONTEXT_COMPACTION_REMINDER_THRESHOLD.toLocaleString()} tokens. Run /handoff-new to summarize into a new chat, or /compact to reduce context in this session. Bigger context windows eat up tokens quickly and degrade AI quality.`;
 
 export default function contextCompactionReminderExtension(pi: ExtensionAPI): void {
 	let reminderShown = false;

package/dist/extensions/grep-app/index.ts

@@ -141,11 +141,7 @@ export default function grepAppExtension(pi: ExtensionAPI): void {
 		label: "grep.app Search",
 		description: "Search public GitHub code through grep.app. Returns one page (up to 10 files); use page to continue.",
 		promptSnippet: "Search public GitHub code through grep.app",
-		discovery: {
-			summary: "Search public GitHub code through grep.app",
-			aliases: ["github code search", "public code search", "grep.app"],
-			category: "web",
-		},
+		exposure: "deferred",
 		promptGuidelines: ["Use grep_app_search to find real public-code implementations and usage examples across GitHub."],
 		parameters: Type.Object({
 			query: Type.String({ minLength: 1, description: "Code or pattern to search for." }),
@@ -188,11 +184,7 @@ export default function grepAppExtension(pi: ExtensionAPI): void {
 		label: "GitHub File",
 		description: "Fetch a public GitHub file found via grep.app. Supports line ranges; output is truncated to 50KB or 2000 lines.",
 		promptSnippet: "Fetch a public GitHub file found via grep.app",
-		discovery: {
-			summary: "Fetch a public GitHub file found through grep.app",
-			aliases: ["github file", "fetch github file"],
-			category: "web",
-		},
+		exposure: "deferred",
 		promptGuidelines: ["Use grep_app_fetch after grep_app_search when the full source context is needed."],
 		parameters: Type.Object({
 			repo: Type.String({ pattern: "^[^/\\s]+/[^/\\s]+$", description: "owner/repository." }),

package/dist/extensions/herdr-agent-state.ts

@@ -7,7 +7,7 @@
 // Instance state lives inside the factory, not at module scope. Selesai caches
 // the extension module per cwd and re-invokes the factory for every session, so
 // a module-scoped `released`/`queuedState`/`sendInFlight` from a previous
-// session (handoff-new, auto-handoff, /new, resume, fork, reload) would make
+// session (handoff-new, /new, resume, fork, reload) would make
 // every successor instance silently drop its state reports and leave the pane
 // stuck on the last reported state. Only the monotonic reportSeq stays
 // module-level: Herdr guards pane.report_agent per source by seq and drops

package/dist/extensions/{pi-subagents/test/fixtures/pi-coding-agent-shim/dist/extensions/index.d.ts → index.d.ts}

@@ -1,3 +1,2 @@
 import type { InlineExtension } from "../core/extensions/types.ts";
 export declare const builtInExtensions: InlineExtension[];
-//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.js

@@ -0,0 +1,12 @@
+import codemodeExtension from "./codemode/index.js";
+import llamaExtension from "./llama/index.js";
+import mcpExtension from "./mcp/index.js";
+import toolSearchExtension from "./tool-search/index.js";
+export const builtInExtensions = [
+    { name: "llama.cpp", factory: llamaExtension, builtin: true },
+    // Replaceable: an extension that registers `codemode`, `tool_search`, or `/mcp` (such as a third-party
+    // MCP extension) takes over instead of running alongside the built-in one.
+    { name: "codemode", factory: codemodeExtension, replaceable: true, builtin: true },
+    { name: "tool-search", factory: toolSearchExtension, replaceable: true, builtin: true },
+    { name: "mcp", factory: mcpExtension, replaceable: true, builtin: true },
+];