klyro 1.0.1 → 1.0.3

package/dist/agent/anthropic-adapter.d.ts

@@ -72,6 +72,9 @@ interface AnthropicRequest {
         name: string;
         description: string;
         input_schema: unknown;
+        cache_control?: {
+            type: 'ephemeral';
+        };
     }>;
     max_tokens: number;
     temperature?: number;
@@ -94,6 +97,14 @@ export declare function anthropicAdapter(opts: AnthropicAdapterOptions): Provide
  * Exported via _internal for testing.
  */
 export declare function buildAnthropicSystem(system: string | undefined, suffix: string | undefined, promptCache: boolean): AnthropicRequest['system'];
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export declare function buildAnthropicTools(tools: ToolDefinition[], promptCache: boolean): AnthropicRequest['tools'];
 /**
  * Mutable per-stream assembly state. Blocks are keyed by content_block
  * index; the tool id is carried inside the block entry. There is no global
@@ -118,15 +129,12 @@ interface AnthropicStreamState {
 }
 declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
 declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
-declare function toAnthropicTool(t: ToolDefinition): {
-    name: string;
-    description: string;
-    input_schema: unknown;
-};
+declare function toAnthropicTool(t: ToolDefinition): NonNullable<AnthropicRequest['tools']>[number];
 export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
     translateSse: typeof translateSse;
     buildAnthropicSystem: typeof buildAnthropicSystem;
+    buildAnthropicTools: typeof buildAnthropicTools;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -75,12 +75,29 @@ export function buildAnthropicSystem(system, suffix, promptCache) {
         return undefined;
     return promptCache ? [{ type: 'text', text: system, ...breakpoint }] : system;
 }
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export function buildAnthropicTools(tools, promptCache) {
+    if (tools.length === 0)
+        return undefined;
+    const out = tools.map(toAnthropicTool);
+    if (promptCache) {
+        const last = out[out.length - 1];
+        last.cache_control = { type: 'ephemeral' };
+    }
+    return out;
+}
 async function* streamAnthropic(req, opts) {
     const body = {
         model: req.model,
         system: buildAnthropicSystem(req.system, req.systemSuffix, opts.promptCache),
         messages: toAnthropicMessages(req.messages),
-        tools: req.tools.length > 0 ? req.tools.map(toAnthropicTool) : undefined,
+        tools: buildAnthropicTools(req.tools, opts.promptCache),
         max_tokens: req.maxTokens ?? 4096,
         temperature: req.temperature,
         stream: true,
@@ -430,4 +447,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem, buildAnthropicTools };

package/dist/agent/capabilities.js

@@ -187,5 +187,11 @@ export const DEFAULT_SPAWN_TOOLS = new Set([
 ]);
 /** Default deny-list — these are NEVER allowed, even if explicitly requested. */
 export const DEFAULT_DENIED_TOOLS = new Set([
-// Add dangerous tools here. Empty by default — extend as policy matures.
+// Intentionally empty. Deny happens per-pattern (shellDenyRule /
+// DANGEROUS_PATTERNS, .env guards, repair-guard), not per-tool: a
+// tool-granularity deny-all entry (e.g. banning `shell_exec` outright)
+// would break legitimate flows that rely on the allowlist + approval
+// path. Seed candidates considered and rejected: `shell_exec` (needed
+// for tests/builds via approval), `run_verify` (needed by tester/
+// implementer agents), `write_file`/`edit_file` (core agent function).
 ]);

package/dist/agent/orchestrator.d.ts

@@ -12,7 +12,7 @@
  * The compact result is a `ChildSummary` — a `ToolResult` the parent model
  * can act on — never the full child transcript.
  */
-import type { RuntimeDeps } from './runtime.js';
+import type { RuntimeDeps, RunOptions, RuntimeEvent } from './runtime.js';
 import type { ToolResult } from '../tools/types.js';
 import { TaskManager, type TaskRecord, type TaskStatus, type TaskSummary } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
@@ -151,12 +151,31 @@ export interface OrchestratorOpts {
     taskManager?: TaskManager;
     workerSpawner?: WorkerSpawner;
     /**
-     * True when the parent is the interactive TUI. TUI children stay in-process
-     * (V1 limitation — the Ink approval bridge is tied to the parent terminal),
-     * while headless/CLI children run process-isolated. Defaults to false.
+     * True when the parent is the interactive TUI. TUI children run
+     * process-isolated *unless* they may need to surface an approval prompt to
+     * the operator (see childCanIsolate) — the Ink bridge is tied to the parent
+     * terminal, so a prompting child must stay in-process. Headless/CLI children
+     * always isolate. Defaults to false.
      */
     isTui?: boolean;
 }
+/**
+ * Build a `subtask.progress` note for one finished tool call.
+ * Pure — unit-tested directly (see agent-tools.test.ts).
+ */
+export declare function progressNote(step: number, tool: string, isError: boolean): string;
+/**
+ * Build the `RunOptions.onEvent` handler the orchestrator passes into each
+ * child's run options. Emits at most one `subtask.progress` per tool call:
+ * a `tool_result` is only mirrored when its `tool_call_end` was observed
+ * first, so duplicate/late results can never double-emit. (The note needs
+ * the ok/ERR outcome, which only `tool_result` carries — `tool_call_end`
+ * alone cannot build it — hence the end-gated result throttle.)
+ */
+export declare function createSubtaskProgressEmitter(opts: {
+    taskId: string;
+    sessionId: string;
+}): (ev: RuntimeEvent) => void;
 export declare class AgentOrchestrator {
     readonly sessionId: string;
     readonly deps: RuntimeDeps;
@@ -172,6 +191,27 @@ export declare class AgentOrchestrator {
     getAgent(id: string): AgentDefinition | undefined;
     /** Build the bridge the parent's runtime hands to tools. */
     bridgeFor(parent: ParentContextRef): AgentSpawnBridge;
+    /**
+     * R2 — decide whether a child may run process-isolated.
+     *
+     * The only thing that forces a child to stay in-process is the possibility
+     * of an interactive approval prompt: the Ink bridge lives in the parent
+     * terminal, so a subprocess could never ask. A child that cannot prompt is
+     * therefore free to isolate.
+     *
+     * A child cannot prompt when any of these hold:
+     *   - it is readonly (no write/execute tools → no `ask` on those),
+     *   - the parent is not a TUI (no bridge to reach in the first place), or
+     *   - the child's toolset contains no tool the policy can put in `ask`.
+     *
+     * Isolation is deliberately conservative here: when in doubt we keep the
+     * child in-process, because a stranded prompt is a hang and a hang is worse
+     * than lost isolation. Public for direct unit testing.
+     */
+    childCanIsolate(resolved: {
+        allowed: ReadonlySet<string>;
+        readonly: boolean;
+    }, def: AgentDefinition, childOptions: RunOptions): boolean;
     /** Compute a child's effective capabilities from the parent's own. */
     private resolveChild;
     /**

package/dist/agent/orchestrator.js

@@ -87,6 +87,45 @@ function mapResultStatus(status) {
             return 'failed';
     }
 }
+/**
+ * Build a `subtask.progress` note for one finished tool call.
+ * Pure — unit-tested directly (see agent-tools.test.ts).
+ */
+export function progressNote(step, tool, isError) {
+    return `step ${step}: ${tool} ${isError ? 'ERR' : 'ok'}`;
+}
+/**
+ * Build the `RunOptions.onEvent` handler the orchestrator passes into each
+ * child's run options. Emits at most one `subtask.progress` per tool call:
+ * a `tool_result` is only mirrored when its `tool_call_end` was observed
+ * first, so duplicate/late results can never double-emit. (The note needs
+ * the ok/ERR outcome, which only `tool_result` carries — `tool_call_end`
+ * alone cannot build it — hence the end-gated result throttle.)
+ */
+export function createSubtaskProgressEmitter(opts) {
+    let step = 0;
+    const ended = new Set();
+    return (ev) => {
+        if (ev.kind === 'step_start') {
+            step = ev.step;
+        }
+        else if (ev.kind === 'tool_call_end') {
+            ended.add(ev.id);
+        }
+        else if (ev.kind === 'tool_result') {
+            if (!ended.has(ev.id))
+                return;
+            ended.delete(ev.id);
+            globalBus.emit({
+                type: 'subtask.progress',
+                ts: Date.now(),
+                sessionId: opts.sessionId,
+                taskId: opts.taskId,
+                note: progressNote(step, ev.name, ev.isError),
+            });
+        }
+    };
+}
 export class AgentOrchestrator {
     sessionId;
     deps;
@@ -131,6 +170,45 @@ export class AgentOrchestrator {
             applyTask: (taskId) => this.applyTask(taskId),
         };
     }
+    /**
+     * R2 — decide whether a child may run process-isolated.
+     *
+     * The only thing that forces a child to stay in-process is the possibility
+     * of an interactive approval prompt: the Ink bridge lives in the parent
+     * terminal, so a subprocess could never ask. A child that cannot prompt is
+     * therefore free to isolate.
+     *
+     * A child cannot prompt when any of these hold:
+     *   - it is readonly (no write/execute tools → no `ask` on those),
+     *   - the parent is not a TUI (no bridge to reach in the first place), or
+     *   - the child's toolset contains no tool the policy can put in `ask`.
+     *
+     * Isolation is deliberately conservative here: when in doubt we keep the
+     * child in-process, because a stranded prompt is a hang and a hang is worse
+     * than lost isolation. Public for direct unit testing.
+     */
+    childCanIsolate(resolved, def, childOptions) {
+        // Headless parents have no approval bridge — isolation is always safe.
+        if (!this.isTui)
+            return true;
+        // Readonly agents never write/execute, so never prompt.
+        if (resolved.readonly)
+            return true;
+        // A child with an inherited bridge (grandchildren possible) must stay
+        // in-process: its own children need the bridge chain.
+        if (childOptions.agentBridge)
+            return false;
+        // Any tool in the child's set that the policy can escalate to `ask`
+        // pins it in-process. `execute` is the class that most commonly prompts
+        // (shell_exec), so its presence is the deciding signal alongside writes.
+        const prompting = new Set(['shell_exec', 'write_file', 'edit_file', 'multi_edit', 'apply_patch', 'run_verify']);
+        for (const t of resolved.allowed) {
+            if (prompting.has(t))
+                return false;
+        }
+        void def;
+        return true;
+    }
     /** Compute a child's effective capabilities from the parent's own. */
     resolveChild(def, parent, registryTools) {
         const input = {
@@ -212,14 +290,17 @@ export class AgentOrchestrator {
         const registryTools = new Set(this.deps.registry.list().map((t) => t.name));
         const resolved = this.resolveChild(def, parent, registryTools);
         const childModel = input.model ?? resolved.model ?? parent.model;
-        // Worktree isolation: write-capable children without an explicit cwd get
-        // their own worktree; readonly agents keep the parent cwd. A
-        // write-capable spawn outside a git repo is rejected outright.
+        // Worktree isolation: write-capable children get their own worktree —
+        // including when the spawn carries an explicit cwd (the worktree is
+        // then rooted at the resolved explicit cwd, which containment above
+        // already pinned inside the parent). Readonly agents keep the resolved
+        // cwd with no worktree. A write-capable spawn outside a git repo is
+        // rejected outright.
         const writeCapable = [...resolved.allowed].some((t) => DEFAULT_WRITE_TOOLS.has(t));
         let childCwd = baseCwd;
         let worktree;
         let repoCwd;
-        if (!resolved.readonly && writeCapable && !input.cwd) {
+        if (!resolved.readonly && writeCapable) {
             const isRepo = await ensureGitRepo(baseCwd).catch(() => false);
             if (!isRepo) {
                 return {
@@ -285,6 +366,11 @@ export class AgentOrchestrator {
             maxTimeMs: def.maxTimeMs ?? input.timeoutMs,
             signal: record.abortController.signal,
             nonInteractive: true,
+            // Mid-life progress: mirror each finished tool call as one
+            // `subtask.progress` bus event (see createSubtaskProgressEmitter).
+            // Process-isolated children don't run this closure — only the
+            // in-process path reports mid-life progress.
+            onEvent: createSubtaskProgressEmitter({ taskId: record.id, sessionId: this.sessionId }),
             // Grandchildren: only children that canSpawn receive the bridge —
             // otherwise tools see NO_ORCHESTRATOR as before.
             ...(resolved.canSpawn ? { agentBridge: this.bridgeFor(childRef) } : {}),
@@ -301,10 +387,18 @@ export class AgentOrchestrator {
             depth: childDepth,
             ...(typeof childModel === 'string' ? { model: childModel } : {}),
         });
-        // G2 — process isolation for headless sub-agents. In-process is the
-        // fallback (and mandatory for TUI children — see OrchestratorOpts.isTui),
-        // and opt-out via KLYRO_WORKER=0 for tests/dev.
-        const useProcessIsolation = !this.isTui && process.env.KLYRO_WORKER !== '0';
+        // G2/R2 — process isolation for sub-agents. A child can be spawned as a
+        // real OS process whenever it will never need to surface an interactive
+        // approval prompt to the operator. Every child that might prompt must stay
+        // in-process so the TUI approval bridge (tied to the parent terminal) can
+        // reach the operator. Headless/readonly/DenyAll children — which is the
+        // ordinary case — isolate into a subprocess. The blanket exclusion of ALL
+        // TUI children (V1) is replaced by this capability-aware rule, so a TUI
+        // session with readonly or non-interactive children gets real isolation
+        // too. Explicitly opt out with KLYRO_WORKER=0.
+        // See orchestratorOpts.isTui, capabilities.resolveCapabilities, and
+        // child-worker.buildChildDeps (DenyAll approval).
+        const useProcessIsolation = process.env.KLYRO_WORKER !== '0' && this.childCanIsolate(resolved, def, childOptions);
         this.workerSpawner.spawn(async (signal) => {
             // Both the in-process path and the forked child resolve to the same
             // minimal outcome shape the settle tail needs.

package/dist/agent/retry.js

@@ -17,6 +17,7 @@
  *
  * The default policy matches the L6 plan: 5 attempts, 500ms base, 8s cap.
  */
+import { acquireStreamSlot, noteRateLimited } from './stream-budget.js';
 export const DEFAULT_RETRY = {
     maxAttempts: 5,
     baseMs: 500,
@@ -88,6 +89,28 @@ export function computeBackoff(attempt, baseMs, maxMs) {
     const jitter = exp * 0.25 * (Math.random() * 2 - 1);
     return Math.max(0, Math.floor(exp + jitter));
 }
+/**
+ * True when a retryable error event carries a 429 rate-limit signal.
+ * Checks the `status` field first, then `code`; accepts numeric values
+ * and `'429'` substrings (e.g. `'429'`, `'HTTP_429'`).
+ */
+function isRateLimitedError(ev) {
+    if (ev.kind !== 'error')
+        return false;
+    const rec = ev;
+    for (const key of ['status', 'code']) {
+        const value = rec[key];
+        if (typeof value === 'string' && value.includes('429'))
+            return true;
+        if (typeof value === 'number' && String(value).includes('429'))
+            return true;
+    }
+    return false;
+}
+function rateLimitDelayMs(ev) {
+    const raw = ev['retryAfterMs'];
+    return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
 export function retryingAdapter(inner, opts = {}) {
     const cfg = { ...DEFAULT_RETRY, ...opts };
     const sleep = opts.sleep ?? defaultSleep;
@@ -129,20 +152,39 @@ export function retryingAdapter(inner, opts = {}) {
                 opts.onAttempt?.(attempt);
                 if (effectiveSignal?.aborted)
                     return;
+                // Rate-limit scheduler: hold one stream slot for the duration of
+                // this attempt's inner.stream consumption. Abort while queued ends
+                // the stream promptly with no inner call.
+                let release;
                 let sawRetryable = false;
                 let lastError = null;
-                for await (const ev of streamWithAbort(inner.stream(attemptReq), effectiveSignal)) {
-                    if (effectiveSignal?.aborted)
+                try {
+                    try {
+                        release = await acquireStreamSlot(effectiveSignal);
+                    }
+                    catch {
                         return;
-                    if (ev.kind === 'error' && ev.retryable) {
-                        // Buffer the retryable error; don't yield it yet. We'll either
-                        // re-issue (and the caller will never see the error) or, on
-                        // final attempt, yield it as the terminal error.
-                        sawRetryable = true;
-                        lastError = ev;
-                        break; // stop consuming; the stream is dead on retryable errors.
                     }
-                    yield ev;
+                    for await (const ev of streamWithAbort(inner.stream(attemptReq), effectiveSignal)) {
+                        if (effectiveSignal?.aborted)
+                            return;
+                        if (ev.kind === 'error' && ev.retryable) {
+                            // Adaptive throttling: a 429 collapses the global stream cap
+                            // to 1 for retryAfterMs (or 60s) — see stream-budget.ts.
+                            if (isRateLimitedError(ev))
+                                noteRateLimited(rateLimitDelayMs(ev));
+                            // Buffer the retryable error; don't yield it yet. We'll either
+                            // re-issue (and the caller will never see the error) or, on
+                            // final attempt, yield it as the terminal error.
+                            sawRetryable = true;
+                            lastError = ev;
+                            break; // stop consuming; the stream is dead on retryable errors.
+                        }
+                        yield ev;
+                    }
+                }
+                finally {
+                    release?.();
                 }
                 if (!sawRetryable)
                     return; // success or non-retryable error — done.

package/dist/agent/runtime.d.ts

@@ -31,6 +31,13 @@ export type VerifyMode = typeof import('../verification/engine.js') extends {
 } ? V : 'strict' | 'advisory' | 'off';
 export interface RuntimeDeps {
     adapter: ProviderAdapter;
+    /**
+     * Ordered failover adapters (L15). When the active adapter ends a step
+     * with a terminal provider error, the runtime swaps to the next entry
+     * and re-issues the step (bounded by chain length, never loops).
+     * Optional — single-adapter callers behave exactly as before.
+     */
+    failoverAdapters?: ProviderAdapter[];
     registry: ToolRegistry;
     policy: PolicyEngine;
     approval: ApprovalPrompt;
@@ -226,6 +233,22 @@ export type RuntimeEvent = {
 } | {
     kind: 'checkpoint_saved';
     sessionId: string;
+} | {
+    kind: 'status';
+    message: string;
+} | {
+    kind: 'budget_warning';
+    ratio: number;
+    threshold: number;
+} | {
+    kind: 'provider_failover';
+    from: string;
+    to: string;
+    reason: string;
+} | {
+    kind: 'model_override';
+    requested: string;
+    effective: string;
 };
 export interface RunResult {
     status: 'complete' | 'max_steps' | 'aborted' | 'no_final' | 'verify_failed' | 'limit' | 'blocked' | 'stuck';
@@ -264,7 +287,18 @@ export declare function toolDefinitions(registry: ToolRegistry): ToolDefinition[
 export declare function estimateCost(model: string, usage: {
     input: number;
     output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
 }): number;
+/**
+ * Parallel fan-out cap: approved concurrencySafe tool calls execute in
+ * sequential chunks of at most this size. Commit order stays identical
+ * (commits run sequentially after execution), so the transcript reads as
+ * if the calls ran in order.
+ */
+export declare const MAX_PARALLEL_TOOLS = 8;
+/** Progressive budget-warning thresholds (fraction of maxCost), fired once each per run. */
+export declare const BUDGET_WARNING_THRESHOLDS: readonly [0.4, 0.7, 0.9];
 /** Run the autonomous loop. */
 export declare function run(opts: RunOptions, deps: RuntimeDeps): Promise<RunResult>;
 export declare function defaultSystemPrompt(ctx: {