@alisio/core 0.5.1 → 0.6.0

package/dist/forge/python/wasm-node.js

@@ -0,0 +1,220 @@
+/**
+ * The `node` that runs Pyodide for the `wasm` backend (Python spec §8.2) and the facts about it:
+ * which binary (the running Node, or under Bun the first supported `node` on PATH (absolute entries only), or the configured
+ * one), the Permission Model flags it is started with, and the network self-probe (D-32). The
+ * probe starts the REAL child with the same flags and tries to connect to a local port: whether
+ * the network is denied is observed, never deduced from a version number.
+ */
+import { execFile, spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { createServer } from "node:net";
+import { delimiter, isAbsolute, join } from "node:path";
+/**
+ * The first release of each line that fixes CVE-2025-55130 (December 2025 security releases): the
+ * Permission Model could be escaped with crafted symlinks, and this backend depends on it. Lines
+ * not listed (23.x, never fixed, and everything older) are refused; newer majors are accepted.
+ * Source: https://nodejs.org/en/blog/vulnerability/december-2025-security-releases
+ */
+const FIXED_LINES = { 22: 22, 24: 13, 25: 3 };
+export const MIN_NODE = { major: 22, minor: 22 };
+const MIN_TEXT = "22.22, 24.13, 25.3 or 26+";
+const CVE_NOTE = "earlier releases have the Permission Model symlink bypass CVE-2025-55130";
+export const currentNodeEnvironment = () => ({
+    isBun: !!process.versions.bun,
+    execPath: process.execPath,
+    version: process.version,
+    pathEnv: process.env.PATH ?? "",
+    platform: process.platform,
+});
+/** `v22.22.0` -> true: at least the release of its line that fixed CVE-2025-55130. */
+export function isSupportedNode(version) {
+    const match = /^v?(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (major > 25)
+        return true;
+    const fixed = FIXED_LINES[major];
+    return fixed !== undefined && minor >= fixed;
+}
+function versionOf(binary) {
+    return new Promise((resolve) => {
+        execFile(binary, ["--version"], { timeout: 5000, env: {}, windowsHide: true }, (error, out) => resolve(error ? undefined : String(out).trim()));
+    });
+}
+const executable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const cache = new Map();
+/** Finds the node to run Pyodide with; only successes are remembered. */
+export async function resolveNode(configured, environment = currentNodeEnvironment()) {
+    const key = `${configured ?? ""}|${environment.isBun}|${environment.execPath}|${environment.pathEnv}`;
+    const hit = cache.get(key);
+    if (hit)
+        return hit;
+    const found = await (async () => {
+        if (configured) {
+            const version = await versionOf(configured);
+            if (!version)
+                return { ok: false, reason: `analysis.wasm.nodePath (${configured}) did not run` };
+            return isSupportedNode(version)
+                ? { ok: true, path: configured, version }
+                : {
+                    ok: false,
+                    reason: `analysis.wasm.nodePath is Node ${version}; Pyodide needs Node ${MIN_TEXT} (${CVE_NOTE})`,
+                };
+        }
+        if (!environment.isBun) {
+            return isSupportedNode(environment.version)
+                ? { ok: true, path: environment.execPath, version: environment.version }
+                : {
+                    ok: false,
+                    reason: `Pyodide needs Node ${MIN_TEXT} (running ${environment.version}; ${CVE_NOTE})`,
+                };
+        }
+        const names = environment.platform === "win32" ? ["node.exe"] : ["node"];
+        let seen;
+        // A relative entry (`.`, `bin`) would run whatever the current folder holds.
+        for (const dir of environment.pathEnv.split(delimiter).filter(isAbsolute)) {
+            for (const name of names) {
+                const candidate = join(dir, name);
+                if (!executable(candidate))
+                    continue;
+                const version = await versionOf(candidate);
+                if (!version)
+                    continue;
+                if (isSupportedNode(version))
+                    return { ok: true, path: candidate, version };
+                seen ??= version;
+            }
+        }
+        return {
+            ok: false,
+            reason: seen
+                ? `the only node on PATH is ${seen}; Pyodide needs Node ${MIN_TEXT} (${CVE_NOTE}; or set analysis.wasm.nodePath)`
+                : `Pyodide runs in a Node child process and no node ${MIN_TEXT} was found on PATH (install Node.js or set analysis.wasm.nodePath)`,
+        };
+    })();
+    if (found.ok)
+        cache.set(key, found);
+    return found;
+}
+/** Clears remembered resolutions and probes (tests, and a changed PATH). */
+export function resetNodeCaches() {
+    cache.clear();
+    probes.clear();
+}
+/**
+ * The flags of the restricted child: the Permission Model with ONE flag per path (a comma list is
+ * invalid in Node 22), reading only the distribution and the job, writing only `work/` and `out/`.
+ * No `--allow-child-process`, `--allow-worker`, `--allow-addons` or `--allow-wasi`; on Node >= 25
+ * `--allow-net` is likewise left out.
+ */
+export function permissionArgs(paths) {
+    return [
+        "--permission",
+        "--no-warnings",
+        ...paths.read.map((p) => `--allow-fs-read=${p}`),
+        ...paths.write.map((p) => `--allow-fs-write=${p}`),
+    ];
+}
+/** Environment of the child: nothing but the job's `ALISIO_*` variables. */
+export function childEnv(vars, platform = process.platform) {
+    const env = {};
+    for (const [key, value] of Object.entries(vars))
+        if (key.startsWith("ALISIO_"))
+            env[key] = value;
+    // Windows cannot start a process without these.
+    if (platform === "win32" && process.env.SystemRoot)
+        env.SystemRoot = process.env.SystemRoot;
+    return env;
+}
+const probes = new Map();
+const PROBE_SCRIPT = `
+import net from "node:net";
+const denied = (e) => { console.log("DENIED " + (e && e.code)); process.exit(0); };
+try {
+  const socket = net.connect(Number(process.argv[1]), "127.0.0.1");
+  socket.on("connect", () => { console.log("CONNECTED"); process.exit(0); });
+  socket.on("error", denied);
+} catch (e) { denied(e); }
+setTimeout(() => { console.log("TIMEOUT"); process.exit(0); }, 4000);
+`;
+/**
+ * Starts `node` with the real flags and tries to reach a port of ours. Remembered per binary and
+ * version (the flags do not change what the network flag does). Inconclusive means "not denied".
+ */
+export function probeNetwork(node, args) {
+    const key = `${node.path}@${node.version}`;
+    let probe = probes.get(key);
+    if (!probe) {
+        probe = runProbe(node.path, args);
+        probes.set(key, probe);
+        // Only a conclusive answer is remembered: an inconclusive one is asked again next time.
+        void probe.then((result) => {
+            if (!result.conclusive && probes.get(key) === probe)
+                probes.delete(key);
+        });
+    }
+    return probe;
+}
+async function runProbe(path, args) {
+    let hits = 0;
+    const server = createServer((socket) => {
+        hits++;
+        socket.destroy();
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", resolve);
+        });
+        const address = server.address();
+        const port = typeof address === "object" && address ? address.port : 0;
+        const output = await new Promise((resolve) => {
+            const child = spawn(path, [...args, "--input-type=module", "-e", PROBE_SCRIPT, String(port)], { env: childEnv({}), stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+            let text = "";
+            child.stdout.on("data", (chunk) => {
+                text += chunk;
+            });
+            const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+            timer.unref?.();
+            child.once("error", () => resolve(""));
+            child.once("close", () => {
+                clearTimeout(timer);
+                resolve(text.trim());
+            });
+        });
+        if (hits > 0)
+            return {
+                denied: false,
+                conclusive: true,
+                detail: "a connection to 127.0.0.1 from the child succeeded",
+            };
+        const code = /^DENIED (\S+)/.exec(output)?.[1];
+        if (code === "ERR_ACCESS_DENIED")
+            return { denied: true, conclusive: true, detail: `the Permission Model refused (${output})` };
+        return {
+            denied: false,
+            conclusive: false,
+            detail: `probe inconclusive: ${code ?? (output || "the child did not answer")}`,
+        };
+    }
+    catch (error) {
+        return {
+            denied: false,
+            conclusive: false,
+            detail: `probe inconclusive: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    finally {
+        server.close();
+    }
+}

package/dist/forge/python/wiring.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Assembly of the Python side of Forja for `python_run` (Python spec §4.1): the two backends, the
+ * two engines registered in the kernel's registry and the selector. The application hands in the
+ * kernel it shares with `js_run` (one journal, one state store, one registry); an embedder that
+ * registers the analysis tools alone gets a private kernel over the same database.
+ */
+import type { AnalysisJobs } from "../../analysis/jobs.ts";
+import { ExecutionKernel } from "../kernel.ts";
+import { EngineRegistry } from "../registry.ts";
+import type { PythonBackend, PythonBackendId } from "./backend.ts";
+import { createPythonBackendSelector } from "./backend-selector.ts";
+import { type ManagedBackendDeps } from "./managed-backend.ts";
+import { type OciBackendDeps } from "./oci-backend.ts";
+import { type PyodideBackendDeps } from "./pyodide-backend.ts";
+export interface PythonBackendOptions {
+    runtime: ManagedBackendDeps["runtime"];
+    oci?: OciBackendDeps["oci"];
+    /** The Pyodide backend; without it `wasm` is not available in this process. */
+    wasm?: PyodideBackendDeps;
+}
+/** The backends of one process, in no particular order (the selector orders them). */
+export declare function createPythonBackends(options: PythonBackendOptions): Partial<Record<PythonBackendId, PythonBackend>>;
+export interface PythonForgeOptions extends PythonBackendOptions {
+    jobs: AnalysisJobs;
+    /** The application's kernel and registry. Without them a private pair is built. */
+    shared?: {
+        kernel: ExecutionKernel;
+        engines: EngineRegistry;
+    };
+}
+export interface PythonForge {
+    kernel: ExecutionKernel;
+    engines: EngineRegistry;
+    backends: Partial<Record<PythonBackendId, PythonBackend>>;
+    selector: ReturnType<typeof createPythonBackendSelector>;
+    /** Registers the engines in the registry (once). Await it before the first execution. */
+    ready(): Promise<void>;
+}
+export declare function createPythonForge(options: PythonForgeOptions): PythonForge;

package/dist/forge/python/wiring.js

@@ -0,0 +1,47 @@
+import { SqliteExecutionJournal } from "../journal.js";
+import { ExecutionKernel } from "../kernel.js";
+import { EngineRegistry } from "../registry.js";
+import { createJavaScriptSelector } from "../selector.js";
+import { SlotTable } from "../slots.js";
+import { SqliteStateStore } from "../state-store.js";
+import { createPythonBackendSelector } from "./backend-selector.js";
+import { PythonEngine } from "./engine.js";
+import { ManagedBackend } from "./managed-backend.js";
+import { OciBackend } from "./oci-backend.js";
+import { PyodideBackend } from "./pyodide-backend.js";
+/** The backends of one process, in no particular order (the selector orders them). */
+export function createPythonBackends(options) {
+    return {
+        managed: new ManagedBackend({ runtime: options.runtime }),
+        ...(options.oci ? { oci: new OciBackend({ oci: options.oci }) } : {}),
+        ...(options.wasm ? { wasm: new PyodideBackend(options.wasm) } : {}),
+    };
+}
+export function createPythonForge(options) {
+    const backends = createPythonBackends(options);
+    const engines = options.shared?.engines ?? new EngineRegistry();
+    const kernel = options.shared?.kernel ??
+        new ExecutionKernel({
+            engines,
+            // Python hands the kernel its own selection; the JavaScript chain is never consulted.
+            selector: createJavaScriptSelector(),
+            journal: new SqliteExecutionJournal(options.jobs.database),
+            state: new SqliteStateStore(options.jobs.database),
+            slots: new SlotTable(),
+            config: () => ({ enabled: false, limits: {}, stateEnabled: true }),
+        });
+    let registered;
+    return {
+        kernel,
+        engines,
+        backends,
+        selector: createPythonBackendSelector(),
+        ready: () => {
+            registered ??= (async () => {
+                for (const backend of Object.values(backends))
+                    await engines.register(new PythonEngine({ backend, jobs: options.jobs }));
+            })();
+            return registered;
+        },
+    };
+}

package/dist/forge/registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Engine registry + null object (spec §4.2, D17). An engine is kept only when its self-description
+ * says it is ready; otherwise an `UnavailableEngine` takes its place, exposes the reason and never
+ * runs code. Fail closed: a throwing or mismatched self-check is "not ready".
+ */
+import type { EngineDescriptor, EngineId } from "@alisio/sdk";
+import type { EngineOutcome, ExecutionEngine, ExecutionRequest, PreparedExecution, TerminationReport, TrustedExecutionContext } from "./ports.ts";
+export declare class UnavailableEngine implements ExecutionEngine {
+    #private;
+    readonly id: EngineId;
+    constructor(descriptor: EngineDescriptor);
+    describe(): Promise<EngineDescriptor>;
+    prepare(_request: ExecutionRequest, _ctx: TrustedExecutionContext): Promise<PreparedExecution>;
+    run(): Promise<EngineOutcome>;
+    /** Nothing ever runs here, so there is nothing left to stop. */
+    terminate(): Promise<TerminationReport>;
+    dispose(): Promise<void>;
+}
+export declare class EngineRegistry {
+    #private;
+    /** Runs the engine's self-check and keeps it only if ready. Returns the descriptor in force. */
+    register(engine: ExecutionEngine): Promise<EngineDescriptor>;
+    /** The registered engine, or an unavailable one: never `undefined`, never a silent fallback. */
+    get(id: EngineId): ExecutionEngine;
+    descriptors(): Partial<Record<EngineId, EngineDescriptor>>;
+}

package/dist/forge/registry.js

@@ -0,0 +1,83 @@
+import { ForgeError } from "./errors.js";
+const languageOf = (id) => id.startsWith("javascript-") ? "javascript" : "python";
+export class UnavailableEngine {
+    id;
+    #descriptor;
+    constructor(descriptor) {
+        this.id = descriptor.id;
+        this.#descriptor = descriptor;
+    }
+    async describe() {
+        return this.#descriptor;
+    }
+    #unavailable() {
+        return new ForgeError("ENGINE_UNAVAILABLE", this.#descriptor.reason ?? `engine ${this.id} is not ready`);
+    }
+    async prepare(_request, _ctx) {
+        throw this.#unavailable();
+    }
+    async run() {
+        throw this.#unavailable();
+    }
+    /** Nothing ever runs here, so there is nothing left to stop. */
+    async terminate() {
+        return { confirmed: true, method: "interrupt", elapsedMs: 0 };
+    }
+    async dispose() { }
+}
+/** A descriptor for an engine that cannot report one itself. */
+function unavailableDescriptor(id, reason) {
+    return {
+        id,
+        language: languageOf(id),
+        version: "unavailable",
+        isolation: "none",
+        ready: false,
+        reason,
+        capabilities: {
+            cooperativeInterrupt: false,
+            hardTermination: false,
+            hardMemoryLimit: false,
+            networkDeniedByOS: false,
+            toolCalls: false,
+        },
+    };
+}
+export class EngineRegistry {
+    #engines = new Map();
+    #descriptors = new Map();
+    /** Runs the engine's self-check and keeps it only if ready. Returns the descriptor in force. */
+    async register(engine) {
+        let descriptor;
+        try {
+            descriptor = await engine.describe();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            descriptor = unavailableDescriptor(engine.id, `self-check failed: ${message}`);
+        }
+        if (descriptor.id !== engine.id) {
+            descriptor = unavailableDescriptor(engine.id, `self-check described ${descriptor.id} instead of ${engine.id}`);
+        }
+        if (!descriptor.ready) {
+            descriptor = {
+                ...descriptor,
+                reason: descriptor.reason ?? `engine ${engine.id} is not ready`,
+            };
+            this.#engines.set(engine.id, new UnavailableEngine(descriptor));
+        }
+        else {
+            this.#engines.set(engine.id, engine);
+        }
+        this.#descriptors.set(engine.id, descriptor);
+        return descriptor;
+    }
+    /** The registered engine, or an unavailable one: never `undefined`, never a silent fallback. */
+    get(id) {
+        return (this.#engines.get(id) ??
+            new UnavailableEngine(unavailableDescriptor(id, `engine ${id} is not registered`)));
+    }
+    descriptors() {
+        return Object.fromEntries(this.#descriptors);
+    }
+}

package/dist/forge/result.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The common result of a Forja execution (spec §5.3) and its compact text projection for the model.
+ * Pure: no I/O. `status: "succeeded"` means the program finished, not that every nested call did;
+ * `calls.failed` and `calls.denied` say the rest.
+ */
+import type { EngineId, IsolationLevel } from "@alisio/sdk";
+import { type ForgeErrorCode, type GuideHint } from "./errors.ts";
+import type { ForgeOutputItem } from "./protocol.ts";
+export type ForgeStatus = "succeeded" | "failed" | "cancelled" | "timed_out";
+export interface ForgeResult {
+    schemaVersion: 1;
+    executionId: string;
+    engine: EngineId;
+    isolation: IsolationLevel;
+    selectionReason: string;
+    status: ForgeStatus;
+    /** Text and JSON the script emitted explicitly, up to the retained-output limit. */
+    output: ForgeOutputItem[];
+    /** The script's `return` value. */
+    value?: unknown;
+    error?: {
+        code: ForgeErrorCode;
+        message: string;
+        hint?: GuideHint;
+    };
+    /** `failed` counts calls that errored; `denied` counts calls the permission gate refused. */
+    calls: {
+        total: number;
+        failed: number;
+        denied: number;
+    };
+    /** What the model sees was cut to the output limit. */
+    truncated: boolean;
+    metrics: {
+        wallMs: number;
+        queueMs: number;
+        outputBytes: number;
+    };
+}
+/** Cuts `text` to `max` characters on a character boundary; reports whether it did. */
+export declare function clipText(text: string, max: number): {
+    text: string;
+    clipped: boolean;
+};
+/** The text of the emitted items, in order; JSON items are rendered as one line each. */
+export declare function outputText(items: readonly ForgeOutputItem[]): string;
+/** Which guide topic explains how to recover from an error, when the cause is known. */
+export declare function hintFor(code: ForgeErrorCode, message: string, source?: string): GuideHint | undefined;
+/** Where a Python failure with a known cause points the model (spec §8.4). */
+export declare function pythonHintFor(code: "PACKAGE_UNAVAILABLE" | "RUNTIME_UNAVAILABLE"): GuideHint;
+/**
+ * The text the model receives. The value and the emitted output share the `maxChars` budget; the
+ * rest of the report (status, calls, error) is small and always kept.
+ */
+export declare function renderForgeResult(result: ForgeResult, maxChars: number): {
+    text: string;
+    truncated: boolean;
+};

package/dist/forge/result.js

@@ -0,0 +1,86 @@
+import { renderHint } from "./errors.js";
+/** Cuts `text` to `max` characters on a character boundary; reports whether it did. */
+export function clipText(text, max) {
+    if (text.length <= max)
+        return { text, clipped: false };
+    let end = max;
+    // Do not leave half of a surrogate pair at the cut.
+    const last = text.charCodeAt(end - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return { text: text.slice(0, end), clipped: true };
+}
+/** The text of the emitted items, in order; JSON items are rendered as one line each. */
+export function outputText(items) {
+    return items
+        .map((item) => (item.type === "text" ? item.text : JSON.stringify(item.value)))
+        .join("");
+}
+/** Which guide topic explains how to recover from an error, when the cause is known. */
+export function hintFor(code, message, source = "") {
+    if (code === "SCRIPT_SYNTAX" &&
+        (/\bimport\b|\brequire\b|\bexport\b/.test(message) ||
+            /^\s*(import|export)\b|\brequire\s*\(/m.test(source)))
+        return {
+            topic: "js.api",
+            reason: "imports and require are not available; call tools with tools.call",
+        };
+    if (code === "TOOL_UNAVAILABLE")
+        return { topic: "js.tools", reason: "list the tools you can call with catalog.search" };
+    if (code === "OUTPUT_LIMIT")
+        return {
+            topic: "js.patterns#filtering",
+            reason: "filter, aggregate or paginate before returning data",
+        };
+    return undefined;
+}
+/** Where a Python failure with a known cause points the model (spec §8.4). */
+export function pythonHintFor(code) {
+    return code === "PACKAGE_UNAVAILABLE"
+        ? {
+            topic: "python.environment",
+            reason: "a package is missing in the backend that runs Python",
+        }
+        : {
+            topic: "python.environment",
+            reason: "no Python backend can run now; the guide lists the shortest fix",
+        };
+}
+/**
+ * The text the model receives. The value and the emitted output share the `maxChars` budget; the
+ * rest of the report (status, calls, error) is small and always kept.
+ */
+export function renderForgeResult(result, maxChars) {
+    const head = [`status: ${result.status}`];
+    const tail = [
+        `calls: ${result.calls.total} total, ${result.calls.failed} failed, ${result.calls.denied} denied`,
+    ];
+    let errorClipped = false;
+    if (result.error) {
+        // The message can come from the script (an error it threw): bound it like any other text.
+        const message = clipText(result.error.message, maxChars);
+        errorClipped = message.clipped;
+        tail.push(`error: ${result.error.code}: ${message.text}`);
+        if (message.clipped)
+            tail.push(`[error message truncated at ${maxChars} characters]`);
+        if (result.error.hint)
+            tail.push(`hint: ${renderHint(result.error.hint)}`);
+    }
+    const body = [];
+    if (result.value !== undefined)
+        body.push(`value: ${JSON.stringify(result.value)}`);
+    const emitted = outputText(result.output);
+    if (emitted !== "")
+        body.push(`output:\n${emitted}`);
+    const clipped = clipText(body.join("\n"), maxChars);
+    const lines = [...head];
+    if (clipped.text !== "")
+        lines.push(clipped.text);
+    if (clipped.clipped)
+        lines.push(`[output truncated at ${maxChars} characters; return less: filter, aggregate or paginate]`);
+    lines.push(...tail);
+    return {
+        text: lines.join("\n"),
+        truncated: clipped.clipped || errorClipped || result.truncated,
+    };
+}

package/dist/forge/routing-rule.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Layer 0 of the incremental context (spec §8.1, D12): a short routing rule, present in the system
+ * prompt only when a Forja engine is registered and ready. With every engine off the prompt stays
+ * byte for byte what it was. The rule is built, never stored: the lines follow the tools actually
+ * registered and the session's real scratchpad path.
+ */
+/** Hard bound of the rule (spec §8.1). */
+export declare const ROUTING_RULE_MAX_CHARS = 900;
+export interface RoutingRuleInput {
+    /** `js_run` is registered. */
+    javascript: boolean;
+    /** `python_run` is registered (Forja line for it only then). */
+    python: boolean;
+    /** `forge_guide` is registered: the rule tells the model to call it. */
+    guide?: boolean;
+    /** Absolute path of this session's scratchpad, when there is one. */
+    scratchpad?: string | undefined;
+}
+export declare function buildRoutingRule(input: RoutingRuleInput): string;

package/dist/forge/routing-rule.js

@@ -0,0 +1,31 @@
+/**
+ * Layer 0 of the incremental context (spec §8.1, D12): a short routing rule, present in the system
+ * prompt only when a Forja engine is registered and ready. With every engine off the prompt stays
+ * byte for byte what it was. The rule is built, never stored: the lines follow the tools actually
+ * registered and the session's real scratchpad path.
+ */
+/** Hard bound of the rule (spec §8.1). */
+export const ROUTING_RULE_MAX_CHARS = 900;
+export function buildRoutingRule(input) {
+    if (!input.javascript && !input.python)
+        return "";
+    const lines = ["# Code execution"];
+    lines.push("- One tool call, or a few you can chain: call the tools directly.");
+    if (input.javascript)
+        lines.push("- Many reads, paging, filtering or aggregating tool results, JSON/text transforms, light maths: `js_run` (sandboxed JS: `await tools.call(name, input)`, `return` a small JSON value).");
+    if (input.python)
+        lines.push("- Data analysis, statistics, ML, charts, XLSX/DOCX/PDF, special dashboards: `python_run`.");
+    if (input.guide)
+        lines.push("- Call `forge_guide` before writing non-trivial code.");
+    if (input.scratchpad) {
+        // Which saved scripts the tools can run: only the tools that exist are named.
+        const runs = input.javascript && input.python
+            ? "; saved scripts: `js_run` `codePath` (.js), `python_run` `codePath` (.py)"
+            : input.javascript
+                ? "; saved scripts run with `js_run` `codePath`"
+                : "; saved scripts run with `python_run` `codePath`";
+        lines.push(`- Scratchpad (no approval for writes): ${input.scratchpad}${runs}.`);
+    }
+    const text = lines.join("\n");
+    return text.length <= ROUTING_RULE_MAX_CHARS ? text : text.slice(0, ROUTING_RULE_MAX_CHARS);
+}