@botiverse/oar 0.0.11 → 0.1.0

package/README.md

@@ -23,8 +23,8 @@ if (installation?.kind === "available") {
 
 The package has exactly two public entry points:
 
-- `@botiverse/oar` — the full surface: runtime registry, adapters, and everything below. Node-only (adapters import `node:child_process` and runtime SDKs).
-- `@botiverse/oar/observe` — browser-safe subset: the pure derivation utilities over `SessionEvent`s (`observeAgent`, `reduceStatus`, `aggregateDeltas`, `observeStalls`, `classifyTool`, …) with zero Node and zero adapter imports. A browser or Electron-renderer bundle can import this subpath directly without dragging Node-only modules in. The root export re-exports the same utilities for Node consumers.
+- `@botiverse/oar`: the full surface (runtime registry, adapters, and everything below). Node-only (adapters import `node:child_process` and runtime SDKs).
+- `@botiverse/oar/observe`: browser-safe subset, the pure derivation utilities over `SessionEvent`s (`observeAgent`, `reduceStatus`, `aggregateDeltas`, `observeStalls`, `classifyTool`, …) with zero Node and zero adapter imports. A browser or Electron-renderer bundle can import this subpath directly without dragging Node-only modules in. The root export re-exports the same utilities for Node consumers.
 
 Any other deep import (`@botiverse/oar/dist/...`, source paths) is internal and may break without notice.
 

package/dist/contracts/model-catalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * Provider-independent model catalog facade — the other half of the provider
+ * Provider-independent model catalog facade: the other half of the provider
  * plane (see {@link ./provider-auth.js}). It lists providers and their models
  * with capabilities and refreshes the remote catalog, but is credential-blind:
  * it reads auth status only to report which providers are usable, never logs

package/dist/contracts/model-catalog.js

@@ -1,5 +1,5 @@
 /**
- * Provider-independent model catalog facade — the other half of the provider
+ * Provider-independent model catalog facade: the other half of the provider
  * plane (see {@link ./provider-auth.js}). It lists providers and their models
  * with capabilities and refreshes the remote catalog, but is credential-blind:
  * it reads auth status only to report which providers are usable, never logs

package/dist/contracts/provider-auth.d.ts

@@ -1,7 +1,7 @@
 /**
  * Provider-independent authentication facade. Unlike a {@link Runtime} facet,
- * this describes the *provider* plane — the accounts and credentials a runtime
- * consumes (Anthropic, xAI, Moonshot, …) — which is orthogonal to which harness
+ * this describes the *provider* plane: the accounts and credentials a runtime
+ * consumes (Anthropic, xAI, Moonshot, …), which is orthogonal to which harness
  * runs them. Implementations wrap a credential/model backend (the built-in one
  * wraps Pi's `ModelRuntime`) without leaking its types.
  */

package/dist/contracts/provider-auth.js

@@ -1,7 +1,7 @@
 /**
  * Provider-independent authentication facade. Unlike a {@link Runtime} facet,
- * this describes the *provider* plane — the accounts and credentials a runtime
- * consumes (Anthropic, xAI, Moonshot, …) — which is orthogonal to which harness
+ * this describes the *provider* plane: the accounts and credentials a runtime
+ * consumes (Anthropic, xAI, Moonshot, …), which is orthogonal to which harness
  * runs them. Implementations wrap a credential/model backend (the built-in one
  * wraps Pi's `ModelRuntime`) without leaking its types.
  */

package/dist/contracts/records.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The record stream: envelope, the three record kinds, event bodies and
+ * views, request/response bodies, and the session graph + cursor types.
+ * Semantics live in docs/spec; the session control surface that produces
+ * these records is in ./session.ts.
+ */
+/**
+ * Self-certifying envelope on every record (docs/spec/attribution.md).
+ * Identity and ordering rest on `seq` alone; `receivedAt` is best-effort
+ * observation time outside any determinism guarantee.
+ */
+export interface RecordEnvelope {
+    /** Runtime-native session the record belongs to. A derived child session (grok child session, codex child thread) carries ITS OWN id here; the session graph says where it came from, and the Session folds (model/usage/contextUsage, awaitTurnEnd) scope to the root session. */
+    readonly sessionId: string;
+    /** Sub-agent lineage inside the session; `[]` is the root agent. Identity of a tool call or span is the composite `(agentPath, id)`; a bare callId is never a global key. */
+    readonly agentPath: readonly string[];
+    /** Runtime-native turn/span id when the runtime has one (codex turnId). oar never generates it; absent means the runtime reported none. */
+    readonly spanId?: string;
+    /** Monotonic per stream; the cursor anchor and the total order for trace alignment. */
+    readonly seq: number;
+    /** Unix epoch milliseconds stamped at adapter ingress: same clock as Date.now(), so fold×clock consumers (stallOf) compose directly. */
+    readonly receivedAt: number;
+}
+export type RecordKind = "event" | "request" | "response";
+/** The runtime's own words. oar never synthesizes an event and never drops one: whatever the runtime said enters the stream, even after a span ended. */
+export interface EventRecord extends RecordEnvelope {
+    readonly kind: "event";
+    readonly body: EventBody;
+}
+export type RequestDirection = "toRuntime" | "toApp";
+/** An action record that expects an outcome. `toRuntime`: prompt / steer / queue / abort / dispose, issued through this Session. `toApp`: the runtime asking the application something (approval, question, external tool), body verbatim. */
+export interface RequestRecord extends RecordEnvelope {
+    readonly kind: "request";
+    readonly id: string;
+    readonly direction: RequestDirection;
+    readonly body: RequestBody;
+}
+/** Always points at a request; the reverse is not guaranteed. A request without a response is an honest record: the action was initiated and its outcome was not observed. Backfilling a guessed response is forbidden. */
+export interface ResponseRecord extends RecordEnvelope {
+    readonly kind: "response";
+    readonly requestId: string;
+    readonly body: ResponseBody;
+}
+export type SessionRecord = EventRecord | RequestRecord | ResponseRecord;
+/**
+ * An event body carries the runtime's frame verbatim plus oar's typed reading
+ * of it. `native` is the source of truth; `views` is a projection for
+ * consumers that want the cross-runtime vocabulary without parsing five wire
+ * formats. One frame is one record: a claude assistant message with a
+ * thinking block, a text block and a tool_use block is ONE event with three
+ * views, in the frame's own order. A frame oar does not interpret still
+ * enters the stream, with `type` and `native` and no views.
+ */
+export interface EventBody {
+    /** Runtime-native discriminator: claude `type[/subtype]`, codex notification method, pi event type, ACP `sessionUpdate`. */
+    readonly type: string;
+    /** The frame as the runtime sent it (JSON-safe). Never trimmed, never re-shaped. */
+    readonly native: unknown;
+    /** oar's readings of the frame, in frame order; empty when oar has none. */
+    readonly views: readonly EventView[];
+}
+export type ReasoningContent = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "redacted";
+} | {
+    readonly kind: "empty";
+};
+/** Token totals; always cumulative for the agent the record is attributed to. */
+export interface TokenTotals {
+    readonly input: number;
+    readonly output: number;
+}
+/**
+ * What a usage-bearing frame says. `context` is current context fullness as
+ * the runtime reports it; `tokens` is the runtime's running total for this
+ * record's `agentPath`, already resolved by the adapter (which runtime view is
+ * authoritative and how overlapping views deduplicate never crosses this
+ * surface; see docs/spec/attribution.md, "usage: one constraint").
+ */
+export interface UsageReport {
+    readonly context?: ContextUsage;
+    readonly tokens?: TokenTotals;
+}
+export type EventView = {
+    readonly kind: "text_delta";
+    readonly text: string;
+}
+/** A reasoning output item; its lifecycle remains observable without readable contents. */
+ | {
+    readonly kind: "reasoning";
+    readonly content: ReasoningContent;
+} | {
+    readonly kind: "tool_call_started";
+    readonly callId: string;
+    readonly tool: string;
+    /** Best-effort human-readable invocation detail when the runtime exposes it. */
+    readonly input?: string;
+} | {
+    readonly kind: "tool_call_ended";
+    readonly callId: string;
+    /** Best-effort human-readable result detail when the runtime exposes it. */
+    readonly output?: string;
+}
+/** The runtime's OWN completion report for a turn (claude `result`, codex `turn/completed`, pi `agent_end`, an ACP prompt answer). The turn's start is the prompt request record itself; if a runtime reports no end, none appears. */
+ | {
+    readonly kind: "turn_ended";
+    readonly outcome: TurnOutcome;
+} | {
+    readonly kind: "usage";
+    readonly usage: UsageReport;
+}
+/** The model the runtime reports as in effect: its own report, never the request echoed. */
+ | {
+    readonly kind: "model";
+    readonly model: string;
+};
+export type RequestBody = {
+    readonly kind: "prompt";
+    readonly input: string;
+} | {
+    readonly kind: "steer";
+    readonly input: string;
+} | {
+    readonly kind: "queue";
+    readonly input: string;
+} | {
+    readonly kind: "abort";
+} | {
+    readonly kind: "dispose";
+}
+/** A runtime→app request, verbatim; `type` is the runtime's method/subtype. */
+ | {
+    readonly kind: "native";
+    readonly type: string;
+    readonly native: unknown;
+};
+/**
+ * Control responses answer only "accepted or not"; final states and landing
+ * points are always events. The remaining bodies are outcomes only oar
+ * observes: its own answer to a runtime→app request, and the process exit.
+ */
+export type ResponseBody = 
+/** The adapter (or runtime) took the action over. For prompt/steer/queue this is ONE deliberately weak promise: the caller's delivery obligation ENDS; do not resubmit. No guarantee it lands in the current turn, that the model attends to it, or that any business outcome happened; where input landed is the event stream's job. `native` is the runtime's own acknowledgement when it gave one. */
+{
+    readonly kind: "accepted";
+    readonly native?: unknown;
+}
+/** Not taken over; the caller still owns the input. `busy` (another turn is active), `not_steerable`, a dead process, or the runtime's typed refusal. */
+ | {
+    readonly kind: "rejected";
+    readonly reason: string;
+    readonly native?: unknown;
+}
+/** oar's reply to a `toApp` request (e.g. the automatic permission grant), verbatim. */
+ | {
+    readonly kind: "answered";
+    readonly native: unknown;
+}
+/** The runtime process exited, an outcome the runtime cannot say itself. Answers a `dispose` request when oar caused it; also recorded for an unrequested exit, pointing at no request. */
+ | {
+    readonly kind: "exited";
+    readonly code: number | null;
+};
+/** Coarse failure classification so applications can react (re-login, back off, report a bug) without parsing vendor error prose. Best-effort: adapters map what the runtime reveals; "unknown" is an honest answer. */
+export type FailureClass = "auth" | "quota" | "invalid_request" | "overloaded" | "provider" | "runtime_exited" | "unknown";
+export type TurnOutcome = {
+    readonly kind: "completed";
+} | {
+    readonly kind: "aborted";
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+    readonly failure: FailureClass;
+};
+/**
+ * Current context fullness, borrowed from pi's shape because it already
+ * models the hard case: `tokens` is null when unknown (right after compaction,
+ * before the next model response), and `percent` follows.
+ */
+export interface ContextUsage {
+    readonly tokens: number | null;
+    readonly contextWindow: number | null;
+    readonly percent: number | null;
+}
+/** True sessions only (docs/spec/session-graph-and-cursor.md): derived child sessions and transcript branches. Agent parent/child is `agentPath`, not a node. */
+export interface SessionNode {
+    readonly id: string;
+}
+export interface SessionEdge {
+    readonly parent: string;
+    readonly child: string;
+    readonly via: "tool_call" | "fork" | "resume";
+}
+export interface SessionGraph {
+    readonly nodes: readonly SessionNode[];
+    readonly edges: readonly SessionEdge[];
+}
+/** Resume reading after `afterSeq`; `-1` (or omitting the cursor) reads from the start. */
+export interface Cursor {
+    readonly sessionId: string;
+    readonly afterSeq: number;
+}
+//# sourceMappingURL=records.d.ts.map

package/dist/contracts/records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.d.ts","sourceRoot":"","sources":["../../src/contracts/records.ts"],"names":[],"mappings":"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"}

package/dist/contracts/records.js

@@ -0,0 +1,8 @@
+/**
+ * The record stream: envelope, the three record kinds, event bodies and
+ * views, request/response bodies, and the session graph + cursor types.
+ * Semantics live in docs/spec; the session control surface that produces
+ * these records is in ./session.ts.
+ */
+export {};
+//# sourceMappingURL=records.js.map

package/dist/contracts/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/contracts/records.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/contracts/session.d.ts

@@ -1,24 +1,33 @@
+import type { ContextUsage, Cursor, RequestRecord, ResponseRecord, SessionGraph, SessionRecord, TokenTotals } from "./records.js";
 import type { AvailableInstallation } from "./installation.js";
+export type { ContextUsage, Cursor, EventBody, EventRecord, EventView, FailureClass, ReasoningContent, RecordEnvelope, RecordKind, RequestBody, RequestDirection, RequestRecord, ResponseBody, ResponseRecord, SessionEdge, SessionGraph, SessionNode, SessionRecord, TokenTotals, TurnOutcome, UsageReport, } from "./records.js";
 /**
- * Session/Turn contract v1. Behavior invariants live as comments on the
- * member they constrain; each "must/never" has (or gets) a sea-trial case.
+ * Session contract: one ordered, resumable record stream.
+ *
+ * The external promise (docs/spec): everything the runtime said is in the
+ * stream, nothing oar didn't observe is in it, every record knows whose it
+ * is, and the stream is readable again from any position. Records split by
+ * OBLIGATION into three kinds, event (the runtime's own words), request (an
+ * action that expects an outcome) and response (points at a request), and
+ * travel on one channel with one monotonic `seq`. Behavior invariants live as
+ * comments on the member they constrain; each "must/never" has (or gets) a
+ * sea-trial case.
  *
  * Scope notes that fit no single member:
  * - Ownership is the object reference; no in-process lease. Multi-controller
  *   arbitration belongs to the application layer.
  * - Sessions run YOLO by default: adapters disable interactive permission
  *   gates (claude --dangerously-skip-permissions, codex approvalPolicy
- *   never, pi pre-trusted cwd) AND default sandboxes off (codex
- *   danger-full-access; claude/pi have none). In embedded use nobody sits
- *   at an approval prompt — a gate is a hang, not safety. A host wanting
- *   isolation opts in (OAR_CODEX_SANDBOX), and codex's exec follows the
- *   USER's config-level sandbox_mode on real logins, which OAR never
- *   overrides.
- * - v1 defers resume/persistence, interactive permission settlement, and any
- *   remote/multi-consumer model.
- * - pi emits session-scoped events (compaction_start/end, queue_update) that
- *   belong to no turn; representing those is a deliberate v2 decision
- *   (nullable turnId vs a second event scope). Until then adapters drop them.
+ *   never, pi pre-trusted cwd, ACP allow_always) AND default sandboxes off
+ *   (codex danger-full-access; claude/pi have none). In embedded use nobody
+ *   sits at an approval prompt: a gate is a hang, not safety. A host wanting
+ *   isolation opts in (OAR_CODEX_SANDBOX). Runtime→app requests that DO
+ *   arrive are recorded verbatim (direction "toApp") and oar's automatic
+ *   answer, when it gives one, is the matching response record.
+ * - The cursor is honored for the lifetime of the adapter process: a
+ *   subscriber reconnecting with `afterSeq` misses nothing and repeats
+ *   nothing. `SessionOptions.resume` reopens the runtime-native conversation
+ *   with a fresh stream starting at seq 0.
  */
 export interface SessionOptions {
     /** Working directory the runtime operates in. */
@@ -27,11 +36,11 @@ export interface SessionOptions {
     readonly model?: string;
     /** Resume the runtime-native session identified by a previous Session.id. */
     readonly resume?: string;
-    /** Extra environment overlaid on the host env for the processes THIS session spawns. Subprocess runtimes: the runtime process itself (tools inherit). In-process runtimes: only the agent's tool subprocesses — provider config needs the runtime's native channel there. CAVEAT for PATH-like entries: a runtime that runs tools through a login shell (codex: zsh/bash -lc) lets profile scripts reorder or rebuild PATH — probed: codex demotes injected entries on Linux and macOS path_helper/.zprofile can drop them. Injected CLIs should be invoked by ABSOLUTE path. */
+    /** Extra environment overlaid on the host env for the processes THIS session spawns. Subprocess runtimes: the runtime process itself (tools inherit). In-process runtimes: only the agent's tool subprocesses; provider config needs the runtime's native channel there. CAVEAT for PATH-like entries: a runtime that runs tools through a login shell (codex: zsh/bash -lc) lets profile scripts reorder or rebuild PATH (probed: codex demotes injected entries on Linux and macOS path_helper/.zprofile can drop them). Injected CLIs should be invoked by ABSOLUTE path. */
     readonly env?: Readonly<Record<string, string>>;
-    /** REPLACE the runtime's built-in system prompt (claude --system-prompt, codex thread baseInstructions, pi resource-loader systemPrompt). Survives runtime compaction — pinned per vendor. */
+    /** REPLACE the runtime's built-in system prompt (claude --system-prompt, codex thread baseInstructions, pi resource-loader systemPrompt). Survives runtime compaction (pinned per vendor). */
     readonly systemPrompt?: string;
-    /** APPEND to the runtime's built-in system prompt, keeping its harness behavior intact (claude --append-system-prompt, codex developerInstructions, pi appendSystemPrompt). Survives runtime compaction — pinned per vendor. */
+    /** APPEND to the runtime's built-in system prompt, keeping its harness behavior intact (claude --append-system-prompt, codex developerInstructions, pi appendSystemPrompt). Survives runtime compaction (pinned per vendor). */
     readonly appendSystemPrompt?: string;
 }
 /**
@@ -40,150 +49,80 @@ export interface SessionOptions {
  * runtime's message).
  */
 export type StartSession = (installation: AvailableInstallation, options: SessionOptions) => Promise<Session>;
+/** Both records a control call produced: the request (its `seq` is where the action sits in the stream) and the accept/reject response. */
+export interface ControlResult {
+    readonly request: RequestRecord;
+    readonly response: ResponseRecord;
+}
 /**
- * The SPI face: what an adapter actually builds. Today every member is also
- * public, so the API face extends this; if an SPI-internal member ever
- * appears, the extends breaks into an explicit mapping inside sealSession —
- * that seam is already the only place the two faces meet.
+ * Which tier of the attribution spectrum the adapter carries, declared
+ * explicitly and required to match what the runtime exposes (adapter red
+ * line, docs/spec/runtime-matrix.md): `none`: the runtime has no sub-agents;
+ * `opaque`: it has them but its selected interface shows only the root;
+ * `attributed`: child records self-attribute via `agentPath`; `nested`:
+ * children are sessions of their own, linked in the graph.
  */
-export interface AdapterSession {
-    readonly id: string;
-    prompt(input: string): PromptResult;
-    subscribe(observer: SessionObserver): Unsubscribe;
-    readonly queue?: TurnQueue;
-    model?(): string | null;
-    contextUsage?(): ContextUsage | null;
-    dispose(): Promise<void>;
+export type AttributionTier = "none" | "opaque" | "attributed" | "nested";
+export interface SessionCapabilities {
+    /** Mid-turn input can be injected into the active turn. */
+    readonly steer: boolean;
+    /** Input can be held for a LATER turn; `durable` says whether that survives a process restart (codex: runtime-persisted; claude/pi/ACP: this process only). Null when the runtime cannot even hold input. */
+    readonly queue: {
+        readonly durable: boolean;
+    } | null;
+    readonly attribution: AttributionTier;
 }
+export type SessionObserver = (record: SessionRecord) => void;
+export type Unsubscribe = () => void;
 /**
- * Current context fullness — borrowed from pi's shape because it already
- * models the hard case: `tokens` is null when unknown (right after compaction,
- * before the next model response), and `percent` follows. NOT a running sum of
- * usage deltas; the latest authoritative snapshot the runtime reported.
+ * The SPI face: what an adapter actually builds. The API face extends it
+ * with derivations sealSession computes over the stream.
  */
-export interface ContextUsage {
-    readonly tokens: number | null;
-    readonly contextWindow: number | null;
-    readonly percent: number | null;
+export interface AdapterSession {
+    readonly id: string;
+    readonly capabilities: SessionCapabilities;
+    prompt(input: string): Promise<ControlResult>;
+    steer(input: string): Promise<ControlResult>;
+    queue(input: string): Promise<ControlResult>;
+    abort(): Promise<ControlResult>;
+    subscribe(observer: SessionObserver, cursor?: Cursor): Unsubscribe;
+    records(): readonly SessionRecord[];
+    graph(): SessionGraph;
+    dispose(): Promise<void>;
 }
-/** The API face: the SPI plus surfaces sealSession derives. */
+/** The API face: the SPI plus surfaces sealSession derives from the stream. */
 export interface Session extends AdapterSession {
+    /** Latest `model` event; null until the runtime has said one. A fold, not an echo of the request. */
+    model(): string | null;
+    /** THIS session's token total plus a per-agent breakdown when children reported: deduplicated, directly summable (sum = total). A derived child session (own `sessionId`, in `graph()`) is not aggregated here; its usage is in its own records. */
+    usage(): SessionUsage;
+    /** Latest context fullness the runtime reported for this session's root agent; null before any. */
+    contextUsage(): ContextUsage | null;
     /**
-     * DERIVED, not adapter-implemented: steer when the runtime can, fall back to
-     * queueing, always report where the input landed. `rejected` means the input
-     * was NOT taken over and the caller still owns it.
+     * DERIVED: steer when the runtime can, fall back to queueing, always report
+     * where the input landed. `rejected` means the input was NOT taken over and
+     * the caller still owns it.
      */
-    steerOrQueue(turn: Turn, input: string): Promise<SteerOrQueueResult>;
+    steerOrQueue(input: string): Promise<SteerOrQueueResult>;
+}
+export interface SessionUsage {
+    /** Null until the runtime has reported token totals, never a guessed zero (kimi's ACP surface reports context only). */
+    readonly total: TokenTotals | null;
+    /** Present only when more than the root agent reported tokens. */
+    readonly byAgent?: readonly {
+        readonly agentPath: readonly string[];
+        readonly tokens: TokenTotals;
+    }[];
 }
 export type SteerOrQueueResult = {
     readonly landed: "steered";
+    readonly result: ControlResult;
 } | {
     readonly landed: "queued";
+    readonly result: ControlResult;
 } | {
     readonly landed: "rejected";
     readonly reason: string;
-};
-/**
- * Queue input to run as a future turn. `add` follows the same weak
- * delivery-obligation transfer as steer's accepted: the adapter (or runtime)
- * now owns not losing it; whether that survives a process restart is what
- * `durable` reports honestly (codex: runtime-persisted; claude/pi: held in
- * this process only).
- */
-export interface TurnQueue {
-    readonly durable: boolean;
-    add(input: string): Promise<void>;
-}
-export type PromptResult = {
-    readonly kind: "turn";
-    readonly turn: Turn;
-} | {
-    readonly kind: "busy";
-};
-export type SessionObserver = (event: SessionEvent) => void;
-export type Unsubscribe = () => void;
-export interface Turn {
-    readonly id: string;
-    readonly outcome: Promise<TurnOutcome>;
-    abort(): Promise<void>;
-    /**
-     * Mid-turn input; absent when the runtime cannot inject into an active turn.
-     * `accepted` is ONE deliberately weak promise, identical on every runtime:
-     * the adapter has taken over this input and the caller's delivery
-     * obligation ENDS — do not resubmit. Taking over means the adapter now owns
-     * not losing it (e.g. holding it through runtime-autonomous compaction);
-     * failure to take over is a typed not_steerable or a thrown operational
-     * error, never a silent drop. No guarantee it lands in the current turn,
-     * that the model attends to it, or that any business outcome happened. How
-     * acceptance happens (stdin write, native enqueue, a runtime-side steer
-     * ack) is adapter-internal and adapter-tested, never an application-facing
-     * difference. Input written during
-     * runtime-autonomous compaction is HELD, not lost; codex Compact/Review
-     * turns reject with not_steerable instead. Where input landed is the event
-     * stream's job: same turnId, or a fresh turn_started when a runtime
-     * auto-queues past a turn that just ended (that spontaneous turn has events
-     * but no control handle yet).
-     */
-    readonly steer?: (input: string) => Promise<SteerResult>;
-}
-/** Coarse failure classification so applications can react (re-login, back off, report a bug) without parsing vendor error prose. Best-effort: adapters map what the runtime reveals; "unknown" is an honest answer. */
-export type FailureClass = "auth" | "quota" | "invalid_request" | "overloaded" | "provider" | "runtime_exited" | "unknown";
-export type TurnOutcome = {
-    readonly kind: "completed";
-} | {
-    readonly kind: "aborted";
-} | {
-    readonly kind: "failed";
-    readonly reason: string;
-    readonly failure: FailureClass;
-};
-export type SteerResult = {
-    readonly kind: "accepted";
-} | {
-    readonly kind: "not_steerable";
-    readonly reason: string;
-};
-/** Envelope + minimal body; runtime-specific detail waits for real demand. */
-export type SessionEvent = SessionEventEnvelope & SessionEventBody;
-export interface SessionEventEnvelope {
-    readonly sessionId: string;
-    readonly turnId: string;
-    /** Monotonic per session; total order for trace alignment. */
-    readonly seq: number;
-    /** Unix epoch milliseconds stamped at adapter ingress — same clock as Date.now(), so fold×clock consumers (stallOf) compose directly. */
-    readonly receivedAt: number;
-}
-export type ReasoningContent = {
-    readonly kind: "text";
-    readonly text: string;
-} | {
-    readonly kind: "redacted";
-} | {
-    readonly kind: "empty";
-};
-export type SessionEventBody = {
-    readonly kind: "turn_started";
-} | {
-    readonly kind: "text_delta";
-    readonly text: string;
-}
-/** A reasoning output item; its lifecycle remains observable without readable contents. */
- | {
-    readonly kind: "reasoning";
-    readonly content: ReasoningContent;
-} | {
-    readonly kind: "tool_call_started";
-    readonly callId: string;
-    readonly tool: string;
-    /** Best-effort human-readable invocation detail when the runtime exposes it. */
-    readonly input?: string;
-} | {
-    readonly kind: "tool_call_ended";
-    readonly callId: string;
-    /** Best-effort human-readable result detail when the runtime exposes it. */
-    readonly output?: string;
-} | {
-    readonly kind: "turn_ended";
-    readonly outcome: TurnOutcome;
+    readonly result: ControlResult;
 };
 //# sourceMappingURL=session.d.ts.map

package/dist/contracts/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/contracts/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/contracts/session.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,12 +5,12 @@ export type { ProviderAuthFacade, ProviderAuthStatus, ProviderLoginEvent, Provid
 export type { CatalogModel, CatalogProvider, CatalogRefreshOptions, CatalogRefreshResult, ModelCatalogFacade, } from "./contracts/model-catalog.js";
 export type { ListModelsOptions, ListModelsResult, ModelEntry, ModelLister, } from "./contracts/list-models.js";
 export type { Runtime } from "./contracts/runtime.js";
-export type { AdapterSession, PromptResult, ReasoningContent, Session, SessionEvent, SessionEventBody, SessionEventEnvelope, SessionObserver, SessionOptions, StartSession, SteerOrQueueResult, SteerResult, Turn, TurnOutcome, TurnQueue, Unsubscribe, } from "./contracts/session.js";
+export type { AdapterSession, AttributionTier, ContextUsage, ControlResult, Cursor, EventBody, EventRecord, EventView, FailureClass, ReasoningContent, RecordEnvelope, RecordKind, RequestBody, RequestDirection, RequestRecord, ResponseBody, ResponseRecord, Session, SessionCapabilities, SessionEdge, SessionGraph, SessionNode, SessionObserver, SessionOptions, SessionRecord, SessionUsage, StartSession, SteerOrQueueResult, TokenTotals, TurnOutcome, Unsubscribe, UsageReport, } from "./contracts/session.js";
 export { defineRuntime } from "./contracts/runtime.js";
 export { utcInstantFromDate } from "./shared/instant.js";
 export { RuntimeRegistry, createRuntimeRegistry } from "./registry.js";
-export { VOYAGE_FORMAT, endLine, eventLine, headerLine, openVoyage, submissionLine, } from "./voyage.js";
-export type { SubmissionVia, VoyageHeader, VoyageRecorder } from "./voyage.js";
+export { VOYAGE_FORMAT, endLine, headerLine, openVoyage, recordLine, } from "./voyage.js";
+export type { VoyageHeader, VoyageRecorder } from "./voyage.js";
 export { aggregateDeltas } from "./observe/aggregate-events.js";
 export { initialStatus, reduceStatus, stallOf, } from "./observe/agent-status.js";
 export type { AgentStatus, RunningPhase } from "./observe/agent-status.js";
@@ -20,6 +20,9 @@ export { observeAgent, simpleStateOf } from "./observe/observe-agent.js";
 export { classifyTool, toolActionLabel } from "./observe/tool-activity.js";
 export type { ToolAction, ToolActionKind } from "./observe/tool-activity.js";
 export type { AgentObserver, AgentView, ObserveAgentOptions } from "./observe/observe-agent.js";
+export { awaitTurnEnd, promptAndWait, turnEndAfter } from "./observe/turns.js";
+export type { PromptRun } from "./observe/turns.js";
+export { contextUsageOf, modelOf, usageOf } from "./observe/usage.js";
 export { claudeRuntime } from "./runtimes/claude/index.js";
 export { claudeListModels, projectClaudeModels } from "./runtimes/claude/list-models.js";
 export { claudeSession } from "./runtimes/claude/session.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}