klyro 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 siddu-lingampelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# Klyro
+
+Minimal streaming CLI for any OpenAI-compatible LLM endpoint. **Foundation piece** of the Klyro harness project.
+
+## What works today
+
+- Streams from `https://<host>/v1/chat/completions`
+- HTTPS-only (with localhost exemption for local LLMs)
+- Per-request timeout
+- Interactive REPL with multi-turn history
+- Bounded error reads
+- Strict TypeScript, zero dependencies beyond `commander`
+
+## Quick start
+
+```bash
+npm run build
+export KLYRO_BASE_URL="https://api.groq.com/openai/v1"
+export KLYRO_API_KEY="gsk_..."
+export KLYRO_MODEL="openai/gpt-oss-20b"
+
+# One-shot
+node dist/index.js chat "Explain TypeScript in 2 sentences"
+
+# Interactive
+node dist/index.js chat
+```
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| [`docs/done.md`](docs/done.md) | **Status** — what's built, what's verified, what isn't |
+| [`docs/plan.md`](docs/plan.md) | **Roadmap** — 20-level plan from bare CLI to super-harness |
+| [`docs/PRD.md`](docs/PRD.md) | (authoritative) product vision |
+| [`docs/HarnessFlow.md`](docs/HarnessFlow.md) | (authoritative) system flow |
+| [`docs/MVP.md`](docs/MVP.md) | (authoritative) MVP scope |
+
+## Code structure
+
+```
+src/
+├── index.ts   # commander entry — two commands (chat, REPL)
+├── chat.ts    # single-turn streaming chat (251 LOC)
+└── repl.ts    # multi-turn REPL (168 LOC)
+```
+
+## License
+
+MIT

package/dist/agent/anthropic-adapter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Anthropic Messages API provider adapter.
+ *
+ * Translates the normalized ProviderAdapter surface to the Anthropic
+ * /v1/messages streaming endpoint. Distinct from httpChatAdapter (which
+ * speaks the OpenAI chat-completions protocol) in three ways:
+ *
+ *  1. `system` is a top-level field, not a message with role=system.
+ *  2. Tool definitions use `input_schema` not `parameters`, and have no
+ *     `type: 'function'` wrapper.
+ *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
+ *     `input_json_delta` block.
+ *
+ * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
+ * Auth can be a Bearer token (for proxies) — the adapter accepts either.
+ */
+import type { Message } from './message.js';
+import type { ProviderAdapter, ToolDefinition } from './provider-adapter.js';
+export interface AnthropicAdapterOptions {
+    baseURL?: string;
+    apiKey: string;
+    /** Per-request timeout in ms (default 120_000). */
+    timeoutMs?: number;
+    /** Override fetch (e.g. for tests). */
+    fetchImpl?: typeof fetch;
+    /** Override the Anthropic API version. Default '2023-06-01'. */
+    anthropicVersion?: string;
+    /** Override the auth header. Default 'x-api-key'. Set to 'Authorization' for proxy compat. */
+    authHeader?: 'x-api-key' | 'Authorization';
+    /** Beta features (e.g. ['prompt-caching-2024-07-31', 'tools-2024-04-04']). */
+    betas?: string[];
+}
+interface AnthropicMessage {
+    role: 'user' | 'assistant';
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'tool_use';
+        id: string;
+        name: string;
+        input: unknown;
+    } | {
+        type: 'tool_result';
+        tool_use_id: string;
+        content: string | Array<{
+            type: 'text';
+            text: string;
+        }>;
+        is_error?: boolean;
+    }>;
+}
+export declare class AnthropicApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export declare function anthropicAdapter(opts: AnthropicAdapterOptions): ProviderAdapter;
+/** Match an Anthropic content_block index to the tool_use id we emitted. */
+declare function findToolIdByIndex(index: number | undefined, buffers: Map<string, {
+    name: string;
+    argsJson: string;
+}>): string | undefined;
+declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
+declare function toAnthropicTool(t: ToolDefinition): {
+    name: string;
+    description: string;
+    input_schema: unknown;
+};
+export declare const _internal: {
+    toAnthropicMessages: typeof toAnthropicMessages;
+    toAnthropicTool: typeof toAnthropicTool;
+    findToolIdByIndex: typeof findToolIdByIndex;
+};
+export {};

package/dist/agent/anthropic-adapter.js

@@ -0,0 +1,297 @@
+/**
+ * Anthropic Messages API provider adapter.
+ *
+ * Translates the normalized ProviderAdapter surface to the Anthropic
+ * /v1/messages streaming endpoint. Distinct from httpChatAdapter (which
+ * speaks the OpenAI chat-completions protocol) in three ways:
+ *
+ *  1. `system` is a top-level field, not a message with role=system.
+ *  2. Tool definitions use `input_schema` not `parameters`, and have no
+ *     `type: 'function'` wrapper.
+ *  3. `tool_use_id` becomes our `id`; the tool input is sent as a single
+ *     `input_json_delta` block.
+ *
+ * Auth: `x-api-key: <key>`. Version header is sent as `anthropic-version`.
+ * Auth can be a Bearer token (for proxies) — the adapter accepts either.
+ */
+const DEFAULT_VERSION = '2023-06-01';
+const DEFAULT_TIMEOUT_MS = 120_000;
+export class AnthropicApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Anthropic API error ${status}: ${body.slice(0, 500)}`);
+        this.name = 'AnthropicApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+export function anthropicAdapter(opts) {
+    const baseURL = (opts.baseURL ?? 'https://api.anthropic.com').replace(/\/+$/, '');
+    const version = opts.anthropicVersion ?? DEFAULT_VERSION;
+    const authHeader = opts.authHeader ?? 'x-api-key';
+    const betas = opts.betas ?? [];
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error('anthropicAdapter: no fetch available — pass opts.fetchImpl or run on Node 18+');
+    }
+    return {
+        id: 'anthropic',
+        stream(req) {
+            return streamAnthropic(req, {
+                baseURL, apiKey: opts.apiKey, timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                fetchImpl, version, authHeader, betas,
+            });
+        },
+    };
+}
+async function* streamAnthropic(req, opts) {
+    const body = {
+        model: req.model,
+        system: req.system,
+        messages: toAnthropicMessages(req.messages),
+        tools: req.tools.length > 0 ? req.tools.map(toAnthropicTool) : undefined,
+        max_tokens: req.maxTokens ?? 4096,
+        temperature: req.temperature,
+        stream: true,
+    };
+    const url = `${opts.baseURL}/v1/messages`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(new Error('anthropicAdapter: timeout')), opts.timeoutMs);
+    if (req.signal) {
+        if (req.signal.aborted)
+            ac.abort(req.signal.reason);
+        else
+            req.signal.addEventListener('abort', () => ac.abort(req.signal?.reason), { once: true });
+    }
+    const headers = {
+        'content-type': 'application/json',
+        'anthropic-version': opts.version,
+    };
+    if (opts.authHeader === 'x-api-key')
+        headers['x-api-key'] = opts.apiKey;
+    else
+        headers['Authorization'] = `Bearer ${opts.apiKey}`;
+    if (opts.betas.length > 0)
+        headers['anthropic-beta'] = opts.betas.join(',');
+    let resp;
+    try {
+        resp = await opts.fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: ac.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const message = err instanceof Error ? err.message : String(err);
+        const retryable = !/abort/i.test(message) || /timeout/i.test(message);
+        yield { kind: 'error', code: 'transport', message, retryable };
+        return;
+    }
+    clearTimeout(timer);
+    if (!resp.ok || !resp.body) {
+        const text = await resp.text().catch(() => '<unreadable>');
+        yield {
+            kind: 'error',
+            code: `http_${resp.status}`,
+            message: `Anthropic API returned ${resp.status}: ${text.slice(0, 500)}`,
+            retryable: resp.status >= 500 || resp.status === 429,
+        };
+        return;
+    }
+    yield { kind: 'message_start' };
+    // Stream SSE: lines are `event: <type>\ndata: <json>\n\n`.
+    // We use a simple incremental parser; Claude's API guarantees
+    // well-formed SSE.
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buf = '';
+    // Track in-progress tool calls so we can emit start/delta/end.
+    const toolBuffers = new Map();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            // Split on SSE event boundary.
+            const events = [];
+            let idx = 0;
+            while (true) {
+                const start = idx;
+                const sep = buf.indexOf('\n\n', start);
+                if (sep === -1)
+                    break;
+                const chunk = buf.slice(start, sep);
+                idx = sep + 2;
+                let event = 'message';
+                let data = '';
+                for (const line of chunk.split('\n')) {
+                    if (line.startsWith('event:'))
+                        event = line.slice(6).trim();
+                    else if (line.startsWith('data:'))
+                        data += line.slice(5).trim();
+                }
+                if (data)
+                    events.push({ event, data });
+            }
+            buf = buf.slice(idx);
+            for (const e of events) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(e.data);
+                }
+                catch {
+                    continue;
+                }
+                const out = translateSse(e.event, parsed, toolBuffers);
+                for (const ev of out)
+                    yield ev;
+            }
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        yield { kind: 'error', code: 'stream', message, retryable: true };
+        return;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    yield { kind: 'message_end', finishReason: 'stop' };
+}
+function translateSse(event, parsed, toolBuffers) {
+    const out = [];
+    switch (event) {
+        case 'content_block_start': {
+            const block = parsed.content_block;
+            if (block?.type === 'tool_use' && block.id && block.name) {
+                toolBuffers.set(block.id, { name: block.name, argsJson: '' });
+                out.push({ kind: 'tool_call_start', id: block.id, name: block.name });
+            }
+            return out;
+        }
+        case 'content_block_delta': {
+            const delta = parsed.delta;
+            const index = parsed.index;
+            // We need the id to know which tool buffer to update. Anthropic sends
+            // index but not id on delta events. Match by name+index pair.
+            if (delta?.type === 'text_delta' && typeof delta.text === 'string') {
+                out.push({ kind: 'text_delta', text: delta.text });
+            }
+            else if (delta?.type === 'input_json_delta' && typeof delta.partial_json === 'string') {
+                // Find the tool buffer whose index matches this delta.
+                // We map by index order: the i-th tool_use block corresponds to the
+                // i-th tool_start we've emitted. Track that counter separately.
+                const id = findToolIdByIndex(index, toolBuffers);
+                if (id) {
+                    const buf = toolBuffers.get(id);
+                    if (buf) {
+                        buf.argsJson += delta.partial_json;
+                        out.push({ kind: 'tool_call_delta', id, argsJson: delta.partial_json });
+                    }
+                }
+            }
+            return out;
+        }
+        case 'content_block_stop': {
+            // The 'index' of the stopped block tells us which tool finished.
+            // We track tool starts in order and match by index.
+            const index = parsed.index;
+            const id = findToolIdByIndex(index, toolBuffers);
+            if (id) {
+                toolBuffers.delete(id);
+                out.push({ kind: 'tool_call_end', id });
+            }
+            return out;
+        }
+        case 'message_stop': {
+            out.push({ kind: 'message_end', finishReason: 'stop' });
+            return out;
+        }
+        case 'error': {
+            const err = parsed.error;
+            out.push({
+                kind: 'error',
+                code: err?.type ?? 'anthropic_error',
+                message: err?.message ?? 'unknown Anthropic error',
+                retryable: false,
+            });
+            return out;
+        }
+        default:
+            return out;
+    }
+}
+/** Match an Anthropic content_block index to the tool_use id we emitted. */
+function findToolIdByIndex(index, buffers) {
+    if (index === undefined)
+        return undefined;
+    // buffers is a Map preserving insertion order. The index of a tool_use
+    // block is its position among all content blocks, not just tool_use
+    // blocks. We don't know about non-tool blocks, so we use a simpler
+    // heuristic: the index matches the i-th tool_use that has been started
+    // since message_start. This is good enough for streamed responses where
+    // tool blocks are typically 0,1,2...
+    let i = 0;
+    for (const id of buffers.keys()) {
+        if (i === index)
+            return id;
+        i++;
+    }
+    // Fallback: if there's exactly one tool in flight, it's almost certainly it.
+    if (buffers.size === 1)
+        return buffers.keys().next().value;
+    return undefined;
+}
+function toAnthropicMessages(messages) {
+    return messages.map((m) => {
+        if (m.role === 'user') {
+            return {
+                role: 'user',
+                content: m.content.map((b) => {
+                    if (b.kind === 'text')
+                        return { type: 'text', text: b.text };
+                    if (b.kind === 'tool_result') {
+                        const content = typeof b.output === 'string'
+                            ? (b.isError ? `Error: ${b.output}` : b.output)
+                            : JSON.stringify(b.output);
+                        return {
+                            type: 'tool_result',
+                            tool_use_id: b.toolCallId,
+                            content,
+                            is_error: b.isError,
+                        };
+                    }
+                    return { type: 'text', text: '' };
+                }),
+            };
+        }
+        if (m.role === 'assistant') {
+            return {
+                role: 'assistant',
+                content: m.content.map((b) => {
+                    if (b.kind === 'text')
+                        return { type: 'text', text: b.text };
+                    if (b.kind === 'tool_use')
+                        return { type: 'tool_use', id: b.id, name: b.name, input: b.input };
+                    return { type: 'text', text: '' };
+                }),
+            };
+        }
+        // 'system' is hoisted to the top-level `system` field; never appears
+        // in the messages array passed to the adapter.
+        return { role: 'user', content: [{ type: 'text', text: '' }] };
+    });
+}
+function toAnthropicTool(t) {
+    return {
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+    };
+}
+// Re-export for testability.
+export const _internal = { toAnthropicMessages, toAnthropicTool, findToolIdByIndex };

package/dist/agent/message.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Message types shared between provider adapters and the runtime loop.
+ *
+ * Modeled after OpenAI/Anthropic chat-message shapes but kept simple:
+ * a Message has a role and an array of ContentBlocks. ContentBlocks
+ * cover text, tool_use (model asks to call a tool), and tool_result
+ * (the harness feeds back the tool's observation).
+ */
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+export interface TextBlock {
+    kind: 'text';
+    text: string;
+}
+export interface ToolUseBlock {
+    kind: 'tool_use';
+    /** Provider-assigned id; used to match a tool_result. */
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    kind: 'tool_result';
+    /** Matches the ToolUseBlock.id. */
+    toolCallId: string;
+    /** Tool name (for routing on resume and debugging). */
+    name: string;
+    output: unknown;
+    /** True if the tool itself failed (vs returning a normal value). */
+    isError?: boolean;
+}
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+export interface Message {
+    role: Role;
+    content: ContentBlock[];
+}
+export declare function text(s: string): TextBlock;
+export declare function toolUse(id: string, name: string, input: Record<string, unknown>): ToolUseBlock;
+export declare function toolResult(toolCallId: string, name: string, output: unknown, isError?: boolean): ToolResultBlock;
+/** Convenience: extract every ToolUseBlock from an assistant message. */
+export declare function toolUses(m: Message): ToolUseBlock[];

package/dist/agent/message.js

@@ -0,0 +1,21 @@
+/**
+ * Message types shared between provider adapters and the runtime loop.
+ *
+ * Modeled after OpenAI/Anthropic chat-message shapes but kept simple:
+ * a Message has a role and an array of ContentBlocks. ContentBlocks
+ * cover text, tool_use (model asks to call a tool), and tool_result
+ * (the harness feeds back the tool's observation).
+ */
+export function text(s) {
+    return { kind: 'text', text: s };
+}
+export function toolUse(id, name, input) {
+    return { kind: 'tool_use', id, name, input };
+}
+export function toolResult(toolCallId, name, output, isError = false) {
+    return { kind: 'tool_result', toolCallId, name, output, isError };
+}
+/** Convenience: extract every ToolUseBlock from an assistant message. */
+export function toolUses(m) {
+    return m.content.filter((b) => b.kind === 'tool_use');
+}

package/dist/agent/observation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-memory ObservationStore — records every tool call + result during a
+ * single agent run so the runtime can recall "what happened so far" when
+ * deciding the next step.
+ *
+ * MVP: in-memory only (no persistence). Persistence is a later level
+ * (per `docs/plan.md` Level 14: durable session).
+ *
+ * Thread-safety: single agent loop = single owner. No locking needed.
+ */
+import type { ToolResult } from '../tools/types.js';
+/** One recorded observation: a tool invocation + its outcome. */
+export interface Observation {
+    /** Monotonic id assigned at record-time. */
+    readonly id: number;
+    /** Name of the tool that was called. */
+    readonly tool: string;
+    /** Validated input that was passed to the tool. */
+    readonly input: unknown;
+    /** Tool's result — success value or structured error. */
+    readonly result: ToolResult<unknown>;
+    /** Wall-clock ms when execution started. */
+    readonly startedAt: number;
+    /** Wall-clock ms when execution finished. */
+    readonly finishedAt: number;
+    /** Duration in ms. */
+    readonly durationMs: number;
+}
+export declare class ObservationStore {
+    private readonly entries;
+    private nextId;
+    /** Record one completed tool call. Returns the assigned observation. */
+    record(entry: Omit<Observation, 'id'>): Observation;
+    /** All observations in insertion order. */
+    all(): readonly Observation[];
+    /** Most recent N observations. */
+    tail(n: number): readonly Observation[];
+    /** Count of observations recorded so far. */
+    size(): number;
+    /** Clear all observations (e.g. after /clear or compact). */
+    clear(): void;
+    /**
+     * Serialize for use as model context. Returns a compact, model-readable
+     * summary — not the full input/result blobs (those can be huge).
+     */
+    toContextSummary(): string;
+}

package/dist/agent/observation.js

@@ -0,0 +1,53 @@
+/**
+ * In-memory ObservationStore — records every tool call + result during a
+ * single agent run so the runtime can recall "what happened so far" when
+ * deciding the next step.
+ *
+ * MVP: in-memory only (no persistence). Persistence is a later level
+ * (per `docs/plan.md` Level 14: durable session).
+ *
+ * Thread-safety: single agent loop = single owner. No locking needed.
+ */
+export class ObservationStore {
+    entries = [];
+    nextId = 0;
+    /** Record one completed tool call. Returns the assigned observation. */
+    record(entry) {
+        const full = { ...entry, id: this.nextId++ };
+        this.entries.push(full);
+        return full;
+    }
+    /** All observations in insertion order. */
+    all() {
+        return this.entries;
+    }
+    /** Most recent N observations. */
+    tail(n) {
+        if (n <= 0)
+            return [];
+        return this.entries.slice(-n);
+    }
+    /** Count of observations recorded so far. */
+    size() {
+        return this.entries.length;
+    }
+    /** Clear all observations (e.g. after /clear or compact). */
+    clear() {
+        this.entries.length = 0;
+    }
+    /**
+     * Serialize for use as model context. Returns a compact, model-readable
+     * summary — not the full input/result blobs (those can be huge).
+     */
+    toContextSummary() {
+        if (this.entries.length === 0)
+            return '(no tool calls yet)';
+        const lines = [];
+        for (const o of this.entries) {
+            const status = o.result.ok ? 'OK' : `ERR(${o.result.error.code})`;
+            const dur = `${o.durationMs}ms`;
+            lines.push(`#${o.id} ${o.tool} ${status} ${dur}`);
+        }
+        return lines.join('\n');
+    }
+}