toolnexus 0.9.4 → 0.10.0

package/dist/agents/index.js

@@ -0,0 +1,10 @@
+/**
+ * Sub-agents & agent runtime (SPEC.md §7D), exported as the `agents` namespace:
+ *
+ *   import { agents } from "toolnexus"
+ *   const explore = agents.agent("explore", { does: "read-only research" })
+ */
+export * from "./runtime.js";
+export * from "./agent.js";
+export * from "./home.js";
+export * from "./compaction.js";

package/dist/agents/runtime.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Agent runtime substrate — SPEC.md §7D.
+ *
+ * A Handle is a live agent: state machine (`idle → running → idle|suspended|closed`,
+ * `suspended → running` only via the Answer to its pending Request), an inbox held as
+ * agent state, hierarchical budgets, and a deterministic parent-scoped id
+ * (`root/coordinator.1/explore.2`). The runtime exposes exactly six host verbs
+ * (spawn/post/wake/wait/interrupt/close) plus read-only list/inspect views, and owns
+ * the cross-cutting infrastructure: ONE ConversationStore for all handles
+ * (conversation id = handle id, so transcripts genuinely survive turns), an
+ * injectable clock (fixtures run virtual), and the handle table.
+ *
+ * Everything rides shipped machinery: the §8 client loop, §10 pending/waitFor, and
+ * the ConversationStore. SPEC pins transitions, never scheduling — conformance is
+ * identical per-handle transition traces against `examples/subagent-*` fixtures.
+ */
+import { type ClientStyle, type ConversationStore } from "../client.js";
+import type { Answer, Request, Tool } from "../types.js";
+/** Injectable time source. All runtime timers, timeouts, and deadlines use it. */
+export interface Clock {
+    /** Current time in ms (epoch or virtual). */
+    now(): number;
+    /** Schedule `fn` after `ms`; returns a cancel function. */
+    setTimeout(fn: () => void, ms: number): () => void;
+}
+/** The real clock (default). Timers are unref'd so they never hold the process open. */
+export declare const systemClock: Clock;
+/** §7D hierarchical budget. Carved at spawn (`min(own, parent remaining)`) and
+ * live-enforced against the whole ancestor chain before each turn and spawn.
+ * Monetary budgets are excluded (vendor data; convert in a host `onBudget`). */
+export interface Budget {
+    /** Turn cap for this handle (LLM round trips per run; lifetime cap across wakes). */
+    maxTurns?: number;
+    /** Token pool, shared downward with descendants. */
+    maxTokens?: number;
+    /** Tool-call pool, shared downward with descendants. */
+    maxToolCalls?: number;
+    /** Wall-clock deadline in ms from spawn (clock-based; min'd with the parent's). */
+    maxWallMs?: number;
+    /** Direct-children cap, checked at spawn. */
+    maxChildren?: number;
+    /** Concurrently RUNNING children cap (admission gate; queued wakes fire FIFO). */
+    maxConcurrent?: number;
+    /** Tree-depth cap, checked at spawn. */
+    maxDepth?: number;
+}
+/** Why a handle was closed (passed to `onClose`). */
+export type CloseReason = "closed" | "interrupted" | "budget" | "error";
+/** An agent definition — the registry entry the runtime spawns handles from. */
+export interface AgentDef {
+    name: string;
+    /** Routing description: what the delegating model sees for this agent. */
+    does: string;
+    /** Identity / system prompt (the "soul"). */
+    soul?: string;
+    /** Model id; "inherit" (default) resolves to the runtime's `llm.model`. */
+    model?: string;
+    /** This agent's scoped tool set (the toolkit view IS the security model). */
+    tools?: Tool[];
+    /** `task`-tool targets. Absent/empty ⇒ this agent gets NO `task` tool
+     * (delegation, like recursion, is opt-in — never default). */
+    team?: string[];
+    budget?: Budget;
+    /** §10 interpreter authority for suspensions escalating through this agent.
+     * Absent ⇒ pendings relay upward (durable at the root). */
+    waitFor?: (request: Request) => Promise<Answer>;
+    /** Runs once, before the first turn — the session-start injection point. */
+    onSpawn?: (h: Handle) => void | Promise<void>;
+    /** Runs before the final checkpoint on close. */
+    onClose?: (h: Handle, reason: CloseReason) => void | Promise<void>;
+}
+/** An unsolicited inbox item. Delivered ONLY as part of a fresh turn's coalesced
+ * drain, with provenance rendered per item (non-ancestor senders are untrusted). */
+export interface InboxItem {
+    /** Sender handle path, or "external" / "clock". */
+    from: string;
+    /** Delivery channel: "peer" | "timer" | "external" | ... */
+    channel: string;
+    text: string;
+}
+export type HandleState = "idle" | "running" | "suspended" | "closed";
+export type TaskStatus = "done" | "pending" | "incomplete" | "interrupted" | "closed" | "timeout" | "error";
+/** The result of one completed (or halted) turn, as seen by waiters and `task`. */
+export interface TaskResult {
+    text: string;
+    isError: boolean;
+    status: TaskStatus;
+    /** Present iff status === "pending". `data.path` carries the suspended handle's
+     * id path (§10 agent-escalation addendum) — never a field grafted on Request. */
+    pending?: Request;
+    turns: number;
+    totalTokens: number;
+}
+/** Uniform verb failure — returned, never thrown (only the root throws to the host). */
+export interface VerbError {
+    error: string;
+}
+/** Type guard for the `spawn` return union. */
+export declare function isVerbError(x: unknown): x is VerbError;
+/** Read-only snapshot row from `list()` / `inspect()`. */
+export interface HandleView {
+    id: string;
+    state: HandleState;
+    /** Total tokens attributed to this handle (own + rolled-up descendants). */
+    tokens: number;
+    /** Buffered inbox items. */
+    inbox: number;
+}
+interface Pools {
+    tokens: number;
+    toolCalls: number;
+    children: number;
+}
+/**
+ * The suspension checkpoint. When a Run halts pending, the handle's stored
+ * transcript is REWOUND to the pre-turn snapshot and the turn's full input is
+ * recorded here; resume replays the whole turn from this point (idempotency for
+ * delegated work comes from `task`-key reattachment, not transcript inspection).
+ */
+interface Checkpoint {
+    /** The exact turn input (prompt + rendered inbox drain) to replay. */
+    input: string;
+}
+interface QueuedWake {
+    h: Handle;
+    prompt?: string;
+}
+/**
+ * A live agent. Public surface is the observable state (§7D pins transitions, not
+ * scheduling); fields below the "runtime internals" marker are owned by AgentRuntime.
+ */
+export declare class Handle {
+    readonly id: string;
+    readonly def: AgentDef;
+    readonly parent: Handle | null;
+    readonly depth: number;
+    readonly children: Handle[];
+    /** Inbox as agent state — bounded, transactional drain, checkpointable. */
+    readonly inbox: InboxItem[];
+    state: HandleState;
+    /** Remaining budget pools (tokens/toolCalls carved at spawn, drained by roll-up). */
+    readonly pool: Pools;
+    /** Effective per-handle limits after defaults. */
+    readonly eff: {
+        maxTurns: number;
+        maxConcurrent: number;
+        maxDepth: number;
+    };
+    /** Wall-clock deadline (clock ms), when a `maxWallMs` applies on this chain. */
+    readonly deadline?: number;
+    /** Total tokens attributed to this handle (own turns + descendant roll-up). */
+    usageTotal: number;
+    /** Total tool calls attributed to this handle (own + descendant roll-up). */
+    toolCallsTotal: number;
+    /** LLM round trips run by this handle itself (never reset — resume grows it). */
+    turnsTotal: number;
+    /** The unresolved Request while `suspended` (already stamped with `data.path`). */
+    pendingRequest?: Request;
+    /** Last settled turn result — what `wait()` answers with on a settled handle. */
+    lastResult?: TaskResult;
+    /** In-flight turn abort seam (the JS cancellation contract, §7D table). */
+    abort: AbortController | null;
+    /** The halted tool call recorded at suspension — resume retries it with the Answer. */
+    checkpoint?: Checkpoint;
+    /** Items consumed by the in-flight turn; restored to the inbox front on abort. */
+    drained: InboxItem[];
+    /** Waiters registered by `wait()`. */
+    waiters: Array<(r: TaskResult) => void>;
+    /** FIFO queue of children's wakes deferred by this handle's `maxConcurrent`. */
+    wakeQueue: QueuedWake[];
+    /** Set when spawned by the `task` tool — the reattachment key (agent+prompt). */
+    taskKey?: string;
+    /** Currently RUNNING children (the concurrency-gate counter). */
+    runningChildren: number;
+    /** Child id sequence (deterministic ids). */
+    seq: number;
+    /** onSpawn completion — awaited before the first turn. */
+    ready?: Promise<void>;
+    constructor(id: string, def: AgentDef, parent: Handle | null, now: number);
+}
+export interface RuntimeOptions {
+    /** Agent definitions by name. The `task` tool resolves targets here. */
+    registry: Record<string, AgentDef>;
+    /** LLM endpoint. Omit for hermetic runs against an injected `fetch` mock. */
+    llm?: {
+        baseUrl?: string;
+        style?: ClientStyle;
+        apiKey?: string;
+        model?: string;
+    };
+    /** HTTP transport for LLM requests (§8 Gap 2) — the hermetic-test seam. */
+    fetch?: typeof fetch;
+    /** Time source for every timer/timeout/deadline. Default: the system clock. */
+    clock?: Clock;
+    /** The ONE ConversationStore for all handles (conversation id = handle id).
+     * Default: in-memory for the runtime's lifetime. */
+    store?: ConversationStore;
+    /** Inbox capacity per handle (gate 1; full ⇒ loud synchronous reject). Default 8. */
+    inboxCap?: number;
+    /** Global turn gate (gate 3): concurrent LLM HTTP calls across the whole tree.
+     * Wraps ONLY the HTTP call, never a Run, and releases on acquirer death. Default 8. */
+    maxConcurrentTurns?: number;
+    /** Graceful-close bound for a running turn before escalating to abort. Default 200. */
+    shutdownMs?: number;
+}
+/**
+ * The §7D agent runtime: six host verbs over a tree of Handles, three loud
+ * backpressure gates, hierarchical budgets, §10 escalation/durable resume, and a
+ * transition trace (`trace`) — the conformance artifact fixtures assert against.
+ */
+export declare class AgentRuntime {
+    /** Transition trace — the §0 conformance artifact. */
+    readonly trace: string[];
+    readonly root: Handle;
+    /** The runtime-wide conversation store (one for ALL handles; id = handle id). */
+    readonly store: ConversationStore;
+    readonly clock: Clock;
+    /** LLM HTTP calls currently in flight (observability for the turn gate). */
+    concurrentTurns: number;
+    /** High-water mark of `concurrentTurns` (fixtures assert gate behavior with it). */
+    maxObservedConcurrentTurns: number;
+    private readonly opts;
+    private readonly registry;
+    private readonly inboxCap;
+    private readonly shutdownMs;
+    private turnSlots;
+    private readonly turnQueue;
+    constructor(opts: RuntimeOptions);
+    private t;
+    /**
+     * Create a child handle under `parent` with a deterministic parent-scoped id.
+     * Caps (`maxDepth`/`maxChildren`) and the live budget walk are checked here; the
+     * handle is returned to the spawner ALONE (handles are capabilities: post/wake
+     * what you hold, wait only on handles you spawned).
+     */
+    spawn(parent: Handle, defName: string, budget?: Budget): Handle | VerbError;
+    /** Append to the inbox. NO state transition. Full or closed ⇒ synchronous reject. */
+    post(h: Handle, item: InboxItem): {
+        ok: true;
+    } | ({
+        ok: false;
+    } & VerbError);
+    /**
+     * `idle → running`. Admission (budget walk + concurrency slot + state flip +
+     * transactional drain) is atomic with the verb. Over the parent's `maxConcurrent`
+     * the wake queues FIFO and a completing sibling transfers its slot. Waking a
+     * suspended handle is a no-op (items buffer; only the Answer wakes it).
+     */
+    wake(h: Handle, prompt?: string): {
+        ok: true;
+    } | ({
+        ok: false;
+    } & VerbError);
+    /**
+     * Resolve with the next completed result — or immediately with the last one when
+     * the handle is already settled (idle with a recorded result, suspended with its
+     * pending, or closed). Registration order is unobservable. An expired timeout
+     * yields an explicit timeout error while the child keeps running. Waiting is
+     * reserved to the spawner: pass `by` to enforce the capability rule.
+     */
+    wait(h: Handle, opts?: {
+        timeoutMs?: number;
+        by?: Handle;
+    }): Promise<TaskResult>;
+    /**
+     * Abort the in-flight Run (JS seam: `AbortSignal`) → `idle`, with the drained
+     * inbox items restored (drain is transactional). On a suspended handle: cancel
+     * the pending Request → `idle` (the operator escape hatch). Waiters receive a
+     * uniform interrupted error result — never an exception.
+     */
+    interrupt(h: Handle): void;
+    /**
+     * Graceful shutdown: stop accepting, close children leaf-first, let a running
+     * turn finish bounded by `shutdownMs` (then escalate to abort), run `onClose`,
+     * notify waiters, keep the final state queryable (close ≠ loss). Stop-all =
+     * `close(root)`. Runs from outside the tree (downward traversal).
+     */
+    close(h: Handle, opts?: {
+        force?: boolean;
+        reason?: CloseReason;
+    }): Promise<void>;
+    /** Read-only snapshot of every handle (tree order, root excluded). */
+    list(h?: Handle, acc?: HandleView[]): HandleView[];
+    /** Read-only detail view of one handle. */
+    inspect(h: Handle): HandleView & {
+        turns: number;
+        poolTokens: number;
+        pending?: Request;
+    };
+    /**
+     * Route an Answer to the DEEPEST suspended handle, resume it from its checkpoint
+     * (retry-with-answer of the halted tool; turns/usage grow, never reset), then
+     * cascade upward: each suspended parent re-runs, and its re-invoked `task`
+     * REATTACHES to the existing child by task key — never spawns a duplicate.
+     * The root alone may throw to the host.
+     */
+    resume(answer: Answer): Promise<void>;
+    private deepestSuspended;
+    /**
+     * Resume a suspended handle by REPLAYING its halted turn from the checkpoint:
+     * the stored transcript was rewound to the pre-turn snapshot when the Run halted,
+     * so the whole turn re-runs with the same input, this time with a one-shot §10
+     * interpreter that returns the Answer (when this level holds one). A replayed
+     * `task` call REATTACHES to the existing child by task key — reattachment, not
+     * transcript inspection, is the idempotency mechanism for delegated work.
+     */
+    private resumeSuspended;
+    /** Walk the LIVE ancestor chain; name the first exhausted pool, if any. */
+    private poolLimit;
+    /** Lifetime turn cap on the handle itself (turns never reset across resumes). */
+    private turnCap;
+    /** A limit stop is LOUD: settle an incomplete result (never silent, never a throw). */
+    private settleRefused;
+    /** Usage roll-up IS the budget ledger: every ancestor's pool drains live. */
+    private rollUp;
+    /** Atomic admission: slot take + state flip (+ trace). Sync with the calling verb. */
+    private admit;
+    private isQueued;
+    private unqueue;
+    /** Transactional drain: one wake consumes the WHOLE inbox as one coalesced block.
+     * Timer ticks dedupe to a single counted entry; every item renders with provenance;
+     * non-ancestor/external senders render inside an explicitly untrusted wrapper. */
+    private drainInbox;
+    private isAncestorSender;
+    private acquireTurnSlot;
+    private makeRelease;
+    private gatedFetch;
+    private toolkitFor;
+    /** Stamp this level's handle path onto the Request at `data.path` (§10 addendum). */
+    private stampPath;
+    private pendingResult;
+    /** The escalation seam: this handle's §10 interpreter authority, with the
+     * escalation traced (nearest interpreter wins; the Request's `data.path` names
+     * the suspended subtree that is asking). */
+    private wrapWaitFor;
+    /**
+     * One turn. The caller has already admitted the handle (state = running); the
+     * synchronous prefix (input assembly + transactional drain) is therefore atomic
+     * with admission. Failures cross the handle boundary as results, never throws.
+     * When the Run halts pending, the stored transcript is REWOUND to the pre-turn
+     * snapshot and the input is checkpointed — resume replays the whole turn.
+     */
+    private executeTurn;
+    /** Concurrency gate (gate 2): free this Run's slot and transfer it to queued
+     * sibling wakes, FIFO, re-checking budgets at dequeue time. */
+    private releaseChildSlot;
+    /**
+     * The one model-visible delegation tool. Advertises ONLY the caller's team
+     * (sorted by name, composed from each agent's `does`); out-of-team targets are
+     * refused with the team listed. A re-invoked call REATTACHES to the existing
+     * child by task key (agent+prompt) — settled ⇒ its recorded result; suspended ⇒
+     * its pending (or an inline resume when the retry carries the Answer); running ⇒
+     * await — and never spawns a duplicate.
+     */
+    private taskTool;
+}
+export {};