klyro 1.0.0 → 1.0.2

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

@@ -30,7 +30,14 @@ export interface AnthropicAdapterOptions {
     authHeader?: 'x-api-key' | 'Authorization';
     /** Beta features (e.g. ['prompt-caching-2024-07-31', 'tools-2024-04-04']). */
     betas?: string[];
+    /**
+     * Prompt caching: put a `cache_control: {type:'ephemeral'}` breakpoint on
+     * the stable system block and send the `prompt-caching-2024-07-31` beta
+     * (merged with user betas). Default true.
+     */
+    promptCache?: boolean;
 }
+export declare const PROMPT_CACHING_BETA = "prompt-caching-2024-07-31";
 interface AnthropicMessage {
     role: 'user' | 'assistant';
     content: Array<{
@@ -51,6 +58,28 @@ interface AnthropicMessage {
         is_error?: boolean;
     }>;
 }
+interface AnthropicRequest {
+    model: string;
+    system?: string | Array<{
+        type: 'text';
+        text: string;
+        cache_control?: {
+            type: 'ephemeral';
+        };
+    }>;
+    messages: AnthropicMessage[];
+    tools?: Array<{
+        name: string;
+        description: string;
+        input_schema: unknown;
+        cache_control?: {
+            type: 'ephemeral';
+        };
+    }>;
+    max_tokens: number;
+    temperature?: number;
+    stream: true;
+}
 interface AnthropicSseEvent {
     type: string;
     [key: string]: unknown;
@@ -61,6 +90,21 @@ export declare class AnthropicApiError extends Error {
     constructor(status: number, body: string);
 }
 export declare function anthropicAdapter(opts: AnthropicAdapterOptions): ProviderAdapter;
+/**
+ * Build the Anthropic `system` field. The stable system text gets the
+ * cache breakpoint; the volatile telemetry suffix (when present) rides as
+ * a second, uncached block so it never poisons the prefix cache.
+ * Exported via _internal for testing.
+ */
+export declare function buildAnthropicSystem(system: string | undefined, suffix: string | undefined, promptCache: boolean): AnthropicRequest['system'];
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export declare function buildAnthropicTools(tools: ToolDefinition[], promptCache: boolean): AnthropicRequest['tools'];
 /**
  * Mutable per-stream assembly state. Blocks are keyed by content_block
  * index; the tool id is carried inside the block entry. There is no global
@@ -79,18 +123,18 @@ interface AnthropicStreamState {
     usage: {
         input?: number;
         output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
 }
 declare function translateSse(event: string, parsed: AnthropicSseEvent, state: AnthropicStreamState): StreamEvent[];
 declare function toAnthropicMessages(messages: Message[]): AnthropicMessage[];
-declare function toAnthropicTool(t: ToolDefinition): {
-    name: string;
-    description: string;
-    input_schema: unknown;
-};
+declare function toAnthropicTool(t: ToolDefinition): NonNullable<AnthropicRequest['tools']>[number];
 export declare const _internal: {
     toAnthropicMessages: typeof toAnthropicMessages;
     toAnthropicTool: typeof toAnthropicTool;
     translateSse: typeof translateSse;
+    buildAnthropicSystem: typeof buildAnthropicSystem;
+    buildAnthropicTools: typeof buildAnthropicTools;
 };
 export {};

package/dist/agent/anthropic-adapter.js

@@ -19,6 +19,7 @@ import { assertSafeBaseURL } from '../chat.js';
 import { parseRetryAfterMs } from './provider-adapter.js';
 const DEFAULT_VERSION = '2023-06-01';
 const DEFAULT_TIMEOUT_MS = 120_000;
+export const PROMPT_CACHING_BETA = 'prompt-caching-2024-07-31';
 export class AnthropicApiError extends Error {
     status;
     body;
@@ -35,7 +36,10 @@ export function anthropicAdapter(opts) {
     const baseURL = rawBase.replace(/\/+$/, '');
     const version = opts.anthropicVersion ?? DEFAULT_VERSION;
     const authHeader = opts.authHeader ?? 'x-api-key';
-    const betas = opts.betas ?? [];
+    const promptCache = opts.promptCache ?? true;
+    const betas = [...(opts.betas ?? [])];
+    if (promptCache && !betas.includes(PROMPT_CACHING_BETA))
+        betas.push(PROMPT_CACHING_BETA);
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
         throw new Error('anthropicAdapter: no fetch available — pass opts.fetchImpl or run on Node 18+');
@@ -45,17 +49,55 @@ export function anthropicAdapter(opts) {
         stream(req) {
             return streamAnthropic(req, {
                 baseURL, apiKey: opts.apiKey, timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-                fetchImpl, version, authHeader, betas,
+                fetchImpl, version, authHeader, betas, promptCache,
             });
         },
     };
 }
+/**
+ * Build the Anthropic `system` field. The stable system text gets the
+ * cache breakpoint; the volatile telemetry suffix (when present) rides as
+ * a second, uncached block so it never poisons the prefix cache.
+ * Exported via _internal for testing.
+ */
+export function buildAnthropicSystem(system, suffix, promptCache) {
+    const hasSuffix = suffix !== undefined && suffix !== '';
+    const breakpoint = promptCache ? { cache_control: { type: 'ephemeral' } } : {};
+    if (hasSuffix) {
+        if (!system)
+            return promptCache ? [{ type: 'text', text: suffix, ...breakpoint }] : suffix;
+        return [
+            { type: 'text', text: system, ...breakpoint },
+            { type: 'text', text: suffix },
+        ];
+    }
+    if (!system)
+        return undefined;
+    return promptCache ? [{ type: 'text', text: system, ...breakpoint }] : system;
+}
+/**
+ * Build the Anthropic `tools` array. When prompt caching is enabled, the
+ * last tool carries a `cache_control: {type:'ephemeral'}` breakpoint so
+ * the (usually stable) tool definitions join the cacheable prefix —
+ * mirroring the system-text breakpoint. OpenAI path untouched.
+ * Exported via _internal for testing.
+ */
+export function buildAnthropicTools(tools, promptCache) {
+    if (tools.length === 0)
+        return undefined;
+    const out = tools.map(toAnthropicTool);
+    if (promptCache) {
+        const last = out[out.length - 1];
+        last.cache_control = { type: 'ephemeral' };
+    }
+    return out;
+}
 async function* streamAnthropic(req, opts) {
     const body = {
         model: req.model,
-        system: req.system,
+        system: buildAnthropicSystem(req.system, req.systemSuffix, opts.promptCache),
         messages: toAnthropicMessages(req.messages),
-        tools: req.tools.length > 0 ? req.tools.map(toAnthropicTool) : undefined,
+        tools: buildAnthropicTools(req.tools, opts.promptCache),
         max_tokens: req.maxTokens ?? 4096,
         temperature: req.temperature,
         stream: true,
@@ -98,11 +140,15 @@ async function* streamAnthropic(req, opts) {
     clearTimeout(timer);
     if (!resp.ok || !resp.body) {
         const text = await resp.text().catch(() => '<unreadable>');
-        const retryable = resp.status >= 500 || resp.status === 429;
+        // 413 / request_too_large (or a too-long-prompt message) is context
+        // overflow, not transient: dedicated code, never retryable here — the
+        // runtime owns compress-and-retry.
+        const isOverflow = resp.status === 413 || /request_too_large|too_large|prompt_too_long|context_length|maximum context length|prompt is too long/i.test(text);
+        const retryable = !isOverflow && (resp.status >= 500 || resp.status === 429);
         const retryAfterMs = retryable ? parseRetryAfterMs(resp.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
-            code: `http_${resp.status}`,
+            code: isOverflow ? 'REQUEST_TOO_LARGE' : `http_${resp.status}`,
             message: `Anthropic API returned ${resp.status}: ${text.slice(0, 500)}`,
             retryable,
             status: String(resp.status),
@@ -208,25 +254,45 @@ async function* streamAnthropic(req, opts) {
             kind: 'message_end',
             finishReason: 'stop',
             ...(state.usage.input !== undefined || state.usage.output !== undefined
-                ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                ? { usage: withCache(state.usage) }
                 : {}),
         };
     }
 }
+/** Copy input/output plus any cache counters into a message_end usage payload. */
+function withCache(u) {
+    return {
+        input: u.input ?? 0,
+        output: u.output ?? 0,
+        ...(u.cacheRead !== undefined ? { cacheRead: u.cacheRead } : {}),
+        ...(u.cacheWrite !== undefined ? { cacheWrite: u.cacheWrite } : {}),
+    };
+}
+/** Fold an Anthropic `usage` object (message_start or message_delta) into stream state. */
+function recordAnthropicUsage(state, u) {
+    const rec = u;
+    if (typeof rec?.input_tokens === 'number')
+        state.usage.input = rec.input_tokens;
+    if (typeof rec?.output_tokens === 'number') {
+        state.usage.output = (state.usage.output ?? 0) + rec.output_tokens;
+    }
+    if (typeof rec?.cache_creation_input_tokens === 'number') {
+        state.usage.cacheWrite = (state.usage.cacheWrite ?? 0) + rec.cache_creation_input_tokens;
+    }
+    if (typeof rec?.cache_read_input_tokens === 'number') {
+        state.usage.cacheRead = (state.usage.cacheRead ?? 0) + rec.cache_read_input_tokens;
+    }
+}
 function translateSse(event, parsed, state) {
     const out = [];
     switch (event) {
         case 'message_start': {
             const usage = parsed.message?.usage;
-            if (typeof usage?.input_tokens === 'number')
-                state.usage.input = usage.input_tokens;
+            recordAnthropicUsage(state, usage);
             return out;
         }
         case 'message_delta': {
-            const usage = parsed.usage;
-            if (typeof usage?.output_tokens === 'number') {
-                state.usage.output = (state.usage.output ?? 0) + usage.output_tokens;
-            }
+            recordAnthropicUsage(state, parsed.usage);
             return out;
         }
         case 'content_block_start': {
@@ -297,17 +363,20 @@ function translateSse(event, parsed, state) {
                 kind: 'message_end',
                 finishReason: 'stop',
                 ...(state.usage.input !== undefined || state.usage.output !== undefined
-                    ? { usage: { input: state.usage.input ?? 0, output: state.usage.output ?? 0 } }
+                    ? { usage: withCache(state.usage) }
                     : {}),
             });
             return out;
         }
         case 'error': {
             const err = parsed.error;
+            const rawType = err?.type ?? 'anthropic_error';
+            const rawMsg = err?.message ?? 'unknown Anthropic error';
+            const isOverflow = /too_large|too_long|context_length|prompt_too_long|prompt is too long/i.test(`${rawType} ${rawMsg}`);
             out.push({
                 kind: 'error',
-                code: err?.type ?? 'anthropic_error',
-                message: err?.message ?? 'unknown Anthropic error',
+                code: isOverflow ? 'REQUEST_TOO_LARGE' : rawType,
+                message: rawMsg,
                 retryable: false,
             });
             return out;
@@ -378,4 +447,4 @@ function toAnthropicTool(t) {
     };
 }
 // Re-export for testability.
-export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse };
+export const _internal = { toAnthropicMessages, toAnthropicTool, translateSse, buildAnthropicSystem, buildAnthropicTools };

package/dist/agent/capabilities.d.ts

@@ -29,6 +29,11 @@ export interface AgentCapabilities {
     model?: string;
     /** Recursion depth cap. Beyond this, spawn attempts are blocked. */
     maxDepth?: number;
+    /**
+     * Path allow-list for filesystem scope. `undefined` means unconstrained.
+     * A child's effective list is the intersection with its parent's.
+     */
+    allowedPaths?: string[];
 }
 export interface ResolveToolsInput {
     /** Tools the parent is allowed to use (or `null` for the root agent = all registered tools). */
@@ -93,6 +98,11 @@ export interface ResolvedCapabilities {
     maxDepth: number;
     readonly: boolean;
     canSpawn: boolean;
+    /**
+     * Effective filesystem scope: parent's `allowedPaths` intersected with the
+     * agent's own. `undefined` means unconstrained (neither side restricts).
+     */
+    allowedPaths?: string[];
 }
 /** Extra knobs consumed by `resolveCapabilities` on top of `ResolveToolsInput`. */
 export interface ResolveCapabilitiesExtra {
@@ -100,10 +110,23 @@ export interface ResolveCapabilitiesExtra {
     maxDepth: number;
     /** If true, the resolved `allowed` set may include tools that themselves spawn agents. */
     canSpawnOverride?: boolean;
+    /**
+     * The parent's filesystem allow-list (`undefined` = unconstrained parent —
+     * the agent's own list, if any, applies as-is).
+     */
+    parentAllowedPaths?: string[];
 }
 /** Combined input for the one-shot resolver used by the orchestrator. */
 export interface ResolveCapabilitiesInput extends ResolveToolsInput, ResolveCapabilitiesExtra {
 }
+/**
+ * Intersect two filesystem allow-lists. `undefined` on either side means
+ * "unconstrained" — the other side applies as-is; both `undefined` stays
+ * `undefined`. Entries survive when they are equal to, or nested inside, an
+ * entry of the other list (so a parent `/repo` and a child `/repo/sub`
+ * intersect to `/repo/sub`). Comparison is case-insensitive on Windows.
+ */
+export declare function intersectAllowedPaths(parentPaths?: string[], agentPaths?: string[]): string[] | undefined;
 /**
  * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
  *

package/dist/agent/capabilities.js

@@ -71,10 +71,11 @@ export function resolveAgentTools(input) {
             }
         }
     }
-    // 4. readonly → strip write tools.
+    // 4. readonly → strip write tools (plus run_verify: verification can
+    // execute arbitrary commands, so it is not read-only).
     if (agent.readonly) {
         for (const name of [...allowed]) {
-            if (writeTools.has(name)) {
+            if (writeTools.has(name) || name === 'run_verify') {
                 allowed.delete(name);
                 dropped.push({ tool: name, reason: 'readonly' });
             }
@@ -104,6 +105,44 @@ export function resolveAgentTools(input) {
         dropped: dropped.sort((a, b) => a.tool.localeCompare(b.tool)),
     };
 }
+/**
+ * Intersect two filesystem allow-lists. `undefined` on either side means
+ * "unconstrained" — the other side applies as-is; both `undefined` stays
+ * `undefined`. Entries survive when they are equal to, or nested inside, an
+ * entry of the other list (so a parent `/repo` and a child `/repo/sub`
+ * intersect to `/repo/sub`). Comparison is case-insensitive on Windows.
+ */
+export function intersectAllowedPaths(parentPaths, agentPaths) {
+    if (parentPaths === undefined)
+        return agentPaths;
+    if (agentPaths === undefined)
+        return [...parentPaths];
+    const out = [];
+    const seen = new Set();
+    const within = (candidate, scope) => {
+        const norm = (p) => {
+            const n = p.replace(/\\/g, '/').replace(/\/+$/, '');
+            return process.platform === 'win32' ? n.toLowerCase() : n;
+        };
+        const c = norm(candidate);
+        const s = norm(scope);
+        return c === s || c.startsWith(s + '/');
+    };
+    for (const a of agentPaths) {
+        for (const p of parentPaths) {
+            // The overlap of two nested scopes is the narrower one.
+            const narrower = within(a, p) ? a : within(p, a) ? p : undefined;
+            if (narrower !== undefined) {
+                const key = process.platform === 'win32' ? narrower.toLowerCase() : narrower;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out.push(narrower);
+                }
+            }
+        }
+    }
+    return out.sort();
+}
 /**
  * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
  *
@@ -118,7 +157,10 @@ export function resolveCapabilities(input) {
     const allowed = new Set(resolved.allowed);
     const model = input.agent.model;
     const maxDepth = input.agent.maxDepth ?? input.maxDepth;
-    const canSpawn = input.canSpawnOverride ?? input.agent.canSpawn ?? false;
+    // Default matches resolveAgentTools: the root agent (parentTools === null)
+    // may spawn; children strip spawn tools unless explicitly enabled.
+    const canSpawn = input.canSpawnOverride ?? input.agent.canSpawn ?? (input.parentTools === null);
+    const allowedPaths = intersectAllowedPaths(input.parentAllowedPaths, input.agent.allowedPaths);
     return {
         allowed,
         dropped: resolved.dropped,
@@ -126,6 +168,7 @@ export function resolveCapabilities(input) {
         maxDepth,
         readonly: input.agent.readonly ?? false,
         canSpawn,
+        ...(allowedPaths !== undefined ? { allowedPaths } : {}),
     };
 }
 /** Sensible defaults for "what counts as a write tool" if a caller doesn't override. */
@@ -136,15 +179,19 @@ export const DEFAULT_WRITE_TOOLS = new Set([
     'apply_patch',
     'shell_exec',
     'memory_write',
-    'background_shell',
     'todo_write',
 ]);
 /** Default spawn tools — removed from children by default. */
 export const DEFAULT_SPAWN_TOOLS = new Set([
     'spawn_agent',
-    'subtask',
 ]);
 /** Default deny-list — these are NEVER allowed, even if explicitly requested. */
 export const DEFAULT_DENIED_TOOLS = new Set([
-// Add dangerous tools here. Empty by default — extend as policy matures.
+// Intentionally empty. Deny happens per-pattern (shellDenyRule /
+// DANGEROUS_PATTERNS, .env guards, repair-guard), not per-tool: a
+// tool-granularity deny-all entry (e.g. banning `shell_exec` outright)
+// would break legitimate flows that rely on the allowlist + approval
+// path. Seed candidates considered and rejected: `shell_exec` (needed
+// for tests/builds via approval), `run_verify` (needed by tester/
+// implementer agents), `write_file`/`edit_file` (core agent function).
 ]);

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

@@ -0,0 +1,104 @@
+/**
+ * G2 — Process isolation for sub-agents (V1: headless/CLI children).
+ *
+ * This module is the *child-process* end of spawn_agent. The orchestrator
+ * forks this file with `node` (never shares a process), passing a
+ * JSON-serializable payload on STDIN (not argv — the system prompt + memory
+ * can exceed argv/command-line length limits, which would fail the spawn with
+ * E2BIG). The child rebuilds a minimal but self-sufficient `RuntimeDeps`,
+ * runs the task through `run()`, emits ONE JSON `ChildResult` line on stdout,
+ * and exits 0/1.
+ *
+ * Isolation contract: a child that OOMs, segfaults, or enters an infinite
+ * loop fails ONLY this process — the parent harness survives and reports
+ * `CHILD_CRASH` exactly as it does for an in-process throw.
+ *
+ * V1 scope (documented honestly):
+ *   - Headless children only. TUI children stay in-process because the Ink
+ *     approval bridge is inherently tied to the parent terminal.
+ *   - The child runs a system-prompt STRING (already assembled by the parent,
+ *     so KLYRO.md + memory + trust decisions match) with a file-system tool
+ *     subset and DenyAll approval — no MCP server forwarding, no live prompt.
+ *   - Grandchild spawning is not forwarded: a process-isolated child rebuilds
+ *     its own agent bridge-less deps, so its tools see NO_ORCHESTRATOR (same
+ *     as a pre-bridge child). V2 may thread a task handle back via a socket.
+ *
+ * Secrets never cross the process boundary via argv/env leaks: the child
+ * reads its provider key/baseURL from the SAME env the parent CLI uses
+ * (KLYRO_API_KEY, KLYRO_BASE_URL), so credentials stay in-process/env,
+ * never in the payload.
+ */
+import type { RunOptions, RunResult, RuntimeDeps } from './runtime.js';
+export interface ChildWorkerPayload {
+    /** Working dir the child operates in (may be a worktree). */
+    cwd: string;
+    /** The task prompt. */
+    task: string;
+    /** Model string (drives adapter selection + rate table). */
+    model: string;
+    /** Pre-assembled system prompt (stable + volatile already spliced). */
+    systemPrompt: string;
+    /** Agent id, for the system prompt identity. */
+    agentId: string;
+    /** Cap caps. */
+    maxSteps?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+    maxTokens?: number;
+}
+/** The one-line result the child prints to stdout on success. */
+export type ChildResult = Pick<RunResult, 'status' | 'steps' | 'toolCalls' | 'finalText' | 'hasEdits' | 'usage'>;
+/**
+ * Differently-phrased crash, distinct from an in-process throw the parent
+ * would catch. The child either exited non-zero without a parseable result
+ * line, or produced a malformed result. Carries the raw stdout/stderr tail.
+ */
+export declare class ChildCrashError extends Error {
+    readonly likelyCause: 'exit' | 'oom' | 'timeout';
+    readonly stderrTail?: string | undefined;
+    constructor(message: string, likelyCause: 'exit' | 'oom' | 'timeout', stderrTail?: string | undefined);
+}
+/**
+ * Resolve the compiled child-worker entry that *this* module's neighboring
+ * build (src or dist) produced. Both dev (tsx, .ts) and packaged (dist, .js)
+ * layouts live beside this file, so we probe for whichever exists.
+ */
+export declare function workerEntryPath(): string;
+export interface ForkChildOptions {
+    /** Abort the child process when this fires (wired to the parent signal). */
+    signal?: AbortSignal;
+    /** Abort+kill the child after this long (defaults to 10 min). */
+    timeoutMs?: number;
+    /** Capture point for stderr (for diagnostics, already included in error). */
+    onStderr?: (chunk: string) => void;
+}
+/**
+ * Fork the child-worker as a real OS process and await its single JSON
+ * ChildResult line. Secrets never reach argv: the payload rides stdin, the
+ * provider key/baseURL come from the inherited env. Non-zero exit / missing
+ * line → rejects with ChildCrashError so the orchestrator maps it to
+ * CHILD_CRASH exactly as an in-process throw does.
+ */
+export declare function forkChild(entry: string, payload: ChildWorkerPayload, opts?: ForkChildOptions): Promise<ChildResult>;
+/**
+ * Rebuild a minimal RuntimeDeps from the payload + inherited env. Centralized
+ * so tests can call it directly. Errors on missing provider config.
+ */
+export declare function buildChildDeps(payload: ChildWorkerPayload): Promise<{
+    deps: RuntimeDeps;
+    options: RunOptions;
+}>;
+/**
+ * Read the JSON payload. Payloads arrive on stdin (the parent writes the JSON
+ * then ends stdin), never argv — large system prompts would otherwise fail
+ * the spawn with E2BIG on both Windows (32K cmdline) and Linux (MAX_ARG_STRLEN).
+ * Callers who must use argv (tests) can route through `runChildFromString`.
+ */
+export declare function readPayloadFromStdin(): Promise<string>;
+/**
+ * Main entry. Reads payload from stdin, runs, prints ONE JSON ChildResult
+ * line, exits 0 on complete, 1 on failure/crash (so the parent knows to mark
+ * CHILD_CRASH). Intended to be the sole behavior of this file when invoked as
+ * a real process.
+ */
+export declare function main(): Promise<void>;