klyro 0.1.63 → 1.0.1

package/dist/agent/provider-adapter.js

@@ -12,6 +12,25 @@
  */
 import { redact } from '../policy/secret-redactor.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Parse a `Retry-After` response header value into milliseconds.
+ * Returns undefined when absent or unparseable. Handles both forms:
+ * delay-seconds ("120") and HTTP-date ("Wed, 21 Oct 2015 07:28:00 GMT",
+ * clamped at 0 when the date is in the past).
+ */
+export function parseRetryAfterMs(value) {
+    if (value == null)
+        return undefined;
+    const v = value.trim();
+    if (!v)
+        return undefined;
+    if (/^\d+$/.test(v))
+        return Number(v) * 1000;
+    const t = Date.parse(v);
+    if (!Number.isNaN(t))
+        return Math.max(0, t - Date.now());
+    return undefined;
+}
 /** 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
@@ -89,8 +108,12 @@ function zodFieldSchema(s) {
  */
 export function buildChatCompletionsBody(req) {
     const messages = [];
+    // OpenAI has no system array form: the volatile suffix rides along as a
+    // plain concatenation (behavior-preserving when absent).
     if (req.system)
-        messages.push({ role: 'system', content: req.system });
+        messages.push({ role: 'system', content: req.systemSuffix ? `${req.system}\n\n${req.systemSuffix}` : req.system });
+    else if (req.systemSuffix)
+        messages.push({ role: 'system', content: req.systemSuffix });
     for (const m of req.messages) {
         if (m.role === 'assistant') {
             const text = m.content.filter((b) => b.kind === 'text').map((b) => b.text).join('');
@@ -183,11 +206,20 @@ async function* streamChatCompletions(url, opts, req, fetchImpl) {
         req.signal?.removeEventListener('abort', onAbort);
         const rawErr = await res.text().catch(() => '');
         const errText = redact(rawErr).slice(0, 500);
+        // Context overflow is a client-side budget problem, not a transient
+        // failure: surface a dedicated code (never retryable here — the runtime
+        // owns the compress-and-retry recovery) so callers can distinguish it
+        // from 429/5xx backoff cases.
+        const isOverflow = res.status === 413 || /request_too_large|too_large|prompt_too_long|context_length|maximum context length/i.test(rawErr);
+        const retryable = !isOverflow && (res.status >= 500 || res.status === 429);
+        const retryAfterMs = retryable ? parseRetryAfterMs(res.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
-            code: `HTTP_${res.status}`,
+            code: isOverflow ? 'REQUEST_TOO_LARGE' : `HTTP_${res.status}`,
             message: `provider returned ${res.status}: ${errText}`,
-            retryable: res.status >= 500 || res.status === 429,
+            retryable,
+            status: String(res.status),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         };
         return;
     }

package/dist/agent/registry.d.ts

@@ -39,4 +39,5 @@ export declare function buildProviderFromCli(args: {
     baseUrl?: string;
     apiKey?: string;
     timeoutMs?: number;
+    retry?: Partial<RetryOptions> | false;
 }): ProviderAdapter;

package/dist/agent/registry.js

@@ -190,5 +190,6 @@ export function buildProviderFromCli(args) {
         baseURL: args.baseUrl,
         apiKey: args.apiKey,
         timeoutMs: args.timeoutMs,
+        ...(args.retry !== undefined ? { retry: args.retry } : {}),
     });
 }

package/dist/agent/retry.d.ts

@@ -15,7 +15,7 @@
  *
  *   delay = min(maxMs, baseMs * 2^attempt) ± jitter
  *
- * The default policy matches the L6 plan: 3 attempts, 500ms base, 8s cap.
+ * The default policy matches the L6 plan: 5 attempts, 500ms base, 8s cap.
  */
 import type { ProviderAdapter } from './provider-adapter.js';
 export interface RetryOptions {
@@ -28,8 +28,19 @@ export interface RetryOptions {
     sleep?: (ms: number) => Promise<void>;
     /** Test hook: called once per attempt with 0-indexed attempt number. */
     onAttempt?: (attempt: number) => void;
+    /**
+     * Retry telemetry hook (operator-visible; the model stays blind).
+     * Called each time a retryable error is buffered and another attempt
+     * will follow (NOT on the terminal failure). `attempt` is the
+     * 1-indexed retry number (1 = first retry after the initial failure).
+     */
+    onRetry?: (info: {
+        attempt: number;
+        status: string;
+        retryAfterMs?: number;
+    }) => void;
 }
-export declare const DEFAULT_RETRY: Required<Omit<RetryOptions, 'signal' | 'onAttempt'>>;
+export declare const DEFAULT_RETRY: Required<Omit<RetryOptions, 'signal' | 'onAttempt' | 'onRetry'>>;
 /**
  * Sleep that resolves early when `signal` aborts (never rejects — callers
  * check `signal.aborted` themselves after waking).

package/dist/agent/retry.js

@@ -15,10 +15,10 @@
  *
  *   delay = min(maxMs, baseMs * 2^attempt) ± jitter
  *
- * The default policy matches the L6 plan: 3 attempts, 500ms base, 8s cap.
+ * The default policy matches the L6 plan: 5 attempts, 500ms base, 8s cap.
  */
 export const DEFAULT_RETRY = {
-    maxAttempts: 3,
+    maxAttempts: 5,
     baseMs: 500,
     maxMs: 8_000,
     sleep: defaultSleep,
@@ -152,7 +152,25 @@ export function retryingAdapter(inner, opts = {}) {
                         yield lastError;
                     return;
                 }
-                const delay = computeBackoff(attempt, cfg.baseMs, cfg.maxMs);
+                // Telemetry for the operator: a retryable error was buffered and
+                // another attempt will follow. The consumer stream never sees the
+                // buffered error, so the model stays blind.
+                const errRec = lastError;
+                const statusRaw = errRec?.['status'];
+                const codeRaw = errRec?.['code'];
+                const status = typeof statusRaw === 'string' && statusRaw.length > 0
+                    ? statusRaw
+                    : typeof codeRaw === 'string' && codeRaw.length > 0
+                        ? codeRaw
+                        : 'retryable';
+                const retryAfterRaw = errRec?.['retryAfterMs'];
+                const retryAfterMs = typeof retryAfterRaw === 'number' && Number.isFinite(retryAfterRaw) && retryAfterRaw >= 0
+                    ? retryAfterRaw
+                    : undefined;
+                opts.onRetry?.({ attempt: attempt + 1, status, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
+                // Honor a server-provided Retry-After delay when present; otherwise
+                // fall back to exponential backoff with jitter.
+                const delay = retryAfterMs ?? computeBackoff(attempt, cfg.baseMs, cfg.maxMs);
                 // Abort-aware backoff: Ctrl+C during the sleep must stop promptly
                 // instead of stalling up to maxMs before noticing.
                 if (delay > 0)

package/dist/agent/runtime.d.ts

@@ -19,6 +19,16 @@ 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';
+/**
+ * Verification mode. The canonical definition lives in verification/engine.ts
+ * (sibling-owned: `export type VerifyMode = 'strict'|'advisory'|'off'`). It is
+ * resolved conditionally here so this file typechecks regardless of sibling
+ * landing order — and converges to the sibling type automatically once the
+ * sibling export exists.
+ */
+export type VerifyMode = typeof import('../verification/engine.js') extends {
+    VerifyMode: infer V;
+} ? V : 'strict' | 'advisory' | 'off';
 export interface RuntimeDeps {
     adapter: ProviderAdapter;
     registry: ToolRegistry;
@@ -26,15 +36,34 @@ export interface RuntimeDeps {
     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.
+     *
+     * TELEMETRY SPLIT: the fn may return either a plain string (legacy —
+     * telemetry already concatenated, cache-unfriendly) or
+     * `{system, suffix}` where `suffix` is the volatile telemetry block.
+     * The runtime forwards both halves via CallRequest (`system` +
+     * `systemSuffix`) so adapters can keep the suffix out of the cacheable
+     * prefix (Anthropic array form) or concatenate it (OpenAI — unchanged).
+     * Both shapes are accepted so custom fns keep compiling.
      */
-    systemPrompt: (ctx: {
-        cwd: string;
-        telemetry?: string;
-    }) => string;
+    systemPrompt: SystemPromptFn;
+}
+/** Split system-prompt result: stable prefix + volatile telemetry suffix. */
+export interface SystemPromptResult {
+    system: string;
+    suffix?: string;
 }
+export type SystemPromptFn = (ctx: {
+    cwd: string;
+    telemetry?: string;
+}) => string | SystemPromptResult;
+/** Normalize either systemPrompt shape into {system, suffix}. */
+export declare function resolveSystemPrompt(fn: SystemPromptFn, ctx: {
+    cwd: string;
+    telemetry?: string;
+}): {
+    system: string;
+    suffix?: string;
+};
 export type Phase = 'understanding' | 'exploring' | 'planning' | 'implementing' | 'verifying' | 'done' | 'blocked' | 'limit';
 export interface RunOptions {
     task: string;
@@ -77,6 +106,9 @@ export interface RunOptions {
         maxRepairAttempts?: number;
         timeoutMs?: number;
         requireVerify?: boolean;
+        /** Verification mode (default 'strict'). 'off' skips the pipeline;
+         * 'advisory' runs verify once on completion without repair turns. */
+        mode?: VerifyMode;
     };
     /**
      * Level 9 — persistence. When a SessionStore is provided, every message
@@ -87,6 +119,28 @@ export interface RunOptions {
         store?: import('../persistence/store.js').SessionStore;
         sessionId?: string;
     };
+    /**
+     * Orchestration context (P0). Present for any agent that is itself managed
+     * by an AgentOrchestrator — so a child knows who its parent is, how deep the
+     * call stack is, which tools it may use, and which task/session it belongs to.
+     */
+    parentContext?: {
+        taskId?: string;
+        parentTaskId?: string;
+        sessionId: string;
+        depth: number;
+        maxDepth: number;
+        allowedTools?: ReadonlySet<string>;
+        /** Path allow-set inherited from the parent (sibling C contract). */
+        allowedPaths?: readonly string[];
+        model?: string;
+    };
+    /**
+     * Delegation bridge (P0). Present on the root run so the model can call
+     * spawn_agent / task_list / task_get. The tool layer reads it from the
+     * ToolContext.
+     */
+    agentBridge?: import('./orchestrator.js').AgentSpawnBridge;
 }
 /** A single plan step emitted by the agent. */
 export interface PlanStep {
@@ -140,6 +194,8 @@ export type RuntimeEvent = {
     input: number;
     output: number;
     estimated?: boolean;
+    cacheRead?: number;
+    cacheWrite?: number;
 } | {
     kind: 'final_text';
     text: string;
@@ -183,6 +239,8 @@ export interface RunResult {
         input: number;
         output: number;
         estimated?: boolean;
+        cacheRead?: number;
+        cacheWrite?: number;
     };
     /** Number of policy-driven user prompts the user accepted. */
     repairs?: number;
@@ -192,6 +250,10 @@ export interface RunResult {
         command?: string;
         attempts: number;
         failureType?: string;
+        repairTokens?: {
+            input: number;
+            output: number;
+        };
     };
     /** 5.1 phase */
     phase?: Phase;
@@ -208,4 +270,4 @@ export declare function run(opts: RunOptions, deps: RuntimeDeps): Promise<RunRes
 export declare function defaultSystemPrompt(ctx: {
     cwd: string;
     telemetry?: string;
-}): string;
+}): SystemPromptResult;