@combycode/llm-sdk 1.0.0-rc.0

package/dist/agent/history.d.ts

@@ -0,0 +1,111 @@
+/** ConversationHistory — traversable, exportable, importable.
+ *  This is the canonical source of truth for any conversation. */
+import type { Message } from '../llm/types/messages';
+import { type Usage } from '../llm/types/response';
+import { ContextRegistry } from './context-registry/registry';
+import type { ConversationHistoryConfig, HistoryEntry, HistorySnapshot } from './history-types';
+export declare class ConversationHistory {
+    private entries;
+    private _id;
+    private _metadata;
+    private _createdAt;
+    private _updatedAt;
+    /** Layered context storage. Contributors (ContextGuard, memory manager,
+     *  RAG, user) write named layers here. `history.system` getter/setter is a
+     *  thin shim over `registry.set(LEGACY_SYSTEM_LAYER, ...)` for backward compat. */
+    readonly registry: ContextRegistry;
+    /** Provider-reported exact input-token count from the last completion (includes system + all prior messages up to that point). */
+    private _lastActualTotal;
+    /** Index of the last entry that was included in _lastActualTotal. Entries after this index are "pending" and estimated. */
+    private _lastActualEntryIndex;
+    private _counter;
+    private _provider;
+    private _model;
+    constructor(idOrConfig?: string | ConversationHistoryConfig);
+    /** Get the last provider-reported exact input token count. */
+    get lastActualTotal(): number;
+    /**
+     * Record the actual input token count reported by a provider for a request.
+     *
+     * Call this BEFORE appending the response. The input tokens describe the state
+     * of history that was sent — which is what's currently in history before the
+     * response is added.
+     *
+     * Note: normally this is automatic. When you call `append()` with an assistant
+     * message carrying `usage.inputTokens`, this is invoked internally.
+     */
+    recordActualUsage(inputTokens: number): void;
+    get id(): string;
+    get length(): number;
+    /** Legacy system-prompt accessor — reads all 'system'-tagged layers in the
+     *  registry. For the common case of a single system prompt, this returns
+     *  the same string that was set via the setter. When other contributors
+     *  (ContextGuard, memory manager) have added more 'system'-tagged layers,
+     *  the returned string is their composed output. */
+    get system(): string | undefined;
+    /** Legacy setter — writes to the `_legacy_system` layer tagged 'system'.
+     *  Priority 200 (in the "dynamic contributor" zone). Historically this field
+     *  was used for content that changes during conversation (ContextGuard facts),
+     *  so it renders AFTER stable prefix layers (agent role @10, context @100)
+     *  for prompt-cache friendliness. Pass undefined to remove the layer. */
+    set system(value: string | undefined);
+    get metadata(): Record<string, unknown>;
+    setMetadata(key: string, value: unknown): void;
+    /** Add a message to history */
+    append(message: Message, meta?: {
+        model?: string;
+        usage?: Usage;
+        latencyMs?: number;
+    }): HistoryEntry;
+    /** Get all messages (for building request) */
+    messages(): Message[];
+    /** Get messages as entries (with metadata) */
+    all(): readonly HistoryEntry[];
+    /** Get entry by index */
+    at(index: number): HistoryEntry | undefined;
+    /** Get last N entries */
+    last(n: number): HistoryEntry[];
+    /** Get last N messages */
+    lastMessages(n: number): Message[];
+    /** Find entries matching a predicate */
+    filter(fn: (entry: HistoryEntry) => boolean): HistoryEntry[];
+    /** Get entries by role */
+    byRole(role: Message['role']): HistoryEntry[];
+    /** Iterate entries */
+    [Symbol.iterator](): Iterator<HistoryEntry>;
+    /** Cumulative usage across all turns */
+    totalUsage(): Usage;
+    /**
+     * Estimated total input tokens for the next request.
+     *
+     * Uses a hybrid: exact count for entries already sent (from last response's usage)
+     * plus estimate of entries added since. Accurate because only the delta is estimated.
+     *
+     * If no actual usage has been recorded yet (fresh history), estimates everything.
+     */
+    estimatedTokens(): number;
+    private estimateTokensForMessage;
+    /** Clear all history */
+    clear(): void;
+    /** Truncate to last N entries */
+    truncate(keepLast: number): HistoryEntry[];
+    /** Replace entries in [from, to) with a single synthetic message.
+     *  Used by ContextGuard when compacting a range into a summary entry.
+     *  - from, to are inclusive-exclusive indices against current entries (0-based).
+     *  - replacement becomes a new HistoryEntry with timestamp = max timestamp in
+     *    the replaced range (preserves chronological order).
+     *  Returns the removed entries. Entry indices past `to` shift down. */
+    spliceRange(from: number, to: number, replacement: Message): HistoryEntry[];
+    /** Append text to the legacy system layer. Preserves backward-compat
+     *  semantics; new code should write named registry layers directly. */
+    appendSystem(text: string): void;
+    /** Deep clone this history, including the registry. */
+    fork(newId?: string): ConversationHistory;
+    /** Export to JSON-serializable snapshot. Includes registry state. */
+    export(): HistorySnapshot;
+    /** Import from snapshot. Supports both new (registry-aware) and legacy
+     *  (`system` field only) snapshots. */
+    static import(snapshot: HistorySnapshot): ConversationHistory;
+    /** Rough token estimate: ~4 chars per token for English */
+    private estimateTokens;
+}

package/dist/agent/loop-config.d.ts

@@ -0,0 +1,67 @@
+/** AgentLoop configuration. */
+import type { HookBus } from '../bus/hook-bus';
+import type { LLMClient } from '../llm/client';
+import type { CacheConfig, ThinkingConfig } from '../llm/types/request';
+import type { ConversationHistory } from './history';
+import type { HistorySnapshot } from './history-types';
+import type { AgentTool } from './types';
+import type { Guardrail } from './guardrail-types';
+import type { PermissionPolicy } from '../plugins/permissions/policy';
+import type { ApprovalRequest, ApprovalDecision } from './approval-types';
+import type { Persistence } from '../plugins/persistence/types';
+export interface AgentLoopConfig {
+    /** LLM client. AgentLoop reads `client.model` and uses `client.complete`/`client.stream`. */
+    client: LLMClient;
+    /** Persona / role text for the agent. Stored as the `agentloop.system` registry
+     *  layer (priority 10). Composed with other system-tagged layers when sending.
+     *  When passed as a function, it is re-evaluated at the start of every
+     *  `complete()` / `stream()` call — useful for live-reload prompts backed
+     *  by a config file or persistence collection. */
+    system?: string | (() => string | Promise<string>);
+    /** Run-scenario context (background for the current task). Stored as the
+     *  `agentloop.context` registry layer (priority 100). */
+    context?: string;
+    /** Executable tools. Indexed by function name (FunctionTool) or type (BuiltinTool). */
+    tools?: AgentTool[];
+    /** Reuse an existing history (or rehydrate from a snapshot). New history
+     *  is created when omitted. */
+    history?: ConversationHistory | HistorySnapshot;
+    /** Hook bus. Optional — a fresh bus is created when omitted. */
+    hooks?: HookBus;
+    maxTokens?: number;
+    temperature?: number;
+    thinking?: ThinkingConfig;
+    cache?: CacheConfig;
+    parallelToolCalls?: boolean;
+    toolTimeout?: number;
+    /** Maximum number of tool-followup rounds per run.
+     *  When the loop has completed this many steps and the model is still
+     *  requesting tools, it stops before the next LLM call and sets the run
+     *  reason to 'max_steps'.
+     *
+     *  Defaults to DEFAULT_MAX_STEPS (16) when omitted or undefined.
+     *  Values <= 0 are treated as "use the default" (not "unlimited").
+     *  To raise the limit pass a larger number; there is no way to disable
+     *  the cap entirely -- set a very large value (e.g. 10_000) if needed. */
+    maxSteps?: number;
+    /** Input and output guardrails. Input guardrails run before each LLM call;
+     *  output guardrails run after each step's response is produced.
+     *  A tripwire decision halts the run with finishReason 'guardrail'. */
+    guardrails?: Guardrail[];
+    /** Permission policy wired into the tool-execution path.
+     *  Called after lookup, before execution.
+     *  'allow' -> proceed; 'deny' -> tool is blocked (error result to model);
+     *  'ask'   -> call the `approve` callback for a human decision. */
+    policy?: PermissionPolicy;
+    /** Human-in-the-loop approver called when a policy rule says 'ask'.
+     *  The loop suspends until the returned Promise resolves.
+     *  The approver MUST always resolve (never reject) — return { decision: 'deny' }
+     *  to block when the approval channel itself fails. */
+    approve?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
+    /** Durable checkpoint storage for the loop snapshot.
+     *  When set, the loop persists its state (including pending approvals) at every
+     *  approval suspension point, enabling kill-process / restore / resume flows.
+     *  Must be cross-env: use MemoryPersistence for browser/tests, FilePersistence for Node.
+     *  When omitted, state is kept in-memory only. */
+    checkpoint?: Persistence;
+}

package/dist/agent/loop-internals.d.ts

@@ -0,0 +1,46 @@
+/** Private helpers for AgentLoop — extracted from the two god-functions.
+ *  Not exported from the library public surface. */
+import type { HookBus } from '../bus/hook-bus';
+import type { ToolCallPart, ContentPart } from '../llm/types/messages';
+import { type CompletionResponse } from '../llm/types/response';
+import type { StreamEvent } from '../llm/types/stream';
+import type { TraceContext } from '../network/types';
+import type { AgentStreamEvent, AgentTool, ToolCallReport, ToolExecutionContext } from './types';
+import type { StepState } from './loop-step-state';
+/** Create a fresh StepState for the start of a streaming step. */
+export declare function makeStepState(): StepState;
+/** Accumulate one SSE StreamEvent into StepState.
+ *  Returns the AgentStreamEvent to yield upstream, or null if nothing to yield. */
+export declare function accumulateStreamEvent(event: StreamEvent, state: StepState): AgentStreamEvent | null;
+/** Finalize any tool calls that never received a tool_call_end event
+ *  (Anthropic/OpenAI streaming quirk). Mutates state.stepToolCalls. */
+export declare function finalizeUnendedToolCalls(state: StepState): void;
+/** Build the CompletionResponse for a completed streaming step. */
+export declare function buildStepResponse(state: StepState, model: string, stepStart: number): {
+    response: CompletionResponse;
+    content: ContentPart[];
+    stepLatency: number;
+};
+type LookupResult = {
+    found: true;
+    tool: AgentTool;
+} | {
+    found: false;
+    errorResult: ContentPart;
+};
+/** Resolve a tool by name; emit not-found hooks and push an error report.
+ *  Returns found tool or an error ContentPart to return to the model. */
+export declare function lookupToolOrError(tc: ToolCallPart, tools: Map<string, AgentTool>, hooks: HookBus, runId: string, agentId: string, step: number, metrics: Map<string, {
+    value: number | string | boolean;
+    type: string;
+}>, reports: ToolCallReport[], toolStart: number, runTrace?: TraceContext): Promise<LookupResult>;
+/** Execute a tool with an AbortController-based timeout.
+ *  Builds a ToolExecutionContext with the timeout signal internally. */
+export declare function executeWithTimeout(tool: AgentTool, tc: ToolCallPart, baseCtx: Omit<ToolExecutionContext, 'signal'>, timeoutMs: number): Promise<string | ContentPart[]>;
+/** Handle a tool execution error: emit onToolCallError, push report, return fallback result.
+ *  Throws if the hook sets continueOnError = false. */
+export declare function handleToolError(e: unknown, tc: ToolCallPart, hooks: HookBus, runId: string, agentId: string, step: number, metrics: Map<string, {
+    value: number | string | boolean;
+    type: string;
+}>, reports: ToolCallReport[], toolStart: number, runTrace?: TraceContext): Promise<ContentPart>;
+export {};

package/dist/agent/loop-step-state.d.ts

@@ -0,0 +1,20 @@
+/** Mutable accumulator for a single agent loop step.
+ *  Passed through stream-event helpers so they don't fight closure state. */
+import type { ToolCallPart } from '../llm/types/messages';
+import type { Usage } from '../llm/types/response';
+/** Accumulation bucket for one in-progress tool call (before tool_call_end). */
+export interface ToolCallAccumEntry {
+    id: string;
+    name: string;
+    args: string;
+    _meta?: Record<string, unknown>;
+}
+/** All mutable state for one streaming step inside AgentLoop.stream(). */
+export interface StepState {
+    stepText: string;
+    stepThinking: string;
+    stepToolCalls: ToolCallPart[];
+    toolCallAccum: Map<string, ToolCallAccumEntry>;
+    stepUsage: Usage;
+    stepFinishReason: string;
+}

package/dist/agent/loop.d.ts

@@ -0,0 +1,133 @@
+/** AgentLoop — Layer 3 multi-step orchestration.
+ *
+ *  Drives a conversation through `client.complete` / `client.stream` until
+ *  the model returns a response without tool calls (or `stop()` is called).
+ *  Owns: history, executable tools, agent-level hooks, run reports.
+ *
+ *  Reshape vs old llm-sdk loop:
+ *    - `model` removed from config — read from `client.model`.
+ *    - `system` lives in history.registry as `agentloop.system` layer.
+ *    - `complete(input, options?)` returns CompletionResponse (not AgentRunResult).
+ *    - `lastReport` getter exposes run-level details (step/tool reports).
+ *    - Input shapes (`string | ContentPart[] | Message[]`) APPEND to history. */
+import { HookBus } from '../bus/hook-bus';
+import { type ContentPart, type Message } from '../llm/types/messages';
+import type { ExecuteOptions } from '../llm/types/options';
+import { type CompletionResponse } from '../llm/types/response';
+import type { LLMClient } from '../llm/client';
+import { ConversationHistory } from './history';
+import type { AgentLoopSnapshot, AgentRunReport, AgentStreamEvent, AgentTool } from './types';
+import type { AgentLoopConfig } from './loop-config';
+import type { PermissionPolicy } from '../plugins/permissions/policy';
+import type { ApprovalRequest, ApprovalDecision, PendingToolCall } from './approval-types';
+export declare class AgentLoop {
+    readonly id: string;
+    readonly client: LLMClient;
+    readonly hooks: HookBus;
+    private _system;
+    private _systemThunk;
+    private _context;
+    private _tools;
+    private _history;
+    private _reports;
+    private _metadata;
+    private _maxTokens?;
+    private _temperature?;
+    private _thinking?;
+    private _cache?;
+    private _parallelToolCalls;
+    private _toolTimeout;
+    private _maxSteps;
+    private _guardrails;
+    private _policy;
+    private _approve;
+    private _checkpoint;
+    /** Tool calls suspended awaiting human approval (populated during a durable pause). */
+    private _pendingToolCalls;
+    private _running;
+    private _stopRequested;
+    private _abortController;
+    constructor(config: AgentLoopConfig);
+    destroy(): void;
+    /** Model is owned by client. */
+    get model(): string;
+    get system(): string;
+    set system(v: string);
+    get context(): string;
+    set context(v: string);
+    get history(): ConversationHistory;
+    get running(): boolean;
+    get reports(): readonly AgentRunReport[];
+    get lastReport(): AgentRunReport | null;
+    get metadata(): Record<string, unknown>;
+    addTool(tool: AgentTool): void;
+    removeTool(name: string): void;
+    toolNames(): string[];
+    stop(): void;
+    complete(input: string | ContentPart[] | Message[], options?: ExecuteOptions): Promise<CompletionResponse>;
+    /** Run `complete` with a JSON Schema enforced via `structured`, then
+     *  JSON.parse the response text. Tool calls are still allowed within the
+     *  loop; only the FINAL turn is constrained. */
+    structuredComplete<T = unknown>(input: string | ContentPart[] | Message[], schema: Record<string, unknown>, options?: ExecuteOptions): Promise<T>;
+    stream(input: string | ContentPart[] | Message[], options?: ExecuteOptions): AsyncIterable<AgentStreamEvent>;
+    /** Yield tool_call_start events for all tool calls in this step. */
+    private emitToolCallStarts;
+    /** Yield tool_call_end events for all completed tool reports. */
+    private emitToolCallEnds;
+    private executeToolCalls;
+    private executeSingleTool;
+    /** Build a skipped-tool result content part and push the report. */
+    private buildSkippedResult;
+    /** Build an overridden-tool result content part and push the report. */
+    private buildOverriddenResult;
+    /** Build a denied-tool result (policy deny) and push the report. */
+    private buildDeniedResult;
+    /** Suspend at the approval gate: emit hooks, optionally persist, await decision. */
+    private runApprovalGate;
+    /** Emit onToolCallComplete, push report, and return success content part. */
+    private buildSuccessResult;
+    /** Merge agent's tool definitions with caller-provided tools (caller wins on conflict). */
+    private toolDefinitions;
+    private beginRun;
+    private finalizeRun;
+    /** Run all input-kind guardrails in order. Returns the trip reason on the first
+     *  tripwire, or null when all pass. Emits onGuardrailTriggered on trip. */
+    private runInputGuardrails;
+    /** Run all output-kind guardrails in order. Returns the trip reason on the first
+     *  tripwire, or null when all pass. Emits onGuardrailTriggered on trip. */
+    private runOutputGuardrails;
+    dump(): AgentLoopSnapshot;
+    static restore(snapshot: AgentLoopSnapshot, config: {
+        client: LLMClient;
+        hooks?: HookBus;
+        tools: AgentTool[];
+        policy?: PermissionPolicy;
+        approve?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
+        checkpoint?: import('../plugins/persistence/types').Persistence;
+    }): AgentLoop;
+    /** Return the list of tool calls currently suspended awaiting approval. */
+    get pendingApprovals(): readonly PendingToolCall[];
+    /** Feed an approval decision for a pending tool call identified by callId.
+     *
+     *  This is the resume entry point after a process restart:
+     *   1. Restore the loop from a snapshot (AgentLoop.restore).
+     *   2. Call resumeWithApproval(callId, decision) to remove the pending record.
+     *   3. Re-run the agent — the approver will be invoked again with the SAME
+     *      callId; provide a pass-through approver that returns the pre-fed decision.
+     *
+     *  Rationale: the tool call itself is not stored in pending state (only its
+     *  metadata), because the actual execution requires re-running the LLM step.
+     *  The canonical resume model is: restore -> re-complete with an approver that
+     *  returns the already-obtained decision for the known callId. This keeps the
+     *  loop stateless w.r.t. execution and the approval decision authoritative. */
+    resumeWithApproval(callId: string, decision: ApprovalDecision): void;
+    /** Pre-fed decisions supplied via resumeWithApproval — consumed on the next run. */
+    private _prefedApprovals;
+    /** Return a prefed decision (consumed once) or fall back to the real approver. */
+    private resolveApproval;
+}
+/** Default maximum number of tool-followup steps per agent run.
+ *  Callers that need more steps should set `maxSteps` in AgentLoopConfig. */
+export declare const DEFAULT_MAX_STEPS = 16;
+/** Default tool execution timeout in milliseconds. */
+export declare const DEFAULT_TOOL_TIMEOUT_MS = 30000;

package/dist/agent/tool-key.d.ts

@@ -0,0 +1,3 @@
+/** Registry key for an AgentTool: the function name, else the builtin type. */
+import type { AgentTool } from './types';
+export declare function toolKey(tool: AgentTool): string;

package/dist/agent/types.d.ts

@@ -0,0 +1,138 @@
+/** Agent-layer shared types — TokenCounter contract used by ContextRegistry,
+ *  ConversationHistory, and the ContextMeasurer plugin.
+ *  Also defines AgentTool (executable tool) and run-report types. */
+import type { ContentPart, Message } from '../llm/types/messages';
+import type { Tool } from '../llm/types/tools';
+import type { Usage } from '../llm/types/response';
+import type { HistorySnapshot } from './history-types';
+import type { PendingToolCall } from './approval-types';
+import type { TraceContext } from '../network/types';
+export type ContentClass = 'prose' | 'code' | 'mixed' | 'structured';
+export interface TokenCountContext {
+    provider?: string;
+    model?: string;
+    contentClass?: ContentClass;
+    accuracy?: 'fast' | 'exact';
+}
+export interface TokenCounter {
+    /** Fast estimate — synchronous, no I/O. Used on every request. */
+    estimate(text: string, ctx?: TokenCountContext): number;
+    /** Estimate for a whole message, including multi-part content. */
+    estimateMessage(msg: Message, ctx?: TokenCountContext): number;
+    /** Accurate count — may perform I/O (lazy tokenizer load, API call). */
+    measure(text: string, ctx?: TokenCountContext): Promise<number>;
+    /** Accurate count for a whole message. */
+    measureMessage(msg: Message, ctx?: TokenCountContext): Promise<number>;
+    /** Feed actual usage for calibration refinement. */
+    learn(input: LearnInput): void;
+}
+export interface LearnInput {
+    provider: string;
+    model: string;
+    bytesSent: number;
+    actualTokens: number;
+    contentClass?: ContentClass;
+    timestamp?: number;
+}
+export interface AgentTool {
+    /** Tool schema sent to the LLM. */
+    definition: Tool;
+    /** Execute the tool. Return string or structured content. */
+    execute: (args: Record<string, unknown>, context: ToolExecutionContext) => Promise<string | ContentPart[]>;
+}
+export interface ToolExecutionContext {
+    step: number;
+    callId: string;
+    signal: AbortSignal;
+    metrics: Map<string, {
+        value: number | string | boolean;
+        type: string;
+    }>;
+    /** Run trace identity: sessionId = agentId (ConversationHistory id),
+     *  requestId = runId for this .complete()/.stream() invocation,
+     *  callId = this tool call's id (same as ctx.callId). */
+    trace?: TraceContext;
+}
+export interface ToolCallReport {
+    callId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    resultSizeBytes: number;
+    latencyMs: number;
+    skipped: boolean;
+    error: string | null;
+    metrics: Record<string, {
+        value: number | string | boolean;
+        type: string;
+    }>;
+}
+export interface StepReport {
+    index: number;
+    type: 'initial' | 'tool_followup';
+    llmLatencyMs: number;
+    usage: Usage;
+    finishReason: string;
+    toolCalls: ToolCallReport[];
+    toolTotalMs: number;
+}
+export interface AgentRunReport {
+    id: string;
+    model: string;
+    startedAt: number;
+    completedAt: number;
+    totalMs: number;
+    reason: 'done' | 'stopped' | 'error' | 'guardrail' | 'max_steps';
+    userMessage: string | ContentPart[] | Message[];
+    finalText: string;
+    error?: string;
+    steps: StepReport[];
+    stepCount: number;
+    toolCallCount: number;
+    totalUsage: Usage;
+    totalLlmTimeMs: number;
+    totalToolTimeMs: number;
+}
+export type AgentStreamEvent = {
+    type: 'step_start';
+    step: number;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_call_start';
+    step: number;
+    callId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'tool_call_end';
+    step: number;
+    callId: string;
+    latencyMs: number;
+} | {
+    type: 'step_end';
+    step: number;
+    usage: Usage;
+    latencyMs: number;
+} | {
+    type: 'done';
+    response: import('../llm/types/response').CompletionResponse;
+};
+export interface AgentLoopSnapshot {
+    version: 1;
+    system: string;
+    context: string;
+    history: HistorySnapshot;
+    toolNames: string[];
+    reports: AgentRunReport[];
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    savedAt: number;
+    /** Tool calls suspended awaiting human approval. Present when the loop was
+     *  checkpointed at an approval gate. Empty or absent otherwise. */
+    pendingToolCalls?: PendingToolCall[];
+}
+export type { PendingToolCall };

package/dist/bus/agent-bus.d.ts

@@ -0,0 +1,99 @@
+/** AgentBus — cross-module event bus for agent systems.
+ *
+ *  Distinct from HookBus:
+ *    - HookBus carries SDK-internal instrumentation (onCompletion, onContextMeasure,
+ *      onToolCallStart, ...). Strongly typed per-event.
+ *    - AgentBus carries business events between agent modules and the app layer
+ *      (ask.permission, log.progress, notify, lifecycle.*). Open envelope,
+ *      user-declared kinds, pattern matching on kind names.
+ *
+ *  Pattern matching rules for `on(kindPattern, handler)`:
+ *    - Exact match:   'ask.permission' matches only 'ask.permission'
+ *    - Prefix match:  'ask.*' matches 'ask.permission', 'ask.choice', 'ask.anything'
+ *    - Wildcard:      '*' matches everything
+ *
+ *  Correlation IDs link request events to reply events:
+ *    bus.emit({ kind: 'ask.permission', correlationId: 'q1', payload: {...} });
+ *    bus.onReply('q1', (replyEvent) => ...);
+ *    // Elsewhere:
+ *    bus.reply('q1', { kind: 'ask.answer', source: 'user', payload: { granted: true } });
+ *
+ *  Ordering guarantees (by design — see orchestrator decomposition spec):
+ *    - Top-level `emit()` calls are processed FIFO globally. Two parallel
+ *      `emit(A)` and `emit(B)` complete in submission order.
+ *    - Reentrant `emit()` (called from within a handler) runs depth-first:
+ *      the nested event's handlers complete before the next sibling handler
+ *      of the outer event runs. This preserves causal order and avoids
+ *      deadlock when a handler awaits its own nested emit. */
+export interface AgentEvent {
+    /** Stable unique id assigned by emit() if not supplied. Used by Journal,
+     *  Aggregator, ResumeManager to reference specific events. */
+    id: string;
+    /** Logical identity of the emitter (usually a module id). */
+    source: string;
+    /** Dot-delimited kind, e.g. 'ask.permission', 'log.progress', 'lifecycle.created'. */
+    kind: string;
+    /** Kind-specific payload. Caller and listener agree on shape by convention. */
+    payload: unknown;
+    /** Milliseconds since epoch — filled in by emit() if not provided. */
+    timestamp: number;
+    /** Optional correlation ID linking a reply or progress update to its origin. */
+    correlationId?: string;
+    /** Optional id of the parent event (set by callers when they emit from
+     *  within a handler and want to record the causal link). The bus does not
+     *  populate this automatically — callers opt in. */
+    causedBy?: string;
+}
+/** Emit form — id and timestamp filled in by bus if absent. */
+export type AgentEventInput = Omit<AgentEvent, 'id' | 'timestamp'> & {
+    id?: string;
+    timestamp?: number;
+};
+export type AgentEventHandler = (event: AgentEvent) => void | Promise<void>;
+export interface SubscribeOptions {
+    /** Optional subscriber identity. Stored on the subscription so future
+     *  components (Wiring, Journal, Aggregator) can record which subscriber
+     *  processed which event. The bus itself does not introspect it today. */
+    name?: string;
+}
+/** `handlerContext` marks "we are currently inside a handler frame". Reentrant
+ *  emits (called from a handler, possibly across awaits) inherit this context;
+ *  external emits do not. This is how we tell "nested" from "concurrent
+ *  external" when both happen while a slow handler is suspended. Imported from
+ *  ./async-context so the browser build can swap AsyncLocalStorage for a
+ *  no-node:async_hooks fallback via the package "browser" field. */
+/** Lightweight, asynchronous, pattern-matched event bus. */
+export declare class AgentBus {
+    /** Pattern → subscribers. Exact patterns and prefix patterns stored separately for speed. */
+    private exact;
+    private prefix;
+    private wildcard;
+    /** correlationId → reply subscribers. Cleared when handler unsubscribes. */
+    private replies;
+    /** FIFO queue for top-level emits. Reentrant emits bypass the queue. */
+    private queue;
+    private draining;
+    /** Subscribe to events whose kind matches the pattern.
+     *  - 'foo.bar'  → exact
+     *  - 'foo.*'    → prefix 'foo.' (matches 'foo.bar', 'foo.baz.qux', etc.)
+     *  - '*'        → all
+     *  Returns unsubscribe function. */
+    on(kindPattern: string, handler: AgentEventHandler, options?: SubscribeOptions): () => void;
+    /** Subscribe to all events carrying this correlation ID. Returns unsubscribe. */
+    onReply(correlationId: string, handler: AgentEventHandler, options?: SubscribeOptions): () => void;
+    /** Publish an event. Top-level calls are queued and processed FIFO globally;
+     *  reentrant calls (from inside a handler) run depth-first.
+     *  Resolves once all handlers for this event have completed. */
+    emit(input: AgentEventInput): Promise<void>;
+    /** Convenience: publish a reply carrying the given correlationId.
+     *  Ensures correlationId is set (caller can't forget it). */
+    reply(correlationId: string, input: Omit<AgentEventInput, 'correlationId'>): Promise<void>;
+    /** Number of registered handlers (sum across exact + prefix + wildcard + reply).
+     *  Useful for leak detection in tests. */
+    get handlerCount(): number;
+    /** Remove all handlers. Use during teardown. */
+    clear(): void;
+    private drain;
+    private processEvent;
+    private emitInternalError;
+}

package/dist/bus/async-context.browser.d.ts

@@ -0,0 +1,13 @@
+/** Browser reentrancy context — a single shared flag, no node:async_hooks.
+ *
+ *  AsyncLocalStorage does not exist in browsers. We keep one module-scoped flag
+ *  and hold it for the WHOLE duration of handler dispatch (including while the
+ *  async handler loop is suspended), restoring it when dispatch fully settles.
+ *
+ *  Trade-off vs. the Node AsyncLocalStorage impl: a genuinely concurrent
+ *  top-level emit that arrives while a handler is suspended sees the flag set
+ *  and runs inline instead of FIFO-queued. That softly weakens global ordering
+ *  but never deadlocks — acceptable for browser, single-user usage. Reentrant
+ *  (nested) emits, the case that matters for correctness, are detected exactly. */
+import type { HandlerContext } from './async-context.types';
+export declare const handlerContext: HandlerContext;

package/dist/bus/async-context.d.ts

@@ -0,0 +1,11 @@
+/** Node/Bun reentrancy context — backed by AsyncLocalStorage.
+ *
+ *  AsyncLocalStorage propagates through awaits, so a reentrant emit (made from
+ *  inside a handler, even after the handler suspended) sees the store while a
+ *  genuinely concurrent external emit does not. This is what lets AgentBus tell
+ *  "nested" from "concurrent external" with full correctness on the server.
+ *
+ *  The browser build never loads this file: the package "browser" field maps it
+ *  to ./async-context.browser.ts, which has no node:async_hooks dependency. */
+import type { HandlerContext } from './async-context.types';
+export declare const handlerContext: HandlerContext;

package/dist/bus/async-context.types.d.ts

@@ -0,0 +1,14 @@
+/** Shared shape for the reentrancy context used by AgentBus.
+ *
+ *  Two implementations satisfy it:
+ *    - async-context.ts          → Node/Bun, backed by AsyncLocalStorage
+ *      (full isolation across awaits and concurrent emits).
+ *    - async-context.browser.ts  → browser, a single shared flag held for the
+ *      duration of handler dispatch (no node:async_hooks). The package "browser"
+ *      field swaps the former for the latter at bundle time. */
+export interface HandlerContext {
+    /** Run `fn` with the store set to `value`. Returns whatever `fn` returns. */
+    run<R>(value: boolean, fn: () => R): R;
+    /** The current store value, or undefined when outside any `run`. */
+    getStore(): boolean | undefined;
+}