indusagi 0.12.32 → 0.12.33

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";

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

@@ -0,0 +1,75 @@
+/**
+ * The tracer instance: a {@link Recorder}.
+ *
+ * A recorder is the object call sites reach for to *start* tracing. It owns a
+ * {@link SignalChannel} (the transport sinks drain) and a {@link SampleGate}
+ * (admission control), and stamps every trace it produces with a `serviceName`.
+ * Its one job is {@link open}: consult the gate, and either mint a live
+ * {@link SegmentHandle} whose signals flow onto the channel, or hand back the
+ * shared {@link NOOP_HANDLE} so a sampled-out trace costs nothing downstream.
+ *
+ * This replaces the OTel "tracer provider / tracer" pair with a single, flat
+ * object: there is no global ambient context, no `startSpan` ceremony, and no
+ * exporter wiring here — sinks subscribe by draining {@link channel}.
+ */
+import { SignalChannel } from "../channel/signal";
+import { type SegmentHandle } from "../signal/handle";
+import { type SegmentKind } from "../signal/segment";
+import { SampleGate, type SampleStrategy } from "./sampling";
+/** Per-`open` options; all optional. */
+export interface OpenOptions {
+    /**
+     * Trace to join. Omit to start a *new* trace (the recorder mints a fresh id
+     * and the gate decides on it). Supplied for a child whose admission should
+     * follow its trace's verdict.
+     */
+    readonly traceId?: string;
+    /** Enclosing segment id, or `null`/omitted for a trace root. */
+    readonly parentId?: string | null;
+    /** Initial attributes for the opened segment. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/** Construction options for a {@link Recorder}. */
+export interface RecorderOptions {
+    /**
+     * Logical name of the service/agent this recorder traces. Stamped onto the
+     * root attributes of every admitted trace under the `service.name` key.
+     */
+    readonly serviceName: string;
+    /** Admission strategy or a pre-built gate; defaults to `"always"`. */
+    readonly sampling?: SampleStrategy | SampleGate;
+    /** Transport to emit onto; a fresh unbounded {@link SignalChannel} by default. */
+    readonly channel?: SignalChannel;
+}
+/**
+ * A homegrown tracer instance.
+ *
+ * Holds a service name, a {@link SampleGate}, and a {@link SignalChannel}.
+ * {@link open} is the sole entry point; {@link channel} exposes the stream for
+ * sinks to drain.
+ */
+export declare class Recorder {
+    /** Logical service/agent name stamped onto admitted root traces. */
+    readonly serviceName: string;
+    private readonly gate;
+    private readonly signalChannel;
+    constructor(options: RecorderOptions);
+    /**
+     * Open a segment, subject to sampling.
+     *
+     * Resolves the trace id (a supplied `opts.traceId` joins an existing trace; a
+     * root mints a fresh one), then consults the {@link SampleGate}. Sampled out →
+     * the frozen {@link NOOP_HANDLE} (nothing is emitted). Sampled in → a live
+     * {@link SegmentHandle} from {@link openHandle}, whose `open` signal — and all
+     * subsequent `update`/`close` signals — land on this recorder's channel. A
+     * root open also folds `serviceName` into the segment's attributes.
+     */
+    open(kind: SegmentKind, name: string, opts?: OpenOptions): SegmentHandle;
+    /**
+     * The recorder's signal stream.
+     *
+     * Sinks drain this with `for await … of recorder.channel()`. It is the same
+     * underlying {@link SignalChannel} every {@link open}ed handle emits onto.
+     */
+    channel(): SignalChannel;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Trace admission control: the {@link SampleGate}.
+ *
+ * A {@link Recorder} consults a gate once per `open` to decide whether a new
+ * trace is recorded at all. Three strategies cover the useful spectrum:
+ *
+ * - `"always"` — admit everything (the default; good for dev/diagnostics).
+ * - `"never"`  — admit nothing (a kill-switch that keeps call sites intact).
+ * - `{ ratio }` — admit a deterministic fraction in `[0, 1]`, keyed by the
+ *   trace id, so the *same* trace id always yields the *same* verdict. This is
+ *   ratio sampling without a random draw: the decision is reproducible across
+ *   processes and replays, and a child opened on an admitted trace id is itself
+ *   admitted (the whole trace is consistently in or out).
+ *
+ * The ratio hash is a small, dependency-free FNV-1a over the trace id's bytes,
+ * folded to a unit fraction. It is *not* cryptographic — it only needs to spread
+ * hex trace ids roughly uniformly across `[0, 1)`, which FNV-1a does well enough
+ * for sampling. (Trace ids are themselves minted from `node:crypto`, so the
+ * input is already high-entropy.)
+ */
+/** A deterministic ratio strategy: admit a fraction `ratio ∈ [0, 1]` of traces. */
+export interface RatioStrategy {
+    readonly ratio: number;
+}
+/**
+ * How a {@link SampleGate} decides admission.
+ *
+ * `"always"`/`"never"` are constant verdicts; `{ ratio }` is a per-trace-id
+ * deterministic fraction.
+ */
+export type SampleStrategy = "always" | "never" | RatioStrategy;
+/**
+ * Admission control for traces.
+ *
+ * Construct with a {@link SampleStrategy} and call {@link decide} with a trace
+ * id; the verdict is constant for `"always"`/`"never"` and deterministic per id
+ * for a ratio. A gate holds no mutable state, so a single instance is safely
+ * shared across recorders and threads of execution.
+ */
+export declare class SampleGate {
+    private readonly strategy;
+    /** Pre-clamped admission threshold for the ratio strategy; unused otherwise. */
+    private readonly threshold;
+    constructor(strategy?: SampleStrategy);
+    /**
+     * Decide whether the trace identified by `traceId` is admitted.
+     *
+     * - `"always"` → always `true`.
+     * - `"never"`  → always `false`.
+     * - `{ ratio }` → `unitHash(traceId) < ratio` (clamped): deterministic, so the
+     *   same id always yields the same answer. Ratio `0` admits nothing and ratio
+     *   `1` admits everything regardless of the hash.
+     */
+    decide(traceId: string): boolean;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Redaction layer — attribute scrubbing before trace data leaves the process.
+ *
+ * Re-exports the {@link SecretScrubber} processor along with its default rule
+ * set and redaction token, so sinks can sanitize segment attributes without
+ * reaching into the module directly.
+ */
+export * from "./secret-scrubber";

package/dist/types/tracing/redaction/secret-scrubber.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Attribute scrubbing: the {@link SecretScrubber} segment-attribute processor.
+ *
+ * Trace attributes are an open `Record<string, unknown>` bag — callers stash
+ * request payloads, tool arguments, headers, and model parameters in there, and
+ * any of those can carry a credential. Before a {@link import('../signal/segment').Segment}'s
+ * attributes leave the process (persisted by a sink, printed to a console), this
+ * processor walks the whole bag and replaces anything that looks secret with an
+ * inert {@link REDACTION_TOKEN}.
+ *
+ * Two independent signals trigger a redaction:
+ *
+ * - **Key shape** — the *path key* matches a {@link SecretPattern} (e.g. a field
+ *   literally named `api_key`, `authorization`, `password`). The value is
+ *   redacted regardless of what it is.
+ * - **Value shape** — a *string value* matches a pattern (e.g. a `Bearer …`
+ *   token or a `sk-…` style key) even when its key looks innocuous.
+ *
+ * The walk is a single iterative pass over an explicit work stack rather than a
+ * recursive per-field branch cascade: every node (object, array, leaf) is
+ * pushed once and handled by one uniform loop body, so arbitrarily nested
+ * structures cost no extra call frames and there is no field-by-field `if`
+ * ladder to maintain. The vocabulary is deliberately our own — `SecretScrubber`
+ * and a guillemet redaction token, not an OTel "attribute processor" emitting
+ * `[REDACTED]`.
+ */
+/**
+ * A rule that flags a secret.
+ *
+ * `key` matches against the *name* of a field on the current path; `value`
+ * matches against a *string* leaf. A pattern provides at least one of the two.
+ * Patterns are tested with {@link RegExp.test}, so a global (`/g`) flag would
+ * make matching stateful — supply non-global expressions.
+ */
+export interface SecretPattern {
+    /** Human label, useful when reasoning about which rule fired. */
+    readonly label: string;
+    /** Matches a field/key name on the attribute path. */
+    readonly key?: RegExp;
+    /** Matches a string leaf value. */
+    readonly value?: RegExp;
+}
+/** The inert string that replaces any redacted value. Not `[REDACTED]`. */
+export declare const REDACTION_TOKEN = "\u2039redacted\u203A";
+/**
+ * The built-in rule set. Fresh wording — these are not lifted from any existing
+ * processor's defaults. Tuned to catch the common shapes that show up in agent
+ * trace attributes without being so broad they swallow ordinary text.
+ */
+export declare const DEFAULT_SECRET_PATTERNS: readonly SecretPattern[];
+/** Construction options for a {@link SecretScrubber}. */
+export interface SecretScrubberOptions {
+    /** Override the default rule set entirely. Defaults to {@link DEFAULT_SECRET_PATTERNS}. */
+    readonly patterns?: readonly SecretPattern[];
+    /** Override the replacement string. Defaults to {@link REDACTION_TOKEN}. */
+    readonly token?: string;
+}
+/**
+ * A configurable, OTel-free attribute processor that redacts secret-looking
+ * keys and values from a trace attribute bag.
+ *
+ * Stateless across calls and safe to share: {@link scrub} never mutates its
+ * input and produces a fresh structure each time.
+ */
+export declare class SecretScrubber {
+    private readonly patterns;
+    private readonly token;
+    /** Pre-split views so the hot loop never re-checks which rules have a key/value side. */
+    private readonly keyRules;
+    private readonly valueRules;
+    constructor(options?: SecretScrubberOptions);
+    /** True when a field name matches any key-shaped rule. */
+    private keyIsSecret;
+    /** True when a string leaf matches any value-shaped rule. */
+    private valueIsSecret;
+    /**
+     * Decide a leaf's sanitized form given the key that points at it.
+     *
+     * Redacts when the key looks secret, or when a string value looks secret.
+     * Non-string leaves under an innocuous key pass through untouched.
+     */
+    private sanitizeLeaf;
+    /**
+     * Return a deep copy of `attributes` with secret-looking keys and values
+     * replaced by the redaction token.
+     *
+     * Walks the structure with a single explicit stack (no recursion). Containers
+     * are cloned shallowly up front and their children enqueued; leaves are
+     * resolved through {@link sanitizeLeaf}. The input — including nested objects
+     * and arrays — is never mutated. A key whose name is itself secret short-
+     * circuits the descent: the whole subtree under it collapses to the token,
+     * so credentials nested inside (e.g. `auth: { token: … }`) cannot leak.
+     */
+    scrub(attributes: Record<string, unknown>): Record<string, unknown>;
+}

package/dist/types/tracing/registry/hub.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The recorder registry: a {@link TelemetryHub}.
+ *
+ * Where a {@link Recorder} traces one service, an application usually wants a
+ * handful — one per agent, subsystem, or tenant — addressable by name without
+ * threading instances through every call site. The hub is that lookup: a small
+ * named map of recorders with a designated default.
+ *
+ * This is the homegrown analogue of an OTel "tracer provider" registry, minus
+ * the global ambient machinery: a hub is an ordinary object you can construct,
+ * pass around, and replace. A module-level *process default* is offered for
+ * convenience ({@link getDefaultHub}/{@link setDefaultHub}) but is strictly
+ * opt-in — nothing here reads it implicitly.
+ */
+import { Recorder, type RecorderOptions } from "../recorder/recorder";
+/**
+ * A named registry of {@link Recorder}s.
+ *
+ * {@link register} adds (or replaces) a recorder under a name and returns it;
+ * {@link recorder} looks one up (falling back to the default when called with no
+ * name); {@link getDefault} returns the default recorder if one exists. The
+ * *first* recorder registered becomes the default unless a later
+ * {@link register} explicitly uses the reserved default name.
+ */
+export declare class TelemetryHub {
+    private readonly recorders;
+    /** Name of the recorder returned by {@link recorder} with no argument. */
+    private defaultName;
+    /**
+     * Register a recorder under `name`, returning the constructed instance.
+     *
+     * Re-registering a name replaces the prior recorder. If no default has been
+     * chosen yet, the first registration becomes the default; registering under
+     * the reserved `"default"` name always (re)designates the default.
+     */
+    register(name: string, options: RecorderOptions): Recorder;
+    /**
+     * Look up a recorder by `name`, or the default when `name` is omitted.
+     *
+     * Throws if the requested (or default) recorder is not registered, so a
+     * missing recorder fails loudly rather than silently dropping traces.
+     */
+    recorder(name?: string): Recorder;
+    /** The default recorder, or `undefined` if none has been registered. */
+    getDefault(): Recorder | undefined;
+    /** Whether a recorder is registered under `name`. */
+    has(name: string): boolean;
+}
+/**
+ * The process-wide default {@link TelemetryHub}, created on first access.
+ *
+ * A convenience for code that has no hub to hand. Purely opt-in: nothing in this
+ * subsystem consults it unless a caller does.
+ */
+export declare function getDefaultHub(): TelemetryHub;
+/** Replace the process-wide default {@link TelemetryHub} (e.g. for tests). */
+export declare function setDefaultHub(hub: TelemetryHub): void;

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

@@ -0,0 +1,7 @@
+/**
+ * The registry layer — public surface.
+ *
+ * The {@link TelemetryHub} named-recorder registry plus the opt-in process
+ * default accessors {@link getDefaultHub}/{@link setDefaultHub}.
+ */
+export { TelemetryHub, getDefaultHub, setDefaultHub } from "./hub";

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

@@ -0,0 +1,73 @@
+/**
+ * The behavioural face of a segment: a functional {@link SegmentHandle}.
+ *
+ * Where {@link Segment} is the immutable data, a {@link SegmentHandle} is the
+ * small bag of closures a caller actually uses — `note`, `child`, `fail`,
+ * `close`. Each operation derives the next frozen segment value and emits a
+ * {@link TraceSignal} onto an injected `sink`. There is intentionally **no
+ * class hierarchy**: a sampled-in handle is a plain object of closures built by
+ * {@link openHandle}, and a sampled-out handle is the single frozen
+ * {@link NOOP_HANDLE} value implementing the same shape with empty methods — not
+ * a subclass, not a separate `NoopSegment` type.
+ *
+ * The handle keeps the segment's *current* value in a closed-over variable so
+ * that `note`/`fail` can derive successive values; this is the only mutable
+ * state in the module and it never escapes — callers only ever see immutable
+ * {@link Segment}/{@link TraceRecord} values via the emitted signals.
+ */
+import type { TraceSignal } from "../channel/signal";
+import { type SegmentKind } from "./segment";
+/** A consumer of trace signals — typically a {@link import('../channel/signal').SignalChannel}'s `emit`. */
+export type SignalSink = (signal: TraceSignal) => void;
+/**
+ * The functional handle over a single in-flight segment.
+ *
+ * `note`, `child`, and `fail` are no-ops after `close`; `close` itself is
+ * idempotent (the first call wins, later calls do nothing). This makes the
+ * happy path forgiving of double-close in `finally` blocks.
+ */
+export interface SegmentHandle {
+    /** The trace this handle's segment belongs to. Hex; stable across the trace. */
+    readonly traceId: string;
+    /** This segment's own id. Hex. `""` for the {@link NOOP_HANDLE}. */
+    readonly id: string;
+    /** Whether this handle does real work (`true`) or is the sampled-out no-op. */
+    readonly active: boolean;
+    /** Amend the segment's attributes; emits an `update` signal. */
+    note(attributes: Readonly<Record<string, unknown>>): void;
+    /** Open a child segment under this one, sharing the trace; returns its handle. */
+    child(kind: SegmentKind, name: string): SegmentHandle;
+    /** Record a failure (sets the closing status to `error`). Does not close. */
+    fail(error: unknown): void;
+    /** Close the segment; emits a `close` signal carrying the {@link TraceRecord}. */
+    close(status?: "ok" | "error"): void;
+}
+/** Inputs for opening a real, sampled-in handle. */
+export interface OpenHandleInput {
+    readonly kind: SegmentKind;
+    readonly name: string;
+    /** Trace to join; a fresh trace id is minted when omitted (a root). */
+    readonly traceId?: string;
+    /** Enclosing segment id, or `null`/omitted for a root. */
+    readonly parentId?: string | null;
+    /** Initial attributes. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Open a live segment and return its functional handle.
+ *
+ * Immediately emits an `open` {@link TraceSignal} carrying the fresh frozen
+ * {@link Segment}. Subsequent `note`/`fail`/`close` derive successive frozen
+ * values and emit `update`/`close` signals through the same `sink`. Children
+ * inherit `traceId` and are parented to this segment, and share the `sink`.
+ */
+export declare function openHandle(input: OpenHandleInput, sink: SignalSink): SegmentHandle;
+/**
+ * The single shared sampled-out handle.
+ *
+ * A frozen no-op object satisfying {@link SegmentHandle}: it emits nothing,
+ * allocates nothing per call, and returns *itself* from `child` so an entire
+ * sampled-out subtree costs nothing. This is the whole "noop" story — there is
+ * no `NoopSegment` class to subclass.
+ */
+export declare const NOOP_HANDLE: SegmentHandle;

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

@@ -0,0 +1,12 @@
+/**
+ * The signal layer — public surface.
+ *
+ * The immutable {@link Segment} data model and its terminal {@link TraceRecord},
+ * the value constructors/derivations ({@link openSegment}/{@link withAttributes}/
+ * {@link closeSegment}) and id minting, plus the functional {@link SegmentHandle}
+ * with its sampled-in factory {@link openHandle} and shared {@link NOOP_HANDLE}.
+ */
+export type { Segment, SegmentKind, SegmentStatus, SegmentError, TraceRecord, OpenSegmentInput, } from "./segment";
+export { openSegment, withAttributes, closeSegment, freshId, freshTraceId, freshSegmentId, } from "./segment";
+export type { SegmentHandle, SignalSink, OpenHandleInput } from "./handle";
+export { openHandle, NOOP_HANDLE } from "./handle";