klyro 0.1.63 → 1.0.0

package/dist/cli/run.js

@@ -10,6 +10,8 @@
 import { stdout, stderr } from 'node:process';
 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';
@@ -22,6 +24,13 @@ function readEnv(name, fallback) {
     return v && v.length > 0 ? v : fallback;
 }
 export async function runOnce(opts) {
+    // P0.5 — load <cwd>/.env first so KLYRO_* vars resolve without `export`.
+    // Never throws (missing file is a no-op); explicit env wins (no-clobber).
+    try {
+        const { loadDotenv } = await import('./dotenv.js');
+        loadDotenv(opts.cwd);
+    }
+    catch { /* ignore */ }
     const output = opts.output ?? 'human';
     if (opts.dryRun) {
         return await dryRunReport(opts);
@@ -32,6 +41,27 @@ export async function runOnce(opts) {
         clearReadHistory();
     }
     catch { /* ignore */ }
+    // P1.4 — validate --agent early so typos fail fast (exit 2) even without API keys.
+    if (opts.agent) {
+        const { BUILTIN_AGENTS: _known } = await import('../agent/orchestrator.js');
+        if (!_known.some((a) => a.id === opts.agent)) {
+            stderr.write(`klyro: unknown agent: ${opts.agent} (known: ${_known.map((a) => a.id).join(', ')})\n`);
+            return 2;
+        }
+    }
+    // Box so retry telemetry (emitted before the session exists) picks up the
+    // real sessionId once create/resume assigns it below.
+    const sessionIdForRetry = { id: 'ephemeral' };
+    const onRetryEmit = (info) => {
+        globalBus.emit({
+            type: 'provider.retry',
+            ts: Date.now(),
+            sessionId: sessionIdForRetry.id,
+            attempt: info.attempt,
+            status: info.status,
+            ...(info.retryAfterMs !== undefined ? { retryAfterMs: info.retryAfterMs } : {}),
+        });
+    };
     let adapter = opts.adapter;
     if (!adapter) {
         const provider = opts.provider ?? 'openai';
@@ -42,19 +72,19 @@ export async function runOnce(opts) {
             return 2;
         }
         if (provider === 'anthropic') {
-            adapter = anthropicAdapter({
+            adapter = retryingAdapter(anthropicAdapter({
                 baseURL: baseUrl,
                 apiKey,
                 timeoutMs: opts.timeoutMs ?? 60_000,
                 authHeader: opts.authHeader,
-            });
+            }), { onRetry: onRetryEmit });
         }
         else {
             if (!baseUrl) {
                 stderr.write('klyro: KLYRO_BASE_URL is not set (or pass --base-url)\n');
                 return 2;
             }
-            adapter = httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 });
+            adapter = retryingAdapter(httpChatAdapter({ baseURL: baseUrl, apiKey, timeoutMs: opts.timeoutMs ?? 60_000 }), { onRetry: onRetryEmit });
         }
     }
     const registry = builtinRegistry();
@@ -67,6 +97,23 @@ export async function runOnce(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). @ts-ignore is used instead
+    // of @ts-expect-error so it stays inert after the sibling file lands.
+    let closeMcp;
+    try {
+        // @ts-ignore — sibling-owned module may not exist yet
+        const { loadAndRegisterMcp } = await import('../mcp/registry.js');
+        const mcp = await loadAndRegisterMcp({ cwd: opts.cwd, registry, policy });
+        for (const e of mcp.errors)
+            stderr.write(`klyro: mcp ${e.server}: ${e.message}\n`);
+        if (mcp.registered.length > 0 && output === 'human') {
+            stderr.write(`klyro: mcp tools: ${mcp.registered.join(', ')}\n`);
+        }
+        closeMcp = mcp.closeAll;
+    }
+    catch { /* ignore — MCP is optional */ }
     const systemPrompt = await makeRunSystemPrompt(opts.cwd, opts.systemPrompt ?? defaultRunSystemPrompt);
     // Level 9 — session setup (create or resume)
     const persistEnabled = opts.persist !== false;
@@ -110,6 +157,9 @@ export async function runOnce(opts) {
     else if (opts.resumePath) {
         initialTranscript = loadTranscript(opts.resumePath);
     }
+    // Publish the real sessionId to retry telemetry (stays 'ephemeral' when
+    // persistence is disabled or the session was never created).
+    sessionIdForRetry.id = sessionId ?? 'ephemeral';
     const ac = new AbortController();
     const onSigint = () => {
         stderr.write('\nklyro: SIGINT — aborting\n');
@@ -131,6 +181,49 @@ export async function runOnce(opts) {
             requireVerify: opts.requireVerify,
         };
     let result;
+    // P1.4 — if --agent is requested, stand up a parent orchestrator so the
+    // model can call spawn_agent / task_list / task_get. The root run keeps
+    // depth 0; children are capped at maxDepth (default 1 per r-6-10.fix.md).
+    let agentBridge;
+    let parentContext;
+    if (opts.agent) {
+        const { AgentOrchestrator, BUILTIN_AGENTS } = await import('../agent/orchestrator.js');
+        const def = BUILTIN_AGENTS.find((a) => a.id === opts.agent); // validated above
+        const maxDepth = opts.maxDepth ?? 1;
+        const rootDeps = { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt };
+        const orchestrator = new AgentOrchestrator({ sessionId: sessionId ?? 'ephemeral', deps: rootDeps });
+        const allowedTools = new Set(registry.list().map((t) => t.name));
+        parentContext = {
+            sessionId: sessionId ?? 'ephemeral',
+            depth: 0,
+            maxDepth,
+            allowedTools,
+            model: def.model ?? opts.model,
+        };
+        agentBridge = orchestrator.bridgeFor({
+            sessionId: sessionId ?? 'ephemeral',
+            cwd: opts.cwd,
+            depth: 0,
+            maxDepth,
+            allowedTools,
+            model: def.model ?? opts.model,
+        });
+    }
+    else if (opts.maxDepth !== undefined) {
+        const allowedTools = new Set(registry.list().map((t) => t.name));
+        const { AgentOrchestrator } = await import('../agent/orchestrator.js');
+        const rootDeps = { adapter, registry, policy, approval: new DenyAllApprovalPrompt(), systemPrompt };
+        const orchestrator = new AgentOrchestrator({ sessionId: sessionId ?? 'ephemeral', deps: rootDeps });
+        parentContext = { sessionId: sessionId ?? 'ephemeral', depth: 0, maxDepth: opts.maxDepth, allowedTools, model: opts.model };
+        agentBridge = orchestrator.bridgeFor({
+            sessionId: sessionId ?? 'ephemeral',
+            cwd: opts.cwd,
+            depth: 0,
+            maxDepth: opts.maxDepth,
+            allowedTools,
+            model: opts.model,
+        });
+    }
     try {
         result = await run({
             task: opts.task,
@@ -144,6 +237,8 @@ export async function runOnce(opts) {
             initialTranscript,
             verify: verifyOpts,
             persist: store && sessionId ? { store, sessionId } : undefined,
+            ...(agentBridge ? { agentBridge } : {}),
+            ...(parentContext ? { parentContext } : {}),
             onEvent: (ev) => {
                 if (output === 'json') {
                     stdout.write(JSON.stringify(ev) + '\n');
@@ -192,6 +287,10 @@ export async function runOnce(opts) {
     }
     finally {
         doneSigint();
+        try {
+            await closeMcp?.();
+        }
+        catch { /* ignore */ }
     }
     if (store && sessionId) {
         // Finalize session status
@@ -295,10 +394,22 @@ export async function makeRunSystemPrompt(cwd, base) {
     const prefix = ctxBlock.formatted ? `\n\n<context>\n${ctxBlock.formatted}\n</context>` : '';
     let klyroBlock = '';
     try {
-        const { loadKlyroMd } = await import('../context/klyro-md.js');
-        const md = await loadKlyroMd(cwd);
-        if (md)
-            klyroBlock = `\n\n<KLYRO.md>\n${md.slice(0, 4000)}\n</KLYRO.md>`;
+        // P0.3 trust gate: unapproved context files are excluded in headless
+        // mode (secure default-deny) and each exclusion is bus-visible.
+        const { loadKlyroMdFiles } = await import('../context/klyro-md.js');
+        const { ContextTrust } = await import('../context/trust.js');
+        const { globalBus } = await import('../events/bus.js');
+        const files = await loadKlyroMdFiles(cwd);
+        const { trusted, untrusted } = new ContextTrust().check(files);
+        for (const { file, reason } of untrusted) {
+            globalBus.emit({ type: 'context.trust_prompt', ts: Date.now(), sessionId: 'ephemeral', path: file.path, reason, trusted: false });
+        }
+        if (untrusted.length > 0) {
+            stderr.write(`klyro: trust gate excluded ${untrusted.length} unapproved context file(s): ${untrusted.map((u) => u.file.path).join(', ')}\n`);
+        }
+        const kept = trusted.map((f) => `# ${f.path}\n${f.content}`).join('\n\n---\n\n');
+        if (kept)
+            klyroBlock = `\n\n<KLYRO.md>\n${kept.slice(0, 4000)}\n</KLYRO.md>`;
     }
     catch { /* ignore */ }
     return (ctx) => {

package/dist/context/klyro-md.d.ts

@@ -6,5 +6,11 @@
  * secret files into context), each file is capped, and total output is
  * capped so a giant monorepo doc can't blow the context budget.
  */
+export interface KlyroMdFile {
+    path: string;
+    content: string;
+}
+/** Per-file loader (used by the trust gate to approve/hash individual files). */
+export declare function loadKlyroMdFiles(cwd: string): Promise<KlyroMdFile[]>;
 export declare function loadKlyroMd(cwd: string): Promise<string>;
 export declare function handleInit(cwd: string): Promise<string>;

package/dist/context/klyro-md.js

@@ -14,37 +14,43 @@ const MAX_TOTAL_CHARS = 8000;
 function cap(s, n) {
     return s.length > n ? s.slice(0, n) + `\n... [truncated ${s.length - n} chars]` : s;
 }
-export async function loadKlyroMd(cwd) {
-    const parts = [];
-    let total = 0;
-    const push = (s) => {
-        if (total >= MAX_TOTAL_CHARS)
-            return;
-        const room = MAX_TOTAL_CHARS - total;
-        const chunk = s.length > room ? s.slice(0, room) + '\n... [truncated]' : s;
-        parts.push(chunk);
-        total += chunk.length;
-    };
-    // Global
+/** Per-file loader (used by the trust gate to approve/hash individual files). */
+export async function loadKlyroMdFiles(cwd) {
+    const files = [];
     const home = os.homedir();
     if (home) {
         for (const p of [path.join(home, '.klyro', 'KLYRO.md'), path.join(home, '.klyro', 'KLYRO.local.md')]) {
             try {
                 const t = await fs.readFile(p, 'utf-8');
-                push(`# ${p}\n${cap(t, MAX_FILE_CHARS)}`);
+                files.push({ path: p, content: cap(t, MAX_FILE_CHARS) });
             }
             catch { /* ignore */ }
         }
     }
-    // Root (imports resolved relative to each file, contained to cwd)
     for (const name of ['KLYRO.md', 'KLYRO.local.md', 'AGENTS.md', '.cursorrules']) {
         const p = path.join(cwd, name);
         try {
             const t = await fs.readFile(p, 'utf-8');
-            push(`# ${p}\n${cap(await resolveImports(t, path.dirname(p), cwd), MAX_FILE_CHARS)}`);
+            files.push({ path: p, content: cap(await resolveImports(t, path.dirname(p), cwd), MAX_FILE_CHARS) });
         }
         catch { /* ignore */ }
     }
+    return files;
+}
+export async function loadKlyroMd(cwd) {
+    const parts = [];
+    let total = 0;
+    const push = (s) => {
+        if (total >= MAX_TOTAL_CHARS)
+            return;
+        const room = MAX_TOTAL_CHARS - total;
+        const chunk = s.length > room ? s.slice(0, room) + '\n... [truncated]' : s;
+        parts.push(chunk);
+        total += chunk.length;
+    };
+    for (const f of await loadKlyroMdFiles(cwd)) {
+        push(`# ${f.path}\n${f.content}`);
+    }
     return parts.join('\n\n---\n\n');
 }
 async function resolveImports(text, base, root, depth = 0) {

package/dist/context/trust.d.ts

@@ -0,0 +1,42 @@
+import type { KlyroEvent } from '../events/catalog.js';
+import { type KlyroMdFile } from './klyro-md.js';
+export interface TrustRecord {
+    sha256: string;
+    trustedAt: number;
+}
+export type TrustStore = Record<string, TrustRecord>;
+export type TrustReason = 'unknown' | 'changed';
+export declare function hashContent(content: string): string;
+/** Pure evaluation: split files into trusted vs needs-approval. */
+export declare function evaluateTrust(stored: TrustStore, files: KlyroMdFile[]): {
+    trusted: KlyroMdFile[];
+    untrusted: {
+        file: KlyroMdFile;
+        reason: TrustReason;
+    }[];
+};
+export declare function defaultTrustStorePath(): string;
+export declare class ContextTrust {
+    private readonly storePath;
+    private store;
+    constructor(storePath?: string);
+    private load;
+    private save;
+    check(files: KlyroMdFile[]): ReturnType<typeof evaluateTrust>;
+    /** Record approval for the file's current content. */
+    approve(file: KlyroMdFile): void;
+    isTrusted(file: KlyroMdFile): boolean;
+}
+export interface TrustedLoadOpts {
+    trust: ContextTrust;
+    /** Return true to include an untrusted file (and persist the approval). */
+    approve: (file: KlyroMdFile, reason: TrustReason) => Promise<boolean>;
+    sessionId?: string;
+    emit?: (ev: KlyroEvent) => void;
+}
+/**
+ * Load KLYRO.md hierarchy with the trust gate applied. Untrusted files are
+ * offered to `approve`; declined files are excluded from the returned text.
+ * Every gate decision emits `context.trust_prompt` on the bus.
+ */
+export declare function loadTrustedKlyroMd(cwd: string, opts: TrustedLoadOpts): Promise<string>;

package/dist/context/trust.js

@@ -0,0 +1,111 @@
+/**
+ * P0.3 — context-file trust gate (r-11-17.md §5.1).
+ *
+ * Closes the shared HIGH flaw: `KLYRO.md` / `AGENTS.md` are auto-loaded into
+ * the prompt, so a malicious commit can smuggle instructions that read as
+ * authenticated system guidance. Every auto-loaded file is hashed; the first
+ * sighting (or any change) requires explicit approval before the content may
+ * enter context. Decisions persist in `~/.klyro/context-trust.json`.
+ *
+ * Headless runs approve nothing (secure default): untrusted files are
+ * excluded and the exclusion is visible on the event bus.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadKlyroMdFiles } from './klyro-md.js';
+export function hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+/** Pure evaluation: split files into trusted vs needs-approval. */
+export function evaluateTrust(stored, files) {
+    const trusted = [];
+    const untrusted = [];
+    for (const f of files) {
+        const rec = stored[f.path];
+        if (!rec) {
+            untrusted.push({ file: f, reason: 'unknown' });
+        }
+        else if (rec.sha256 !== hashContent(f.content)) {
+            untrusted.push({ file: f, reason: 'changed' });
+        }
+        else {
+            trusted.push(f);
+        }
+    }
+    return { trusted, untrusted };
+}
+export function defaultTrustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'context-trust.json');
+}
+export class ContextTrust {
+    storePath;
+    store = {};
+    constructor(storePath = defaultTrustStorePath()) {
+        this.storePath = storePath;
+        this.load();
+    }
+    load() {
+        try {
+            const raw = fs.readFileSync(this.storePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                this.store = parsed;
+            }
+        }
+        catch {
+            this.store = {};
+        }
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
+            fs.writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), 'utf-8');
+        }
+        catch {
+            /* best-effort — trust stays in memory for the session */
+        }
+    }
+    check(files) {
+        return evaluateTrust(this.store, files);
+    }
+    /** Record approval for the file's current content. */
+    approve(file) {
+        this.store[file.path] = { sha256: hashContent(file.content), trustedAt: Date.now() };
+        this.save();
+    }
+    isTrusted(file) {
+        const rec = this.store[file.path];
+        return !!rec && rec.sha256 === hashContent(file.content);
+    }
+}
+/**
+ * Load KLYRO.md hierarchy with the trust gate applied. Untrusted files are
+ * offered to `approve`; declined files are excluded from the returned text.
+ * Every gate decision emits `context.trust_prompt` on the bus.
+ */
+export async function loadTrustedKlyroMd(cwd, opts) {
+    const sessionId = opts.sessionId ?? 'ephemeral';
+    const files = await loadKlyroMdFiles(cwd);
+    const { trusted, untrusted } = opts.trust.check(files);
+    const kept = [...trusted];
+    for (const { file, reason } of untrusted) {
+        let ok = false;
+        try {
+            ok = await opts.approve(file, reason);
+        }
+        catch {
+            ok = false;
+        }
+        opts.emit?.({ type: 'context.trust_prompt', ts: Date.now(), sessionId, path: file.path, reason, trusted: ok });
+        if (ok) {
+            opts.trust.approve(file);
+            kept.push(file);
+        }
+    }
+    // Preserve loader order.
+    const order = new Map(files.map((f, i) => [f.path, i]));
+    kept.sort((a, b) => (order.get(a.path) ?? 0) - (order.get(b.path) ?? 0));
+    return kept.map((f) => `# ${f.path}\n${f.content}`).join('\n\n---\n\n');
+}

package/dist/events/catalog.d.ts

@@ -132,5 +132,76 @@ export type KlyroEvent = {
     ts: number;
     sessionId: string;
     reason: string;
+} | {
+    type: 'subtask.started';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    parentTaskId?: string;
+    agentName: string;
+    depth: number;
+    model?: string;
+} | {
+    type: 'subtask.progress';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    note: string;
+} | {
+    type: 'subtask.completed';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'succeeded';
+    durationMs: number;
+    steps: number;
+    toolCalls: number;
+} | {
+    type: 'subtask.failed';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    status: 'failed' | 'cancelled' | 'timed_out' | 'blocked';
+    durationMs: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+} | {
+    type: 'subtask.tool_call';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    callId: string;
+    name: string;
+} | {
+    type: 'subtask.tool_result';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    callId: string;
+    name: string;
+    isError: boolean;
+    latencyMs: number;
+} | {
+    type: 'subtask.merged';
+    ts: number;
+    sessionId: string;
+    taskId: string;
+    changedFiles: string[];
+} | {
+    type: 'provider.retry';
+    ts: number;
+    sessionId: string;
+    attempt: number;
+    status: string;
+    retryAfterMs?: number;
+} | {
+    type: 'context.trust_prompt';
+    ts: number;
+    sessionId: string;
+    path: string;
+    reason: 'unknown' | 'changed';
+    trusted: boolean;
 };
 export type KlyroEventType = KlyroEvent['type'];

package/dist/index.js

@@ -274,6 +274,8 @@ async function main() {
         .option('--max-repairs <n>', 'Max autonomous repair attempts (default 3)', (v) => parsePositiveInt('--max-repairs', v))
         .option('--persist', 'Enable session persistence (Level 9, default: enabled)')
         .option('--require-verify', 'Fail with exit 8 if no verification passed after edits (6.5)')
+        .option('--agent <name>', 'Run under an orchestrator context enabling spawn_agent/task_list/task_get (explorer|implementer|tester|reviewer)')
+        .option('--max-depth <n>', 'Max spawn depth for child agents (default 1)', (v) => parsePositiveInt('--max-depth', v))
         .action(async (prompt, opts) => {
         const model = opts.model ?? process.env.KLYRO_MODEL;
         if (!model) {
@@ -307,6 +309,8 @@ async function main() {
                 maxRepairAttempts: opts.maxRepairs,
                 persist: opts.persist,
                 requireVerify: !!opts.requireVerify,
+                agent: opts.agent,
+                maxDepth: opts.maxDepth,
             });
             process.exit(code);
         }

package/dist/mcp/client.d.ts

@@ -0,0 +1,53 @@
+import type { McpServerSpec } from './config.js';
+export interface McpToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    mimeType?: string;
+}
+export interface McpCallResult {
+    /** Normalized text payload (content blocks joined). */
+    text: string;
+    isError: boolean;
+    raw: unknown;
+}
+export interface McpClientLike {
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
+    listResources(): Promise<McpResource[]>;
+    close(): Promise<void>;
+}
+export declare class McpError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+export declare class McpClient implements McpClientLike {
+    readonly name: string;
+    private readonly spec;
+    private child;
+    private nextId;
+    private readonly pending;
+    private stdoutBuf;
+    private stderrTail;
+    private dead;
+    private closed;
+    constructor(name: string, spec: McpServerSpec);
+    connect(): Promise<void>;
+    private connected;
+    listTools(): Promise<McpToolDef[]>;
+    callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpCallResult>;
+    listResources(): Promise<McpResource[]>;
+    readResource(uri: string, signal?: AbortSignal): Promise<string>;
+    close(): Promise<void>;
+    private timeout;
+    private assertLive;
+    private onStdout;
+    private notify;
+    private request;
+    private failAll;
+}