dsh-continual-evolve 0.1.0

package/lib/mount.js

@@ -0,0 +1,198 @@
+/**
+ * Hot mounting: materialize a skill-kind harness entry as a real cordis
+ * plugin (v2 optional item, design.md §6) and load it into the live loader
+ * tree — no process restart. The generated plugin registers a model-facing
+ * tool that carries the skill's description, argument contract, and python
+ * reference; the `skill` tool remains the way to actually execute it.
+ *
+ * Layout under `<baseDir>/evolve/mounted/`:
+ *   index.json                    mount ledger (id -> path, restored at boot)
+ *   <skillName>/package.json      plugin manifest (ESM, main index.js)
+ *   <skillName>/index.js          generated plugin: registers one tool
+ *
+ * The generated plugin imports nothing outside node builtins, so the mount
+ * directory needs no node_modules of its own.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { skillNameOf } from "./skill.js";
+export function mountedDir(baseDir) {
+    return join(baseDir, "evolve", "mounted");
+}
+export function ledgerPath(baseDir) {
+    return join(mountedDir(baseDir), "index.json");
+}
+export function loadLedger(baseDir) {
+    const path = ledgerPath(baseDir);
+    if (!existsSync(path)) {
+        return { mounted: [] };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return { mounted: Array.isArray(raw.mounted) ? raw.mounted : [] };
+    }
+    catch {
+        return { mounted: [] };
+    }
+}
+export function saveLedger(baseDir, ledger) {
+    mkdirSync(mountedDir(baseDir), { recursive: true });
+    writeFileSync(ledgerPath(baseDir), `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+}
+/** Generate the plugin package files for one skill entry; returns the package dir. */
+export function renderMountPackage(baseDir, entry) {
+    const dir = join(mountedDir(baseDir), skillNameOf(entry.id));
+    mkdirSync(dir, { recursive: true });
+    const toolName = `skill_${skillNameOf(entry.id)}`;
+    writeFileSync(join(dir, "package.json"), `{\n  "name": "evolve-skill-${skillNameOf(entry.id)}",\n  "version": "1.0.0",\n  "main": "index.js",\n  "type": "module"\n}\n`, "utf8");
+    writeFileSync(join(dir, "index.js"), renderPluginSource(toolName, entry), "utf8");
+    return dir;
+}
+/** The generated plugin source: one tool registration, no external imports. */
+export function renderPluginSource(toolName, entry) {
+    const description = `${oneLine(entry.title)}. ${oneLine(entry.content)}`.slice(0, 400);
+    const parameters = renderParameters(entry);
+    const reference = JSON.stringify(entry.reference ?? {}, null, 2);
+    const entryId = JSON.stringify(entry.id);
+    const entryVersion = JSON.stringify(entry.version);
+    const entryTitle = JSON.stringify(oneLine(entry.title));
+    const skillName = JSON.stringify(skillNameOf(entry.id));
+    return `/**
+ * Generated by dsh-continual-evolve mount (${entry.id} v${entry.version}).
+ * Hot-mounted into the live loader tree; edit the harness entry and remount
+ * to regenerate. Execute the skill through the \`skill\` tool — this plugin
+ * exposes its contract to the model.
+ */
+export const name = "evolve-skill-${skillNameOf(entry.id)}";
+
+// Cordis requires declared service access; without this, \`ctx.tools\` throws
+// "cannot get property \\"tools\\" without inject".
+export const inject = ["tools"];
+
+export function apply(ctx) {
+  ctx.tools.register({
+    name: ${JSON.stringify(toolName)},
+    description: ${JSON.stringify(description)},
+    parameters: ${JSON.stringify(parameters, null, 2)},
+    output: {
+      // No \`required\` on the string property: the direct-register value-schema
+      // path rejects it ("required is not supported on type string").
+      schema: { type: "object", additionalProperties: false, properties: { text: { type: "string" } } },
+      render: (_args, value) => [{ type: "text", text: value?.text ?? "" }],
+    },
+    execute: async (args) => ({
+      text: "Mounted skill " + ${entryId} + " (v" + ${entryVersion} + ").\\n" +
+        "Description: " + ${entryTitle} + "\\n" +
+        "Argument contract: " + JSON.stringify(args ?? {}) + "\\n" +
+        "Python reference: " + ${JSON.stringify(reference)} + "\\n" +
+        "Execute via the \`skill\` tool (skill name " + ${skillName} + ").",
+    }),
+  });
+}
+`;
+}
+/**
+ * Map a skill entry's arguments contract to the tool-parameter schema.
+ * Requiredness goes in a root-level `required` array (valid JSON Schema):
+ * the mounted plugin registers via raw `ctx.tools.register`, and dsh-llm
+ * sends `parameters` verbatim to the API, which rejects per-property
+ * `required: true` ("true is not of type array").
+ */
+export function renderParameters(entry) {
+    const contract = entry.arguments ?? {};
+    const properties = {};
+    const required = [];
+    for (const [key, spec] of Object.entries(contract)) {
+        const record = typeof spec === "object" && spec !== null && !Array.isArray(spec) ? spec : {};
+        const type = typeof record["type"] === "string" ? record["type"] : "string";
+        const description = typeof record["description"] === "string" ? record["description"] : key;
+        properties[key] = { type, description };
+        if (record["required"] === true) {
+            required.push(key);
+        }
+    }
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}
+/**
+ * Mount one skill entry into the live loader. Requires the `loader` service
+ * (resolved lazily, see FAQ #1); without it the package is still written and
+ * the ledger records the entry for the next boot.
+ */
+export async function mountSkill(ctx, baseDir, entry) {
+    const dir = renderMountPackage(baseDir, entry);
+    const entryId = `evolve-mount-${skillNameOf(entry.id)}`;
+    const loader = ctx.get("loader");
+    if (loader) {
+        try {
+            // EntryOptions: {id, name (module specifier), config, group, disabled, inject} —
+            // `name` must resolve as an ES module: Node ESM does not support
+            // directory imports, so point at the generated index.js explicitly.
+            await loader.create({ id: entryId, name: join(dir, "index.js") });
+        }
+        catch (cause) {
+            throw new Error(`hot mount failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+    const record = {
+        id: entry.id,
+        entryId,
+        path: dir,
+        version: entry.version,
+        mountedAt: new Date().toISOString(),
+    };
+    const ledger = loadLedger(baseDir);
+    ledger.mounted = [...ledger.mounted.filter((m) => m.id !== entry.id), record];
+    saveLedger(baseDir, ledger);
+    return record;
+}
+/** Unmount a skill entry: remove the loader entry and the generated package. */
+export async function unmountSkill(ctx, baseDir, id) {
+    const ledger = loadLedger(baseDir);
+    const record = ledger.mounted.find((m) => m.id === id);
+    if (!record) {
+        return undefined;
+    }
+    const loader = ctx.get("loader");
+    if (loader) {
+        try {
+            await loader.remove(record.entryId);
+        }
+        catch (cause) {
+            throw new Error(`hot unmount failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+    if (existsSync(record.path)) {
+        rmSync(record.path, { recursive: true, force: true });
+    }
+    ledger.mounted = ledger.mounted.filter((m) => m.id !== id);
+    saveLedger(baseDir, ledger);
+    return record;
+}
+/** Re-mount every ledger entry at plugin boot (restart persistence). */
+export async function restoreMounted(ctx, baseDir) {
+    const ledger = loadLedger(baseDir);
+    const loader = ctx.get("loader");
+    for (const record of ledger.mounted) {
+        if (!existsSync(join(record.path, "index.js"))) {
+            continue; // package was removed; ledger prunes on next unmount
+        }
+        if (!loader) {
+            continue;
+        }
+        try {
+            await loader.create({ id: record.entryId, name: join(record.path, "index.js") });
+        }
+        catch (cause) {
+            ctx.logger("continual-evolve").warn(`mount restore failed for ${record.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+    }
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+//# sourceMappingURL=mount.js.map

package/lib/notify.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Auto-review visibility: the gate used to work fully in the background —
+ * the user never saw a decision, a persisted entry, or the token spend. This
+ * module queues a short follow-up turn after an approved gate run so the
+ * user SEES what was persisted, how to inspect it, and how to roll it back.
+ *
+ * The notice is a plugin-sourced user message (`agent.followup`), so it is
+ * rendered in the session transcript like any other input and the agent
+ * answers with a one-line confirmation. It never fakes tool or assistant
+ * events, so session replay, the ordered surface, and derived history stay
+ * untouched: the notice is a plain `user/message` with a plugin source.
+ *
+ * Every mechanical property stays in code: the notice text is built from the
+ * applied refinement result, never from model text.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { RefinementResult } from "./types.js";
+/**
+ * Compose the user-visible gate notice from an applied refinement result.
+ * Lists every successfully applied edit (kind + title + id) and the rollback
+ * command; failed edits are summarized in one line so nothing is hidden.
+ */
+export declare function buildGateNotice(result: RefinementResult, turnsSinceLastReview: number): string;
+/**
+ * Queue the follow-up notice turn for the agent. Failure is contained: a
+ * broken notification must never break the gate path that already recorded
+ * the decision in reviews.jsonl.
+ */
+export declare function notifyAutoReview(ctx: Context, agent: Agent, result: RefinementResult, turnsSinceLastReview: number): void;
+//# sourceMappingURL=notify.d.ts.map

package/lib/notify.js

@@ -0,0 +1,42 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+/**
+ * Compose the user-visible gate notice from an applied refinement result.
+ * Lists every successfully applied edit (kind + title + id) and the rollback
+ * command; failed edits are summarized in one line so nothing is hidden.
+ */
+export function buildGateNotice(result, turnsSinceLastReview) {
+    const applied = result.appliedEdits.filter((edit) => edit.applied);
+    const failed = result.appliedEdits.filter((edit) => !edit.applied);
+    const kindLabel = { prompt: "提示词", memory: "记忆", skill: "技能", subagent: "子代理" };
+    const lines = applied.map((edit) => `- ${kindLabel[edit.kind] ?? edit.kind}「${edit.title ?? edit.id}」（${edit.id}）`);
+    const linesText = lines.length > 0 ? lines.join("\n") : "（无条目成功应用）";
+    const failedText = failed.length > 0 ? `\n另有 ${failed.length} 条编辑未应用。` : "";
+    return [
+        `🔎 自动进化门禁：会话第 ${turnsSinceLastReview} 回合检查完成，本次沉淀 ${applied.length} 条条目：`,
+        linesText,
+        failedText,
+        `查看全部条目：/evolve list；回滚本次沉淀：/evolve rollback ${result.id}`,
+        "请用一句话简短确认即可，不要调用任何工具。",
+    ]
+        .filter((part) => part !== "")
+        .join("\n");
+}
+/**
+ * Queue the follow-up notice turn for the agent. Failure is contained: a
+ * broken notification must never break the gate path that already recorded
+ * the decision in reviews.jsonl.
+ */
+export function notifyAutoReview(ctx, agent, result, turnsSinceLastReview) {
+    try {
+        agent.followup(createUserMessage({
+            content: [{ type: "text", text: buildGateNotice(result, turnsSinceLastReview) }],
+            source: { kind: "plugin", plugin: "dsh-continual-evolve" },
+        }));
+    }
+    catch (cause) {
+        ctx
+            .logger("continual-evolve")
+            .warn(`auto-review notice failed for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+}
+//# sourceMappingURL=notify.js.map

package/lib/plan.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parsing helpers for the model-produced proposal JSON. A planner reply is
+ * untrusted text: it may carry prose, a fenced block, or be truncated by an
+ * exhausted output budget. These helpers recover the JSON object when
+ * possible and name the cause (truncation vs malformed) when not.
+ */
+import type { RefinementProposal } from "./types.js";
+/** True when the text ends mid-string or with unclosed brackets. */
+export declare function isIncompleteJson(candidate: string): boolean;
+/** Parse a JSON candidate, distinguishing truncation from malformation. */
+export declare function parseJsonCandidate(candidate: string): unknown;
+/** Recover a JSON object from raw model text. */
+export declare function extractJsonObject(text: string): unknown;
+/** Parse and shape a proposal, dropping non-object edits. */
+export declare function parseProposal(text: string): RefinementProposal;
+//# sourceMappingURL=plan.d.ts.map

package/lib/plan.js

@@ -0,0 +1,121 @@
+/** True when the text ends mid-string or with unclosed brackets. */
+export function isIncompleteJson(candidate) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (const char of candidate) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (inString) {
+            if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"')
+            inString = true;
+        else if (char === "{" || char === "[")
+            depth++;
+        else if (char === "}" || char === "]")
+            depth--;
+    }
+    return inString || depth > 0;
+}
+/** Parse a JSON candidate, distinguishing truncation from malformation. */
+export function parseJsonCandidate(candidate) {
+    try {
+        return JSON.parse(candidate);
+    }
+    catch (error) {
+        if (isIncompleteJson(candidate)) {
+            throw new Error("the model stopped before completing its JSON object (output budget exhausted?)");
+        }
+        throw new Error(`the model did not return valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Recover a JSON object from raw model text. */
+export function extractJsonObject(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        return parseJsonCandidate(trimmed);
+    }
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced) {
+        return parseJsonCandidate(fenced[1]?.trim() ?? "");
+    }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start !== -1 && end > start) {
+        try {
+            return JSON.parse(trimmed.slice(start, end + 1));
+        }
+        catch {
+            return parseJsonCandidate(trimmed.slice(start));
+        }
+    }
+    if (isIncompleteJson(trimmed)) {
+        throw new Error("the model stopped before completing its JSON object (output budget exhausted?)");
+    }
+    throw new Error("the planner did not return a JSON object");
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+/** Assign a string field only when it is present, honoring exactOptionalPropertyTypes. */
+function assignIfString(target, key, value) {
+    const str = asString(value);
+    if (str !== undefined) {
+        target[key] = str;
+    }
+}
+/** Parse and shape a proposal, dropping non-object edits. */
+export function parseProposal(text) {
+    const value = extractJsonObject(text);
+    const record = asRecord(value);
+    if (!record) {
+        throw new Error("the planner JSON must be an object");
+    }
+    const edits = [];
+    if (Array.isArray(record["edits"])) {
+        for (const raw of record["edits"]) {
+            const edit = asRecord(raw);
+            if (!edit)
+                continue;
+            const built = {
+                action: asString(edit["action"]),
+                kind: asString(edit["kind"]),
+            };
+            assignIfString(built, "id", edit["id"]);
+            assignIfString(built, "title", edit["title"]);
+            assignIfString(built, "content", edit["content"]);
+            assignIfString(built, "path", edit["path"]);
+            assignIfString(built, "reason", edit["reason"]);
+            const reference = asRecord(edit["reference"]);
+            if (reference)
+                built.reference = reference;
+            const argumentsRecord = asRecord(edit["arguments"]);
+            if (argumentsRecord)
+                built.arguments = argumentsRecord;
+            const metadata = asRecord(edit["metadata"]);
+            if (metadata)
+                built.metadata = metadata;
+            edits.push(built);
+        }
+    }
+    return {
+        summary: asString(record["summary"]) ?? "Refined harness state",
+        rationale: asString(record["rationale"]) ?? "",
+        expectedOutcome: asString(record["expectedOutcome"]) ?? "",
+        edits,
+    };
+}
+//# sourceMappingURL=plan.js.map

package/lib/planner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The LLM planning pass. Given the current harness state, refinement history,
+ * and optional instructions, a direct model call produces a JSON proposal
+ * which is parsed (truncation-aware) and validated by the pure core.
+ *
+ * The call routes through `ctx.llm` with the calling agent's own
+ * provider/model so the plan uses the same model the session runs on.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { HarnessState, RefinementProposal, RefinementResult } from "./types.js";
+export declare const PLANNER_SYSTEM_PROMPT = "You are the /evolve continual harness subsystem.\n\nYour job is to improve the editable continual harness state. Instead of\nsummarizing the conversation you emit precise Create, Update, or Delete edits\nto reusable state: prompt notes, memories, skills, and subagent specs.\n\nRules:\n- The base system prompt is immutable and MUST NOT be rewritten (never edit id \"base_system_prompt\").\n- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.\n- prompt = narrow behavioral policy addendums; memory = durable facts/preferences/failures;\n  skill = repeatable procedures (must carry a python reference {type:\"python\", import, callable}\n  and an arguments object); subagent = reusable delegation roles.\n- Local edits are session-scoped; global edits persist across sessions.\n- Ground every edit in evidence: the session trajectory (recent direct user\n  messages) is provided when available; prefer edits backed by it over\n  speculation, and never invent preferences the user did not express.\n- Stale entries (superseded by newer ones, never referenced in recent\n  trajectories, obsolete facts): propose action \"archive\" instead of\n  \"delete\" \u2014 archive hides the entry from injection while keeping its data\n  restorable; it requires only kind + id.\n- Output JSON only, exactly this shape:\n{\n  \"summary\": \"one sentence\",\n  \"rationale\": \"why these edits are justified by the evidence\",\n  \"expectedOutcome\": \"what should improve and how to validate it\",\n  \"edits\": [\n    {\n      \"action\": \"create|update|delete\",\n      \"kind\": \"prompt|memory|skill|subagent\",\n      \"id\": \"stable id for update/delete, optional for create\",\n      \"title\": \"required for create/update except delete\",\n      \"content\": \"required for create/update except delete\",\n      \"path\": \"optional grouping path\",\n      \"reference\": {\"type\":\"python\",\"import\":\"pkg.mod\",\"callable\":\"fn\"} ,\n      \"arguments\": {\"name\": {\"type\":\"string\",\"required\":true,\"description\":\"...\"}},\n      \"metadata\": {},\n      \"reason\": \"why this edit is useful\"\n    }\n  ]\n}";
+export interface PlanOptions {
+    agent: Agent;
+    state: HarnessState;
+    history: readonly RefinementResult[];
+    instructions?: string;
+    /**
+     * Explicit session-trajectory text (recent direct user messages). When
+     * omitted, it is extracted from the agent's own session log via
+     * `recentUserText` — the same extraction the injection ranking uses — so
+     * every planning call is grounded in what the user actually said.
+     */
+    trajectory?: string;
+    global?: boolean;
+    signal?: AbortSignal;
+    maxOutputTokens?: number;
+}
+export declare function planWithLlm(ctx: Context, options: PlanOptions): Promise<RefinementProposal>;
+//# sourceMappingURL=planner.d.ts.map

package/lib/planner.js

@@ -0,0 +1,110 @@
+import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { parseProposal } from "./plan.js";
+import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+import { recentUserText } from "./inject.js";
+export const PLANNER_SYSTEM_PROMPT = `You are the /evolve continual harness subsystem.
+
+Your job is to improve the editable continual harness state. Instead of
+summarizing the conversation you emit precise Create, Update, or Delete edits
+to reusable state: prompt notes, memories, skills, and subagent specs.
+
+Rules:
+- The base system prompt is immutable and MUST NOT be rewritten (never edit id "base_system_prompt").
+- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.
+- prompt = narrow behavioral policy addendums; memory = durable facts/preferences/failures;
+  skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
+  and an arguments object); subagent = reusable delegation roles.
+- Local edits are session-scoped; global edits persist across sessions.
+- Ground every edit in evidence: the session trajectory (recent direct user
+  messages) is provided when available; prefer edits backed by it over
+  speculation, and never invent preferences the user did not express.
+- Stale entries (superseded by newer ones, never referenced in recent
+  trajectories, obsolete facts): propose action "archive" instead of
+  "delete" — archive hides the entry from injection while keeping its data
+  restorable; it requires only kind + id.
+- Output JSON only, exactly this shape:
+{
+  "summary": "one sentence",
+  "rationale": "why these edits are justified by the evidence",
+  "expectedOutcome": "what should improve and how to validate it",
+  "edits": [
+    {
+      "action": "create|update|delete",
+      "kind": "prompt|memory|skill|subagent",
+      "id": "stable id for update/delete, optional for create",
+      "title": "required for create/update except delete",
+      "content": "required for create/update except delete",
+      "path": "optional grouping path",
+      "reference": {"type":"python","import":"pkg.mod","callable":"fn"} ,
+      "arguments": {"name": {"type":"string","required":true,"description":"..."}},
+      "metadata": {},
+      "reason": "why this edit is useful"
+    }
+  ]
+}`;
+export async function planWithLlm(ctx, options) {
+    const { agent, state, history } = options;
+    if (!agent.options.provider || !agent.options.model) {
+        throw new Error("evolve: the calling agent has no provider/model route to plan with");
+    }
+    const scopeInstruction = options.global
+        ? "Requested scope: global. Only propose stable cross-session lessons, durable preferences, reusable skills/subagents, or explicitly project-qualified facts."
+        : "Requested scope: local. Prefer session-scoped edits for current task progress; global entries are read-only context — do not propose update/delete for them.";
+    // Ground the plan in the caller's session: the trajectory block is the
+    // most recent direct user messages ("" when none qualify — the block is
+    // then omitted entirely, keeping an empty trajectory zero-cost).
+    const trajectory = options.trajectory ?? recentUserText(agent);
+    const userPrompt = [
+        `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
+        `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
+        `<scope_policy>\n${scopeInstruction}\n</scope_policy>`,
+        trajectory ? `<session_trajectory>\n${trajectory}\n</session_trajectory>` : "",
+        options.instructions ? `<user_instructions>\n${options.instructions}\n</user_instructions>` : "",
+        "Return only JSON edits. If no useful edit is justified, return an empty edits array with a rationale.",
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    const assembler = new BlockAssembler();
+    for await (const chunk of ctx.llm.stream({
+        provider: agent.options.provider,
+        model: agent.options.model,
+        system: PLANNER_SYSTEM_PROMPT,
+        messages: [
+            createUserMessage({
+                content: [{ type: "text", text: userPrompt }],
+                source: { kind: "plugin", plugin: "dsh-continual-evolve" },
+            }),
+        ],
+        // Force non-reasoning output: the proposal must be pure JSON text.
+        reasoningEffort: ReasoningEffortId("off"),
+        maxTokens: options.maxOutputTokens ?? 8000,
+        ...(options.signal ? { signal: options.signal } : {}),
+    })) {
+        assembler.push(chunk);
+    }
+    throwOnFinishError(assembler.finish);
+    const blocks = assembler.blocks();
+    const text = blocks
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (text.length === 0) {
+        throw new Error("evolve: planner produced no text output");
+    }
+    return parseProposal(text);
+}
+/** Surface terminal stream states as errors so the caller never sees a silent partial plan. */
+function throwOnFinishError(finish) {
+    switch (finish.kind) {
+        case "stop":
+        case "tool-calls":
+            return;
+        case "max-tokens":
+            throw new Error("evolve: planner output budget exhausted (max-tokens)");
+        case "aborted":
+            throw new Error("evolve: planner call aborted");
+        case "error":
+            throw new Error(`evolve: planner call failed: ${finish.failure?.message ?? "unknown error"}`);
+    }
+}
+//# sourceMappingURL=planner.js.map

package/lib/pool.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Bounded-concurrency map: run async workers over items with at most
+ * `concurrency` in flight. Used by the evaluation matrix so case × run units
+ * execute in parallel without unbounded subagent fan-out.
+ */
+export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=pool.d.ts.map

package/lib/pool.js

@@ -0,0 +1,25 @@
+/**
+ * Bounded-concurrency map: run async workers over items with at most
+ * `concurrency` in flight. Used by the evaluation matrix so case × run units
+ * execute in parallel without unbounded subagent fan-out.
+ */
+export async function mapPool(items, concurrency, worker) {
+    if (items.length === 0) {
+        return [];
+    }
+    const results = new Array(items.length);
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    let next = 0;
+    async function runner() {
+        while (true) {
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => runner()));
+    return results;
+}
+//# sourceMappingURL=pool.js.map

package/lib/render.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Prompt rendering: bounded, model-visible views of harness state and
+ * refinement history. Every cap exists to keep token cost predictable no
+ * matter how large the store grows.
+ */
+import type { HarnessEntry, HarnessRefinementEvent, HarnessState, RefinementResult } from "./types.js";
+export declare function compactText(text: string, maxLength: number): string;
+export declare function entryLine(entry: HarnessEntry, maxContentLength: number): string;
+/** Render the full merged state as a bounded overview for the system prompt. */
+export declare function formatHarnessStateForPrompt(state: HarnessState): string;
+/** Render recent refinement results for the planner. */
+export declare function historyForPrompt(history: readonly RefinementResult[]): string;
+/** Serialize a refinement event for persistence (lightweight). */
+export declare function eventToLine(event: HarnessRefinementEvent): string;
+//# sourceMappingURL=render.d.ts.map