indusagi 0.12.32 → 0.12.34

package/dist/types/swarm/telemetry/activity.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `ActivityLog` — the crew's append-only transcript of what happened, when.
+ *
+ * Where the {@link import("../workboard").TicketBoard} holds the *current* state
+ * of the work and the {@link import("../postbox").Channel} carries the *messages*
+ * between teammates, the activity log is the third leg: an immutable, ordered
+ * record of the coordination *events* themselves — a member was spawned, a ticket
+ * was claimed or completed, a result envelope was sent. It is what a transcript
+ * viewer replays and what an audit reads back; nothing in the crew depends on it
+ * for correctness, so it is a pure observer.
+ *
+ * It is a deliberately thin wrapper over the kernel's {@link JsonlLog}: every
+ * event is one schema-validated append, and the timeline is one validated read.
+ * The log never touches `node:fs` locking, temp renames, or coercion — that all
+ * lives in the kernel. Events are a small, table-like discriminated union keyed
+ * by `kind`, validated by zod on the way in and out, so a malformed event can
+ * never reach (or be trusted from) disk.
+ *
+ * Two verbs:
+ *   - {@link ActivityLog.record} — validate and append one {@link CrewEvent}.
+ *   - {@link ActivityLog.timeline} — read back every event in append order.
+ */
+import { z } from "zod";
+/** The closed set of coordination events the crew narrates. */
+export declare const CREW_EVENT_KINDS: readonly ["member_spawned", "ticket_posted", "ticket_claimed", "ticket_done", "ticket_failed", "message_sent"];
+/** One coordination-event class — the discriminant of {@link CrewEvent}. */
+export type CrewEventKind = (typeof CREW_EVENT_KINDS)[number];
+/**
+ * The event schema, as a discriminated union over `kind`. Each branch pins the
+ * fields that class of event carries — the role for a spawn, the ticket id for a
+ * lifecycle transition, the envelope id and endpoints for a message — so a
+ * timeline consumer can narrow on `kind` and read exactly the fields that apply.
+ */
+declare const crewEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"member_spawned">;
+    memberId: z.ZodString;
+    role: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_posted">;
+    ticketId: z.ZodString;
+    title: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_claimed">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_done">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    summary: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ticket_failed">;
+    ticketId: z.ZodString;
+    memberId: z.ZodString;
+    error: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"message_sent">;
+    envelopeId: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    envelopeType: z.ZodString;
+    id: z.ZodString;
+    ts: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+/** A validated crew coordination event. */
+export type CrewEvent = z.infer<typeof crewEventSchema>;
+/**
+ * What a caller hands to {@link ActivityLog.record}: any {@link CrewEvent}
+ * without the auto-stamped `id`/`ts` header (either may still be supplied to
+ * override the defaults). The id is minted and the timestamp is stamped by the
+ * log if absent.
+ */
+export type CrewEventInput = (Omit<Extract<CrewEvent, {
+    kind: "member_spawned";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_posted";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_claimed";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_done";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "ticket_failed";
+}>, "id" | "ts"> & EventStamp) | (Omit<Extract<CrewEvent, {
+    kind: "message_sent";
+}>, "id" | "ts"> & EventStamp);
+/** The optional header overrides a caller may pin on a recorded event. */
+interface EventStamp {
+    /** Override the minted id. */
+    readonly id?: string;
+    /** Override the stamped timestamp. */
+    readonly ts?: number;
+}
+/**
+ * The crew's audit/transcript observer, backed by one {@link JsonlLog}.
+ *
+ * Open with {@link ActivityLog.open}; the factory wires up the underlying log
+ * (which ensures the parent directory exists). It is an *observer*: the crew
+ * narrates events to it, but it holds no authority over the work and can be
+ * dropped without affecting correctness.
+ */
+export declare class ActivityLog {
+    private readonly log;
+    /** Injected clock, epoch ms — overridable for deterministic tests. */
+    private readonly now;
+    private constructor();
+    /** Absolute path of the `.jsonl` file backing this log. */
+    get path(): string;
+    /**
+     * Open (or adopt) the activity log stored at `path`.
+     *
+     * `now` defaults to `Date.now`; tests may inject a deterministic clock so
+     * recorded timestamps are reproducible.
+     */
+    static open(path: string, now?: () => number): Promise<ActivityLog>;
+    /**
+     * Validate and append one coordination event, returning the stored record.
+     *
+     * The event's `id` is minted (`act_<ULID>`) and its `ts` is stamped with the
+     * current time when the caller leaves them off. The completed event is run
+     * through the schema before it touches disk, so a malformed event raises a
+     * `validation` fault rather than corrupting the transcript.
+     */
+    record(event: CrewEventInput): Promise<CrewEvent>;
+    /**
+     * Read back every recorded event, in append (chronological) order.
+     *
+     * A missing log is an empty timeline, not an error. Each line is schema-checked
+     * on the way out, so a corrupt transcript surfaces as a `validation` fault
+     * naming the bad line rather than silently returning garbage.
+     */
+    timeline(): Promise<CrewEvent[]>;
+}
+export {};

package/dist/types/swarm/workboard/board.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `TicketBoard` — the swarm's unit-of-work store.
+ *
+ * A board is the shared to-do list a crew of agent teammates pulls from. Each
+ * piece of work is a {@link Ticket}: a small, schema-validated record with a
+ * lifecycle (`open → claimed → done | failed`, plus a `blocked` side-state) and
+ * an optional set of `deps` on other tickets. The whole board lives in one JSON
+ * file, mediated by the kernel's {@link JsonCell}, so every mutation is a single
+ * guarded read-modify-write — the board never touches `node:fs` locking, temp
+ * renames, or coercion itself. It is, as intended, a thin domain wrapper over
+ * `JsonCell.mutate`.
+ *
+ * The dependency relation is a first-class concern. `deps` form a directed graph
+ * ("A must be `done` before B is workable"); {@link TicketBoard} keeps that graph
+ * honest in two ways, both delegated to {@link DepGraph}:
+ *
+ *   - **Edges once.** A dependency declared twice contributes a single edge; the
+ *     graph carries no parallel edges.
+ *   - **No cycles.** {@link TicketBoard.add} rebuilds the graph including the
+ *     incoming ticket and rejects the insert with a `conflict` fault if it would
+ *     introduce a cycle — a dependency loop can never reach disk.
+ *
+ * Readiness falls out of that graph: {@link TicketBoard.ready} returns the `open`
+ * tickets whose every dependency has reached `done`. Those are the tickets a
+ * member may safely {@link TicketBoard.claim}; claiming is atomic (it runs inside
+ * the cell's guarded transform), so two members racing for the same ticket cannot
+ * both win.
+ */
+import { z } from "zod";
+/** The lifecycle states a ticket moves through. */
+export declare const ticketStatuses: readonly ["open", "claimed", "blocked", "done", "failed"];
+/** A ticket's lifecycle state. */
+export type TicketStatus = (typeof ticketStatuses)[number];
+/**
+ * One unit of work on the board.
+ *
+ * `status` is the lifecycle discriminant; `assignee` names the member that holds
+ * a `claimed`/`blocked` ticket (and survives onto `done`/`failed` as the record
+ * of who did it). `deps` are the ids of tickets that must reach `done` before
+ * this one is workable. `result`/`error` capture the terminal payload of a
+ * completed/failed ticket. Timestamps are epoch milliseconds.
+ */
+export declare const ticketSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    status: z.ZodEnum<{
+        done: "done";
+        failed: "failed";
+        open: "open";
+        claimed: "claimed";
+        blocked: "blocked";
+    }>;
+    assignee: z.ZodOptional<z.ZodString>;
+    deps: z.ZodArray<z.ZodString>;
+    result: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    blockReason: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+/** A validated ticket. */
+export type Ticket = z.infer<typeof ticketSchema>;
+/** Fields a caller may set when adding a ticket. */
+export interface TicketDraft {
+    /** Short human-facing summary (required). */
+    readonly title: string;
+    /** Full task description; defaults to empty. */
+    readonly body?: string;
+    /** Ids of tickets that must complete first; defaults to none. */
+    readonly deps?: readonly string[];
+}
+/**
+ * The shared, durable ticket store a swarm coordinates through.
+ *
+ * Open one with {@link TicketBoard.open}; every method is a thin pass over the
+ * underlying {@link JsonCell}. Mutators (`add`, `claim`, `complete`, `fail`,
+ * `block`, `unblock`) run inside a single guarded transform so concurrent crews
+ * sharing the file serialize correctly; readers (`get`, `list`, `ready`) are
+ * lock-free.
+ */
+export declare class TicketBoard {
+    private readonly cell;
+    /** Injected clock, epoch ms — overridable for deterministic tests. */
+    private readonly now;
+    private constructor();
+    /**
+     * Open (or adopt) the board backed by the JSON file at `path`.
+     *
+     * `now` defaults to `Date.now`; tests may inject a deterministic clock. The
+     * file is not created until the first mutation.
+     */
+    static open(path: string, now?: () => number): Promise<TicketBoard>;
+    /**
+     * Admit a new ticket, returning the persisted record.
+     *
+     * The ticket is born `open` with a freshly minted id and the current
+     * timestamp. Its `deps` are de-duplicated; every dep must already name a
+     * ticket on the board (a dangling dependency raises `not_found`). The
+     * dependency graph is rebuilt including the newcomer, and the insert is
+     * rejected with a `conflict` fault if it would introduce a cycle — the board
+     * never persists a cyclic dependency relation.
+     */
+    add(draft: TicketDraft): Promise<Ticket>;
+    /**
+     * Atomically claim an `open` ticket for `member`.
+     *
+     * Moves the ticket `open → claimed` and stamps `assignee = member`. The check
+     * and the write happen inside one guarded transform, so two members racing for
+     * the same ticket cannot both succeed — the loser sees a `conflict` fault. A
+     * ticket that is missing (`not_found`) or not currently `open` (`conflict`)
+     * cannot be claimed.
+     */
+    claim(id: string, member: string): Promise<Ticket>;
+    /**
+     * Mark a `claimed` ticket `done`, recording its `result`.
+     *
+     * Only a `claimed` ticket may complete; completing anything else raises
+     * `conflict`. Completion can unblock other tickets — see {@link ready}.
+     */
+    complete(id: string, result: string): Promise<Ticket>;
+    /**
+     * Mark a `claimed` ticket `failed`, recording the `error`.
+     *
+     * Only a `claimed` ticket may fail; failing anything else raises `conflict`. A
+     * failed dependency never satisfies a dependent (only `done` does), so its
+     * dependents stay out of {@link ready}.
+     */
+    fail(id: string, err: string): Promise<Ticket>;
+    /**
+     * Move an `open` or `claimed` ticket into the `blocked` side-state.
+     *
+     * Blocking records an optional human-readable `reason` and preserves the
+     * `assignee`. A terminal ticket (`done`/`failed`) cannot be blocked
+     * (`conflict`). Use {@link unblock} to return it to the queue.
+     */
+    block(id: string, reason?: string): Promise<Ticket>;
+    /**
+     * Return a `blocked` ticket to `open`, clearing its assignee and block reason.
+     *
+     * Only a `blocked` ticket may be unblocked (`conflict` otherwise). It re-enters
+     * the queue unowned, so any member may {@link claim} it next.
+     */
+    unblock(id: string): Promise<Ticket>;
+    /** Fetch one ticket by id, or `null` if the board has no such ticket. */
+    get(id: string): Promise<Ticket | null>;
+    /**
+     * List every ticket in insertion order, optionally filtered by status.
+     *
+     * The order is stable across reads and process restarts (it follows the
+     * persisted insertion sequence, not map iteration order).
+     */
+    list(status?: TicketStatus): Promise<Ticket[]>;
+    /**
+     * The `open` tickets that are workable right now.
+     *
+     * A ticket is ready when it is `open` and every id in its `deps` names a
+     * ticket that has reached `done`. Tickets with unmet, failed, or still-running
+     * dependencies are withheld. Results are in insertion order, so the board hands
+     * work out fairly (oldest first). These are exactly the tickets a member may
+     * {@link claim}.
+     */
+    ready(): Promise<Ticket[]>;
+    /**
+     * Guarded transform of a single ticket by id.
+     *
+     * Loads the named ticket, applies `change` (which stamps a fresh `updatedAt`),
+     * and writes the whole board back — all inside one {@link JsonCell.mutate}, so
+     * the read-decide-write is atomic against concurrent members. A missing id
+     * raises `not_found`; `change` may throw a `conflict` to veto an illegal
+     * transition.
+     */
+    private transition;
+}

package/dist/types/swarm/workboard/dep-graph.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `DepGraph` — the workboard's dependency relation, with edges added exactly once.
+ *
+ * A ticket may declare it `deps` on other tickets: ticket *B* depends on ticket
+ * *A* means "A must reach `done` before B is workable". That relation is a
+ * directed acyclic graph — an edge `A → B` ("A unblocks B") for every `A` in
+ * `B.deps`. This module is the pure, in-memory view of that graph, rebuilt from
+ * the ticket store whenever the board needs to reason about readiness or admit a
+ * new ticket.
+ *
+ * Two properties the workboard leans on, both enforced here rather than scattered
+ * across the board logic:
+ *
+ *   1. **Edges are added once.** Declaring the same dependency twice (a duplicate
+ *      in `deps`, or the same pair re-derived on a later rebuild) adds the edge a
+ *      single time. The adjacency sets are de-duplicating by construction, so the
+ *      graph carries no parallel edges and downstream traversals visit each
+ *      neighbour at most once.
+ *   2. **Cycles are detectable.** {@link DepGraph.firstCycle} returns the first
+ *      dependency cycle it finds (as the node path that closes the loop) or
+ *      `null` when the graph is acyclic. The board calls this when admitting a
+ *      ticket so a dependency loop is rejected at `add()` time instead of
+ *      deadlocking `ready()` forever.
+ *
+ * The graph is intentionally decoupled from persistence and from the `Ticket`
+ * shape: it speaks only in node ids and `id → deps` adjacency, so it is trivial
+ * to test and reuse.
+ */
+/**
+ * A directed dependency graph over ticket ids.
+ *
+ * Build one with {@link DepGraph.fromDeps}; the constructor is private so every
+ * graph goes through the de-duplicating edge-insertion path. Nodes are ticket
+ * ids; an edge `dep → ticket` records that `dep` must complete before `ticket`.
+ */
+export declare class DepGraph {
+    /** `dep → set of tickets it unblocks`. De-duplicating: each edge appears once. */
+    private readonly forward;
+    /** `ticket → set of tickets it depends on`. The reverse of {@link forward}. */
+    private readonly backward;
+    /** Every node known to the graph (a dependency may be named before it exists). */
+    private readonly nodes;
+    private constructor();
+    /**
+     * Build a graph from an `id → deps` mapping.
+     *
+     * Each `(dep, id)` pair becomes the edge `dep → id`, inserted via
+     * {@link addEdge} so duplicates collapse. Self-edges (`id` listing itself in
+     * its own `deps`) are admitted as ordinary edges so that {@link firstCycle}
+     * reports them as the trivial one-node cycle rather than silently dropping
+     * them.
+     */
+    static fromDeps(entries: Iterable<readonly [id: string, deps: readonly string[]]>): DepGraph;
+    /**
+     * Record the edge `from → to` (i.e. `from` must finish before `to`).
+     *
+     * Idempotent: the backing adjacency is a `Set`, so re-adding an existing edge
+     * is a no-op and the graph never accumulates parallel edges.
+     */
+    private addEdge;
+    /** Lazily fetch (or create) the adjacency set for `key` in `side`. */
+    private edgeSet;
+    /** The ids this node directly depends on (its in-neighbours). */
+    dependenciesOf(id: string): readonly string[];
+    /** The ids directly unblocked by this node (its out-neighbours). */
+    dependentsOf(id: string): readonly string[];
+    /**
+     * Find the first dependency cycle, or `null` if the graph is acyclic.
+     *
+     * Runs an iterative depth-first search colouring nodes white/grey/black; the
+     * first back-edge to a grey (on-stack) node closes a cycle, which is returned
+     * as the node path from the re-encountered node around to itself
+     * (`[a, b, …, a]`). Detection is what lets the board reject a cyclic `add()`
+     * up front rather than letting `ready()` starve.
+     */
+    firstCycle(): readonly string[] | null;
+}

package/dist/types/swarm/workboard/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The workboard — public surface.
+ *
+ * One domain service, {@link TicketBoard}: the swarm's shared, durable task store.
+ * It is a thin wrapper over the kernel's `JsonCell` (every mutation is one guarded
+ * read-modify-write) that adds a ticket lifecycle and an edges-once dependency
+ * graph with cycle detection. {@link DepGraph} is exported for callers that want
+ * to reason about the dependency relation directly.
+ */
+export { TicketBoard, ticketSchema, ticketStatuses } from "./board";
+export type { Ticket, TicketStatus, TicketDraft } from "./board";
+export { DepGraph } from "./dep-graph";

package/dist/types/tracing/adapter/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The adapter layer — public surface.
+ *
+ * The OPTIONAL runtime bridge {@link traceAgentRun}, which projects a runtime
+ * {@link import('../../runtime').RunEvent} stream onto a
+ * {@link import('../recorder/recorder').Recorder} as nested `run`/`inference`/
+ * `action` {@link import('../signal/segment').Segment}s. Importing it is the one
+ * place tracing knows the runtime's event vocabulary; the rest of the subsystem
+ * stays runtime-agnostic.
+ */
+export type { RunEventSubscribe } from "./runtime-trace";
+export { traceAgentRun } from "./runtime-trace";

package/dist/types/tracing/adapter/runtime-trace.d.ts

@@ -0,0 +1,54 @@
+/**
+ * An OPTIONAL bridge from the agent runtime's {@link RunEvent} stream to the
+ * tracing layer's {@link Recorder} / {@link Segment} model.
+ *
+ * The runtime publishes a flat stream of {@link RunEvent}s (snapshots, deltas,
+ * tool lifecycle, settle/fault). {@link traceAgentRun} subscribes to that stream
+ * and *projects* it into nested {@link Segment}s on a {@link Recorder}: a `run`
+ * segment that spans a whole prompt-to-settlement interaction, an `inference`
+ * child per model turn, and an `action` child per tool invocation. The result is
+ * a hierarchical trace that flows onto the recorder's {@link SignalChannel} for
+ * any {@link import('../sinks/base').Sink} to drain.
+ *
+ * The mapping is deliberately *best-effort* and decoupled: it reads only the
+ * public {@link RunEvent} shape (imported from "../../runtime") and never reaches
+ * into runtime internals. It tolerates events arriving in any order — a missing
+ * `tool_started` for a `tool_finished`, a `settled` with an inference still
+ * open, repeated terminal events — by closing whatever is open and ignoring the
+ * rest. Wiring it is optional: nothing in the runtime depends on it.
+ *
+ * This is the one place the tracing subsystem is allowed to know the runtime's
+ * event vocabulary; the tracing core (signal/channel/recorder/…) stays entirely
+ * runtime-agnostic.
+ */
+import type { RunEvent } from "../../runtime";
+import type { Recorder } from "../recorder/recorder";
+/**
+ * Subscribe to a runtime {@link RunEvent} source and call `handler` for each
+ * event, returning a disposer that detaches the subscription. This matches the
+ * shape of `Agent.subscribe` without importing the `Agent` type, so the adapter
+ * stays decoupled from the conductor.
+ */
+export type RunEventSubscribe = (handler: (event: RunEvent) => void) => () => void;
+/**
+ * Project a runtime {@link RunEvent} stream onto a {@link Recorder} as nested
+ * {@link Segment}s, returning a disposer that detaches and tidies up.
+ *
+ * Lifecycle mapping (best-effort):
+ *
+ * - **run** — opened lazily on the first event of a fresh run (or the first
+ *   `snapshot`/`settled`/`faulted` carrying a `runId`), named after the run.
+ *   Closed on `settled` (status `ok`) or `faulted` (status `error`).
+ * - **inference** — a child of the run, opened when the run enters its
+ *   `invoking` phase (a model turn begins) and closed when the model output is
+ *   consumed (the run leaves `streaming` for `dispatching`/`compacting`, or the
+ *   run terminates). Streaming deltas (`text_delta`/`thinking_delta`) are folded
+ *   onto the open inference as attribute counts.
+ * - **action** — a child of the run, opened on `tool_started` and closed on the
+ *   matching `tool_finished` (status `error` when the outcome `isError`).
+ *
+ * Calling the returned disposer (or the stream ending without a terminal event)
+ * closes any still-open segments so nothing dangles. The function never throws
+ * on malformed input; it simply maps what it can.
+ */
+export declare function traceAgentRun(recorder: Recorder, subscribe: RunEventSubscribe): () => void;

package/dist/types/tracing/channel/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The channel layer — public surface.
+ *
+ * The {@link TraceSignal} union ({@link OpenSignal}/{@link UpdateSignal}/
+ * {@link CloseSignal}) and the {@link SignalChannel} async-iterable transport
+ * that carries it from producers to consumers.
+ */
+export type { TraceSignal, OpenSignal, UpdateSignal, CloseSignal, SignalChannelOptions, } from "./signal";
+export { SignalChannel } from "./signal";

package/dist/types/tracing/channel/signal.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The trace transport: a {@link TraceSignal} union and the {@link SignalChannel}
+ * that streams it.
+ *
+ * Rather than a `Set` of push subscribers with a manually-drained `flush()`,
+ * trace data flows through a single backpressure-free queue exposed as an
+ * `AsyncIterable<TraceSignal>`. A producer calls {@link SignalChannel.emit} as
+ * segments open, change, and close; one or more consumers pull with
+ * `for await … of channel`. The drain semantics are therefore the language's
+ * own async-iteration protocol — no iteration cap, no subscriber bookkeeping.
+ *
+ * Exactly one signal is emitted per state transition of a {@link import('../signal/handle').SegmentHandle}:
+ * `open` when a segment is created, `update` when attributes are noted, and
+ * `close` carrying the terminal {@link TraceRecord}.
+ */
+import type { Segment, TraceRecord } from "../signal/segment";
+/** Emitted once, when a segment is first opened. Carries the full open value. */
+export interface OpenSignal {
+    readonly type: "open";
+    readonly segment: Segment;
+}
+/** Emitted when an open segment's attributes are amended in place (by id). */
+export interface UpdateSignal {
+    readonly type: "update";
+    readonly id: string;
+    readonly attributes: Readonly<Record<string, unknown>>;
+}
+/** Emitted once, when a segment reaches a terminal state. Carries the record. */
+export interface CloseSignal {
+    readonly type: "close";
+    readonly record: TraceRecord;
+}
+/** The tagged union every consumer of a {@link SignalChannel} branches on. */
+export type TraceSignal = OpenSignal | UpdateSignal | CloseSignal;
+/**
+ * Optional behaviour for a {@link SignalChannel}.
+ *
+ * `bound` caps the number of signals buffered while no consumer is pulling;
+ * once exceeded the *oldest* unread signal is dropped (newest data wins). Left
+ * unset, the buffer is unbounded.
+ */
+export interface SignalChannelOptions {
+    readonly bound?: number;
+}
+/**
+ * A single-stream, multi-emit, async-iterable transport for {@link TraceSignal}s.
+ *
+ * Producers push with {@link emit}; a consumer drains with `for await`. When the
+ * channel is faster than its consumer, signals queue (subject to `bound`); when
+ * the consumer is faster, its pull parks on a promise the next `emit` resolves.
+ * {@link close} ends the stream — the active iterator completes after draining
+ * whatever is already queued, and further `emit`s are ignored.
+ *
+ * The channel is *cold-tolerant but single-consumer*: a second concurrent
+ * `[Symbol.asyncIterator]()` pull shares the same queue (signals are not
+ * fanned out / cloned). For fan-out, compose multiple channels upstream.
+ */
+export declare class SignalChannel implements AsyncIterable<TraceSignal> {
+    /** Buffered signals awaiting a consumer, oldest first. */
+    private readonly buffer;
+    /** A parked consumer's resolver, set while a pull awaits the next signal. */
+    private waiting;
+    /** Once true, no further signals are accepted and pulls drain then end. */
+    private closed;
+    /** Upper bound on the unread buffer; `Infinity` means unbounded. */
+    private readonly bound;
+    constructor(options?: SignalChannelOptions);
+    /**
+     * Publish a signal onto the stream.
+     *
+     * If a consumer is parked, the signal is handed to it directly; otherwise it
+     * is buffered (dropping the oldest entry past `bound`). A no-op once closed.
+     */
+    emit(signal: TraceSignal): void;
+    /**
+     * End the stream.
+     *
+     * A parked consumer is completed immediately; a consumer that later pulls
+     * receives any still-buffered signals before the terminal `done`. Idempotent.
+     */
+    close(): void;
+    /** Whether {@link close} has been called. */
+    get isClosed(): boolean;
+    /** Count of signals buffered but not yet consumed. */
+    get pending(): number;
+    /**
+     * The async-iteration entrypoint.
+     *
+     * Yields buffered signals immediately, then parks awaiting the next `emit`,
+     * and returns `{ done: true }` once the channel is closed and drained.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<TraceSignal>;
+}

package/dist/types/tracing/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Homegrown agent tracer — public surface (core).
+ *
+ * A dependency-light, OTel-free tracing core with a deliberately fresh
+ * vocabulary: an immutable {@link Segment} value (kinds `run`/`inference`/
+ * `action`/`recall`/`custom`) driven by a functional {@link SegmentHandle}
+ * (`note`/`child`/`fail`/`close`), and a {@link TraceSignal} stream delivered
+ * over a {@link SignalChannel} async iterable. Sampled-out work collapses to the
+ * single frozen {@link NOOP_HANDLE}.
+ *
+ * This barrel re-exports the foundational layers — `signal` (the data model +
+ * handle), `channel` (the transport), `redaction` (the {@link SecretScrubber}
+ * attribute processor), and `sinks` (terminal consumers that drain a channel and
+ * write somewhere) — together with `recorder` (the {@link Recorder} tracer +
+ * {@link SampleGate} admission control), `registry` (the {@link TelemetryHub}
+ * of named recorders), and the optional `adapter` ({@link traceAgentRun}, the
+ * runtime {@link import('../runtime').RunEvent} bridge).
+ */
+export * from "./signal";
+export * from "./channel";
+export * from "./redaction";
+export * from "./sinks";
+export * from "./recorder";
+export * from "./registry";
+export * from "./adapter";

package/dist/types/tracing/recorder/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The recorder layer — public surface.
+ *
+ * The {@link SampleGate} admission control (its {@link SampleStrategy} /
+ * {@link RatioStrategy} shapes) and the {@link Recorder} tracer instance (its
+ * {@link OpenOptions} / {@link RecorderOptions}) that mints {@link SegmentHandle}s
+ * onto a {@link SignalChannel}.
+ */
+export type { SampleStrategy, RatioStrategy } from "./sampling";
+export { SampleGate } from "./sampling";
+export type { OpenOptions, RecorderOptions } from "./recorder";
+export { Recorder } from "./recorder";