@alisio/core 0.5.2 → 0.6.0

package/dist/forge/broker.js

@@ -0,0 +1,244 @@
+/**
+ * The capability broker (spec §4.2, §6.4): the kernel's side of the guest's messages. A script sees
+ * proxy functions; every real decision happens here, with the numbers the HOST keeps:
+ *
+ *  - nested calls go through the run's nested-call dispatcher (the same gate as a direct call, no
+ *    new approvals, D7/D-24), paced by the `BudgetLedger` (total, concurrent, credits);
+ *  - sizes, output and state are bounded again no matter what the prelude checked;
+ *  - every nested call is journaled and reported as `ForgeProgress`.
+ *
+ * Errors that mean "the guest broke a limit" are thrown as `ForgeError`: the engine ends the
+ * execution with that code. Errors of one tool call are answered to the guest as `ok: false`.
+ */
+import { createHash } from "node:crypto";
+import { describeTool, searchCatalog } from "./catalog-view.js";
+import { ForgeError } from "./errors.js";
+import { clipText } from "./result.js";
+/** Maximum catalog lookups per execution; they are cheap but not free. */
+export const MAX_CATALOG_REQUESTS = 200;
+/** Progress messages one execution may report; the rest is dropped (counted, not stored). */
+export const MAX_PROGRESS_MESSAGES = 10_000;
+/** Characters of one progress message the host keeps. */
+export const MAX_PROGRESS_CHARS = 500;
+/** Bytes of state operations one execution may queue (the commit enforces the stored total). */
+export const MAX_STATE_DELTA_BYTES = 1024 * 1024;
+const DENIED = new Set(["PERMISSION_DENIED", "APPROVAL_REQUIRED"]);
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const positionOf = (nestedCallId) => Number(nestedCallId.slice(nestedCallId.lastIndexOf(":") + 1));
+export class CapabilityBroker {
+    #deps;
+    #now;
+    output = [];
+    stats = { total: 0, failed: 0, denied: 0 };
+    #inflight = new Set();
+    #send = () => { };
+    /** Progress messages dropped past `MAX_PROGRESS_MESSAGES` (reported in the journal metrics). */
+    progressDropped = 0;
+    #progressSeen = 0;
+    #catalogRequests = 0;
+    #stateBytes = 0;
+    constructor(deps) {
+        this.#deps = deps;
+        this.#now = deps.now ?? Date.now;
+    }
+    bind(send) {
+        this.#send = send;
+    }
+    /** Resolves when every call the guest started has finished (or the timeout passed). */
+    async drain(timeoutMs) {
+        if (this.#inflight.size === 0)
+            return;
+        await Promise.race([
+            Promise.allSettled([...this.#inflight]),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs).unref?.()),
+        ]);
+    }
+    async receive(message) {
+        switch (message.type) {
+            case "ready":
+                return { type: "grant", payload: this.#deps.ledger.grant() };
+            case "progress": {
+                if (++this.#progressSeen > MAX_PROGRESS_MESSAGES) {
+                    if (this.progressDropped++ === 0)
+                        this.#deps.log(`progress: more than ${MAX_PROGRESS_MESSAGES} messages; the rest is dropped`);
+                    return undefined;
+                }
+                const text = clipText(message.payload.message, MAX_PROGRESS_CHARS).text;
+                this.#deps.log(`progress: ${text}`);
+                this.#deps.update({
+                    kind: "forge",
+                    executionId: this.#deps.executionId,
+                    engine: this.#deps.engine,
+                    phase: "running",
+                    message: text,
+                    ...(message.payload.completed !== undefined
+                        ? { completed: message.payload.completed }
+                        : {}),
+                    ...(message.payload.total !== undefined ? { total: message.payload.total } : {}),
+                });
+                return undefined;
+            }
+            case "output":
+                this.#recordOutput(message.payload);
+                return undefined;
+            case "state.set":
+                this.#state().set(message.payload.key, message.payload.value);
+                this.#countState(message.payload.key, message.payload.value);
+                return undefined;
+            case "state.delete":
+                this.#state().delete(message.payload.key);
+                this.#countState(message.payload.key, null);
+                return undefined;
+            case "catalog":
+                return this.#catalog(message.payload);
+            case "call": {
+                // Not awaited by the engine's dispatch: calls of one script run concurrently.
+                const job = this.#call(message.payload);
+                this.#inflight.add(job);
+                const settled = () => this.#inflight.delete(job);
+                job.then(settled, settled);
+                await job;
+                return undefined;
+            }
+            default:
+                return undefined;
+        }
+    }
+    #state() {
+        const state = this.#deps.state;
+        if (!state)
+            throw new ForgeError("INVALID_INPUT", "stored state is switched off (forge.state.enabled)");
+        return state;
+    }
+    #countState(key, value) {
+        this.#stateBytes += key.length + JSON.stringify(value).length;
+        if (this.#stateBytes > MAX_STATE_DELTA_BYTES)
+            throw new ForgeError("BUDGET_EXCEEDED", "this execution changed too much stored state");
+    }
+    #recordOutput(item) {
+        const bytes = Buffer.byteLength(JSON.stringify(item), "utf8");
+        this.#deps.ledger.recordOutput(bytes);
+        this.output.push(item);
+        if (item.type === "text")
+            this.#deps.log(item.text.replace(/\n$/, ""));
+    }
+    #catalog(payload) {
+        if (++this.#catalogRequests > MAX_CATALOG_REQUESTS)
+            throw new ForgeError("BUDGET_EXCEEDED", `catalog lookups are limited to ${MAX_CATALOG_REQUESTS} per execution`);
+        const tools = this.#deps.dispatcher.catalog();
+        const entries = payload.op === "search"
+            ? searchCatalog(tools, payload.query, payload.limit)
+            : [describeTool(tools, payload.query)].filter((entry) => entry !== undefined);
+        return { type: "catalog.result", payload: { requestId: payload.requestId, entries } };
+    }
+    async #call(payload) {
+        const { ledger, journal, executionId, limits } = this.#deps;
+        // Only names the registry has are ever recorded or broadcast; anything else is a placeholder.
+        const tool = this.#deps.dispatcher.knows(payload.tool)
+            ? payload.tool
+            : `unknown:${sha256(payload.tool).slice(0, 12)}`;
+        // The host's own count: a call without a credit, or past the total, ends the execution.
+        ledger.startCall();
+        this.stats.total++;
+        const startedAt = this.#now();
+        const progress = (status, extra = {}) => ({
+            kind: "forge",
+            executionId,
+            engine: this.#deps.engine,
+            phase: "call",
+            call: { callId: payload.callId, tool, status, ...extra },
+        });
+        let journalId;
+        let ended = false;
+        const end = (status, errorCode) => {
+            if (journalId && !ended) {
+                ended = true;
+                journal.endCall(executionId, journalId, {
+                    status,
+                    durationMs: this.#now() - startedAt,
+                    ...(errorCode ? { errorCode } : {}),
+                });
+            }
+        };
+        let reply;
+        try {
+            const inputJson = JSON.stringify(payload.input ?? {});
+            if (Buffer.byteLength(inputJson, "utf8") > limits.maxCallInputBytes) {
+                reply = this.#error(payload.callId, "TOOL_INPUT_INVALID", `tool input is larger than ${limits.maxCallInputBytes} bytes`);
+                this.stats.failed++;
+                this.#deps.terminal(progress("failed"));
+            }
+            else {
+                this.#deps.log(`call ${tool}`);
+                this.#deps.update(progress("started"));
+                const outcome = await this.#deps.dispatcher.call({
+                    name: payload.tool,
+                    input: payload.input,
+                    signal: this.#deps.signal,
+                    onStart: (start) => {
+                        journalId = journal.startCall({
+                            executionId,
+                            n: positionOf(start.nestedCallId),
+                            toolName: start.name,
+                            effect: start.effect,
+                            inputSha256: sha256(inputJson),
+                            paths: start.paths,
+                        });
+                    },
+                });
+                if (outcome.ok) {
+                    const valueJson = JSON.stringify(outcome.value) ?? "null";
+                    if (Buffer.byteLength(valueJson, "utf8") > limits.maxCallResponseBytes) {
+                        reply = this.#error(payload.callId, "OUTPUT_LIMIT", `${payload.tool} returned ${Buffer.byteLength(valueJson, "utf8")} bytes, over the ${limits.maxCallResponseBytes} byte limit; ask for less (a smaller range, a filter, a page)`);
+                        this.stats.failed++;
+                        end("failed", "OUTPUT_LIMIT");
+                        this.#deps.terminal(progress("failed", { durationMs: this.#now() - startedAt }));
+                    }
+                    else {
+                        reply = {
+                            type: "result",
+                            payload: { callId: payload.callId, ok: true, value: outcome.value ?? null },
+                        };
+                        end("succeeded");
+                        this.#deps.terminal(progress("succeeded", { durationMs: this.#now() - startedAt }));
+                    }
+                }
+                else {
+                    if (!journalId) {
+                        // Refused before it started (denied, unknown, invalid): still on the record.
+                        journalId = journal.startCall({
+                            executionId,
+                            n: positionOf(outcome.nestedCallId),
+                            toolName: tool,
+                            effect: (outcome.effect ?? "external"),
+                            inputSha256: sha256(inputJson),
+                        });
+                    }
+                    const denied = DENIED.has(outcome.code);
+                    if (denied)
+                        this.stats.denied++;
+                    else
+                        this.stats.failed++;
+                    end("failed", outcome.code);
+                    this.#deps.log(`call ${tool} failed: ${outcome.code}`);
+                    this.#deps.terminal(progress(denied ? "denied" : "failed", { durationMs: this.#now() - startedAt }));
+                    reply = this.#error(payload.callId, outcome.code, outcome.message);
+                }
+            }
+        }
+        catch (error) {
+            end("failed", "TOOL_FAILED");
+            this.stats.failed++;
+            this.#deps.terminal(progress("failed", { durationMs: this.#now() - startedAt }));
+            reply = this.#error(payload.callId, "TOOL_FAILED", error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            ledger.finishCall();
+        }
+        this.#send(reply);
+        this.#send({ type: "grant", payload: ledger.grant() });
+    }
+    #error(callId, code, message) {
+        return { type: "result", payload: { callId, ok: false, error: { code, message } } };
+    }
+}

package/dist/forge/budget.d.ts

@@ -0,0 +1,27 @@
+export interface BudgetLimits {
+    maxToolCalls: number;
+    maxConcurrency: number;
+    maxRetainedOutputBytes: number;
+}
+export declare class BudgetLedger {
+    #private;
+    constructor(limits: BudgetLimits);
+    get stats(): {
+        started: number;
+        active: number;
+        outputBytes: number;
+    };
+    /**
+     * Tops the guest's credits up to what it may still use and returns the increment to send in a
+     * `grant` message. Call credits never exceed the free concurrency slots or the remaining total.
+     */
+    grant(): {
+        calls: number;
+        bytes: number;
+    };
+    /** Spends a credit for a new nested call or throws `BUDGET_EXCEEDED` without changing state. */
+    startCall(): void;
+    finishCall(): void;
+    /** Accounts output bytes, or throws `OUTPUT_LIMIT` without partial accounting. */
+    recordOutput(bytes: number): void;
+}

package/dist/forge/budget.js

@@ -0,0 +1,60 @@
+/**
+ * Per-execution budget: total and concurrent nested calls, the credits granted to the guest
+ * (backpressure, spec §5.4) and retained output bytes. The host enforces these numbers even when
+ * the guest prelude checks them too. Pure: no I/O.
+ */
+import { ForgeError } from "./errors.js";
+export class BudgetLedger {
+    #limits;
+    #started = 0;
+    #active = 0;
+    #outputBytes = 0;
+    #callCredits = 0;
+    #byteCredits = 0;
+    constructor(limits) {
+        this.#limits = limits;
+    }
+    get stats() {
+        return { started: this.#started, active: this.#active, outputBytes: this.#outputBytes };
+    }
+    /**
+     * Tops the guest's credits up to what it may still use and returns the increment to send in a
+     * `grant` message. Call credits never exceed the free concurrency slots or the remaining total.
+     */
+    grant() {
+        const callTarget = Math.max(0, Math.min(this.#limits.maxConcurrency - this.#active, this.#limits.maxToolCalls - this.#started));
+        const calls = Math.max(0, callTarget - this.#callCredits);
+        this.#callCredits += calls;
+        const bytes = this.#limits.maxRetainedOutputBytes - this.#outputBytes - this.#byteCredits;
+        this.#byteCredits += bytes;
+        return { calls, bytes };
+    }
+    /** Spends a credit for a new nested call or throws `BUDGET_EXCEEDED` without changing state. */
+    startCall() {
+        if (this.#started >= this.#limits.maxToolCalls) {
+            throw new ForgeError("BUDGET_EXCEEDED", `Tool call limit reached (${this.#limits.maxToolCalls})`);
+        }
+        if (this.#active >= this.#limits.maxConcurrency) {
+            throw new ForgeError("BUDGET_EXCEEDED", `Concurrent tool call limit reached (${this.#limits.maxConcurrency})`);
+        }
+        if (this.#callCredits <= 0) {
+            throw new ForgeError("BUDGET_EXCEEDED", "Tool call without a granted credit");
+        }
+        this.#callCredits--;
+        this.#started++;
+        this.#active++;
+    }
+    finishCall() {
+        if (this.#active <= 0)
+            throw new Error("finishCall without an active call");
+        this.#active--;
+    }
+    /** Accounts output bytes, or throws `OUTPUT_LIMIT` without partial accounting. */
+    recordOutput(bytes) {
+        if (this.#outputBytes + bytes > this.#limits.maxRetainedOutputBytes) {
+            throw new ForgeError("OUTPUT_LIMIT", `Retained output limit reached (${this.#limits.maxRetainedOutputBytes} bytes)`);
+        }
+        this.#outputBytes += bytes;
+        this.#byteCredits = Math.max(0, this.#byteCredits - bytes);
+    }
+}

package/dist/forge/catalog-view.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What `catalog.search` and `catalog.describe` show a script (spec §6.2, D13): the tools the run
+ * lets it call right now, found by name or description, never the whole prompt-sized catalog.
+ * Pure over the tool definitions.
+ */
+import type { ToolDefinition } from "@alisio/sdk";
+export declare const CATALOG_DEFAULT_LIMIT = 10;
+export declare const CATALOG_MAX_LIMIT = 25;
+export interface CatalogEntry {
+    name: string;
+    effect: string;
+    summary: string;
+}
+export interface CatalogDetail {
+    name: string;
+    effect: string;
+    description: string;
+    inputSchema: unknown;
+}
+/** The first sentence of a description, bounded. */
+export declare function summarize(description: string): string;
+/** Tools whose name or description holds every term of the query (all of them for an empty query). */
+export declare function searchCatalog(tools: readonly ToolDefinition[], query: string, limit?: number): CatalogEntry[];
+export declare function describeTool(tools: readonly ToolDefinition[], name: string): CatalogDetail | undefined;

package/dist/forge/catalog-view.js

@@ -0,0 +1,43 @@
+import { effectOf } from "../permissions/decide.js";
+export const CATALOG_DEFAULT_LIMIT = 10;
+export const CATALOG_MAX_LIMIT = 25;
+const SUMMARY_CHARS = 160;
+/** The first sentence of a description, bounded. */
+export function summarize(description) {
+    const flat = description.replace(/\s+/g, " ").trim();
+    const end = flat.search(/[.!?](\s|$)/);
+    const sentence = end >= 0 ? flat.slice(0, end + 1) : flat;
+    return sentence.length > SUMMARY_CHARS ? `${sentence.slice(0, SUMMARY_CHARS - 1)}…` : sentence;
+}
+const terms = (query) => query
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/)
+    .filter(Boolean);
+/** Tools whose name or description holds every term of the query (all of them for an empty query). */
+export function searchCatalog(tools, query, limit = CATALOG_DEFAULT_LIMIT) {
+    const wanted = terms(query);
+    const bounded = Math.max(1, Math.min(Math.floor(limit), CATALOG_MAX_LIMIT));
+    return tools
+        .filter((tool) => {
+        const haystack = `${tool.name} ${tool.description}`.toLowerCase();
+        return wanted.every((term) => haystack.includes(term));
+    })
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .slice(0, bounded)
+        .map((tool) => ({
+        name: tool.name,
+        effect: effectOf(tool),
+        summary: summarize(tool.description),
+    }));
+}
+export function describeTool(tools, name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool)
+        return undefined;
+    return {
+        name: tool.name,
+        effect: effectOf(tool),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    };
+}

package/dist/forge/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Forja error codes and the error type that carries them. Pure: no I/O. The Python specification
+ * adds its own codes with the same shape.
+ */
+export declare const FORGE_ERROR_CODES: readonly ["INVALID_INPUT", "ENGINE_UNAVAILABLE", "SCRIPT_SYNTAX", "SCRIPT_RUNTIME", "PERMISSION_DENIED", "APPROVAL_REQUIRED", "TOOL_UNAVAILABLE", "TOOL_INPUT_INVALID", "TOOL_FAILED", "BUDGET_EXCEEDED", "OUTPUT_LIMIT", "MEMORY_LIMIT", "STACK_LIMIT", "TIMEOUT", "CANCELLED", "STATE_CONFLICT", "PROTOCOL_VIOLATION", "UNRESOLVABLE_PROMISE", "ISOLATE_FAILURE", 
+/** Python: the artifact publisher refused the files the script left (symlink, size, count). */
+"PUBLICATION_REJECTED"];
+export type ForgeErrorCode = (typeof FORGE_ERROR_CODES)[number];
+/** Points the model at the guide topic that explains how to recover from an error. */
+export interface GuideHint {
+    topic: string;
+    reason: string;
+}
+/**
+ * The one-line pointer the model reads (spec §8.4): the reason and the guide topic to call, never the
+ * guide itself. An anchor (`js.patterns#filtering`) names a section of the topic.
+ */
+export declare function renderHint(hint: GuideHint): string;
+export declare class ForgeError extends Error {
+    readonly code: ForgeErrorCode;
+    readonly hint?: GuideHint;
+    constructor(code: ForgeErrorCode, message: string, options?: {
+        hint?: GuideHint;
+    });
+}
+export declare function isForgeError(value: unknown): value is ForgeError;

package/dist/forge/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Forja error codes and the error type that carries them. Pure: no I/O. The Python specification
+ * adds its own codes with the same shape.
+ */
+export const FORGE_ERROR_CODES = [
+    "INVALID_INPUT",
+    "ENGINE_UNAVAILABLE",
+    "SCRIPT_SYNTAX",
+    "SCRIPT_RUNTIME",
+    "PERMISSION_DENIED",
+    "APPROVAL_REQUIRED",
+    "TOOL_UNAVAILABLE",
+    "TOOL_INPUT_INVALID",
+    "TOOL_FAILED",
+    "BUDGET_EXCEEDED",
+    "OUTPUT_LIMIT",
+    "MEMORY_LIMIT",
+    "STACK_LIMIT",
+    "TIMEOUT",
+    "CANCELLED",
+    "STATE_CONFLICT",
+    "PROTOCOL_VIOLATION",
+    "UNRESOLVABLE_PROMISE",
+    "ISOLATE_FAILURE",
+    /** Python: the artifact publisher refused the files the script left (symlink, size, count). */
+    "PUBLICATION_REJECTED",
+];
+/**
+ * The one-line pointer the model reads (spec §8.4): the reason and the guide topic to call, never the
+ * guide itself. An anchor (`js.patterns#filtering`) names a section of the topic.
+ */
+export function renderHint(hint) {
+    const [topic = hint.topic, anchor] = hint.topic.split("#");
+    return `${hint.reason} (forge_guide topic "${topic}"${anchor ? `, section #${anchor}` : ""})`;
+}
+export class ForgeError extends Error {
+    code;
+    hint;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "ForgeError";
+        this.code = code;
+        if (options.hint)
+            this.hint = options.hint;
+    }
+}
+export function isForgeError(value) {
+    return value instanceof ForgeError;
+}

package/dist/forge/guides/javascript.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The JavaScript topics of `forge_guide` (spec §8.3): `js.api`, `js.patterns` and `js.tools`. Pure
+ * functions of the engine's live state (effective limits, host) and, for `js.tools`, of the tools
+ * a script can call right now. No I/O here; the provider gathers the state.
+ */
+import type { IsolationLevel } from "@alisio/sdk";
+import type { ForgeLimits } from "../limits.ts";
+/** What the guide needs to know about the running JavaScript engine. */
+export interface JavascriptGuideState {
+    /** Engine build, e.g. `quickjs-wasi@3.6.2`. */
+    version: string;
+    isolation: IsolationLevel;
+    host: "worker" | "process";
+    limits: ForgeLimits;
+}
+/** One line of the permission-filtered catalog summary. */
+export interface CatalogSummaryEntry {
+    name: string;
+    effect: string;
+}
+/** The most entries `js.tools` lists (spec §8.3). */
+export declare const TOOLS_GUIDE_MAX_ENTRIES = 40;
+export declare function jsApiGuide(state: JavascriptGuideState): string;
+export declare function jsPatternsGuide(state: JavascriptGuideState): string;
+export declare function jsToolsGuide(catalog: readonly CatalogSummaryEntry[] | undefined): string;

package/dist/forge/guides/javascript.js

@@ -0,0 +1,90 @@
+/** The most entries `js.tools` lists (spec §8.3). */
+export const TOOLS_GUIDE_MAX_ENTRIES = 40;
+const KiB = 1024;
+const MiB = 1024 * KiB;
+const size = (bytes) => bytes >= MiB && bytes % MiB === 0
+    ? `${bytes / MiB} MiB`
+    : bytes >= KiB
+        ? `${Math.round(bytes / KiB)} KiB`
+        : `${bytes} B`;
+const seconds = (ms) => `${Math.round((ms / 1000) * 10) / 10} s`;
+export function jsApiGuide(state) {
+    const l = state.limits;
+    const where = state.host === "worker" ? "a worker thread of this process" : "a child process of this program";
+    return [
+        `# js_run API (${state.version})`,
+        "",
+        `Isolation: ${state.isolation}. A fresh VM per run, hosted in ${where}. No imports, require, network, files, timers or WebAssembly. The body is an async function: use await and \`return\` a small JSON value.`,
+        "",
+        "## Globals",
+        "- `tools.call(name, input?)`: call another tool; resolves to its JSON result (or its text), rejects with an error that has `code` and `message`. `callTool` is the same.",
+        "- `catalog.search(query, {limit?})`: `[{name, effect, summary}]`. `catalog.describe(name)`: `{name, effect, description, inputSchema}`. Call it before using a tool you do not know.",
+        "- `state.get(key)`, `state.set(key, value)`, `state.delete(key)`: small JSON kept for later runs of this session; committed only if the run succeeds.",
+        "- `text(value)`: explicit output for the model. `progress({message, completed?, total?})`: live progress. `console.log/warn/error` go to the output too.",
+        "- `parallel.map(items, fn, {concurrency?})`: results in input order; no new item starts after the first failure and it rejects with that error. `parallel.settle(...)`: every result as `{ok:true,value}` or `{ok:false,error:{code,message}}`.",
+        "",
+        "## Effective limits now",
+        `- Time ${seconds(l.timeoutMs)} per run (\`timeoutMs\` can only lower it); heap ${size(l.memoryBytes)}; stack ${size(l.stackBytes)}; source ${size(l.maxSourceBytes)}.`,
+        `- Nested calls: ${l.maxToolCalls} per run, ${l.maxConcurrency} at once (\`Promise.all\` does not avoid this); input ${size(l.maxCallInputBytes)}, response ${size(l.maxCallResponseBytes)} each.`,
+        `- Returned to you: at most ${l.maxOutputChars} characters (\`OUTPUT_LIMIT\` beyond that); retained output ${size(l.maxRetainedOutputBytes)}.`,
+        "",
+        "## Permissions",
+        "Nested calls pass the same gate as a direct call of this session and never open an approval: a tool that needs one fails with `APPROVAL_REQUIRED`; call it directly instead. `js.tools` lists what is callable now.",
+        "",
+        "## Errors you can catch",
+        "`TOOL_UNAVAILABLE`, `TOOL_INPUT_INVALID`, `TOOL_FAILED`, `PERMISSION_DENIED`, `APPROVAL_REQUIRED`, `BUDGET_EXCEEDED`, `OUTPUT_LIMIT`. Anything else a script throws is `SCRIPT_RUNTIME`.",
+    ].join("\n");
+}
+export function jsPatternsGuide(state) {
+    const l = state.limits;
+    return [
+        "# js_run patterns",
+        "",
+        "## #filtering",
+        `Filter, aggregate or count INSIDE the script and return the result, not the data: the model sees at most ${l.maxOutputChars} characters.`,
+        "```js",
+        'const rows = await tools.call("<tool>", { /* input */ });  // check the shape with catalog.describe',
+        "const big = rows.filter((r) => r.size > 1000);",
+        "return { total: rows.length, big: big.length, sample: big.slice(0, 5) };",
+        "```",
+        "",
+        "## #parallel",
+        `Use \`parallel.map(items, fn, {concurrency: 4})\` for independent reads: up to ${l.maxConcurrency} run at once, ${l.maxToolCalls} in total. It stops at the first failure. Use \`parallel.settle\` when partial results are fine and report the failed ones.`,
+        "```js",
+        'const results = await parallel.settle(paths, (p) => tools.call("read_file", { path: p, limit: 50 }));',
+        "return results.map((r, i) => (r.ok ? { path: paths[i], ok: true } : { path: paths[i], error: r.error.code }));",
+        "```",
+        "",
+        "## #pagination",
+        "Loop until the tool says there is no more, and keep only what you need from each page. Count calls: the budget is shared by the whole run.",
+        "",
+        "## #state",
+        "`state.set('cursor', value)` survives to the next run, but only when this run succeeds. Keep it small JSON; large data belongs in a scratchpad file.",
+        "",
+        "## #files",
+        "Scripts cannot touch files. To keep a long script, write it to the scratchpad with the file tools and run it with `js_run` `codePath` (a .js file); edit it between runs instead of resending the code. Intermediate results go to scratchpad files the same way.",
+        "",
+        "## #errors",
+        "Wrap risky calls in try/catch and return `{ error: e.code }`. A script that throws ends the run; one that returns a value is a success even if some calls failed (check `calls` in the result).",
+    ].join("\n");
+}
+export function jsToolsGuide(catalog) {
+    const head = ["# Tools a script can call now", ""];
+    if (!catalog)
+        return [
+            ...head,
+            "The tool list depends on the live session and is not available here. Inside a script, `await catalog.search('')` lists what is callable and `await catalog.describe(name)` gives the schema.",
+        ].join("\n");
+    const sorted = [...catalog].sort((a, b) => a.name.localeCompare(b.name));
+    const shown = sorted.slice(0, TOOLS_GUIDE_MAX_ENTRIES);
+    const more = sorted.length - shown.length;
+    return [
+        ...head,
+        `Only tools this session's permissions allow without asking are listed (${sorted.length}). Others fail with \`APPROVAL_REQUIRED\` or \`PERMISSION_DENIED\`; call those directly.`,
+        "",
+        ...shown.map((tool) => `- ${tool.name} (${tool.effect})`),
+        ...(more > 0 ? [`- ... and ${more} more: use \`catalog.search(query)\``] : []),
+        "",
+        "Details and input schemas: `await catalog.describe(name)` inside the script. Never reachable from a script: `js_run`, `forge_guide`, `task`, `task_wait`, `send_message`, `ask_user_question`. `python_run` only when this run allows analysis or process effects.",
+    ].join("\n");
+}

package/dist/forge/guides/provider.d.ts

@@ -0,0 +1,42 @@
+import { type CatalogSummaryEntry, type JavascriptGuideState } from "./javascript.ts";
+import { type PythonEnvironment } from "./python.ts";
+export declare const JS_GUIDE_TOPICS: readonly ["js.api", "js.patterns", "js.tools"];
+export declare const PYTHON_GUIDE_TOPICS: readonly ["python.runtime", "python.data", "python.ml", "python.dashboards", "python.environment"];
+export declare const GUIDE_TOPICS: readonly ["js.api", "js.patterns", "js.tools", "python.runtime", "python.data", "python.ml", "python.dashboards", "python.environment"];
+export type GuideTopic = (typeof GUIDE_TOPICS)[number];
+/** Hard bound of one topic (spec §8.3). */
+export declare const GUIDE_MAX_BYTES = 4096;
+/** Characters of the SHA-256 kept as the etag. */
+export declare const ETAG_LENGTH = 16;
+export interface GuideSources {
+    /** Present when the JavaScript engine is ready; its absence removes the `js.*` topics. */
+    javascript?: () => Promise<JavascriptGuideState>;
+    /** Present when `python_run` is registered; its absence removes the `python.*` topics. */
+    python?: () => Promise<PythonEnvironment>;
+}
+export type GuideResponse = {
+    unchanged: true;
+    etag: string;
+} | {
+    unchanged: false;
+    topic: GuideTopic;
+    etag: string;
+    content: string;
+};
+export interface GuideRequest {
+    topic: string;
+    ifNoneMatch?: string | undefined;
+    /** The tools a script can call right now (for `js.tools`). */
+    catalog?: readonly CatalogSummaryEntry[] | undefined;
+}
+export declare class UnknownGuideTopicError extends Error {
+    constructor(topic: string, available: readonly string[]);
+}
+export declare const etagOf: (content: string) => string;
+export declare class GuideProvider {
+    #private;
+    constructor(sources: GuideSources);
+    /** The topics that exist now: the JavaScript ones with a ready engine, the Python ones with `python_run`. */
+    topics(): GuideTopic[];
+    get(request: GuideRequest): Promise<GuideResponse>;
+}