@9thprotocol/agent-core 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,73 @@
+import type { AgentEvent, DelegationTotals, PermissionMode, SessionOptions, UsageTotals } from "./types.js";
+/**
+ * One conversation with the agent. `send()` streams AgentEvents; messages
+ * accumulate across sends until `clear()`.
+ */
+export declare class AgentSession {
+    private readonly opts;
+    /**
+     * Stable id for this conversation, sent with every platform request so the
+     * ledger can attribute spend to a session. M7 calibrates cost *per session*
+     * (PLAN.md §5.1); without this the ledger can only aggregate per user/day.
+     * Sub-agents inherit the parent's id so their burn rolls into the same session.
+     */
+    readonly sessionId: string;
+    /** The model that actually ran the last turn (resolved, never `"auto"`). */
+    model: string;
+    mode: PermissionMode;
+    readonly usage: UsageTotals;
+    /**
+     * Running delegation totals. `usage` already includes the worker's burn;
+     * this is the separate accounting of what it bought, so hosts can show the
+     * one number the session-window pitch rests on: context that never had to be
+     * paid for, on this turn or any turn after it.
+     */
+    readonly delegated: DelegationTotals;
+    private messages;
+    private readonly ctx;
+    private readonly tools;
+    private readonly memory;
+    private readonly depth;
+    /** `"auto"` (route per turn) or a pinned model id. Toggled by `setModel`. */
+    private modelPreference;
+    /** Set once compaction fails to shrink, so we stop paying to retry it. */
+    private compactionIneffective;
+    /** Whether bulk_read/code_write exist and the read gate is armed. */
+    private readonly delegationOn;
+    constructor(opts: SessionOptions);
+    /** Tool names available this session, for hosts and tests. */
+    get toolNames(): string[];
+    /** True while the session lets the router pick per turn. */
+    get isAuto(): boolean;
+    /** Pin a model, or pass `"auto"` to hand routing back to the router. */
+    setModel(id: string): void;
+    /** Estimated prompt tokens the next request would send. */
+    get contextTokens(): number;
+    /** Context window of the model that will run, from the catalog when known. */
+    private get contextLimit();
+    /**
+     * Summarise older history into one message, keeping recent turns verbatim.
+     * Returns null when there was nothing safe to compact.
+     *
+     * The summary is produced by a real model call, cheap and toolless, because
+     * a mechanical truncation loses exactly the decisions and constraints that
+     * make the rest of the session coherent.
+     */
+    compact(): Promise<{
+        before: number;
+        after: number;
+    } | null>;
+    clear(): void;
+    send(userText: string): AsyncGenerator<AgentEvent>;
+    private addUsage;
+    private makeAskUserTool;
+    /** Cheapest model the plan allows, unless the host pinned one. */
+    private get workerModelId();
+    /** Shared plumbing for both delegating tools. */
+    private runDelegation;
+    /** Read the requested paths, failing loudly on any that are missing. */
+    private loadFiles;
+    private makeBulkReadTool;
+    private makeCodeWriteTool;
+    private makeTaskTool;
+}

package/dist/session.js

@@ -0,0 +1,574 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { buildSystemPrompt } from "./prompt.js";
+import { loadMemory } from "./memory.js";
+import { gateFor } from "./permissions.js";
+import { CORE_TOOLS } from "./tools/registry.js";
+import { str, toSchema, truncate } from "./tools/types.js";
+import { ApiError, streamChat, } from "./model/openrouter.js";
+import { AUTO_MODEL, FALLBACK_DISPLAY_MODEL, route, workerModel } from "./model/router.js";
+import { DELEGATION_MIN_LINES, buildReadCorpus, buildWriteCorpus, delegate, estimateCorpusTokens, stripFences, } from "./delegate.js";
+import { DEFAULT_CONTEXT_TOKENS, applyCompaction, estimateTokens, planCompaction, renderTranscript, shouldCompact, summaryPrompt, } from "./compaction.js";
+const MAX_TURNS_DEFAULT = 40;
+/** Cheap, long-context model for summarising history. */
+const COMPACTION_MODEL = "z-ai/glm-4.7-flash";
+const MAX_TOOL_RESULT = 30_000;
+const MAX_SUBAGENT_DEPTH = 2;
+/**
+ * One conversation with the agent. `send()` streams AgentEvents; messages
+ * accumulate across sends until `clear()`.
+ */
+export class AgentSession {
+    opts;
+    /**
+     * Stable id for this conversation, sent with every platform request so the
+     * ledger can attribute spend to a session. M7 calibrates cost *per session*
+     * (PLAN.md §5.1); without this the ledger can only aggregate per user/day.
+     * Sub-agents inherit the parent's id so their burn rolls into the same session.
+     */
+    sessionId;
+    /** The model that actually ran the last turn (resolved, never `"auto"`). */
+    model;
+    mode;
+    usage = { inputTokens: 0, cachedTokens: 0, outputTokens: 0, requests: 0 };
+    /**
+     * Running delegation totals. `usage` already includes the worker's burn;
+     * this is the separate accounting of what it bought, so hosts can show the
+     * one number the session-window pitch rests on: context that never had to be
+     * paid for, on this turn or any turn after it.
+     */
+    delegated = {
+        calls: 0,
+        contextTokensSaved: 0,
+        workerUsage: { inputTokens: 0, cachedTokens: 0, outputTokens: 0, requests: 0 },
+    };
+    messages = [];
+    ctx;
+    tools;
+    memory;
+    depth;
+    /** `"auto"` (route per turn) or a pinned model id. Toggled by `setModel`. */
+    modelPreference;
+    /** Set once compaction fails to shrink, so we stop paying to retry it. */
+    compactionIneffective = false;
+    /** Whether bulk_read/code_write exist and the read gate is armed. */
+    delegationOn;
+    constructor(opts) {
+        this.opts = opts;
+        this.sessionId = opts.sessionId ?? randomUUID();
+        this.modelPreference = opts.model;
+        // Until the first turn routes, report the fallback rather than "auto".
+        this.model = opts.model === AUTO_MODEL ? FALLBACK_DISPLAY_MODEL : opts.model;
+        this.mode = opts.mode ?? "default";
+        this.depth = opts.depth ?? 0;
+        this.memory = loadMemory(opts.cwd);
+        // Explore sub-agents already run on the worker tier, so delegating from one
+        // would pay a round trip to move work from a flash model to a flash model.
+        this.delegationOn =
+            opts.delegation?.enabled !== false && opts.subagent !== "explore";
+        const minLines = opts.delegation?.minLines ?? DELEGATION_MIN_LINES;
+        this.ctx = {
+            cwd: opts.cwd,
+            readFiles: new Set(),
+            ...(this.delegationOn ? { delegation: { minLines } } : {}),
+        };
+        let tools = [...CORE_TOOLS, ...(opts.mcp?.tools ?? [])];
+        if (this.delegationOn)
+            tools.push(this.makeBulkReadTool(), this.makeCodeWriteTool());
+        if (opts.toolset === "read-only")
+            tools = tools.filter((t) => t.kind === "read");
+        if (opts.askUser)
+            tools.push(this.makeAskUserTool());
+        if (this.depth < MAX_SUBAGENT_DEPTH)
+            tools.push(this.makeTaskTool());
+        this.tools = tools;
+        // Platform mode: the API assembles the system prompt server-side per request.
+        if (!opts.platform) {
+            this.messages.push({ role: "system", content: buildSystemPrompt(opts.cwd, this.memory) });
+        }
+    }
+    /** Tool names available this session, for hosts and tests. */
+    get toolNames() {
+        return this.tools.map((t) => t.name);
+    }
+    /** True while the session lets the router pick per turn. */
+    get isAuto() {
+        return this.modelPreference === AUTO_MODEL;
+    }
+    /** Pin a model, or pass `"auto"` to hand routing back to the router. */
+    setModel(id) {
+        this.modelPreference = id;
+        if (id !== AUTO_MODEL)
+            this.model = id;
+    }
+    /** Estimated prompt tokens the next request would send. */
+    get contextTokens() {
+        return estimateTokens(this.messages);
+    }
+    /** Context window of the model that will run, from the catalog when known. */
+    get contextLimit() {
+        const entry = this.opts.autoRouter?.catalog?.find((m) => m.id === this.model);
+        return entry?.contextLength ?? this.opts.contextTokens ?? DEFAULT_CONTEXT_TOKENS;
+    }
+    /**
+     * Summarise older history into one message, keeping recent turns verbatim.
+     * Returns null when there was nothing safe to compact.
+     *
+     * The summary is produced by a real model call, cheap and toolless, because
+     * a mechanical truncation loses exactly the decisions and constraints that
+     * make the rest of the session coherent.
+     */
+    async compact() {
+        const plan = planCompaction(this.messages, this.contextLimit);
+        if (!plan)
+            return null;
+        // In platform mode the summariser gets its own server-assembled prompt via
+        // `context.mode`, so the transcript travels alone. Sending it as a plain
+        // user message would have the API prepend the full agent prompt instead:
+        // ~356 tokens against the summariser prompt's 186, and far more once a
+        // 9P.md memory is in play, all of it telling a model whose only job is to
+        // summarise that it should investigate and edit files.
+        const transcript = renderTranscript(plan.toSummarise);
+        let summary = "";
+        for await (const ev of streamChat({
+            apiKey: this.opts.apiKey,
+            model: this.opts.compactionModel ?? COMPACTION_MODEL,
+            messages: [
+                {
+                    role: "user",
+                    content: this.opts.platform
+                        ? `TRANSCRIPT:\n${transcript}`
+                        : summaryPrompt(transcript),
+                },
+            ],
+            tools: [],
+            ...(this.opts.platform
+                ? {
+                    baseUrl: this.opts.platform.baseUrl,
+                    extraBody: {
+                        context: {
+                            cwd: this.opts.cwd,
+                            sessionId: this.sessionId,
+                            mode: "compaction",
+                        },
+                    },
+                }
+                : {}),
+        })) {
+            if (ev.type === "done") {
+                summary = ev.result.message.content ?? "";
+                this.addUsage(ev.result.usage);
+            }
+        }
+        // A failed or empty summary must not destroy history.
+        if (!summary.trim())
+            return null;
+        const compacted = applyCompaction(plan, summary);
+        const after = estimateTokens(compacted);
+        // A summary can come back longer than what it replaced (verbose model, or
+        // very little history to compress). Keeping it would grow the context AND
+        // re-trigger compaction next turn, a loop that burns a model call per turn
+        // and never converges. Discard it and stop auto-compacting instead.
+        if (after >= plan.beforeTokens) {
+            this.compactionIneffective = true;
+            return null;
+        }
+        this.messages = compacted;
+        return { before: plan.beforeTokens, after };
+    }
+    clear() {
+        this.messages = this.opts.platform
+            ? []
+            : [{ role: "system", content: buildSystemPrompt(this.opts.cwd, this.memory) }];
+        this.ctx.readFiles.clear();
+    }
+    async *send(userText) {
+        // Auto routing resolves once per user message, not per tool-loop turn: the
+        // task's difficulty is set by what was asked, and switching models mid-loop
+        // would throw away the provider-side prompt cache that decides margins.
+        if (this.modelPreference === AUTO_MODEL) {
+            const decision = route({
+                text: userText,
+                planMode: this.mode === "plan",
+                ...(this.opts.autoRouter?.bias ? { bias: this.opts.autoRouter.bias } : {}),
+                ...(this.opts.autoRouter?.catalog ? { available: this.opts.autoRouter.catalog } : {}),
+                ...(this.opts.subagent ? { subagent: this.opts.subagent } : {}),
+            });
+            this.model = decision.model;
+            yield {
+                type: "model_selected",
+                model: decision.model,
+                complexity: decision.complexity,
+                reason: decision.reason,
+            };
+        }
+        this.messages.push({ role: "user", content: userText });
+        const maxTurns = this.opts.maxTurnsPerMessage ?? MAX_TURNS_DEFAULT;
+        for (let turn = 0; turn < maxTurns; turn++) {
+            // Compact between turns, never mid-exchange: at the top of a turn every
+            // tool call from the previous one already has its result, so the history
+            // is in a state that can be safely cut.
+            if (this.opts.autoCompact !== false &&
+                !this.compactionIneffective &&
+                shouldCompact(this.messages, this.contextLimit)) {
+                const result = await this.compact();
+                if (result) {
+                    yield {
+                        type: "compacted",
+                        beforeTokens: result.before,
+                        afterTokens: result.after,
+                    };
+                }
+            }
+            let result = null;
+            try {
+                for await (const ev of streamChat({
+                    apiKey: this.opts.apiKey,
+                    model: this.model,
+                    messages: this.messages,
+                    tools: this.tools.map(toSchema),
+                    ...(this.opts.platform
+                        ? {
+                            baseUrl: this.opts.platform.baseUrl,
+                            extraBody: {
+                                context: {
+                                    cwd: this.opts.cwd,
+                                    platform: process.platform,
+                                    memory: this.memory || undefined,
+                                    sessionId: this.sessionId,
+                                    // Sub-agent burn is attributed to the session but tagged, so
+                                    // calibration can separate main-loop cost from fan-out cost.
+                                    ...(this.opts.subagent ? { subagent: this.opts.subagent } : {}),
+                                },
+                            },
+                        }
+                        : {}),
+                })) {
+                    if (ev.type === "delta")
+                        yield { type: "text_delta", text: ev.text };
+                    else
+                        result = ev.result;
+                }
+            }
+            catch (err) {
+                yield {
+                    type: "error",
+                    message: err instanceof Error ? err.message : String(err),
+                    ...(err instanceof ApiError && err.code ? { code: err.code } : {}),
+                };
+                return;
+            }
+            if (!result) {
+                yield { type: "error", message: "stream ended without a result" };
+                return;
+            }
+            this.messages.push(result.message);
+            this.addUsage(result.usage);
+            const toolCalls = result.message.tool_calls ?? [];
+            if (!toolCalls.length) {
+                yield { type: "turn_end", usage: { ...this.usage } };
+                return;
+            }
+            // Phase 1, parse + permission-gate sequentially (deciders are interactive).
+            const prepared = [];
+            for (const raw of toolCalls) {
+                let input = {};
+                let early;
+                try {
+                    input = raw.function.arguments ? JSON.parse(raw.function.arguments) : {};
+                }
+                catch {
+                    early = "Error: tool arguments were not valid JSON";
+                }
+                const call = { id: raw.id, name: raw.function.name, input };
+                const tool = this.tools.find((t) => t.name === call.name);
+                if (!tool && !early)
+                    early = `Error: unknown tool "${call.name}"`;
+                if (tool && !early) {
+                    const summary = tool.summarize(call.input);
+                    const gate = gateFor(tool.kind, this.mode);
+                    if (gate === "deny") {
+                        yield { type: "permission_denied", call, summary };
+                        early = "Error: not permitted in plan (read-only) mode. Present a plan instead.";
+                    }
+                    else if (gate === "ask") {
+                        const allowed = this.opts.decide
+                            ? await this.opts.decide({ tool: call.name, summary, input: call.input })
+                            : false;
+                        if (!allowed) {
+                            yield { type: "permission_denied", call, summary };
+                            early =
+                                "Error: the user declined this tool call. Adjust your approach or ask them how to proceed.";
+                        }
+                    }
+                }
+                prepared.push({ call, tool, early });
+            }
+            // Phase 2, execute. `task` calls run concurrently (sub-agents are independent);
+            // everything else runs sequentially to keep fs/shell effects ordered.
+            const outputs = new Map();
+            const taskBatch = prepared.filter((p) => !p.early && p.tool?.name === "task");
+            for (const p of taskBatch) {
+                yield { type: "tool_start", call: p.call, summary: p.tool.summarize(p.call.input) };
+            }
+            const taskResults = await Promise.all(taskBatch.map(async (p) => {
+                const started = Date.now();
+                try {
+                    return { p, output: await p.tool.run(p.call.input, this.ctx), isError: false, ms: Date.now() - started };
+                }
+                catch (err) {
+                    return {
+                        p,
+                        output: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                        isError: true,
+                        ms: Date.now() - started,
+                    };
+                }
+            }));
+            for (const r of taskResults) {
+                outputs.set(r.p.call.id, r.output);
+                yield { type: "tool_end", call: r.p.call, output: r.output, isError: r.isError, durationMs: r.ms };
+            }
+            for (const p of prepared) {
+                if (outputs.has(p.call.id))
+                    continue;
+                if (p.early) {
+                    outputs.set(p.call.id, p.early);
+                    continue;
+                }
+                const tool = p.tool;
+                yield { type: "tool_start", call: p.call, summary: tool.summarize(p.call.input) };
+                const started = Date.now();
+                let output;
+                let isError = false;
+                try {
+                    output = await tool.run(p.call.input, this.ctx);
+                }
+                catch (err) {
+                    output = `Error: ${err instanceof Error ? err.message : String(err)}`;
+                    isError = true;
+                }
+                outputs.set(p.call.id, output);
+                yield { type: "tool_end", call: p.call, output, isError, durationMs: Date.now() - started };
+            }
+            // Tool results append in the model's original call order.
+            for (const raw of toolCalls) {
+                this.messages.push({
+                    role: "tool",
+                    tool_call_id: raw.id,
+                    content: truncate(outputs.get(raw.id) ?? "Error: no result", MAX_TOOL_RESULT),
+                });
+            }
+        }
+        yield { type: "error", message: `stopped after ${maxTurns} tool turns for one message` };
+    }
+    addUsage(u) {
+        this.usage.inputTokens += u.inputTokens;
+        this.usage.cachedTokens += u.cachedTokens;
+        this.usage.outputTokens += u.outputTokens;
+        this.usage.requests += u.requests;
+    }
+    makeAskUserTool() {
+        const askUser = this.opts.askUser;
+        return {
+            name: "ask_user",
+            description: "Ask the user a clarifying question when a decision is genuinely theirs, requirements, preferences, trade-offs. Offer 2-4 options when applicable. Never ask for information your other tools can find.",
+            kind: "read", // interactive but harmless; allowed even in plan mode
+            parameters: {
+                type: "object",
+                properties: {
+                    question: { type: "string" },
+                    options: { type: "array", items: { type: "string" }, description: "Optional choices" },
+                },
+                required: ["question"],
+            },
+            summarize: (i) => `ask: ${String(i.question ?? "").slice(0, 80)}`,
+            run: async (input) => {
+                const question = String(input.question ?? "");
+                const options = Array.isArray(input.options) ? input.options.map(String) : undefined;
+                const answer = await askUser({ question, ...(options ? { options } : {}) });
+                return `User answered: ${answer}`;
+            },
+        };
+    }
+    /** Cheapest model the plan allows, unless the host pinned one. */
+    get workerModelId() {
+        return (this.opts.delegation?.model ?? workerModel(this.opts.autoRouter?.catalog));
+    }
+    /** Shared plumbing for both delegating tools. */
+    async runDelegation(mode, message) {
+        const result = await delegate({
+            apiKey: this.opts.apiKey,
+            model: this.workerModelId,
+            mode,
+            message,
+            cwd: this.opts.cwd,
+            sessionId: this.sessionId,
+            ...(this.opts.platform ? { platform: this.opts.platform } : {}),
+        });
+        // Worker burn is real spend and belongs in the session total, exactly as
+        // sub-agent burn does. The saving is the corpus that never became context.
+        this.addUsage(result.usage);
+        this.delegated.calls += 1;
+        this.delegated.contextTokensSaved += estimateCorpusTokens(message.length);
+        this.delegated.workerUsage.inputTokens += result.usage.inputTokens;
+        this.delegated.workerUsage.cachedTokens += result.usage.cachedTokens;
+        this.delegated.workerUsage.outputTokens += result.usage.outputTokens;
+        this.delegated.workerUsage.requests += result.usage.requests;
+        return result.text;
+    }
+    /** Read the requested paths, failing loudly on any that are missing. */
+    async loadFiles(paths) {
+        return Promise.all(paths.map(async (raw) => {
+            const file = path.resolve(this.opts.cwd, raw);
+            try {
+                return { path: file, content: await fs.readFile(file, "utf8") };
+            }
+            catch {
+                // A path that silently became an empty block would produce a
+                // confident answer about nothing, which is worse than an error.
+                throw new Error(`cannot read ${file}`);
+            }
+        }));
+    }
+    makeBulkReadTool() {
+        return {
+            name: "bulk_read",
+            description: "Read files through a cheap worker model and get back only the answer. Use it for any file the read tool refuses, for a question spanning several files, and for large diffs, logs or generated output. The files go to the worker, never into this conversation, so asking a second question about the same paths costs nothing. Ask one specific question per call rather than requesting a summary. Do not use it to prepare an edit (you need exact bytes: read with offset/limit), to debug, or to make a design decision, where the reasoning is the whole job.",
+            kind: "read",
+            parameters: {
+                type: "object",
+                properties: {
+                    question: {
+                        type: "string",
+                        description: "One specific question. Ask for path:line citations if you will need to read the section afterwards.",
+                    },
+                    paths: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Files to send to the worker (absolute or relative to cwd)",
+                    },
+                },
+                required: ["question", "paths"],
+            },
+            summarize: (i) => {
+                const n = Array.isArray(i.paths) ? i.paths.length : 0;
+                return `bulk_read ${n} file(s): ${String(i.question ?? "").slice(0, 60)}`;
+            },
+            run: async (input) => {
+                const question = str(input.question);
+                const paths = Array.isArray(input.paths) ? input.paths.map(String) : [];
+                if (!paths.length)
+                    throw new Error("paths is required and must be non-empty");
+                const files = await this.loadFiles(paths);
+                return this.runDelegation("bulk-reader", buildReadCorpus(files, question));
+            },
+        };
+    }
+    makeCodeWriteTool() {
+        return {
+            name: "code_write",
+            description: "Generate predictable code on a cheap worker model, optionally straight to disk. Use it for tests, fixtures, config, migrations, type stubs, docstrings: anything where most of the output follows from a reference file. `reference` is required, because without a file to match the worker invents conventions that fit nothing in the project. Pass the closest existing sibling. Review what it produces and edit the part that needed judgement; the worker matches patterns, not intent.",
+            kind: "mutate",
+            parameters: {
+                type: "object",
+                properties: {
+                    spec: { type: "string", description: "What to generate" },
+                    reference: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Files whose patterns and style the output must match",
+                    },
+                    target: {
+                        type: "string",
+                        description: "Where to write. Omitted, the code is returned instead.",
+                    },
+                },
+                required: ["spec", "reference"],
+            },
+            summarize: (i) => `code_write ${i.target ? `→ ${i.target}` : "(stdout)"}: ${String(i.spec ?? "").slice(0, 60)}`,
+            run: async (input, ctx) => {
+                const spec = str(input.spec);
+                const refs = Array.isArray(input.reference) ? input.reference.map(String) : [];
+                if (!refs.length) {
+                    throw new Error("reference is required: pass a file whose patterns the output should match. For a follow-up, reference the file the previous call generated.");
+                }
+                const references = await this.loadFiles(refs);
+                const target = typeof input.target === "string" ? path.resolve(this.opts.cwd, input.target) : null;
+                // Same read-before-overwrite rule the write tool enforces: worker output
+                // lands unreviewed, so clobbering a file nobody looked at is worse here.
+                if (target) {
+                    const exists = await fs.access(target).then(() => true, () => false);
+                    if (exists && !ctx.readFiles.has(target)) {
+                        throw new Error(`${target} exists. Read it before overwriting`);
+                    }
+                }
+                const code = stripFences(await this.runDelegation("code-writer", buildWriteCorpus(spec, references)));
+                if (!target)
+                    return code;
+                await fs.mkdir(path.dirname(target), { recursive: true });
+                await fs.writeFile(target, code + "\n", "utf8");
+                ctx.readFiles.add(target);
+                return `Wrote ${code.split("\n").length} lines to ${target}. Review it before relying on it.`;
+            },
+        };
+    }
+    makeTaskTool() {
+        return {
+            name: "task",
+            description: 'Spawn a sub-agent with its own fresh context. agent_type "explore" gets read-only tools (codebase investigation, returns findings); "general" gets all tools and runs unattended. Give a complete, self-contained prompt including what to return. Multiple task calls in one response run in parallel.',
+            kind: "exec", // spawning an unattended agent ≈ running a command
+            parameters: {
+                type: "object",
+                properties: {
+                    description: { type: "string", description: "Short label shown to the user" },
+                    prompt: { type: "string", description: "Complete instructions for the sub-agent" },
+                    agent_type: { type: "string", enum: ["explore", "general"] },
+                    model: { type: "string", description: "Override model (default: parent's model)" },
+                },
+                required: ["description", "prompt", "agent_type"],
+            },
+            summarize: (i) => `task(${i.agent_type}): ${String(i.description ?? "").slice(0, 80)}`,
+            run: async (input) => {
+                const agentType = input.agent_type === "explore" ? "explore" : "general";
+                // In Auto mode the sub-agent routes for itself, so explore agents drop
+                // to economy models instead of inheriting the parent's resolved pick -
+                // the big burn saver on parallel sub-agents (PLAN.md §5.5).
+                const subModel = typeof input.model === "string"
+                    ? input.model
+                    : this.isAuto
+                        ? AUTO_MODEL
+                        : this.model;
+                const sub = new AgentSession({
+                    apiKey: this.opts.apiKey,
+                    model: subModel,
+                    cwd: this.opts.cwd,
+                    // the spawn itself was permission-gated; the sub-agent runs unattended
+                    mode: "bypass",
+                    toolset: agentType === "explore" ? "read-only" : "all",
+                    subagent: agentType,
+                    sessionId: this.sessionId, // fan-out burn belongs to the parent session
+                    depth: this.depth + 1,
+                    maxTurnsPerMessage: 25,
+                    ...(this.opts.platform ? { platform: this.opts.platform } : {}),
+                    ...(this.opts.mcp ? { mcp: this.opts.mcp } : {}),
+                    ...(this.opts.autoRouter ? { autoRouter: this.opts.autoRouter } : {}),
+                });
+                let text = "";
+                let error = null;
+                for await (const ev of sub.send(String(input.prompt ?? ""))) {
+                    if (ev.type === "text_delta")
+                        text += ev.text;
+                    if (ev.type === "error")
+                        error = ev.message;
+                }
+                this.addUsage(sub.usage); // sub-agent burn rolls up to the parent's totals
+                if (error)
+                    throw new Error(`sub-agent failed: ${error}`);
+                return text.trim() || "[sub-agent returned no text]";
+            },
+        };
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/skills.d.ts

@@ -0,0 +1,14 @@
+export interface Skill {
+    name: string;
+    description: string;
+    body: string;
+    source: string;
+}
+/**
+ * Skills: markdown files with optional `--- name/description ---` frontmatter, loaded
+ * from ~/.9p/skills and <cwd>/.9p/skills (project wins on name clash). Anti-bloat rule
+ * (PLAN.md §4.1): a skill's body enters context only when the user invokes /<name>.
+ */
+export declare function loadSkills(cwd: string): Skill[];
+/** The message sent when a user invokes /<skill> [args]. */
+export declare function skillMessage(skill: Skill, args: string): string;