klyro 0.1.63 → 1.0.0

package/dist/agent/anthropic-adapter.js

@@ -16,6 +16,7 @@
  * Auth can be a Bearer token (for proxies) — the adapter accepts either.
  */
 import { assertSafeBaseURL } from '../chat.js';
+import { parseRetryAfterMs } from './provider-adapter.js';
 const DEFAULT_VERSION = '2023-06-01';
 const DEFAULT_TIMEOUT_MS = 120_000;
 export class AnthropicApiError extends Error {
@@ -97,11 +98,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;
+        const retryAfterMs = retryable ? parseRetryAfterMs(resp.headers?.get('retry-after')) : undefined;
         yield {
             kind: 'error',
             code: `http_${resp.status}`,
             message: `Anthropic API returned ${resp.status}: ${text.slice(0, 500)}`,
-            retryable: resp.status >= 500 || resp.status === 429,
+            retryable,
+            status: String(resp.status),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         };
         return;
     }

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Agent capability enforcement (P0.2 from r-6-10.fix.md).
+ *
+ * Resolves the **effective tool set** for a (child) agent by intersecting:
+ *
+ *   1. the parent's effective tools — a child can never receive more tools than its parent
+ *   2. the agent definition's `allowedTools` (if specified)
+ *   3. the runtime policy's allowed tools (e.g. `--allow-write` flags)
+ *
+ * Then applies safety modifiers:
+ *
+ *   - `readonly: true` strips every tool classified as write or mutation.
+ *   - `canSpawn: false` (default for children) removes any spawn_agent-like tools.
+ *   - A deny-list always wins, regardless of what the agent declares.
+ *
+ * This is a pure function — no I/O, no side effects. It exists so the runtime
+ * can decide which tools to expose to the model BEFORE the model picks one.
+ *
+ * Wiring lives in src/agent/runtime.ts (see the tool-filter hook).
+ */
+export interface AgentCapabilities {
+    /** Tools the agent definition explicitly allows. `undefined` means "no allow-list". */
+    allowedTools?: string[];
+    /** If true, write/mutation tools are stripped. */
+    readonly?: boolean;
+    /** If false (or unset), tools that can spawn new agents are stripped. */
+    canSpawn?: boolean;
+    /** Model override — if the provider cannot satisfy it, callers must error rather than fall back. */
+    model?: string;
+    /** Recursion depth cap. Beyond this, spawn attempts are blocked. */
+    maxDepth?: number;
+}
+export interface ResolveToolsInput {
+    /** Tools the parent is allowed to use (or `null` for the root agent = all registered tools). */
+    parentTools: ReadonlySet<string> | null;
+    /** The agent's declared capability profile. */
+    agent: AgentCapabilities;
+    /** Tools currently allowed by runtime policy (e.g. user-permission flags). */
+    policyAllowed: ReadonlySet<string>;
+    /** All tools known to the registry (used when parentTools is null). */
+    registryTools: ReadonlySet<string>;
+    /** Tools that mutate state — stripped under `readonly`. */
+    writeTools: ReadonlySet<string>;
+    /** Tools that spawn other agents — stripped when `canSpawn` is false. */
+    spawnTools: ReadonlySet<string>;
+    /** Tools that are NEVER allowed, even if explicitly requested. */
+    denied: ReadonlySet<string>;
+    /** If true, spawn tools are kept even when agent.canSpawn is false/unset. */
+    canSpawnOverride?: boolean;
+}
+export interface ResolveToolsResult {
+    /** Tools the child agent is permitted to call. */
+    allowed: string[];
+    /** Tools that were denied (debugging/observability). */
+    dropped: {
+        tool: string;
+        reason: 'denied' | 'readonly' | 'no-spawn' | 'not-in-parent' | 'not-in-policy' | 'unknown';
+    }[];
+}
+/**
+ * Resolve the effective tool set for an agent.
+ *
+ * Order of operations:
+ *   1. Start from `parentTools ?? registryTools`.
+ *   2. Intersect with `policyAllowed`.
+ *   3. If `allowedTools` is set, intersect again.
+ *   4. Strip `writeTools` if `readonly`.
+ *   5. Strip `spawnTools` if `!canSpawn`.
+ *   6. Remove `denied` last (always wins).
+ */
+export declare function resolveAgentTools(input: ResolveToolsInput): ResolveToolsResult;
+/**
+ * Reason a tool was dropped from the resolved capability set. Mirrors
+ * `ResolveToolsResult.dropped[].reason`.
+ */
+export type DropReason = 'denied' | 'readonly' | 'no-spawn' | 'not-in-parent' | 'not-in-policy' | 'unknown';
+/**
+ * Fully-resolved capability profile for a child agent — tool set plus
+ * non-tool knobs (model override, recursion cap). Computed once at spawn
+ * time and threaded through the runtime as `parentContext`.
+ */
+export interface ResolvedCapabilities {
+    /** Sorted tool names the child is allowed to invoke. */
+    allowed: ReadonlySet<string>;
+    /** Per-tool drop reasons — surfaced in ChildSummary for parent visibility. */
+    dropped: {
+        tool: string;
+        reason: DropReason;
+    }[];
+    /** Model override to send to the provider (or undefined to inherit parent). */
+    model?: string;
+    /** Effective recursion depth cap. Caller MUST reject spawn when depth + 1 > maxDepth. */
+    maxDepth: number;
+    readonly: boolean;
+    canSpawn: boolean;
+}
+/** Extra knobs consumed by `resolveCapabilities` on top of `ResolveToolsInput`. */
+export interface ResolveCapabilitiesExtra {
+    /** Caller-provided maxDepth (e.g. from CLI `--max-depth` or a parent's maxDepth). Required. */
+    maxDepth: number;
+    /** If true, the resolved `allowed` set may include tools that themselves spawn agents. */
+    canSpawnOverride?: boolean;
+}
+/** Combined input for the one-shot resolver used by the orchestrator. */
+export interface ResolveCapabilitiesInput extends ResolveToolsInput, ResolveCapabilitiesExtra {
+}
+/**
+ * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
+ *
+ * `maxDepth` precedence (most specific wins):
+ *   1. `agent.maxDepth` (if set on the definition)
+ *   2. `extra.maxDepth` (parent / CLI cap)
+ * `model` is propagated only when the agent declares one; we do not silently
+ * override a parent's chosen model.
+ */
+export declare function resolveCapabilities(input: ResolveCapabilitiesInput): ResolvedCapabilities;
+/** Sensible defaults for "what counts as a write tool" if a caller doesn't override. */
+export declare const DEFAULT_WRITE_TOOLS: ReadonlySet<string>;
+/** Default spawn tools — removed from children by default. */
+export declare const DEFAULT_SPAWN_TOOLS: ReadonlySet<string>;
+/** Default deny-list — these are NEVER allowed, even if explicitly requested. */
+export declare const DEFAULT_DENIED_TOOLS: ReadonlySet<string>;

package/dist/agent/capabilities.js

@@ -0,0 +1,150 @@
+/**
+ * Agent capability enforcement (P0.2 from r-6-10.fix.md).
+ *
+ * Resolves the **effective tool set** for a (child) agent by intersecting:
+ *
+ *   1. the parent's effective tools — a child can never receive more tools than its parent
+ *   2. the agent definition's `allowedTools` (if specified)
+ *   3. the runtime policy's allowed tools (e.g. `--allow-write` flags)
+ *
+ * Then applies safety modifiers:
+ *
+ *   - `readonly: true` strips every tool classified as write or mutation.
+ *   - `canSpawn: false` (default for children) removes any spawn_agent-like tools.
+ *   - A deny-list always wins, regardless of what the agent declares.
+ *
+ * This is a pure function — no I/O, no side effects. It exists so the runtime
+ * can decide which tools to expose to the model BEFORE the model picks one.
+ *
+ * Wiring lives in src/agent/runtime.ts (see the tool-filter hook).
+ */
+/**
+ * Resolve the effective tool set for an agent.
+ *
+ * Order of operations:
+ *   1. Start from `parentTools ?? registryTools`.
+ *   2. Intersect with `policyAllowed`.
+ *   3. If `allowedTools` is set, intersect again.
+ *   4. Strip `writeTools` if `readonly`.
+ *   5. Strip `spawnTools` if `!canSpawn`.
+ *   6. Remove `denied` last (always wins).
+ */
+export function resolveAgentTools(input) {
+    const { parentTools, agent, policyAllowed, registryTools, writeTools, spawnTools, denied, } = input;
+    const allowed = new Set();
+    const dropped = [];
+    // 1. Baseline: parent's tools, or all registered tools for the root agent.
+    // Record narrowing for observability: registry tools outside the parent's
+    // set are reported as 'not-in-parent' drops (child can never exceed parent).
+    const baseline = parentTools ?? registryTools;
+    if (parentTools !== null) {
+        for (const name of registryTools) {
+            if (!parentTools.has(name)) {
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+    }
+    for (const name of baseline) {
+        if (!registryTools.has(name)) {
+            dropped.push({ tool: name, reason: 'unknown' });
+            continue;
+        }
+        if (!policyAllowed.has(name)) {
+            dropped.push({ tool: name, reason: 'not-in-policy' });
+            continue;
+        }
+        allowed.add(name);
+    }
+    // 3. Apply the agent's allow-list (if any). Anything not in the list is dropped.
+    if (agent.allowedTools) {
+        const explicit = new Set(agent.allowedTools);
+        for (const name of [...allowed]) {
+            if (!explicit.has(name)) {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+        // Tools requested in allowedTools but not in the baseline cannot be granted.
+        for (const name of agent.allowedTools) {
+            if (!allowed.has(name) && registryTools.has(name) && policyAllowed.has(name)) {
+                dropped.push({ tool: name, reason: 'not-in-parent' });
+            }
+        }
+    }
+    // 4. readonly → strip write tools.
+    if (agent.readonly) {
+        for (const name of [...allowed]) {
+            if (writeTools.has(name)) {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'readonly' });
+            }
+        }
+    }
+    // 5. canSpawn=false → strip spawn tools. Default: root agent (parentTools
+    // === null) may spawn; children strip unless explicitly enabled. An explicit
+    // canSpawnOverride=true (via resolveCapabilities) also keeps them.
+    const canSpawnEffective = input.canSpawnOverride ?? input.agent.canSpawn ?? (input.parentTools === null);
+    if (!canSpawnEffective) {
+        for (const name of [...allowed]) {
+            if (spawnTools.has(name)) {
+                allowed.delete(name);
+                dropped.push({ tool: name, reason: 'no-spawn' });
+            }
+        }
+    }
+    // 6. Deny-list always wins.
+    for (const name of [...allowed]) {
+        if (denied.has(name)) {
+            allowed.delete(name);
+            dropped.push({ tool: name, reason: 'denied' });
+        }
+    }
+    return {
+        allowed: [...allowed].sort(),
+        dropped: dropped.sort((a, b) => a.tool.localeCompare(b.tool)),
+    };
+}
+/**
+ * One-shot capability resolver: tool intersection + per-agent model/maxDepth.
+ *
+ * `maxDepth` precedence (most specific wins):
+ *   1. `agent.maxDepth` (if set on the definition)
+ *   2. `extra.maxDepth` (parent / CLI cap)
+ * `model` is propagated only when the agent declares one; we do not silently
+ * override a parent's chosen model.
+ */
+export function resolveCapabilities(input) {
+    const resolved = resolveAgentTools(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;
+    return {
+        allowed,
+        dropped: resolved.dropped,
+        ...(model !== undefined ? { model } : {}),
+        maxDepth,
+        readonly: input.agent.readonly ?? false,
+        canSpawn,
+    };
+}
+/** Sensible defaults for "what counts as a write tool" if a caller doesn't override. */
+export const DEFAULT_WRITE_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'multi_edit',
+    '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.
+]);

package/dist/agent/orchestrator.d.ts

@@ -0,0 +1,131 @@
+/**
+ * AgentOrchestrator — spawns child agents and turns them into tasks.
+ *
+ * The lowest-level way to run Klyro is `run(options, deps)` (one agent,
+ * one loop). Orchestration layers on top of that: a parent agent calls
+ * `spawn_agent`, which resolves the target `AgentDefinition`, computes its
+ * effective capabilities (via `resolveCapabilities`), creates a
+ * `TaskRecord`, and runs a *scoped* child loop. The child runs in-process
+ * with a `ScopedRegistry` (narrowed tool set), an optional model override,
+ * a depth cap, and an AbortController wired to the parent's signal.
+ *
+ * The compact result is a `ChildSummary` — a `ToolResult` the parent model
+ * can act on — never the full child transcript.
+ */
+import type { RuntimeDeps } from './runtime.js';
+import type { ToolResult } from '../tools/types.js';
+import { TaskManager, type TaskStatus, type TaskSummary } from './task-manager.js';
+import { WorkerSpawner } from './worker-spawner.js';
+import { type DropReason } from './capabilities.js';
+/** An agent a model can delegate to via `spawn_agent`. */
+export interface AgentDefinition {
+    id: string;
+    description: string;
+    /** Explicit allow-list. Undefined means "inherit every tool the parent has". */
+    allowedTools?: string[];
+    readonly?: boolean;
+    /** Children cannot spawn further agents unless explicitly enabled. */
+    canSpawn?: boolean;
+    /** Per-agent model override. Must be honoured (or surfaced as an error). */
+    model?: string;
+    maxDepth?: number;
+    maxSteps?: number;
+    maxCost?: number;
+    maxTimeMs?: number;
+}
+/** Default agents a model can delegate to. */
+export declare const BUILTIN_AGENTS: readonly AgentDefinition[];
+/** Compact summary returned to the parent — the child's transcript stays separate. */
+export interface ChildSummary {
+    taskId: string;
+    agentName: string;
+    status: TaskStatus;
+    durationMs: number;
+    finalText?: string;
+    changedFiles: string[];
+    usage?: {
+        input: number;
+        output: number;
+        estimated?: boolean;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Tool drops from capability resolution, surfaced for parent visibility. */
+    droppedTools?: {
+        tool: string;
+        reason: DropReason;
+    }[];
+}
+/** Capability context the bridge passes when the parent calls spawn_agent. */
+export interface ParentContextRef {
+    taskId?: string;
+    parentTaskId?: string;
+    sessionId: string;
+    cwd: string;
+    depth: number;
+    maxDepth: number;
+    allowedTools: ReadonlySet<string> | null;
+    model?: string;
+}
+/** Interface exposed to the runtime/tools for a child spawn request. */
+export interface AgentSpawnBridge {
+    parent: ParentContextRef;
+    spawnAgent(input: {
+        agent: string;
+        task: string;
+        cwd?: string;
+        model?: string;
+        timeoutMs?: number;
+    }): Promise<ToolResult<ChildSummary>>;
+    listAgents(): AgentDefinition[];
+    getAgent(id: string): AgentDefinition | undefined;
+    listTasks(filter?: {
+        parentTaskId?: string;
+        status?: TaskStatus;
+    }): TaskSummary[];
+    getTask(id: string): TaskSummary & {
+        error?: {
+            code: string;
+            message: string;
+        };
+    } | undefined;
+}
+/** Constructor options for the orchestrator — the parent runtime's deps. */
+export interface OrchestratorOpts {
+    sessionId: string;
+    deps: RuntimeDeps;
+    taskManager?: TaskManager;
+    workerSpawner?: WorkerSpawner;
+}
+export declare class AgentOrchestrator {
+    readonly sessionId: string;
+    readonly deps: RuntimeDeps;
+    readonly taskManager: TaskManager;
+    readonly workerSpawner: WorkerSpawner;
+    constructor(opts: OrchestratorOpts);
+    listAgents(): AgentDefinition[];
+    getAgent(id: string): AgentDefinition | undefined;
+    /** Build the bridge the parent's runtime hands to tools. */
+    bridgeFor(parent: ParentContextRef): AgentSpawnBridge;
+    /** Compute a child's effective capabilities from the parent's own. */
+    private resolveChild;
+    /**
+     * Spawn a child agent for a given capability context, await its run, and
+     * return a compact summary. Blocks until the child settles (P0 scope;
+     * async task_wait arrives in a later slice).
+     */
+    spawnAgent(input: {
+        agent: string;
+        task: string;
+        cwd?: string;
+        model?: string;
+        timeoutMs?: number;
+    }, parent: ParentContextRef): Promise<ToolResult<ChildSummary>>;
+    private toChildSummary;
+}
+/** Module-scoped holder the orchestrator sets so children inherit the parent's signal. */
+export declare const parentAbortSignalRef: {
+    current: AbortSignal | null;
+};