klyro 1.0.0 → 1.0.2

package/dist/agent/child-worker.js

@@ -0,0 +1,250 @@
+/**
+ * G2 — Process isolation for sub-agents (V1: headless/CLI children).
+ *
+ * This module is the *child-process* end of spawn_agent. The orchestrator
+ * forks this file with `node` (never shares a process), passing a
+ * JSON-serializable payload on STDIN (not argv — the system prompt + memory
+ * can exceed argv/command-line length limits, which would fail the spawn with
+ * E2BIG). The child rebuilds a minimal but self-sufficient `RuntimeDeps`,
+ * runs the task through `run()`, emits ONE JSON `ChildResult` line on stdout,
+ * and exits 0/1.
+ *
+ * Isolation contract: a child that OOMs, segfaults, or enters an infinite
+ * loop fails ONLY this process — the parent harness survives and reports
+ * `CHILD_CRASH` exactly as it does for an in-process throw.
+ *
+ * V1 scope (documented honestly):
+ *   - Headless children only. TUI children stay in-process because the Ink
+ *     approval bridge is inherently tied to the parent terminal.
+ *   - The child runs a system-prompt STRING (already assembled by the parent,
+ *     so KLYRO.md + memory + trust decisions match) with a file-system tool
+ *     subset and DenyAll approval — no MCP server forwarding, no live prompt.
+ *   - Grandchild spawning is not forwarded: a process-isolated child rebuilds
+ *     its own agent bridge-less deps, so its tools see NO_ORCHESTRATOR (same
+ *     as a pre-bridge child). V2 may thread a task handle back via a socket.
+ *
+ * Secrets never cross the process boundary via argv/env leaks: the child
+ * reads its provider key/baseURL from the SAME env the parent CLI uses
+ * (KLYRO_API_KEY, KLYRO_BASE_URL), so credentials stay in-process/env,
+ * never in the payload.
+ */
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { run } from './runtime.js';
+/**
+ * Differently-phrased crash, distinct from an in-process throw the parent
+ * would catch. The child either exited non-zero without a parseable result
+ * line, or produced a malformed result. Carries the raw stdout/stderr tail.
+ */
+export class ChildCrashError extends Error {
+    likelyCause;
+    stderrTail;
+    constructor(message, likelyCause, stderrTail) {
+        super(message);
+        this.likelyCause = likelyCause;
+        this.stderrTail = stderrTail;
+        this.name = 'ChildCrashError';
+    }
+}
+/**
+ * Resolve the compiled child-worker entry that *this* module's neighboring
+ * build (src or dist) produced. Both dev (tsx, .ts) and packaged (dist, .js)
+ * layouts live beside this file, so we probe for whichever exists.
+ */
+export function workerEntryPath() {
+    const here = fileURLToPath(import.meta.url);
+    const dir = path.dirname(here);
+    for (const ext of ['js', 'ts']) {
+        const candidate = path.join(dir, `child-worker.${ext}`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // Fall back to the compiled name — the load path both layouts converge on.
+    return path.join(dir, 'child-worker.js');
+}
+/**
+ * Fork the child-worker as a real OS process and await its single JSON
+ * ChildResult line. Secrets never reach argv: the payload rides stdin, the
+ * provider key/baseURL come from the inherited env. Non-zero exit / missing
+ * line → rejects with ChildCrashError so the orchestrator maps it to
+ * CHILD_CRASH exactly as an in-process throw does.
+ */
+export async function forkChild(entry, payload, opts = {}) {
+    const isTs = entry.endsWith('.ts');
+    // tsx dev: run under the tsx loader; prod dist: plain node.
+    const args = isTs ? ['--import', 'tsx/esm', entry] : [entry];
+    const child = spawn(process.execPath, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: process.env,
+        windowsHide: true,
+        shell: false,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (c) => { stdout += c; });
+    child.stderr.on('data', (c) => { opts.onStderr?.(c); stderr += c; });
+    // Write the payload to stdin, then signal EOF so the child knows it has
+    // the whole payload before it starts running.
+    child.stdin.on('error', () => { });
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+    const timeout = opts.timeoutMs ?? 10 * 60_000;
+    let killedForTimeout = false;
+    const timer = setTimeout(() => {
+        killedForTimeout = true;
+        try {
+            child.kill();
+        }
+        catch { /* already gone */ }
+    }, timeout);
+    const abortListener = () => { try {
+        child.kill();
+    }
+    catch { /* already gone */ } };
+    if (opts.signal?.aborted)
+        abortListener();
+    opts.signal?.addEventListener('abort', abortListener, { once: true });
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', abortListener);
+        };
+        child.on('error', (err) => {
+            cleanup();
+            reject(new ChildCrashError(`child spawn failed: ${err.message}`, 'exit'));
+        });
+        child.on('close', (code, signal) => {
+            cleanup();
+            const first = stdout.split('\n').find((l) => l.trim().length > 0);
+            if (code === 0 && first) {
+                try {
+                    resolve(JSON.parse(first));
+                }
+                catch {
+                    reject(new ChildCrashError('child exited 0 but emitted malformed ChildResult', 'exit', stderr.slice(-1000)));
+                }
+                return;
+            }
+            const cause = signal === 'SIGKILL' || signal === 'SIGTERM'
+                ? (killedForTimeout ? 'timeout' : 'oom')
+                : 'exit';
+            reject(new ChildCrashError(`child exited ${code ?? signal ?? '??'} without a ChildResult` + (stderr ? `: ${stderr.slice(-500)}` : ''), cause, stderr.slice(-1000)));
+        });
+    });
+}
+/**
+ * Rebuild a minimal RuntimeDeps from the payload + inherited env. Centralized
+ * so tests can call it directly. Errors on missing provider config.
+ */
+export async function buildChildDeps(payload) {
+    const provider = process.env.KLYRO_PROVIDER ?? 'openai';
+    const baseUrl = process.env.KLYRO_BASE_URL;
+    const apiKey = process.env.KLYRO_API_KEY;
+    if (!apiKey)
+        throw new Error('KLYRO_API_KEY is not set in the child environment');
+    let adapter;
+    if (provider === 'anthropic') {
+        const { anthropicAdapter } = await import('./anthropic-adapter.js');
+        adapter = anthropicAdapter({ baseURL: baseUrl, apiKey, timeoutMs: 240_000 });
+    }
+    else {
+        if (!baseUrl) {
+            throw new Error(`KLYRO_BASE_URL is not set for provider "${provider}" in the child environment`);
+        }
+        const { httpChatAdapter } = await import('./provider-adapter.js');
+        adapter = httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: 240_000 });
+    }
+    const { builtinRegistry } = await import('../tools/registry.js');
+    const { builtinRules, clonePolicyConfig, PolicyEngine } = await import('../policy/engine.js');
+    const { DenyAllApprovalPrompt } = await import('../policy/approval.js');
+    // File-system-only tool subset is the policy node's concern, handled by the
+    // parent's scoping; the child just needs a working registry. DenyAll keeps
+    // any tool that genuinely needs a user-prompt from stalling the child.
+    const deps = {
+        adapter,
+        registry: builtinRegistry(),
+        policy: new PolicyEngine(builtinRules(), clonePolicyConfig()),
+        approval: new DenyAllApprovalPrompt(),
+        systemPrompt: () => payload.systemPrompt,
+    };
+    const options = {
+        task: payload.task,
+        cwd: path.resolve(payload.cwd),
+        model: payload.model,
+        maxSteps: payload.maxSteps,
+        maxCost: payload.maxCost,
+        maxTimeMs: payload.maxTimeMs,
+        ...(payload.maxTokens !== undefined ? { maxTokens: payload.maxTokens } : {}),
+        nonInteractive: true,
+    };
+    return { deps, options };
+}
+/**
+ * Read the JSON payload. Payloads arrive on stdin (the parent writes the JSON
+ * then ends stdin), never argv — large system prompts would otherwise fail
+ * the spawn with E2BIG on both Windows (32K cmdline) and Linux (MAX_ARG_STRLEN).
+ * Callers who must use argv (tests) can route through `runChildFromString`.
+ */
+export function readPayloadFromStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on('data', (c) => chunks.push(c));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        process.stdin.on('error', reject);
+    });
+}
+/**
+ * Main entry. Reads payload from stdin, runs, prints ONE JSON ChildResult
+ * line, exits 0 on complete, 1 on failure/crash (so the parent knows to mark
+ * CHILD_CRASH). Intended to be the sole behavior of this file when invoked as
+ * a real process.
+ */
+export async function main() {
+    let raw;
+    try {
+        raw = await readPayloadFromStdin();
+    }
+    catch (e) {
+        process.stderr.write(`child-worker: failed reading payload: ${e}\n`);
+        process.exit(2);
+    }
+    if (!raw) {
+        process.stderr.write('child-worker: missing payload on stdin\n');
+        process.exit(2);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (e) {
+        process.stderr.write(`child-worker: invalid payload: ${e}\n`);
+        process.exit(2);
+    }
+    try {
+        const { deps, options } = await buildChildDeps(payload);
+        const result = await run(options, deps);
+        const out = {
+            status: result.status,
+            steps: result.steps,
+            toolCalls: result.toolCalls,
+            finalText: result.finalText,
+            hasEdits: result.hasEdits,
+            usage: result.usage,
+        };
+        process.stdout.write(JSON.stringify(out));
+        process.exit(result.status === 'complete' ? 0 : 1);
+    }
+    catch (err) {
+        process.stderr.write(`child-worker: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}
+// Run directly only when executed as a child process (not imported by tests).
+// Match both bare "child-worker" and the compiled "child-worker.js".
+if (process.argv[1] && /child-worker(?:\.js)?$/.test(process.argv[1])) {
+    void main();
+}

package/dist/agent/orchestrator.d.ts

@@ -12,11 +12,15 @@
  * 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, RuntimeEvent } from './runtime.js';
 import type { ToolResult } from '../tools/types.js';
-import { TaskManager, type TaskStatus, type TaskSummary } from './task-manager.js';
+import { TaskManager, type TaskRecord, type TaskStatus, type TaskSummary } from './task-manager.js';
 import { WorkerSpawner } from './worker-spawner.js';
 import { type DropReason } from './capabilities.js';
+/** Concurrency budgets enforced in `spawnAgent` (CONCURRENCY_LIMIT on exceed). */
+export declare const MAX_CONCURRENT_TASKS = 4;
+export declare const MAX_TASKS_PER_PARENT = 8;
+export declare const MAX_TOTAL_TASKS_PER_SESSION = 32;
 /** An agent a model can delegate to via `spawn_agent`. */
 export interface AgentDefinition {
     id: string;
@@ -32,6 +36,13 @@ export interface AgentDefinition {
     maxSteps?: number;
     maxCost?: number;
     maxTimeMs?: number;
+    /** Token budget forwarded to the child's run options. */
+    maxTokens?: number;
+    /**
+     * Filesystem allow-list for this agent; intersected with the parent's at
+     * spawn time (`undefined` = no additional constraint).
+     */
+    allowedPaths?: string[];
 }
 /** Default agents a model can delegate to. */
 export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
@@ -68,6 +79,21 @@ export interface ParentContextRef {
     maxDepth: number;
     allowedTools: ReadonlySet<string> | null;
     model?: string;
+    /**
+     * Effective filesystem allow-list threaded through to the child (sibling C
+     * enforces it in fs tools). `undefined` = unconstrained.
+     */
+    allowedPaths?: string[];
+}
+/** One awaited task entry returned by `waitForTasks`. */
+export interface WaitedTask {
+    taskId: string;
+    status: TaskStatus;
+    summary?: ChildSummary;
+    error?: {
+        code: string;
+        message: string;
+    };
 }
 /** Interface exposed to the runtime/tools for a child spawn request. */
 export interface AgentSpawnBridge {
@@ -91,6 +117,32 @@ export interface AgentSpawnBridge {
             message: string;
         };
     } | undefined;
+    /**
+     * Return completed-then-undrained child summaries. Each completed task is
+     * drained exactly once — subsequent calls omit it. Optional so older
+     * (sibling A) bridge fakes still satisfy the type.
+     */
+    drainCompletions?(): ChildSummary[];
+    /**
+     * Await each task's `record.done` up to `timeoutMs` (per task). Entries
+     * that do not settle in time are returned with status `'running'` — the
+     * underlying task is NOT cancelled. Never throws for unknown ids: they
+     * come back as `{ status: 'failed', error: NOT_FOUND }`.
+     */
+    waitForTasks?(taskIds: string[], timeoutMs?: number): Promise<{
+        tasks: WaitedTask[];
+    }>;
+    /** Signal abort for a live task (in-process workers; no subprocesses yet — no process tree to kill). Idempotent on terminal tasks. */
+    cancelTask?(taskId: string): ToolResult<{
+        taskId: string;
+        status: TaskStatus;
+    }>;
+    /**
+     * Merge a succeeded task's worktree branch into the parent tree (or
+     * acknowledge a shared-cwd task) and emit `subtask.merged`. Errors with
+     * NOT_FOUND / NOT_READY / MERGE_CONFLICT.
+     */
+    applyTask?(taskId: string): Promise<ToolResult<ChildSummary>>;
 }
 /** Constructor options for the orchestrator — the parent runtime's deps. */
 export interface OrchestratorOpts {
@@ -98,12 +150,40 @@ export interface OrchestratorOpts {
     deps: RuntimeDeps;
     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.
+     */
+    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;
     readonly taskManager: TaskManager;
     readonly workerSpawner: WorkerSpawner;
+    readonly isTui: boolean;
+    /** Per-task spawn metadata: capability drops + worktree placement. */
+    private readonly taskMeta;
+    /** Finished summaries not yet drained via `drainCompletions`. */
+    private readonly undrained;
     constructor(opts: OrchestratorOpts);
     listAgents(): AgentDefinition[];
     getAgent(id: string): AgentDefinition | undefined;
@@ -112,9 +192,10 @@ export declare class AgentOrchestrator {
     /** Compute a child's effective capabilities from the parent's own. */
     private resolveChild;
     /**
-     * Spawn a child agent for a given capability context, await its run, and
-     * return a compact summary. Blocks until the child settles (P0 scope;
-     * async task_wait arrives in a later slice).
+     * Spawn a child agent asynchronously: start the child worker and return
+     * IMMEDIATELY with `{ status: 'running' }`. Completion/failure bus emits
+     * and `taskManager.finish` happen in the worker closure; the parent
+     * observes them via `task_wait` / `task_get` / `drainCompletions`.
      */
     spawnAgent(input: {
         agent: string;
@@ -123,7 +204,44 @@ export declare class AgentOrchestrator {
         model?: string;
         timeoutMs?: number;
     }, parent: ParentContextRef): Promise<ToolResult<ChildSummary>>;
-    private toChildSummary;
+    /**
+     * Settle a child in the worker closure: finish the task (idempotent —
+     * a TaskManager timeout/cancel that fired first wins), emit the terminal
+     * bus event, stash the summary for `drainCompletions`, and best-effort
+     * remove the worktree unless the child succeeded (merge happens later in
+     * `task_apply`).
+     */
+    private settleChild;
+    /** Build and stash the finished summary for `drainCompletions`. */
+    private stashSummary;
+    /** Completed-then-undrained child summaries; each drained exactly once. */
+    drainCompletions(): ChildSummary[];
+    /**
+     * Await each task's `done` up to `timeoutMs` per task. Unsettled entries
+     * come back with status `'running'` and a running summary — the underlying
+     * task is NOT cancelled.
+     */
+    waitForTasks(taskIds: string[], timeoutMs?: number): Promise<{
+        tasks: WaitedTask[];
+    }>;
+    private awaitDone;
+    /** Signal abort for a live task via `taskManager.cancel` (in-process workers; no subprocesses yet). Idempotent on terminal tasks. */
+    cancelTask(taskId: string): ToolResult<{
+        taskId: string;
+        status: TaskStatus;
+    }>;
+    /**
+     * Apply a succeeded task: merge its worktree branch into the parent tree
+     * (or acknowledge a shared-cwd task whose edits already landed) and emit
+     * `subtask.merged`. Non-succeeded tasks error with NOT_READY; merge
+     * conflicts error with MERGE_CONFLICT (merge already aborted, branch kept).
+     */
+    applyTask(taskId: string): Promise<ToolResult<ChildSummary>>;
+    /** Compact summary for a task record (also used by task_wait). */
+    toChildSummary(r: TaskRecord, def: AgentDefinition, dropped: {
+        tool: string;
+        reason: DropReason;
+    }[]): ChildSummary;
 }
 /** Module-scoped holder the orchestrator sets so children inherit the parent's signal. */
 export declare const parentAbortSignalRef: {