klyro 0.1.1

package/dist/chat.js

@@ -0,0 +1,235 @@
+/**
+ * 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.
+ */
+/** Default request timeout: 60s. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Max bytes of an error response body we will print. */
+const MAX_ERROR_BODY_BYTES = 4_000;
+/** Strip a trailing slash so we can append /chat/completions cleanly. */
+export function normalizeBaseURL(url) {
+    return url.replace(/\/+$/, '');
+}
+/**
+ * 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 function assertSafeBaseURL(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`KLYRO_BASE_URL is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol === 'https:')
+        return;
+    if (parsed.protocol === 'http:') {
+        const host = parsed.hostname.toLowerCase();
+        if (host === 'localhost' || host === '127.0.0.1' || host === '::1')
+            return;
+        throw new Error(`Refusing to send KLYRO_API_KEY over plaintext HTTP to ${host}. ` +
+            `Use https:// or a localhost URL.`);
+    }
+    throw new Error(`Unsupported KLYRO_BASE_URL protocol: ${parsed.protocol}`);
+}
+export async function chat(prompt, system, modelOverride, opts = {}) {
+    const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL ?? 'https://api.openai.com/v1';
+    const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY;
+    const model = modelOverride ?? opts.model ?? process.env.KLYRO_MODEL ?? 'gpt-4o-mini';
+    const timeoutMs = opts.timeoutMs ?? (Number(process.env.KLYRO_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS);
+    if (!apiKey) {
+        console.error('klyro: KLYRO_API_KEY is not set. Set it in your environment.');
+        process.exit(2);
+    }
+    assertSafeBaseURL(baseURL);
+    const ac = new AbortController();
+    const timeout = setTimeout(() => ac.abort(new Error(`request timed out after ${timeoutMs}ms`)), timeoutMs);
+    // If the caller passed their own signal, abort when they abort.
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            ac.abort(opts.signal.reason);
+        else
+            opts.signal.addEventListener('abort', () => ac.abort(opts.signal?.reason), { once: true });
+    }
+    let res;
+    try {
+        res = await fetch(`${normalizeBaseURL(baseURL)}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                model,
+                messages: [
+                    { role: 'system', content: system },
+                    { role: 'user', content: prompt },
+                ],
+                stream: true,
+            }),
+            signal: ac.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeout);
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`klyro: request failed: ${msg}`);
+        process.exit(1);
+    }
+    clearTimeout(timeout);
+    if (!res.ok) {
+        const text = await readBoundedText(res.body, MAX_ERROR_BODY_BYTES);
+        console.error(`klyro: HTTP ${res.status} ${res.statusText}\n${text}`);
+        process.exit(1);
+    }
+    if (!res.body) {
+        console.error('klyro: response had no body');
+        process.exit(1);
+    }
+    try {
+        await streamToStdout(res.body, ac.signal);
+    }
+    catch (err) {
+        if (ac.signal.aborted) {
+            // Cancelled by us (timeout) or the caller. Quiet exit.
+            return;
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nklyro: stream error: ${msg}`);
+        process.exit(1);
+    }
+}
+/**
+ * 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 async function streamToStdout(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buf = '';
+    process.stdout.write('\n');
+    try {
+        while (true) {
+            if (signal.aborted)
+                throw new Error('aborted');
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buf.indexOf('\n')) !== -1) {
+                if (signal.aborted)
+                    throw new Error('aborted');
+                const line = buf.slice(0, idx).replace(/\r$/, '');
+                buf = buf.slice(idx + 1);
+                if (!line.startsWith('data:'))
+                    continue;
+                const data = line.slice(5).trim();
+                if (data === '[DONE]') {
+                    process.stdout.write('\n');
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(data);
+                }
+                catch {
+                    continue;
+                }
+                const text = parsed.choices?.[0]?.delta?.content;
+                if (text) {
+                    if (!await writeWithBackpressure(text)) {
+                        // stdout closed (pipe severed). Stop reading.
+                        try {
+                            await reader.cancel();
+                        }
+                        catch {
+                            /* ignore */
+                        }
+                        return;
+                    }
+                }
+            }
+        }
+        process.stdout.write('\n');
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* already released */
+        }
+    }
+}
+/**
+ * Write to stdout and wait for the drain event if the buffer is full.
+ * Returns false if stdout has been closed (e.g. piped to `head`).
+ */
+function writeWithBackpressure(chunk) {
+    return new Promise((resolve) => {
+        if (!process.stdout.write(chunk)) {
+            const onDrain = () => {
+                process.stdout.off('error', onError);
+                resolve(true);
+            };
+            const onError = () => {
+                process.stdout.off('drain', onDrain);
+                resolve(false);
+            };
+            process.stdout.once('drain', onDrain);
+            process.stdout.once('error', onError);
+        }
+        else {
+            resolve(true);
+        }
+    });
+}
+/**
+ * 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 async function readBoundedText(body, max) {
+    if (!body)
+        return '';
+    const reader = body.getReader();
+    let received = 0;
+    const chunks = [];
+    try {
+        while (received < max) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            const remaining = max - received;
+            if (value.byteLength <= remaining) {
+                chunks.push(value);
+                received += value.byteLength;
+            }
+            else {
+                chunks.push(value.slice(0, remaining));
+                received += remaining;
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    const decoder = new TextDecoder('utf-8');
+    const text = decoder.decode(Buffer.concat(chunks));
+    return received >= max ? `${text}\n[truncated]` : text;
+}

package/dist/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../src/chat.ts"],"names":[],"mappings":"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"}

package/dist/cli/eval.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `klyro eval` — drive the agent runtime against scripted scenarios.
+ *
+ * Useful for:
+ *  - regression testing the loop (status code, tool call count, etc.)
+ *  - reproducing a buggy run from a saved transcript
+ *  - smoke-testing provider adapters without hitting a real API
+ *
+ * Each scenario in the JSONL input is one object:
+ *
+ *   {
+ *     "name": "string-contains-shell",
+ *     "task": "say hi and run shell_exec",
+ *     "model": "mock",
+ *     "maxSteps": 5,
+ *     "scripted_events": [
+ *       [["message_start"], ["text_delta", "Hello"], ["message_end", "stop"]],
+ *       [["message_start"], ["tool_call_start", "c1", "shell_exec"],
+ *        ["tool_call_delta", "c1", "{\"command\":\"echo hi\"}"],
+ *        ["tool_call_end", "c1"], ["message_end", "tool_calls"]]
+ *     ],
+ *     "expect": {
+ *       "status": "complete" | "max_steps" | "no_final" | "aborted",
+ *       "textContains": "Hello",
+ *       "toolCallsAtLeast": 1,
+ *       "toolCallsAtMost": 3
+ *     }
+ *   }
+ *
+ * `scripted_events` is an array of *steps*; each step is an array of
+ * [eventKind, ...args] tuples. The i-th step of the scenario is fed to
+ * the i-th call to the adapter.stream() generator.
+ *
+ * If `scripted_events` is omitted or empty, the scenario just runs to
+ * max_steps with no model output (useful for testing the harness
+ * itself).
+ *
+ * Output: prints each scenario's pass/fail as a line; if --output json
+ * is set, emits one JSON object per line. Exit code 0 if all pass, 1
+ * otherwise.
+ */
+import { type RunResult } from '../agent/runtime.js';
+import type { ProviderAdapter } from '../agent/provider-adapter.js';
+export interface EvalScenario {
+    name: string;
+    task: string;
+    model?: string;
+    maxSteps?: number;
+    maxTokens?: number;
+    /** Adapter events to script, as [eventKind, ...args] tuples. */
+    scripted_events?: Array<Array<unknown[]>>;
+    expect?: {
+        status?: RunResult['status'];
+        textContains?: string;
+        toolCallsAtLeast?: number;
+        toolCallsAtMost?: number;
+    };
+}
+export interface EvalResult {
+    name: string;
+    passed: boolean;
+    failures: string[];
+    status: RunResult['status'];
+    steps: number;
+    toolCalls: number;
+    text: string;
+    durationMs: number;
+}
+export interface RunEvalOptions {
+    inputPath: string;
+    output: 'human' | 'json' | 'silent';
+}
+export declare function runEval(opts: RunEvalOptions): Promise<number>;
+export declare function scriptedAdapterFromSpec(spec: Array<Array<unknown[]>> | undefined): ProviderAdapter;
+export declare function runScenario(sc: EvalScenario): Promise<EvalResult>;

package/dist/cli/eval.js

@@ -0,0 +1,190 @@
+/**
+ * `klyro eval` — drive the agent runtime against scripted scenarios.
+ *
+ * Useful for:
+ *  - regression testing the loop (status code, tool call count, etc.)
+ *  - reproducing a buggy run from a saved transcript
+ *  - smoke-testing provider adapters without hitting a real API
+ *
+ * Each scenario in the JSONL input is one object:
+ *
+ *   {
+ *     "name": "string-contains-shell",
+ *     "task": "say hi and run shell_exec",
+ *     "model": "mock",
+ *     "maxSteps": 5,
+ *     "scripted_events": [
+ *       [["message_start"], ["text_delta", "Hello"], ["message_end", "stop"]],
+ *       [["message_start"], ["tool_call_start", "c1", "shell_exec"],
+ *        ["tool_call_delta", "c1", "{\"command\":\"echo hi\"}"],
+ *        ["tool_call_end", "c1"], ["message_end", "tool_calls"]]
+ *     ],
+ *     "expect": {
+ *       "status": "complete" | "max_steps" | "no_final" | "aborted",
+ *       "textContains": "Hello",
+ *       "toolCallsAtLeast": 1,
+ *       "toolCallsAtMost": 3
+ *     }
+ *   }
+ *
+ * `scripted_events` is an array of *steps*; each step is an array of
+ * [eventKind, ...args] tuples. The i-th step of the scenario is fed to
+ * the i-th call to the adapter.stream() generator.
+ *
+ * If `scripted_events` is omitted or empty, the scenario just runs to
+ * max_steps with no model output (useful for testing the harness
+ * itself).
+ *
+ * Output: prints each scenario's pass/fail as a line; if --output json
+ * is set, emits one JSON object per line. Exit code 0 if all pass, 1
+ * otherwise.
+ */
+import * as fs from 'node:fs';
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout, stderr } from 'node:process';
+import { run } from '../agent/runtime.js';
+import { builtinRegistry } from '../tools/registry.js';
+import { builtinRules, DEFAULT_POLICY_CONFIG, PolicyEngine } from '../policy/engine.js';
+import { DenyAllApprovalPrompt } from '../policy/approval.js';
+export async function runEval(opts) {
+    const scenarios = await readScenarios(opts.inputPath);
+    if (scenarios.length === 0) {
+        stderr.write('klyro eval: no scenarios in input\n');
+        return 2;
+    }
+    const results = [];
+    for (const sc of scenarios) {
+        const start = Date.now();
+        const r = await runScenario(sc);
+        r.durationMs = Date.now() - start;
+        results.push(r);
+        if (opts.output === 'json') {
+            stdout.write(JSON.stringify({ kind: 'eval_result', ...r }) + '\n');
+        }
+        else if (opts.output === 'human') {
+            const tag = r.passed ? 'PASS' : 'FAIL';
+            stdout.write(`[${tag}] ${r.name} (${r.durationMs}ms, ${r.steps} steps, ${r.toolCalls} tools)\n`);
+            for (const f of r.failures)
+                stdout.write(`         - ${f}\n`);
+        }
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const failed = results.length - passed;
+    if (opts.output === 'json') {
+        stdout.write(JSON.stringify({ kind: 'eval_summary', total: results.length, passed, failed }) + '\n');
+    }
+    else if (opts.output === 'human') {
+        stdout.write(`\n${passed}/${results.length} passed\n`);
+    }
+    return failed === 0 ? 0 : 1;
+}
+async function readScenarios(path) {
+    const text = await readAll(path);
+    const out = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        out.push(JSON.parse(trimmed));
+    }
+    return out;
+}
+async function readAll(path) {
+    if (path === '-') {
+        // Drain stdin.
+        const chunks = [];
+        const rl = readline.createInterface({ input, crlfDelay: Infinity });
+        for await (const line of rl)
+            chunks.push(Buffer.from(line + '\n', 'utf8'));
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    return fs.promises.readFile(path, 'utf8');
+}
+export function scriptedAdapterFromSpec(spec) {
+    const steps = spec ?? [];
+    let i = 0;
+    return {
+        id: 'scripted',
+        async *stream() {
+            if (i < steps.length) {
+                const step = steps[i++];
+                if (!step)
+                    return;
+                for (const tuple of step) {
+                    yield tupleToEvent(tuple);
+                }
+            }
+            else {
+                // No more scripted output — emit message_end so the loop terminates
+                // with status='no_final' if max_steps isn't reached, or max_steps otherwise.
+                yield { kind: 'message_start' };
+                yield { kind: 'message_end', finishReason: 'stop' };
+            }
+        },
+    };
+}
+function tupleToEvent(tuple) {
+    const [kind, ...args] = tuple;
+    switch (kind) {
+        case 'message_start':
+            return { kind: 'message_start', id: args[0], model: args[1] };
+        case 'text_delta':
+            return { kind: 'text_delta', text: args[0] };
+        case 'message_end':
+            return { kind: 'message_end', finishReason: args[0], usage: args[1] };
+        case 'tool_call_start':
+            return { kind: 'tool_call_start', id: args[0], name: args[1] };
+        case 'tool_call_delta':
+            return { kind: 'tool_call_delta', id: args[0], argsJson: args[1] };
+        case 'tool_call_end':
+            return { kind: 'tool_call_end', id: args[0] };
+        case 'error':
+            return { kind: 'error', code: args[0], message: args[1], retryable: Boolean(args[2]) };
+        default:
+            throw new Error(`scriptedAdapterFromSpec: unknown event kind: ${kind}`);
+    }
+}
+export async function runScenario(sc) {
+    const failures = [];
+    const model = sc.model ?? 'mock';
+    const adapter = scriptedAdapterFromSpec(sc.scripted_events);
+    const registry = builtinRegistry();
+    const policy = new PolicyEngine(builtinRules(), DEFAULT_POLICY_CONFIG);
+    const result = await run({
+        task: sc.task,
+        cwd: process.cwd(),
+        model,
+        maxSteps: sc.maxSteps,
+        maxTokens: sc.maxTokens,
+        nonInteractive: true,
+    }, {
+        adapter,
+        registry,
+        policy,
+        approval: new DenyAllApprovalPrompt(),
+        systemPrompt: ({ cwd }) => `You are Klyro. cwd=${cwd}.`,
+    });
+    const exp = sc.expect ?? {};
+    if (exp.status !== undefined && result.status !== exp.status) {
+        failures.push(`status: expected ${exp.status}, got ${result.status}`);
+    }
+    if (exp.textContains !== undefined && !result.finalText.includes(exp.textContains)) {
+        failures.push(`text: expected to contain "${exp.textContains}", got "${result.finalText}"`);
+    }
+    if (exp.toolCallsAtLeast !== undefined && result.toolCalls < exp.toolCallsAtLeast) {
+        failures.push(`toolCalls: expected >= ${exp.toolCallsAtLeast}, got ${result.toolCalls}`);
+    }
+    if (exp.toolCallsAtMost !== undefined && result.toolCalls > exp.toolCallsAtMost) {
+        failures.push(`toolCalls: expected <= ${exp.toolCallsAtMost}, got ${result.toolCalls}`);
+    }
+    return {
+        name: sc.name,
+        passed: failures.length === 0,
+        failures,
+        status: result.status,
+        steps: result.steps,
+        toolCalls: result.toolCalls,
+        text: result.finalText,
+        durationMs: 0,
+    };
+}

package/dist/cli/repl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `klyro` (no args) — the TUI REPL.
+ *
+ * Loads config from env, builds the agent runtime deps, mounts the
+ * Ink app, and bridges RuntimeEvents to the app's transcript/status
+ * via the global hooks installed by App.useEffect.
+ */
+export interface ReplOptions {
+    systemPrompt?: string;
+    cwd?: string;
+    maxSteps?: number;
+    model?: string;
+    nonInteractive?: boolean;
+}
+export declare function startRepl(opts?: ReplOptions): Promise<number>;