klyro 0.1.1

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

@@ -0,0 +1,101 @@
+/**
+ * ProviderAdapter — a normalized streaming chat-completion interface
+ * that the agent runtime consumes.
+ *
+ * Implementations:
+ *   - httpChatAdapter (default): OpenAI-compatible /v1/chat/completions
+ *     with tool calls. Works against api.openai.com, Ollama, LM Studio,
+ *     vLLM, llama.cpp, and any compatible proxy.
+ *
+ * The adapter exposes a single async generator of StreamEvents so the
+ * runtime loop sees one shape regardless of provider quirks.
+ */
+import { z } from 'zod';
+import type { Message } from './message.js';
+export type StreamEvent = {
+    kind: 'text_delta';
+    text: string;
+} | {
+    kind: 'message_start';
+    id?: string;
+    model?: string;
+} | {
+    kind: 'message_end';
+    finishReason?: string;
+    usage?: {
+        input: number;
+        output: number;
+    };
+} | {
+    kind: 'tool_call_start';
+    id: string;
+    name: string;
+} | {
+    kind: 'tool_call_delta';
+    id: string;
+    argsJson: string;
+} | {
+    kind: 'tool_call_end';
+    id: string;
+} | {
+    kind: 'error';
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+export interface CallRequest {
+    model: string;
+    system?: string;
+    messages: Message[];
+    tools: ToolDefinition[];
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+}
+export interface ProviderAdapter {
+    readonly id: string;
+    stream(req: CallRequest): AsyncIterable<StreamEvent>;
+}
+export interface HttpAdapterOptions {
+    baseURL: string;
+    apiKey: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Override fetch (e.g. for tests). */
+    fetchImpl?: typeof fetch;
+}
+/** Convert a Zod schema to a permissive JSON Schema object for tool defs. */
+export declare function zodToJsonSchema(schema: z.ZodType<unknown>): Record<string, unknown>;
+interface ChatCompletionsRequest {
+    model: string;
+    messages: Array<{
+        role: string;
+        content?: string;
+        tool_calls?: unknown[];
+        tool_call_id?: string;
+        name?: string;
+    }>;
+    tools?: Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: unknown;
+        };
+    }>;
+    max_tokens?: number;
+    temperature?: number;
+    stream: true;
+}
+/**
+ * Build the OpenAI-compatible request body from our normalized CallRequest.
+ * Exported for testing.
+ */
+export declare function buildChatCompletionsBody(req: CallRequest): ChatCompletionsRequest;
+export declare function httpChatAdapter(opts: HttpAdapterOptions): ProviderAdapter;
+export {};

package/dist/agent/provider-adapter.js

@@ -0,0 +1,254 @@
+/**
+ * ProviderAdapter — a normalized streaming chat-completion interface
+ * that the agent runtime consumes.
+ *
+ * Implementations:
+ *   - httpChatAdapter (default): OpenAI-compatible /v1/chat/completions
+ *     with tool calls. Works against api.openai.com, Ollama, LM Studio,
+ *     vLLM, llama.cpp, and any compatible proxy.
+ *
+ * The adapter exposes a single async generator of StreamEvents so the
+ * runtime loop sees one shape regardless of provider quirks.
+ */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Convert a Zod schema to a permissive JSON Schema object for tool defs. */
+export function zodToJsonSchema(schema) {
+    // We keep this simple: zod's own _def is enough to give the model a
+    // shape. A full conversion library isn't needed for MVP — most tool
+    // inputs are flat objects with primitive types.
+    const def = schema._def;
+    if (!def)
+        return { type: 'object', properties: {}, additionalProperties: true };
+    if (def.typeName === 'ZodObject' && def.shape) {
+        const props = {};
+        const required = [];
+        for (const [k, v] of Object.entries(def.shape())) {
+            props[k] = zodFieldSchema(v);
+            if (!v.isOptional())
+                required.push(k);
+        }
+        const out = { type: 'object', properties: props };
+        if (required.length)
+            out.required = required;
+        out.additionalProperties = false;
+        return out;
+    }
+    return { type: 'object', properties: {}, additionalProperties: true };
+}
+function zodFieldSchema(s) {
+    const def = s._def;
+    const name = def?.typeName;
+    switch (name) {
+        case 'ZodString':
+            return { type: 'string' };
+        case 'ZodNumber':
+            return { type: 'number' };
+        case 'ZodBoolean':
+            return { type: 'boolean' };
+        case 'ZodArray': {
+            const inner = def?.innerType;
+            return { type: 'array', items: inner ? zodFieldSchema(inner) : { type: 'string' } };
+        }
+        case 'ZodOptional': {
+            const inner = def?.innerType;
+            return inner ? zodFieldSchema(inner) : { type: 'string' };
+        }
+        case 'ZodEnum': {
+            const values = s._def.values;
+            return { type: 'string', enum: [...values] };
+        }
+        case 'ZodObject':
+            return zodToJsonSchema(s);
+        default:
+            return { type: 'string' };
+    }
+}
+/**
+ * Build the OpenAI-compatible request body from our normalized CallRequest.
+ * Exported for testing.
+ */
+export function buildChatCompletionsBody(req) {
+    const messages = [];
+    if (req.system)
+        messages.push({ role: 'system', content: req.system });
+    for (const m of req.messages) {
+        if (m.role === 'assistant') {
+            const text = m.content.filter((b) => b.kind === 'text').map((b) => b.text).join('');
+            const tcs = m.content
+                .filter((b) => b.kind === 'tool_use')
+                .map((b) => {
+                const tb = b;
+                return {
+                    id: tb.id,
+                    type: 'function',
+                    function: { name: tb.name, arguments: JSON.stringify(tb.input) },
+                };
+            });
+            const msg = { role: 'assistant' };
+            if (text)
+                msg.content = text;
+            if (tcs.length)
+                msg.tool_calls = tcs;
+            messages.push(msg);
+        }
+        else if (m.role === 'tool') {
+            for (const b of m.content) {
+                if (b.kind === 'tool_result') {
+                    const tr = b;
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: tr.toolCallId,
+                        name: tr.name,
+                        content: typeof tr.output === 'string' ? tr.output : JSON.stringify(tr.output ?? ''),
+                    });
+                }
+            }
+        }
+        else if (m.role === 'user') {
+            const text = m.content.filter((b) => b.kind === 'text').map((b) => b.text).join('');
+            messages.push({ role: 'user', content: text });
+        }
+    }
+    const body = { model: req.model, messages, stream: true };
+    if (req.maxTokens)
+        body.max_tokens = req.maxTokens;
+    if (typeof req.temperature === 'number')
+        body.temperature = req.temperature;
+    if (req.tools.length) {
+        body.tools = req.tools.map((t) => ({
+            type: 'function',
+            function: { name: t.name, description: t.description, parameters: t.inputSchema },
+        }));
+    }
+    return body;
+}
+export function httpChatAdapter(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `${opts.baseURL.replace(/\/$/, '')}/chat/completions`;
+    return {
+        id: 'http-chat',
+        stream(req) {
+            return streamChatCompletions(url, opts, req, fetchImpl);
+        },
+    };
+}
+async function* streamChatCompletions(url, opts, req, fetchImpl) {
+    const body = buildChatCompletionsBody(req);
+    const ac = new AbortController();
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => ac.abort(new Error(`request timed out after ${timeoutMs}ms`)), timeoutMs);
+    const onAbort = () => ac.abort(req.signal?.reason);
+    req.signal?.addEventListener('abort', onAbort);
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {}),
+            },
+            body: JSON.stringify(body),
+            signal: ac.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timer);
+        req.signal?.removeEventListener('abort', onAbort);
+        const msg = err instanceof Error ? err.message : String(err);
+        yield { kind: 'error', code: 'NETWORK', message: msg, retryable: true };
+        return;
+    }
+    if (!res.ok || !res.body) {
+        clearTimeout(timer);
+        req.signal?.removeEventListener('abort', onAbort);
+        const errText = await res.text().catch(() => '');
+        yield {
+            kind: 'error',
+            code: `HTTP_${res.status}`,
+            message: `provider returned ${res.status}: ${errText.slice(0, 500)}`,
+            retryable: res.status >= 500 || res.status === 429,
+        };
+        return;
+    }
+    yield { kind: 'message_start' };
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    // Track per-tool-call id by index.
+    const toolIds = new Map();
+    const toolNames = new Map();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            // SSE: events separated by \n\n
+            let idx;
+            while ((idx = buf.indexOf('\n\n')) !== -1) {
+                const event = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                for (const line of event.split('\n')) {
+                    if (!line.startsWith('data:'))
+                        continue;
+                    const data = line.slice(5).trim();
+                    if (data === '[DONE]') {
+                        yield { kind: 'message_end' };
+                        return;
+                    }
+                    let chunk;
+                    try {
+                        chunk = JSON.parse(data);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const choice of chunk.choices) {
+                        if (choice.delta.content) {
+                            yield { kind: 'text_delta', text: choice.delta.content };
+                        }
+                        for (const tc of choice.delta.tool_calls ?? []) {
+                            if (tc.id && tc.function?.name) {
+                                toolIds.set(tc.index, tc.id);
+                                toolNames.set(tc.index, tc.function.name);
+                                yield { kind: 'tool_call_start', id: tc.id, name: tc.function.name };
+                            }
+                            else if (tc.id) {
+                                toolIds.set(tc.index, tc.id);
+                            }
+                            if (tc.function?.arguments) {
+                                const id = toolIds.get(tc.index) ?? `call_${tc.index}`;
+                                yield { kind: 'tool_call_delta', id, argsJson: tc.function.arguments };
+                            }
+                        }
+                        if (choice.finish_reason) {
+                            const usage = chunk.usage
+                                ? { input: chunk.usage.prompt_tokens, output: chunk.usage.completion_tokens }
+                                : undefined;
+                            yield { kind: 'message_end', finishReason: choice.finish_reason, usage };
+                        }
+                    }
+                }
+            }
+        }
+        if (toolIds.size) {
+            for (const id of toolIds.values())
+                yield { kind: 'tool_call_end', id };
+        }
+        else {
+            yield { kind: 'message_end' };
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        yield { kind: 'error', code: 'STREAM', message: msg, retryable: true };
+    }
+    finally {
+        clearTimeout(timer);
+        req.signal?.removeEventListener('abort', onAbort);
+        try {
+            reader.releaseLock();
+        }
+        catch { /* ignore */ }
+    }
+}

package/dist/agent/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Provider registry — config-driven selection of ProviderAdapter.
+ *
+ * Two providers today:
+ *   - "openai"  → OpenAI-compatible /v1/chat/completions (works with
+ *                 OpenAI, Azure, Ollama, vLLM, LocalAI, OpenRouter,
+ *                 Anthropic's OpenAI-compat endpoint, etc.)
+ *   - "anthropic" → Anthropic's native /v1/messages streaming API
+ *
+ * Selection precedence (later overrides earlier):
+ *   1. function arg (e.g. --provider CLI flag)
+ *   2. KLYRO_PROVIDER env var
+ *   3. inference from KLYRO_BASE_URL host (heuristic)
+ *   4. default: "openai"
+ *
+ * The result is wrapped in retryingAdapter by default. Pass
+ * { retry: false } to skip.
+ */
+import type { ProviderAdapter } from './provider-adapter.js';
+import { type RetryOptions } from './retry.js';
+export type ProviderName = 'openai' | 'anthropic';
+export interface BuildProviderOptions {
+    provider?: ProviderName;
+    baseURL?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    retry?: Partial<RetryOptions> | false;
+}
+export declare function inferProviderFromBaseURL(baseURL: string | undefined): ProviderName;
+export declare function buildProvider(opts?: BuildProviderOptions): ProviderAdapter;
+/**
+ * Build the provider used by `klyro run` / `klyro chat` — honors --provider
+ * flag, then KLYRO_PROVIDER env, then heuristic.
+ *
+ * This is the version called from CLI entry points.
+ */
+export declare function buildProviderFromCli(args: {
+    provider?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+}): ProviderAdapter;

package/dist/agent/registry.js

@@ -0,0 +1,86 @@
+/**
+ * Provider registry — config-driven selection of ProviderAdapter.
+ *
+ * Two providers today:
+ *   - "openai"  → OpenAI-compatible /v1/chat/completions (works with
+ *                 OpenAI, Azure, Ollama, vLLM, LocalAI, OpenRouter,
+ *                 Anthropic's OpenAI-compat endpoint, etc.)
+ *   - "anthropic" → Anthropic's native /v1/messages streaming API
+ *
+ * Selection precedence (later overrides earlier):
+ *   1. function arg (e.g. --provider CLI flag)
+ *   2. KLYRO_PROVIDER env var
+ *   3. inference from KLYRO_BASE_URL host (heuristic)
+ *   4. default: "openai"
+ *
+ * The result is wrapped in retryingAdapter by default. Pass
+ * { retry: false } to skip.
+ */
+import { httpChatAdapter } from './provider-adapter.js';
+import { anthropicAdapter } from './anthropic-adapter.js';
+import { retryingAdapter } from './retry.js';
+/** Heuristic: hosts that look like Anthropic's API. */
+function looksLikeAnthropic(host) {
+    return /(^|\.)anthropic\.com$/i.test(host) || /anthropic/i.test(host);
+}
+export function inferProviderFromBaseURL(baseURL) {
+    if (!baseURL)
+        return 'openai';
+    try {
+        const u = new URL(baseURL);
+        return looksLikeAnthropic(u.hostname) ? 'anthropic' : 'openai';
+    }
+    catch {
+        return 'openai';
+    }
+}
+export function buildProvider(opts = {}) {
+    const baseURL = opts.baseURL ?? process.env.KLYRO_BASE_URL;
+    const apiKey = opts.apiKey ?? process.env.KLYRO_API_KEY;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    // Resolve provider.
+    let provider;
+    if (opts.provider) {
+        provider = opts.provider;
+    }
+    else if (process.env.KLYRO_PROVIDER === 'anthropic' || process.env.KLYRO_PROVIDER === 'openai') {
+        provider = process.env.KLYRO_PROVIDER;
+    }
+    else {
+        provider = inferProviderFromBaseURL(baseURL);
+    }
+    let inner;
+    if (provider === 'anthropic') {
+        if (!apiKey) {
+            throw new Error('buildProvider: anthropic provider requires an apiKey (or KLYRO_API_KEY).');
+        }
+        inner = anthropicAdapter({ baseURL, apiKey, timeoutMs });
+    }
+    else {
+        if (!baseURL || !apiKey) {
+            throw new Error('buildProvider: openai provider requires baseURL and apiKey (or KLYRO_BASE_URL + KLYRO_API_KEY).');
+        }
+        inner = httpChatAdapter({ baseURL, apiKey, timeoutMs });
+    }
+    if (opts.retry === false)
+        return inner;
+    return retryingAdapter(inner, opts.retry ?? {});
+}
+/**
+ * Build the provider used by `klyro run` / `klyro chat` — honors --provider
+ * flag, then KLYRO_PROVIDER env, then heuristic.
+ *
+ * This is the version called from CLI entry points.
+ */
+export function buildProviderFromCli(args) {
+    const provider = args.provider;
+    if (provider && provider !== 'openai' && provider !== 'anthropic') {
+        throw new Error(`unknown provider: ${provider}`);
+    }
+    return buildProvider({
+        provider,
+        baseURL: args.baseUrl,
+        apiKey: args.apiKey,
+        timeoutMs: args.timeoutMs,
+    });
+}

package/dist/agent/retry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Retry wrapper for ProviderAdapter.
+ *
+ * Wraps a ProviderAdapter.stream so that on a yielded `error` event with
+ * `retryable: true`, the request is re-issued with exponential backoff +
+ * jitter. Non-retryable errors fall through immediately.
+ *
+ * Important: this only retries errors that the adapter itself surfaces
+ * via StreamEvent. The adapter is responsible for translating HTTP
+ * status codes to retryable: true/false. We never reach into the
+ * adapter to retry raw transport errors.
+ *
+ * The retry consumes the entire generator each attempt, then re-issues.
+ * Between attempts we sleep with backoff:
+ *
+ *   delay = min(maxMs, baseMs * 2^attempt) ± jitter
+ *
+ * The default policy matches the L6 plan: 3 attempts, 500ms base, 8s cap.
+ */
+import type { ProviderAdapter } from './provider-adapter.js';
+export interface RetryOptions {
+    maxAttempts: number;
+    baseMs: number;
+    maxMs: number;
+    /** Per-attempt AbortSignal honored — abort cancels the sleep + the next call. */
+    signal?: AbortSignal;
+    /** Sleep impl — tests inject a synchronous zero. Default: real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Test hook: called once per attempt with 0-indexed attempt number. */
+    onAttempt?: (attempt: number) => void;
+}
+export declare const DEFAULT_RETRY: Required<Omit<RetryOptions, 'signal' | 'onAttempt'>>;
+export declare function computeBackoff(attempt: number, baseMs: number, maxMs: number): number;
+export declare function retryingAdapter(inner: ProviderAdapter, opts?: Partial<RetryOptions>): ProviderAdapter;

package/dist/agent/retry.js

@@ -0,0 +1,91 @@
+/**
+ * Retry wrapper for ProviderAdapter.
+ *
+ * Wraps a ProviderAdapter.stream so that on a yielded `error` event with
+ * `retryable: true`, the request is re-issued with exponential backoff +
+ * jitter. Non-retryable errors fall through immediately.
+ *
+ * Important: this only retries errors that the adapter itself surfaces
+ * via StreamEvent. The adapter is responsible for translating HTTP
+ * status codes to retryable: true/false. We never reach into the
+ * adapter to retry raw transport errors.
+ *
+ * The retry consumes the entire generator each attempt, then re-issues.
+ * Between attempts we sleep with backoff:
+ *
+ *   delay = min(maxMs, baseMs * 2^attempt) ± jitter
+ *
+ * The default policy matches the L6 plan: 3 attempts, 500ms base, 8s cap.
+ */
+export const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    baseMs: 500,
+    maxMs: 8_000,
+    sleep: defaultSleep,
+};
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* streamWithAbort(source, signal) {
+    if (!signal) {
+        for await (const ev of source)
+            yield ev;
+        return;
+    }
+    const it = source[Symbol.asyncIterator]();
+    while (true) {
+        if (signal.aborted)
+            return;
+        const next = await it.next();
+        if (next.done)
+            return;
+        yield next.value;
+    }
+}
+export function computeBackoff(attempt, baseMs, maxMs) {
+    const exp = Math.min(maxMs, baseMs * 2 ** attempt);
+    // Jitter: ±25% to spread thundering herds.
+    const jitter = exp * 0.25 * (Math.random() * 2 - 1);
+    return Math.max(0, Math.floor(exp + jitter));
+}
+export function retryingAdapter(inner, opts = {}) {
+    const cfg = { ...DEFAULT_RETRY, ...opts };
+    const sleep = opts.sleep ?? defaultSleep;
+    return {
+        id: `${inner.id}+retry`,
+        async *stream(req, signal) {
+            const effectiveSignal = signal ?? opts.signal;
+            for (let attempt = 0; attempt < cfg.maxAttempts; attempt++) {
+                opts.onAttempt?.(attempt);
+                if (effectiveSignal?.aborted)
+                    return;
+                let sawRetryable = false;
+                let lastError = null;
+                for await (const ev of streamWithAbort(inner.stream(req), effectiveSignal)) {
+                    if (effectiveSignal?.aborted)
+                        return;
+                    if (ev.kind === 'error' && ev.retryable) {
+                        // Buffer the retryable error; don't yield it yet. We'll either
+                        // re-issue (and the caller will never see the error) or, on
+                        // final attempt, yield it as the terminal error.
+                        sawRetryable = true;
+                        lastError = ev;
+                        break; // stop consuming; the stream is dead on retryable errors.
+                    }
+                    yield ev;
+                }
+                if (!sawRetryable)
+                    return; // success or non-retryable error — done.
+                if (attempt === cfg.maxAttempts - 1) {
+                    // Final attempt failed — surface the error.
+                    if (lastError)
+                        yield lastError;
+                    return;
+                }
+                const delay = computeBackoff(attempt, cfg.baseMs, cfg.maxMs);
+                if (delay > 0)
+                    await sleep(delay);
+            }
+        },
+    };
+}