klyro 0.1.63 → 1.0.1

package/dist/agent/runtime.js

@@ -23,10 +23,16 @@ import { verify, diagnosticForModel } from '../verification/engine.js';
 import { detectVerifyCommand } from '../verification/auto.js';
 import { ensureBaseline, getBaseline } from '../verification/baseline.js';
 import { compressTranscript, totalTokens } from '../context/tokenizer.js';
+import { ratesFor } from '../providers/model-info.js';
 import { classifyFailure, rerunOnce, gatherRepairContext, guardRepair } from '../verification/classify.js';
 import { findRelatedTests, buildScopedCommand, runScopedVerify, syntaxCheck, checkImports } from '../verification/scoped.js';
 import { globalBus } from '../events/bus.js';
 import { TraceWriter } from '../trace/writer.js';
+/** Normalize either systemPrompt shape into {system, suffix}. */
+export function resolveSystemPrompt(fn, ctx) {
+    const r = fn(ctx);
+    return typeof r === 'string' ? { system: r } : { system: r.system, suffix: r.suffix };
+}
 const DEFAULT_MAX_STEPS = 30;
 /** Convert a registry of tools into ToolDefinitions for the provider. */
 export function toolDefinitions(registry) {
@@ -36,19 +42,16 @@ export function toolDefinitions(registry) {
         inputSchema: t.function.parameters,
     }));
 }
-// BUG-005: Model-aware cost estimation with sensible defaults.
-// Rates are per-1K tokens (input / output). Local models are $0.
-const MODEL_RATES = [
-    { test: (m) => /gpt-4/i.test(m), input: 0.003, output: 0.015 },
-    { test: (m) => /gpt-3\.5/i.test(m), input: 0.0005, output: 0.0015 },
-    { test: (m) => /claude|anthropic/i.test(m), input: 0.003, output: 0.015 },
-    { test: (m) => /gemini/i.test(m), input: 0.00075, output: 0.003 },
-    { test: (m) => /o1/i.test(m), input: 0.015, output: 0.06 },
-];
+// BUG-005: Model-aware cost estimation, single-sourced from the
+// providers/model-info.ts rate table (local/unknown models are $0).
+// Cost is computed on input/output ONLY: cacheRead/cacheWrite are tracked
+// for observability but excluded because cached tokens bill at
+// provider-specific discounted rates we don't model — charging them at
+// full input rates would overstate spend, silently dropping them
+// understates it, so we keep them visible and out of the math.
 /** Estimate USD cost of a usage block given the model name. */
 export function estimateCost(model, usage) {
-    const match = MODEL_RATES.find((r) => r.test(model));
-    const { input: inRate, output: outRate } = match ?? { input: 0.003, output: 0.015 };
+    const { input: inRate, output: outRate } = ratesFor(model);
     return (usage.input / 1000) * inRate + (usage.output / 1000) * outRate;
 }
 // PERF-002: Memoized token counting cache.
@@ -93,6 +96,27 @@ export async function run(opts, deps) {
     let repairs = 0;
     let verificationAttempts = 0;
     let hasEdits = false;
+    // Overflow recovery: at most one compress-and-retry per run.
+    let overflowRetried = false;
+    // Repair ledger + guard: set from the first verification failure until a
+    // verification passes. repairUsageStart snapshots usage at failure time so
+    // every verification payload can attribute its repairTokens delta.
+    let inRepairTurn = false;
+    let repairUsageStart;
+    const verifyMode = opts.verify?.mode ?? 'strict';
+    const markRepairStarted = () => {
+        if (!repairUsageStart)
+            repairUsageStart = { input: usage.input, output: usage.output };
+        inRepairTurn = true;
+    };
+    const repairTokensNow = () => repairUsageStart
+        ? { input: usage.input - repairUsageStart.input, output: usage.output - repairUsageStart.output }
+        : undefined;
+    /** Attach repairTokens to a verification payload when a repair ledger exists. */
+    const withRepairTokens = (v) => {
+        const rt = repairTokensNow();
+        return rt ? { ...v, repairTokens: rt } : v;
+    };
     const emit = opts.onEvent;
     const telemetry = new RuntimeTelemetry();
     telemetry.setMaxSteps(maxSteps);
@@ -200,7 +224,7 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined, phase: 'blocked' };
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined, phase: 'blocked' };
         }
         steps++;
         // 5.1 phase transitions (model-narrated)
@@ -216,21 +240,30 @@ export async function run(opts, deps) {
             setPhase('verifying');
         emit?.({ kind: 'step_start', step: steps });
         telemetry.recordStepStart(steps);
-        const systemPrompt = deps.systemPrompt({ cwd: opts.cwd, telemetry: steps === 1 ? emptyTelemetryBlock() : telemetry.format() });
+        const { system: stableSystem, suffix: telemetrySuffix } = resolveSystemPrompt(deps.systemPrompt, {
+            cwd: opts.cwd,
+            telemetry: steps === 1 ? emptyTelemetryBlock() : telemetry.format(),
+        });
+        // Budget accounting sees what the model sees (prefix + suffix); the
+        // request itself keeps the halves split for cache-friendly adapters.
+        const systemForBudget = telemetrySuffix ? `${stableSystem}\n\n${telemetrySuffix}` : stableSystem;
         const BUDGET = { total: 120_000, reservedOutput: 4000 };
         let reqMessages = transcript;
-        let reqSystem = systemPrompt;
-        if (cachedTotalTokens(systemPrompt, transcript) > BUDGET.total) {
-            const c = compressTranscript(systemPrompt, transcript, BUDGET);
+        let reqSystem = stableSystem;
+        let reqSuffix = telemetrySuffix;
+        if (cachedTotalTokens(systemForBudget, transcript) > BUDGET.total) {
+            const c = compressTranscript(systemForBudget, transcript, BUDGET);
             reqSystem = c.system;
+            reqSuffix = undefined; // telemetry is regenerable — drop it under pressure
             reqMessages = c.messages;
             tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
             if (c.dropped > 0)
                 emitKlyro({ type: 'context.compacted', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', dropped: c.dropped });
         }
         const req = {
-            model: opts.model,
+            model: opts.parentContext?.model ?? opts.model,
             system: reqSystem,
+            ...(reqSuffix ? { systemSuffix: reqSuffix } : {}),
             messages: reqMessages,
             tools: toolDefinitions(deps.registry),
             ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
@@ -244,6 +277,8 @@ export async function run(opts, deps) {
         let thinkingBuf = '';
         const pendingToolCalls = new Map();
         let lastFinishReason;
+        // Set when this step's request must be re-issued after overflow recovery.
+        let overflowRetryPending = false;
         for await (const ev of events) {
             if (opts.signal?.aborted)
                 break outer;
@@ -273,14 +308,22 @@ export async function run(opts, deps) {
                 if (ev.usage) {
                     usage.input += ev.usage.input;
                     usage.output += ev.usage.output;
+                    if (ev.usage.cacheRead !== undefined)
+                        usage.cacheRead = (usage.cacheRead ?? 0) + ev.usage.cacheRead;
+                    if (ev.usage.cacheWrite !== undefined)
+                        usage.cacheWrite = (usage.cacheWrite ?? 0) + ev.usage.cacheWrite;
                     telemetry.recordUsage(ev.usage.input, ev.usage.output);
-                    emit?.({ kind: 'usage', input: usage.input, output: usage.output });
+                    emit?.({
+                        kind: 'usage', input: usage.input, output: usage.output,
+                        ...(usage.cacheRead !== undefined ? { cacheRead: usage.cacheRead } : {}),
+                        ...(usage.cacheWrite !== undefined ? { cacheWrite: usage.cacheWrite } : {}),
+                    });
                 }
                 else {
                     // Providers that omit usage (Ollama, vLLM, proxies): estimate from
                     // the actual request + generated output so cost accounting never
                     // silently records zero. Marked estimated for the UI/debugging.
-                    const est = estimateTurnUsage(reqSystem, reqMessages, textBuf, pendingToolCalls);
+                    const est = estimateTurnUsage(systemForBudget, reqMessages, textBuf, pendingToolCalls);
                     usage.input += est.input;
                     usage.output += est.output;
                     usage.estimated = true;
@@ -289,6 +332,31 @@ export async function run(opts, deps) {
                 }
             }
             else if (ev.kind === 'error') {
+                // Overflow recovery: on the first REQUEST_TOO_LARGE of a run,
+                // aggressively compact the transcript and re-issue the request once.
+                // A second occurrence fails normally (returned as no_final below).
+                if (ev.code === 'REQUEST_TOO_LARGE' && !overflowRetried) {
+                    overflowRetried = true;
+                    overflowRetryPending = true;
+                    telemetry.recordError('overflow_retry');
+                    emitKlyro({ type: 'error', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', code: 'REQUEST_TOO_LARGE', message: 'context overflow — aggressively compacting transcript and retrying the request once' });
+                    try {
+                        const compacted = compressTranscript(reqSystem, transcript, { total: 30_000, reservedOutput: 4000 });
+                        if (compacted.messages.length < transcript.length || compacted.dropped > 0) {
+                            transcript.splice(0, transcript.length, ...compacted.messages);
+                        }
+                        else {
+                            // Transcript already fits the aggressive budget — force it
+                            // strictly smaller so the retry cannot repeat the overflow.
+                            const halved = Math.max(4000, Math.floor(totalTokens(reqSystem, transcript) / 2));
+                            const smaller = compressTranscript(reqSystem, transcript, { total: halved, reservedOutput: 4000 });
+                            transcript.splice(0, transcript.length, ...smaller.messages);
+                        }
+                        tokenCache = { lastRef: null, lastSystem: undefined, lastCount: 0 };
+                    }
+                    catch { /* ignore — retry with the transcript as-is */ }
+                    break;
+                }
                 telemetry.recordError(`stream_error: ${ev.code}`);
                 if (store && sessionId) {
                     try {
@@ -306,10 +374,18 @@ export async function run(opts, deps) {
                     hasEdits,
                     usage,
                     repairs,
-                    verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined,
+                    verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined,
                 };
             }
         }
+        // Overflow recovery lands here via `break`: re-issue the same step
+        // without consuming the step budget.
+        if (overflowRetryPending) {
+            overflowRetryPending = false;
+            steps--;
+            emit?.({ kind: 'step_end', step: steps + 1 });
+            continue outer;
+        }
         // Build the assistant message. Tool calls are finalized here: JSON is
         // parsed and schema-validated BEFORE policy/execution. Malformed calls
         // become structured MALFORMED_TOOL_CALL results — garbage arguments must
@@ -368,7 +444,7 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
         }
         if (finalizedCalls.length === 0) {
             if (hadInvalidTool) {
@@ -380,6 +456,66 @@ export async function run(opts, deps) {
                 continue;
             }
             finalText = textBuf;
+            // Verify modes: 'off' skips the pipeline entirely (verification stays
+            // undefined, no repair turns). 'advisory' runs verify once on
+            // completion and reports the outcome without repair turns. 'strict'
+            // (default) runs the full pipeline with autonomous repair below.
+            if (verifyMode === 'off') {
+                emit?.({ kind: 'final_text', text: finalText });
+                emit?.({ kind: 'step_end', step: steps });
+                if (store && sessionId) {
+                    try {
+                        await store.setStatus(sessionId, 'complete', finalText);
+                    }
+                    catch { /* ignore */ }
+                }
+                await closeTracer();
+                return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: undefined };
+            }
+            if (verifyMode === 'advisory') {
+                const advisoryCmd = opts.verify?.command ?? detectVerifyCommand(opts.cwd);
+                if (opts.verify?.enabled !== false && hasEdits && advisoryCmd) {
+                    emit?.({ kind: 'verification_started', command: advisoryCmd });
+                    let advisoryResult;
+                    try {
+                        advisoryResult = await verify({ cwd: opts.cwd, command: advisoryCmd, timeoutMs: opts.verify?.timeoutMs });
+                    }
+                    catch (e) {
+                        const msg = e instanceof Error ? e.message : String(e);
+                        advisoryResult = { ok: false, exitCode: -1, stdout: '', stderr: msg, failure: { type: 'unknown', files: [], raw: msg, exitCode: -1 } };
+                    }
+                    verificationAttempts++;
+                    if (advisoryResult.ok) {
+                        inRepairTurn = false;
+                        emit?.({ kind: 'verification_succeeded', command: advisoryCmd });
+                        emit?.({ kind: 'final_text', text: finalText });
+                        emit?.({ kind: 'step_end', step: steps });
+                        if (store && sessionId) {
+                            try {
+                                await store.setStatus(sessionId, 'complete', finalText);
+                            }
+                            catch { /* ignore */ }
+                        }
+                        await closeTracer();
+                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: advisoryCmd, attempts: verificationAttempts }) };
+                    }
+                    const advisoryFailure = advisoryResult.failure?.type ?? 'unknown';
+                    markRepairStarted();
+                    emit?.({ kind: 'verification_failed', step: String(steps), reason: diagnosticForModel(advisoryResult).slice(0, 800) });
+                    emit?.({ kind: 'final_text', text: finalText });
+                    emit?.({ kind: 'step_end', step: steps });
+                    if (store && sessionId) {
+                        try {
+                            await store.setStatus(sessionId, 'complete', finalText);
+                        }
+                        catch { /* ignore */ }
+                    }
+                    await closeTracer();
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: advisoryCmd, attempts: verificationAttempts, failureType: advisoryFailure }) };
+                }
+                // No verify applicable (disabled, no edits, or no command) — fall
+                // through to the normal completion return below.
+            }
             // Level 8 — Verification + Autonomous Repair (gated on hasEdits below — pure analysis skips verify)
             const verifyEnabled = opts.verify?.enabled !== false;
             const verifyCmd = opts.verify?.command ?? detectVerifyCommand(opts.cwd);
@@ -439,6 +575,7 @@ export async function run(opts, deps) {
                     catch { /* scoped success is enough */ }
                 }
                 if (vResult.ok) {
+                    inRepairTurn = false;
                     emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
@@ -449,7 +586,7 @@ export async function run(opts, deps) {
                         catch { /* ignore */ }
                     }
                     await closeTracer();
-                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                 }
                 // 6.4 — classify
                 const baseline = await getBaseline(opts.cwd, verifyCmd);
@@ -457,6 +594,7 @@ export async function run(opts, deps) {
                 const cls = classifyFailure({ failure: vResult.failure, stdout: vResult.stdout, stderr: vResult.stderr }, baseline, isFlaky);
                 if (cls === 'flaky') {
                     // rerun succeeded on second try — treat as flaky, don't count as repair
+                    inRepairTurn = false;
                     emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
@@ -467,7 +605,7 @@ export async function run(opts, deps) {
                         catch { /* ignore */ }
                     }
                     await closeTracer();
-                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                    return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                 }
                 if (cls === 'env') {
                     // don't try to repair env failures with code edits
@@ -475,10 +613,11 @@ export async function run(opts, deps) {
                     transcript.push(envMsg);
                     await checkpoint(envMsg);
                     verificationAttempts++;
+                    markRepairStarted();
                     emit?.({ kind: 'verification_failed', step: String(steps), reason: `env: ${diagnosticForModel(vResult).slice(0, 600)}` });
                     if (verificationAttempts >= maxRepairs) {
                         await closeTracer();
-                        return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: false, command: verifyCmd, attempts: verificationAttempts, failureType: 'env' } };
+                        return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: verifyCmd, attempts: verificationAttempts, failureType: 'env' }) };
                     }
                     emit?.({ kind: 'step_end', step: steps });
                     continue;
@@ -494,6 +633,7 @@ export async function run(opts, deps) {
                     const failurePaths = new Set(vResult.failure?.files.map((f) => f.path).filter(Boolean) ?? []);
                     const overlaps = [...failurePaths].some((p) => introducedPaths.has(p) || introducedPaths.has(path.basename(p)));
                     if (!overlaps) {
+                        inRepairTurn = false;
                         emit?.({ kind: 'verification_succeeded', command: verifyCmd });
                         emit?.({ kind: 'final_text', text: finalText });
                         emit?.({ kind: 'step_end', step: steps });
@@ -504,11 +644,12 @@ export async function run(opts, deps) {
                             catch { /* ignore */ }
                         }
                         await closeTracer();
-                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: true, command: verifyCmd, attempts: verificationAttempts } };
+                        return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: true, command: verifyCmd, attempts: verificationAttempts }) };
                     }
                 }
                 // Failure → repair loop (introduced)
                 verificationAttempts++;
+                markRepairStarted();
                 const diagnostic = diagnosticForModel(vResult);
                 const failureType = vResult.failure?.type ?? 'unknown';
                 // 6.4 — gather context
@@ -548,7 +689,7 @@ export async function run(opts, deps) {
                     emit?.({ kind: 'final_text', text: finalText });
                     emit?.({ kind: 'step_end', step: steps });
                     await closeTracer();
-                    return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: { ok: false, command: verifyCmd, attempts: verificationAttempts, failureType } };
+                    return { status: 'verify_failed', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: withRepairTokens({ ok: false, command: verifyCmd, attempts: verificationAttempts, failureType }) };
                 }
                 emit?.({ kind: 'step_end', step: steps });
                 continue; // -> next iteration lets model repair
@@ -562,17 +703,26 @@ export async function run(opts, deps) {
                 catch { /* ignore */ }
             }
             await closeTracer();
-            return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: true, attempts: verificationAttempts } : undefined };
+            return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: true, attempts: verificationAttempts }) : undefined };
         }
         // 3.1 — emit turn events
         emitKlyro({ type: 'turn.start', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', turn: steps, model: opts.model });
-        // Execute each tool call (after policy) — 3.5 parallel if all concurrencySafe
         const toolCtx = {
             cwd: opts.cwd,
             env: process.env,
             signal: opts.signal,
             nonInteractive: opts.nonInteractive,
             sessionId,
+            ...(opts.agentBridge ? { agentBridge: opts.agentBridge } : {}),
+            ...(opts.parentContext?.taskId
+                ? { parentTaskId: opts.parentContext.parentTaskId ?? opts.parentContext.taskId }
+                : {}),
+            agentDepth: opts.parentContext?.depth ?? 0,
+            agentMaxDepth: opts.parentContext?.maxDepth ?? 1,
+            ...(opts.parentContext?.allowedTools ? { agentAllowedTools: opts.parentContext.allowedTools } : {}),
+            ...(opts.parentContext?.allowedPaths ? { agentAllowedPaths: opts.parentContext.allowedPaths } : {}),
+            ...(opts.parentContext?.model ?? opts.model ? { agentModel: opts.parentContext?.model ?? opts.model } : {}),
+            repairGuard: { denyTestEdits: inRepairTurn },
         };
         const allSafe = finalizedCalls.length > 1 && finalizedCalls.every((c) => deps.registry.get(c.name)?.isConcurrencySafe !== false);
         // Gate phase: policy decision + approval prompt for one call. Runs
@@ -583,7 +733,12 @@ export async function run(opts, deps) {
             const decision = await deps.policy.evaluate({ name: call.name, input: call.input }, { cwd: opts.cwd, nonInteractive: opts.nonInteractive });
             emit?.({ kind: 'policy_decision', id: call.id, name: call.name, action: decision.action, ...(decision.action !== 'allow' ? { reason: decision.reason } : {}) });
             // Mirror to KlyroEvent bus
-            emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: decision.action, ...(decision.action !== 'allow' ? { reason: decision.reason } : {}) });
+            if (decision.action === 'allow') {
+                emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: 'allow' });
+            }
+            else {
+                emitKlyro({ type: 'permission.decision', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, action: decision.action, reason: decision.reason });
+            }
             if (decision.action === 'deny') {
                 const denyMsg = {
                     role: 'tool',
@@ -762,6 +917,19 @@ export async function run(opts, deps) {
                     break;
             }
         }
+        // P0 — drain finished sub-agent completions into parent visibility.
+        // drainCompletions is OPTIONAL on the bridge — guarded with `?.` so
+        // older bridges without it simply yield nothing.
+        try {
+            const completions = opts.agentBridge?.drainCompletions?.() ?? [];
+            for (const c of completions) {
+                const body = c.finalText ?? c.error?.message ?? '';
+                const msg = { role: 'user', content: [text(`Subtask ${c.taskId} (${c.agentName}) ${c.status}: ${body.slice(0, 500)}`)] };
+                transcript.push(msg);
+                await checkpoint(msg);
+            }
+        }
+        catch { /* ignore — completions are best-effort visibility */ }
         emit?.({ kind: 'step_end', step: steps });
         emitKlyro({ type: 'turn.end', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', turn: steps });
         // Level 9 — checkpoint status after each step
@@ -784,7 +952,7 @@ export async function run(opts, deps) {
             catch { /* ignore */ }
         }
         await closeTracer();
-        return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+        return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
     }
     // 5.2 — stuck termination (P0-3): bounded stop instead of unbounded token burn.
     if (stuckAbort) {
@@ -796,7 +964,7 @@ export async function run(opts, deps) {
             catch { /* ignore */ }
         }
         await closeTracer();
-        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+        return { status: 'stuck', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
     }
     emit?.({ kind: 'final_text', text: finalText });
     if (store && sessionId) {
@@ -806,7 +974,7 @@ export async function run(opts, deps) {
         catch { /* ignore */ }
     }
     await closeTracer();
-    return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? { ok: false, attempts: verificationAttempts } : undefined };
+    return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, hasEdits, usage, repairs, verification: hasEdits ? withRepairTokens({ ok: false, attempts: verificationAttempts }) : undefined };
 }
 /**
  * Estimate usage for a turn whose provider omitted it (Ollama, vLLM,
@@ -942,7 +1110,10 @@ export function defaultSystemPrompt(ctx) {
         'Do not invent file paths. Do not call tools outside the working directory.',
     ].join(' ');
     if (ctx.telemetry) {
-        return base + '\n\n' + ctx.telemetry + '\n\nUse the telemetry above to avoid repeating the same failing call and to keep within the step budget.';
+        return {
+            system: base,
+            suffix: ctx.telemetry + '\n\nUse the telemetry above to avoid repeating the same failing call and to keep within the step budget.',
+        };
     }
-    return base;
+    return { system: base };
 }

package/dist/agent/scoped-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ScopedRegistry — a `ToolRegistry` that narrows the surface to a resolved
+ * capability set.
+ *
+ * Both surfaces the runtime relies on (`toolDefinitions(deps.registry)`
+ * and `deps.registry.execute(...)`) go through `list()` / `execute()`, so
+ * wrapping the child's registry in this class enforces the tool allow-set
+ * end-to-end without touching the runtime loop: the model only sees the
+ * allowed tools, and any call to a disallowed tool returns `UNKNOWN_TOOL`.
+ */
+import type { Tool, ToolContext, ToolResult } from '../tools/types.js';
+import { ToolRegistry } from '../tools/registry.js';
+export declare class ScopedRegistry extends ToolRegistry {
+    private readonly parent;
+    private readonly allowed;
+    constructor(parent: ToolRegistry, allowed: ReadonlySet<string>);
+    get(name: string): Tool<unknown, unknown> | undefined;
+    list(): Tool<unknown, unknown>[];
+    /** Which tools this scope permits, by name (for diagnostics/tests). */
+    names(): string[];
+    execute(name: string, rawInput: unknown, ctx: ToolContext): Promise<ToolResult<unknown>>;
+}

package/dist/agent/scoped-registry.js

@@ -0,0 +1,42 @@
+/**
+ * ScopedRegistry — a `ToolRegistry` that narrows the surface to a resolved
+ * capability set.
+ *
+ * Both surfaces the runtime relies on (`toolDefinitions(deps.registry)`
+ * and `deps.registry.execute(...)`) go through `list()` / `execute()`, so
+ * wrapping the child's registry in this class enforces the tool allow-set
+ * end-to-end without touching the runtime loop: the model only sees the
+ * allowed tools, and any call to a disallowed tool returns `UNKNOWN_TOOL`.
+ */
+import { ToolRegistry } from '../tools/registry.js';
+export class ScopedRegistry extends ToolRegistry {
+    parent;
+    allowed;
+    constructor(parent, allowed) {
+        super();
+        this.parent = parent;
+        this.allowed = allowed;
+    }
+    get(name) {
+        return this.allowed.has(name) ? this.parent.get(name) : undefined;
+    }
+    list() {
+        return this.parent.list().filter((t) => this.allowed.has(t.name));
+    }
+    /** Which tools this scope permits, by name (for diagnostics/tests). */
+    names() {
+        return [...this.allowed].sort();
+    }
+    async execute(name, rawInput, ctx) {
+        if (!this.allowed.has(name)) {
+            return {
+                ok: false,
+                error: {
+                    code: 'UNKNOWN_TOOL',
+                    message: `Tool not available in this agent context: ${name}`,
+                },
+            };
+        }
+        return this.parent.execute(name, rawInput, ctx);
+    }
+}

package/dist/agent/task-manager.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Task manager — tracks the lifecycle of a (possibly nested) agent run.
+ *
+ * Each `spawn_agent` call creates a `TaskRecord` in a `TaskManager`.
+ * The manager owns an `AbortController` per task so that the parent (or
+ * the user) can cancel a running child without tearing down the entire
+ * process. It enforces a recursion / depth cap and emits `subtask.*`
+ * events so the event bus and trace writer can see the task tree.
+ *
+ * Exactly one task manager exists per session, wired into the orchestrator
+ * (src/agent/orchestrator.ts), which the runtime reaches via
+ * `parentContext`.
+ */
+import { type EventBus } from '../events/bus.js';
+export type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+export interface TaskError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/**
+ * The full runtime record for one task. `summary` is a free-form progress
+ * log; `done` resolves to this very record once the task reaches a terminal
+ * status, so `await rec.done` yields the record with its final status.
+ */
+export interface TaskRecord {
+    id: string;
+    parentTaskId?: string;
+    sessionId: string;
+    agentName: string;
+    status: TaskStatus;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    model?: string;
+    startedAt: number;
+    finishedAt?: number;
+    summary: string[];
+    error?: TaskError;
+    abortController: AbortController;
+    done: Promise<TaskRecord>;
+    /** Internal — resolves `done`. Do not call outside TaskManager. */
+    _resolveDone: (r: TaskRecord) => void;
+    /** Internal cleanup handles, not part of the stable contract. */
+    _cleanupParentAbort?: () => void;
+    timeoutHandle?: NodeJS.Timeout;
+}
+/** Serialisable, stable subset of a task for logs, tools, and the trace. */
+export interface TaskSummary {
+    id: string;
+    parentTaskId?: string;
+    agentName: string;
+    sessionId: string;
+    status: TaskStatus;
+    cwd: string;
+    depth: number;
+    model?: string;
+    durationMs?: number;
+}
+export interface CreateTaskOpts {
+    agentName: string;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    parentTaskId?: string;
+    model?: string;
+    timeoutMs?: number;
+    /** Abort this task when the given signal fires. */
+    abortOnParent?: AbortSignal;
+    /** Defaults to true. When false, the task starts in 'queued'. */
+    autoStart?: boolean;
+}
+export declare class TaskManager {
+    private readonly tasks;
+    private readonly watchers;
+    private counter;
+    private readonly sessionId;
+    private readonly bus;
+    constructor(opts: {
+        sessionId: string;
+        bus?: EventBus;
+    });
+    /** Create a task. Blocks instead of running when the recursion cap is exceeded. */
+    create(opts: CreateTaskOpts): TaskRecord;
+    /** Look up a live record. */
+    get(id: string): TaskRecord | undefined;
+    /** List tasks, optionally filtered by parent and/or status. Returns summaries. */
+    list(filter?: {
+        parentTaskId?: string;
+        status?: TaskStatus;
+    }): TaskSummary[];
+    /** Transition a task to a terminal status and resolve its `done`. */
+    finish(id: string, status: 'succeeded' | 'failed' | 'cancelled' | 'timed_out' | 'blocked', patch?: {
+        summary?: string[];
+        error?: TaskError;
+    }): TaskRecord;
+    /** Cancel a live task: abort, mark cancelled/timed_out, resolve done. */
+    cancel(id: string, reason?: string, finalStatus?: 'cancelled' | 'timed_out'): TaskRecord;
+    /** Confirm a task that policy/depth prevented from running. */
+    block(id: string, reason: string): TaskRecord;
+    /** Cancel `id` and every transitive descendant. */
+    cancelTree(id: string, reason?: string): Promise<void>;
+    /** Subscribe to status transitions for one task. Delivers the current status immediately. */
+    subscribe(id: string, listener: (r: TaskRecord) => void): () => void;
+    /** Cancel every live task (used on shutdown / ctrl-c). */
+    shutdown(): Promise<void>;
+    /** Compact serialisable summary. */
+    toSummary(r: TaskRecord): TaskSummary;
+    /** Resolve a record's `done` (idempotent). */
+    private resolve;
+    private _resolveOnce;
+    /** Deliver a transition to the task's own watchers, then each ancestor's. */
+    private emit;
+    private notify;
+}