klyro 0.1.1

package/dist/agent/runtime.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Agent runtime — the core autonomous loop.
+ *
+ * Loop:
+ *   1. Build a CallRequest from the current transcript + system prompt.
+ *   2. Stream from the provider; collect text + tool calls.
+ *   3. If the assistant produced no tool calls, treat as final answer.
+ *   4. Otherwise, evaluate policy for each call, execute (or deny), feed
+ *      tool_results back as the next user message.
+ *   5. Repeat up to maxSteps. Cap at maxSteps to avoid runaway costs.
+ *
+ * Stream cancellation: pass `signal` to abort mid-step.
+ *
+ * The runtime is intentionally provider-agnostic — it only sees the
+ * normalized StreamEvent shape from ProviderAdapter.
+ */
+import type { ProviderAdapter, ToolDefinition } from './provider-adapter.js';
+import type { Message } from './message.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { PolicyEngine } from '../policy/engine.js';
+import type { ApprovalPrompt } from '../policy/approval.js';
+export interface RuntimeDeps {
+    adapter: ProviderAdapter;
+    registry: ToolRegistry;
+    policy: PolicyEngine;
+    approval: ApprovalPrompt;
+    /**
+     * Build a system prompt given cwd + the current Level-7 runtime telemetry.
+     * The telemetry block is a compact, in-memory summary of the run so far
+     * (step count, last tool calls, recent errors). Injected as part of the
+     * system prompt so the model can see its own state mid-run.
+     */
+    systemPrompt: (ctx: {
+        cwd: string;
+        telemetry?: string;
+    }) => string;
+}
+export interface RunOptions {
+    task: string;
+    cwd: string;
+    model: string;
+    maxSteps?: number;
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+    nonInteractive: boolean;
+    /**
+     * Optional pre-existing transcript to seed the conversation. When set,
+     * the runtime skips the initial `[{role:'user', content:[text(task)]}]`
+     * and starts with this list instead. Used for `--resume` and tests.
+     *
+     * If provided AND `task` is set, the task is appended as a new user
+     * message at the end (so resume+continue works naturally).
+     */
+    initialTranscript?: Message[];
+    /**
+     * Optional hook for live UIs (e.g. the TUI). Fires for every observable
+     * event the runtime processes: text deltas, tool-call boundaries,
+     * policy decisions, observation results, and step boundaries. Callers
+     * that don't pass it pay zero cost.
+     */
+    onEvent?: (ev: RuntimeEvent) => void;
+}
+/** High-level event stream the runtime emits. Safe for UI consumption. */
+export type RuntimeEvent = {
+    kind: 'step_start';
+    step: number;
+} | {
+    kind: 'step_end';
+    step: number;
+} | {
+    kind: 'text_delta';
+    text: string;
+} | {
+    kind: 'tool_call_start';
+    id: string;
+    name: string;
+} | {
+    kind: 'tool_call_delta';
+    id: string;
+    argsJson: string;
+} | {
+    kind: 'tool_call_end';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    kind: 'policy_decision';
+    id: string;
+    name: string;
+    action: 'allow' | 'ask' | 'deny';
+    reason?: string;
+} | {
+    kind: 'tool_result';
+    id: string;
+    name: string;
+    output: unknown;
+    isError: boolean;
+    latencyMs: number;
+} | {
+    kind: 'usage';
+    input: number;
+    output: number;
+} | {
+    kind: 'final_text';
+    text: string;
+} | {
+    kind: 'aborted';
+};
+export interface RunResult {
+    status: 'complete' | 'max_steps' | 'aborted' | 'no_final';
+    steps: number;
+    toolCalls: number;
+    finalText: string;
+    transcript: Message[];
+    usage: {
+        input: number;
+        output: number;
+    };
+    /** Number of policy-driven user prompts the user accepted. */
+    repairs?: number;
+}
+/** Convert a registry of tools into ToolDefinitions for the provider. */
+export declare function toolDefinitions(registry: ToolRegistry): ToolDefinition[];
+/** Run the autonomous loop. */
+export declare function run(opts: RunOptions, deps: RuntimeDeps): Promise<RunResult>;
+export declare function defaultSystemPrompt(ctx: {
+    cwd: string;
+    telemetry?: string;
+}): string;

package/dist/agent/runtime.js

@@ -0,0 +1,221 @@
+/**
+ * Agent runtime — the core autonomous loop.
+ *
+ * Loop:
+ *   1. Build a CallRequest from the current transcript + system prompt.
+ *   2. Stream from the provider; collect text + tool calls.
+ *   3. If the assistant produced no tool calls, treat as final answer.
+ *   4. Otherwise, evaluate policy for each call, execute (or deny), feed
+ *      tool_results back as the next user message.
+ *   5. Repeat up to maxSteps. Cap at maxSteps to avoid runaway costs.
+ *
+ * Stream cancellation: pass `signal` to abort mid-step.
+ *
+ * The runtime is intentionally provider-agnostic — it only sees the
+ * normalized StreamEvent shape from ProviderAdapter.
+ */
+import { text, toolUse, toolResult as mkToolResult } from './message.js';
+import { redact } from '../policy/secret-redactor.js';
+import { RuntimeTelemetry, emptyTelemetryBlock, summarizeToolCall } from '../context/level7.js';
+const DEFAULT_MAX_STEPS = 30;
+/** Convert a registry of tools into ToolDefinitions for the provider. */
+export function toolDefinitions(registry) {
+    return registry.toOpenAITools().map((t) => ({
+        name: t.function.name,
+        description: t.function.description,
+        inputSchema: t.function.parameters,
+    }));
+}
+/** Run the autonomous loop. */
+export async function run(opts, deps) {
+    const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+    const transcript = opts.initialTranscript
+        ? [...opts.initialTranscript, { role: 'user', content: [text(opts.task)] }]
+        : [{ role: 'user', content: [text(opts.task)] }];
+    const usage = { input: 0, output: 0 };
+    let steps = 0;
+    let toolCallCount = 0;
+    let finalText = '';
+    let repairs = 0;
+    const emit = opts.onEvent;
+    const telemetry = new RuntimeTelemetry();
+    telemetry.setMaxSteps(maxSteps);
+    outer: while (steps < maxSteps) {
+        if (opts.signal?.aborted) {
+            emit?.({ kind: 'aborted' });
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, usage, repairs };
+        }
+        steps++;
+        emit?.({ kind: 'step_start', step: steps });
+        telemetry.recordStepStart(steps);
+        const req = {
+            model: opts.model,
+            system: deps.systemPrompt({ cwd: opts.cwd, telemetry: steps === 1 ? emptyTelemetryBlock() : telemetry.format() }),
+            messages: transcript,
+            tools: toolDefinitions(deps.registry),
+            ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
+            ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        };
+        const events = deps.adapter.stream(req);
+        let textBuf = '';
+        const pendingToolCalls = new Map();
+        let lastFinishReason;
+        for await (const ev of events) {
+            if (opts.signal?.aborted)
+                break outer;
+            if (ev.kind === 'text_delta') {
+                textBuf += ev.text;
+                emit?.({ kind: 'text_delta', text: ev.text });
+            }
+            else if (ev.kind === 'tool_call_start') {
+                pendingToolCalls.set(ev.id, { id: ev.id, name: ev.name, argsJson: '' });
+                emit?.({ kind: 'tool_call_start', id: ev.id, name: ev.name });
+            }
+            else if (ev.kind === 'tool_call_delta') {
+                const tc = pendingToolCalls.get(ev.id);
+                if (tc)
+                    tc.argsJson += ev.argsJson;
+                emit?.({ kind: 'tool_call_delta', id: ev.id, argsJson: ev.argsJson });
+            }
+            else if (ev.kind === 'tool_call_end') {
+                // tool_calls are accumulated; finalization happens after stream.
+            }
+            else if (ev.kind === 'message_end') {
+                lastFinishReason = ev.finishReason;
+                if (ev.usage) {
+                    usage.input += ev.usage.input;
+                    usage.output += ev.usage.output;
+                    telemetry.recordUsage(ev.usage.input, ev.usage.output);
+                    emit?.({ kind: 'usage', input: usage.input, output: usage.output });
+                }
+            }
+            else if (ev.kind === 'error') {
+                telemetry.recordError(`stream_error: ${ev.code}`);
+                return {
+                    status: 'no_final',
+                    steps,
+                    toolCalls: toolCallCount,
+                    finalText: textBuf,
+                    transcript,
+                    usage,
+                };
+            }
+        }
+        // Build the assistant message.
+        const assistantContent = [];
+        if (textBuf)
+            assistantContent.push(text(textBuf));
+        const finalizedCalls = [];
+        for (const tc of pendingToolCalls.values()) {
+            let input = {};
+            try {
+                input = JSON.parse(tc.argsJson || '{}');
+            }
+            catch {
+                input = { _parse_error: true, raw: tc.argsJson };
+            }
+            finalizedCalls.push(toolUse(tc.id, tc.name, input));
+            assistantContent.push(toolUse(tc.id, tc.name, input));
+            emit?.({ kind: 'tool_call_end', id: tc.id, name: tc.name, input });
+        }
+        transcript.push({ role: 'assistant', content: assistantContent });
+        // No tool calls → done.
+        if (opts.signal?.aborted) {
+            finalText = textBuf;
+            emit?.({ kind: 'aborted' });
+            return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, usage, repairs };
+        }
+        if (finalizedCalls.length === 0) {
+            finalText = textBuf;
+            emit?.({ kind: 'final_text', text: finalText });
+            emit?.({ kind: 'step_end', step: steps });
+            return { status: 'complete', steps, toolCalls: toolCallCount, finalText, transcript, usage, repairs };
+        }
+        // Execute each tool call (after policy).
+        const toolCtx = {
+            cwd: opts.cwd,
+            env: process.env,
+            signal: opts.signal,
+            nonInteractive: opts.nonInteractive,
+        };
+        for (const call of finalizedCalls) {
+            toolCallCount++;
+            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 } : {}) });
+            if (decision.action === 'deny') {
+                transcript.push({
+                    role: 'tool',
+                    content: [
+                        mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: decision.reason }, true),
+                    ],
+                });
+                telemetry.recordToolError(call, 'policy_denied');
+                emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: decision.reason }, isError: true, latencyMs: 0 });
+                continue;
+            }
+            if (decision.action === 'ask') {
+                const choice = await deps.approval.ask({
+                    toolName: call.name,
+                    reason: decision.reason,
+                    summary: summarizeToolCall(call),
+                });
+                if (choice === 'deny') {
+                    transcript.push({
+                        role: 'tool',
+                        content: [
+                            mkToolResult(call.id, call.name, { error: 'POLICY_DENIED', reason: 'user denied' }, true),
+                        ],
+                    });
+                    telemetry.recordToolError(call, 'user_denied');
+                    emit?.({ kind: 'tool_result', id: call.id, name: call.name, output: { error: 'POLICY_DENIED', reason: 'user denied' }, isError: true, latencyMs: 0 });
+                    continue;
+                }
+                repairs++;
+            }
+            const t0 = Date.now();
+            const obs = await deps.registry.execute(call.name, call.input, toolCtx);
+            const latencyMs = Date.now() - t0;
+            const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
+            transcript.push({
+                role: 'tool',
+                content: [mkToolResult(call.id, call.name, output, !obs.ok)],
+            });
+            if (obs.ok) {
+                telemetry.recordToolCall(call, latencyMs, false);
+            }
+            else {
+                const code = String(obs.error?.code ?? 'tool_error');
+                telemetry.recordToolCall(call, latencyMs, true);
+                telemetry.recordError(`${code}: ${call.name}`);
+            }
+            emit?.({ kind: 'tool_result', id: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
+        }
+        emit?.({ kind: 'step_end', step: steps });
+    }
+    if (opts.signal?.aborted) {
+        emit?.({ kind: 'aborted' });
+        return { status: 'aborted', steps, toolCalls: toolCallCount, finalText, transcript, usage, repairs };
+    }
+    emit?.({ kind: 'final_text', text: finalText });
+    return { status: 'max_steps', steps, toolCalls: toolCallCount, finalText, transcript, usage, repairs };
+}
+function redactOutput(v) {
+    if (typeof v === 'string')
+        return redact(v);
+    if (v && typeof v === 'object')
+        return v; // structured outputs are not redacted wholesale
+    return v;
+}
+export function defaultSystemPrompt(ctx) {
+    const base = [
+        'You are Klyro, an autonomous coding harness. You solve the user\'s task by',
+        'calling tools in a loop. Prefer the smallest change that solves the task.',
+        'When you have finished, produce a short final text answer (no tool calls).',
+        '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 base;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * In-process worker spawner (MVP).
+ *
+ * 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 with an AbortController. The
+ * spawner keeps a registry so they can be cancelled together (e.g. on
+ * user Ctrl+C, /abort, or session shutdown).
+ */
+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. */
+    readonly signal: AbortSignal;
+    /** Resolves when the worker's main promise settles. */
+    readonly done: Promise<void>;
+}
+export interface SpawnOptions {
+    label?: string;
+    /** If true, the worker is started immediately on spawn (default true). */
+    autoStart?: boolean;
+}
+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(factory: (signal: AbortSignal) => Promise<void>, opts?: SpawnOptions): WorkerHandle;
+    /** Abort every active worker. Their factories should observe signal. */
+    cancelAll(reason?: string): void;
+    /** Count of currently-active workers. */
+    activeCount(): number;
+    /** Snapshot of all live worker handles. */
+    list(): readonly WorkerHandle[];
+}

package/dist/agent/worker-spawner.js

@@ -0,0 +1,76 @@
+/**
+ * In-process worker spawner (MVP).
+ *
+ * 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 with an AbortController. The
+ * spawner keeps a registry so they can be cancelled together (e.g. on
+ * user Ctrl+C, /abort, or session shutdown).
+ */
+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(factory, opts = {}) {
+        const id = this.nextId++;
+        const ac = new AbortController();
+        const label = opts.label ?? `worker-${id}`;
+        const autoStart = opts.autoStart ?? true;
+        let resolveDone = () => { };
+        let rejectDone = () => { };
+        const done = new Promise((res, rej) => {
+            resolveDone = res;
+            rejectDone = rej;
+        });
+        const handle = {
+            id,
+            label,
+            signal: ac.signal,
+            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.
+            resolveDone();
+            return handle;
+        }
+        // Fire-and-forget; user awaits handle.done.
+        factory(ac.signal).then(() => {
+            this.handles.delete(handle);
+            resolveDone();
+        }, (err) => {
+            this.handles.delete(handle);
+            rejectDone(err);
+        });
+        return handle;
+    }
+    /** Abort every active worker. Their factories should observe signal. */
+    cancelAll(reason = 'cancelled') {
+        for (const h of [...this.handles]) {
+            try {
+                h.signal.reason = reason;
+            }
+            catch {
+                // AbortSignal.reason is read-only in some envs — fine.
+            }
+        }
+        // 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() {
+        return this.handles.size;
+    }
+    /** Snapshot of all live worker handles. */
+    list() {
+        return [...this.handles];
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,39 @@
+/**
+ * One-shot chat. POSTs to an OpenAI-compatible /v1/chat/completions endpoint
+ * and streams the response to stdout.
+ *
+ * Config (env):
+ *   KLYRO_BASE_URL  e.g. https://api.openai.com/v1
+ *   KLYRO_API_KEY   bearer token
+ *   KLYRO_MODEL     e.g. gpt-4o-mini
+ *   KLYRO_TIMEOUT_MS request timeout in ms (default 60000)
+ *
+ * No abstractions, no registry, no retries. If you want those, layer them on later.
+ */
+export interface ChatOptions {
+    system?: string;
+    model?: string;
+    baseURL?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** Strip a trailing slash so we can append /chat/completions cleanly. */
+export declare function normalizeBaseURL(url: string): string;
+/**
+ * Validate that the base URL is HTTPS (or localhost over HTTP for local LLMs).
+ * Refuses to send the bearer token over a plaintext remote connection.
+ */
+export declare function assertSafeBaseURL(url: string): void;
+export declare function chat(prompt: string, system: string, modelOverride?: string, opts?: ChatOptions): Promise<void>;
+/**
+ * Parse SSE frames and write text deltas to stdout. Each `data: ...` line is
+ * one chunk; `[DONE]` terminates the stream. Respects backpressure on stdout
+ * and the provided abort signal.
+ */
+export declare function streamToStdout(body: ReadableStream<Uint8Array>, signal: AbortSignal): Promise<void>;
+/**
+ * Read up to `max` bytes from a response body. Used for error responses where
+ * we want to surface the cause without risking OOM on a misbehaving server.
+ */
+export declare function readBoundedText(body: ReadableStream<Uint8Array> | null, max: number): Promise<string>;