klyro 0.1.63 → 1.0.0

package/dist/agent/task-manager.js

@@ -0,0 +1,250 @@
+/**
+ * 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 { globalBus } from '../events/bus.js';
+export class TaskManager {
+    tasks = new Map();
+    watchers = new Map();
+    counter = 0;
+    sessionId;
+    bus;
+    constructor(opts) {
+        this.sessionId = opts.sessionId;
+        this.bus = opts.bus ?? globalBus;
+    }
+    /** Create a task. Blocks instead of running when the recursion cap is exceeded. */
+    create(opts) {
+        const id = `task_${++this.counter}`;
+        const running = opts.autoStart !== false;
+        let resolveDone;
+        const record = {
+            id,
+            parentTaskId: opts.parentTaskId,
+            sessionId: this.sessionId,
+            agentName: opts.agentName,
+            status: running ? 'running' : 'queued',
+            cwd: opts.cwd,
+            depth: opts.depth,
+            maxDepth: opts.maxDepth,
+            model: opts.model,
+            startedAt: Date.now(),
+            summary: [],
+            abortController: new AbortController(),
+            done: new Promise((res) => {
+                resolveDone = res;
+            }),
+            _resolveDone: (r) => resolveDone(r),
+        };
+        this.tasks.set(id, record);
+        // Recursion / depth guard — enforced at the boundary so a deep-deep
+        // call chain can never be constructed in the first place.
+        if (opts.depth > opts.maxDepth) {
+            record.status = 'blocked';
+            record.timeoutHandle = undefined;
+            record.error = {
+                code: 'BLOCKED',
+                message: `recursion limit: depth ${opts.depth} exceeds maxDepth ${opts.maxDepth}`,
+            };
+            this.resolve(record);
+            this.emit(record);
+            return record;
+        }
+        // Parent abort → child abort chain.
+        if (opts.abortOnParent) {
+            const onAbort = () => this.cancel(id, 'parent aborted');
+            if (opts.abortOnParent.aborted) {
+                onAbort();
+            }
+            else {
+                opts.abortOnParent.addEventListener('abort', onAbort, { once: true });
+                record._cleanupParentAbort = () => opts.abortOnParent.removeEventListener('abort', onAbort);
+            }
+        }
+        // Timeout: transition to 'timed_out' and abort if still live.
+        if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+            record.timeoutHandle = setTimeout(() => {
+                const r = this.tasks.get(id);
+                if (r && (r.status === 'running' || r.status === 'queued')) {
+                    this.cancel(id, 'timeout', 'timed_out');
+                }
+            }, opts.timeoutMs);
+        }
+        this.emit(record);
+        return record;
+    }
+    /** Look up a live record. */
+    get(id) {
+        return this.tasks.get(id);
+    }
+    /** List tasks, optionally filtered by parent and/or status. Returns summaries. */
+    list(filter) {
+        const out = [];
+        for (const r of this.tasks.values()) {
+            if (filter?.parentTaskId !== undefined && r.parentTaskId !== filter.parentTaskId)
+                continue;
+            if (filter?.status !== undefined && r.status !== filter.status)
+                continue;
+            out.push(this.toSummary(r));
+        }
+        return out;
+    }
+    /** Transition a task to a terminal status and resolve its `done`. */
+    finish(id, status, patch) {
+        const r = this.get(id);
+        if (!r)
+            throw new Error(`unknown task: ${id}`);
+        if (status !== 'blocked' && r.timeoutHandle) {
+            clearTimeout(r.timeoutHandle);
+            r.timeoutHandle = undefined;
+        }
+        if (patch?.summary)
+            r.summary.push(...patch.summary);
+        r.status = status;
+        r.finishedAt = Date.now();
+        if (patch?.error)
+            r.error = patch.error;
+        this.resolve(r);
+        this.emit(r);
+        return r;
+    }
+    /** Cancel a live task: abort, mark cancelled/timed_out, resolve done. */
+    cancel(id, reason = 'cancelled', finalStatus = 'cancelled') {
+        const r = this.get(id);
+        if (!r)
+            throw new Error(`unknown task: ${id}`);
+        if (r.status !== 'queued' && r.status !== 'running')
+            return r; // idempotent on terminal
+        r.abortController.abort(reason);
+        r._cleanupParentAbort?.();
+        r._cleanupParentAbort = undefined;
+        if (r.timeoutHandle) {
+            clearTimeout(r.timeoutHandle);
+            r.timeoutHandle = undefined;
+        }
+        r.status = finalStatus;
+        r.finishedAt = Date.now();
+        r.error = {
+            code: finalStatus === 'timed_out' ? 'TIMED_OUT' : 'CANCELLED',
+            message: reason,
+        };
+        this.resolve(r);
+        this.emit(r);
+        return r;
+    }
+    /** Confirm a task that policy/depth prevented from running. */
+    block(id, reason) {
+        return this.finish(id, 'blocked', {
+            error: { code: 'BLOCKED', message: reason },
+        });
+    }
+    /** Cancel `id` and every transitive descendant. */
+    async cancelTree(id, reason = 'cancelled') {
+        const ids = [id];
+        const walk = (pid) => {
+            for (const r of this.tasks.values()) {
+                if (r.parentTaskId === pid) {
+                    ids.push(r.id);
+                    walk(r.id);
+                }
+            }
+        };
+        walk(id);
+        // Children first so a parent's abort doesn't race a child still being torn down.
+        ids.reverse();
+        for (const tid of ids) {
+            this.cancel(tid, reason);
+        }
+    }
+    /** Subscribe to status transitions for one task. Delivers the current status immediately. */
+    subscribe(id, listener) {
+        let set = this.watchers.get(id);
+        if (!set) {
+            set = new Set();
+            this.watchers.set(id, set);
+        }
+        set.add(listener);
+        const r = this.get(id);
+        if (r) {
+            try {
+                listener(r);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return () => {
+            set.delete(listener);
+            if (set.size === 0)
+                this.watchers.delete(id);
+        };
+    }
+    /** Cancel every live task (used on shutdown / ctrl-c). */
+    async shutdown() {
+        for (const id of [...this.tasks.keys()]) {
+            const r = this.get(id);
+            if (r && (r.status === 'queued' || r.status === 'running')) {
+                this.cancel(id, 'shutdown');
+            }
+        }
+    }
+    /** Compact serialisable summary. */
+    toSummary(r) {
+        return {
+            id: r.id,
+            ...(r.parentTaskId ? { parentTaskId: r.parentTaskId } : {}),
+            agentName: r.agentName,
+            sessionId: r.sessionId,
+            status: r.status,
+            cwd: r.cwd,
+            depth: r.depth,
+            ...(typeof r.model === 'string' ? { model: r.model } : {}),
+            ...(r.finishedAt ? { durationMs: r.finishedAt - r.startedAt } : {}),
+        };
+    }
+    /* ---------------------- internals ---------------------- */
+    /** Resolve a record's `done` (idempotent). */
+    resolve(r) {
+        this._resolveOnce(r);
+    }
+    _resolveOnce(r) {
+        try {
+            r._resolveDone(r);
+        }
+        catch {
+            /* already resolved */
+        }
+    }
+    /** Deliver a transition to the task's own watchers, then each ancestor's. */
+    emit(r) {
+        this.notify(r.id, r);
+        let pid = r.parentTaskId;
+        while (pid) {
+            const p = this.get(pid);
+            this.notify(pid, r);
+            pid = p?.parentTaskId;
+        }
+    }
+    notify(id, r) {
+        const set = this.watchers.get(id);
+        if (!set)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(r);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}

package/dist/agent/worker-spawner.d.ts

@@ -1,21 +1,23 @@
 /**
- * In-process worker spawner (MVP).
+ * In-process worker spawner.
  *
- * Per `docs/plan-fix.md` Step 2: workers run in-process for the MVP.
- * Real subprocess / child-process spawning belongs to a later level
- * (Level 7: sandboxed execution, Level 19: distributed workers).
+ * A "worker" here is just an async task tied to an AbortController. The
+ * spawner keeps the controllers so workers can actually be cancelled
+ * (user Ctrl+C, /abort, session shutdown, or a parent signalling a child).
  *
- * A "worker" here is just an async task with an AbortController. The
- * spawner keeps a registry so they can be cancelled together (e.g. on
- * user Ctrl+C, /abort, or session shutdown).
+ * Real subprocess / child-process spawning belongs to a later level;
+ * this module is the single-process cancellation primitive the agent
+ * orchestration layer builds on.
  */
 export interface WorkerHandle {
     /** Stable id, monotonically increasing per spawner instance. */
     readonly id: number;
     /** Human-readable label, used in logs. */
     readonly label: string;
-    /** AbortController tied to this worker's lifetime. */
+    /** AbortSignal delivered to the factory so it can observe cancellation. */
     readonly signal: AbortSignal;
+    /** The controller backing `signal` — retained so we can actually abort. */
+    readonly controller: AbortController;
     /** Resolves when the worker's main promise settles. */
     readonly done: Promise<void>;
 }
@@ -28,12 +30,15 @@ export declare class WorkerSpawner {
     private nextId;
     private readonly handles;
     /**
-     * Spawn a worker. The factory returns a promise; the spawner wires it
-     * up to an AbortController and tracks it.
+     * Spawn a worker. The factory receives an AbortSignal; when the worker is
+     * cancelled (via `cancel`, `cancelAll`, or the parent signal wiring) that
+     * signal fires and `done` settles.
      */
     spawn(factory: (signal: AbortSignal) => Promise<void>, opts?: SpawnOptions): WorkerHandle;
-    /** Abort every active worker. Their factories should observe signal. */
-    cancelAll(reason?: string): void;
+    /** Cancel a single worker: fires its AbortSignal. */
+    cancel(handle: WorkerHandle, reason?: unknown): void;
+    /** Cancel every active worker by firing their AbortSignals. */
+    cancelAll(reason?: unknown): void;
     /** Count of currently-active workers. */
     activeCount(): number;
     /** Snapshot of all live worker handles. */

package/dist/agent/worker-spawner.js

@@ -1,20 +1,21 @@
 /**
- * In-process worker spawner (MVP).
+ * In-process worker spawner.
  *
- * Per `docs/plan-fix.md` Step 2: workers run in-process for the MVP.
- * Real subprocess / child-process spawning belongs to a later level
- * (Level 7: sandboxed execution, Level 19: distributed workers).
+ * A "worker" here is just an async task tied to an AbortController. The
+ * spawner keeps the controllers so workers can actually be cancelled
+ * (user Ctrl+C, /abort, session shutdown, or a parent signalling a child).
  *
- * A "worker" here is just an async task with an AbortController. The
- * spawner keeps a registry so they can be cancelled together (e.g. on
- * user Ctrl+C, /abort, or session shutdown).
+ * Real subprocess / child-process spawning belongs to a later level;
+ * this module is the single-process cancellation primitive the agent
+ * orchestration layer builds on.
  */
 export class WorkerSpawner {
     nextId = 0;
     handles = new Set();
     /**
-     * Spawn a worker. The factory returns a promise; the spawner wires it
-     * up to an AbortController and tracks it.
+     * Spawn a worker. The factory receives an AbortSignal; when the worker is
+     * cancelled (via `cancel`, `cancelAll`, or the parent signal wiring) that
+     * signal fires and `done` settles.
      */
     spawn(factory, opts = {}) {
         const id = this.nextId++;
@@ -31,16 +32,16 @@ export class WorkerSpawner {
             id,
             label,
             signal: ac.signal,
+            controller: ac,
             done,
         };
         this.handles.add(handle);
         if (!autoStart) {
-            // Caller will invoke factory manually and pass the signal — for now
-            // we just resolve immediately so .done doesn't hang.
+            // Caller will invoke the factory manually and pass the signal.
             resolveDone();
             return handle;
         }
-        // Fire-and-forget; user awaits handle.done.
+        // Fire-and-forget; the caller awaits handle.done.
         factory(ac.signal).then(() => {
             this.handles.delete(handle);
             resolveDone();
@@ -50,20 +51,25 @@ export class WorkerSpawner {
         });
         return handle;
     }
-    /** Abort every active worker. Their factories should observe signal. */
-    cancelAll(reason = 'cancelled') {
+    /** Cancel a single worker: fires its AbortSignal. */
+    cancel(handle, reason) {
+        try {
+            handle.controller.abort(reason);
+        }
+        catch {
+            /* already aborted */
+        }
+    }
+    /** Cancel every active worker by firing their AbortSignals. */
+    cancelAll(reason) {
         for (const h of [...this.handles]) {
             try {
-                h.signal.reason = reason;
+                h.controller.abort(reason);
             }
             catch {
-                // AbortSignal.reason is read-only in some envs — fine.
+                /* already aborted */
             }
         }
-        // Real abort uses the controller stored on the handle's signal — we
-        // don't keep the controller here. In the MVP, callers can pass their
-        // own AbortController via factory; this method is a no-op stub for
-        // the contract. See `cancel(handle)` for the per-worker variant.
     }
     /** Count of currently-active workers. */
     activeCount() {

package/dist/cli/dotenv.d.ts

@@ -0,0 +1,3 @@
+export declare function parseDotenv(text: string): Record<string, string>;
+/** Load `<cwd>/.env` into `process.env` (no-clobber). Returns loaded keys. */
+export declare function loadDotenv(cwd: string): string[];

package/dist/cli/dotenv.js

@@ -0,0 +1,57 @@
+/**
+ * P0.5 — `.env` auto-load (r-11-17.md).
+ *
+ * Loads `<cwd>/.env` at startup so `KLYRO_API_KEY` etc. work without `export`.
+ * Rules:
+ * - Never overwrites an already-set variable (explicit env wins).
+ * - Only `KEY=VALUE` lines; `#` comments and `export ` prefixes tolerated.
+ * - Single/double quotes stripped; missing file is a no-op (never throws).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function parseDotenv(text) {
+    const out = {};
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const body = line.startsWith('export ') ? line.slice('export '.length).trim() : line;
+        const eq = body.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = body.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let val = body.slice(eq + 1).trim();
+        if (val.length >= 2 && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
+            val = val.slice(1, -1);
+        }
+        // Strip trailing inline comments on unquoted values.
+        if (!body.slice(eq + 1).trim().startsWith('"') && !body.slice(eq + 1).trim().startsWith("'")) {
+            const hash = val.indexOf(' #');
+            if (hash >= 0)
+                val = val.slice(0, hash).trimEnd();
+        }
+        out[key] = val;
+    }
+    return out;
+}
+/** Load `<cwd>/.env` into `process.env` (no-clobber). Returns loaded keys. */
+export function loadDotenv(cwd) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(cwd, '.env'), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const parsed = parseDotenv(text);
+    const loaded = [];
+    for (const [k, v] of Object.entries(parsed)) {
+        if (process.env[k] === undefined) {
+            process.env[k] = v;
+            loaded.push(k);
+        }
+    }
+    return loaded;
+}

package/dist/cli/repl.js

@@ -12,6 +12,8 @@ import { render } from 'ink';
 import { App } from '../tui/app.js';
 import { httpChatAdapter } from '../agent/provider-adapter.js';
 import { anthropicAdapter } from '../agent/anthropic-adapter.js';
+import { retryingAdapter } from '../agent/retry.js';
+import { globalBus } from '../events/bus.js';
 import { run } from '../agent/runtime.js';
 import { builtinRegistry } from '../tools/registry.js';
 import { builtinRules, clonePolicyConfig, PolicyEngine } from '../policy/engine.js';
@@ -28,6 +30,13 @@ import { getDefaultSessionStore } from '../persistence/session.js';
 import { buildSystemPrompt, parseImageInput } from '../context/system-prompt.js';
 import { estimateCost } from '../providers/model-info.js';
 export async function startRepl(opts = {}) {
+    // P0.5 — load <cwd>/.env first so provider resolution below sees KLYRO_*
+    // vars without `export`. Never throws; explicit env wins (no-clobber).
+    try {
+        const { loadDotenv } = await import('./dotenv.js');
+        loadDotenv(opts.cwd ?? process.cwd());
+    }
+    catch { /* ignore */ }
     // Reuse the same provider resolution as legacy repl.ts — probes local
     // Ollama / LM Studio / vLLM when env is not fully set, so bare `klyro`
     // works with a local model just like `klyro chat` does.
@@ -81,6 +90,21 @@ export async function startRepl(opts = {}) {
     catch {
         /* ignore — engine defaults stand */
     }
+    // Best-effort MCP tools: never fatal, never prompts. src/mcp/registry.ts
+    // lands from a sibling agent — the lazy import keeps runtime + builds green
+    // until then (import failure is caught below). Servers live for the process
+    // lifetime, so no close wiring here (unlike runOnce's finally).
+    try {
+        // @ts-ignore — sibling-owned module may not exist yet
+        const { loadAndRegisterMcp } = await import('../mcp/registry.js');
+        const mcp = await loadAndRegisterMcp({ cwd, registry, policy });
+        for (const e of mcp.errors)
+            process.stderr.write(`klyro: mcp ${e.server}: ${e.message}\n`);
+        if (mcp.registered.length > 0) {
+            process.stderr.write(`klyro: mcp tools: ${mcp.registered.join(', ')}\n`);
+        }
+    }
+    catch { /* ignore — MCP is optional */ }
     const providerKind = inferProviderFromBaseURL(baseUrl);
     // Local Ollama exposes OpenAI-compat but hostname could contain "anthropic"
     // via proxy — don't try anthropic adapter with empty key (would 401).
@@ -93,9 +117,24 @@ export async function startRepl(opts = {}) {
     let currentApiKey = apiKey;
     let currentMaxSteps = opts.maxSteps ?? 30;
     let effortLevel = 'medium';
-    const buildAdapter = (prov, url, key) => prov === 'anthropic'
+    // Retry wrapper lives inside the factory so the initial construction AND
+    // the /provider switch + /reload rebuilds (which re-call buildAdapter)
+    // all stay wrapped. REPL has no session id at adapter scope, so retry
+    // telemetry uses 'ephemeral'.
+    const buildAdapter = (prov, url, key) => retryingAdapter(prov === 'anthropic'
         ? anthropicAdapter({ baseURL: url, apiKey: key, timeoutMs: 60_000 })
-        : httpChatAdapter({ baseURL: url, apiKey: key, timeoutMs: 60_000 });
+        : httpChatAdapter({ baseURL: url, apiKey: key, timeoutMs: 60_000 }), {
+        onRetry: (info) => {
+            globalBus.emit({
+                type: 'provider.retry',
+                ts: Date.now(),
+                sessionId: 'ephemeral',
+                attempt: info.attempt,
+                status: info.status,
+                ...(info.retryAfterMs !== undefined ? { retryAfterMs: info.retryAfterMs } : {}),
+            });
+        },
+    });
     let adapter = buildAdapter(currentProvider, currentBaseUrl, currentApiKey);
     const ctxBlock = await buildLevel6Context({ cwd });
     let ctxPrefix = ctxBlock.formatted ? `\n\n<context>\n${ctxBlock.formatted}\n</context>` : '';

package/dist/cli/run.d.ts

@@ -64,6 +64,9 @@ export interface RunCliOptions {
     persist?: boolean;
     sessionId?: string;
     sessionsDir?: string;
+    /** P1.4 — run the task under a named child-capable orchestrator context. */
+    agent?: string;
+    maxDepth?: number;
 }
 export declare function runOnce(opts: RunCliOptions): Promise<number>;
 /** Wrap a system-prompt fn to inject Level-6 context (project map etc.) + KLYRO.md (4.4). */