@graphorin/core 0.5.0 → 0.6.0

package/dist/types/memory.d.ts

@@ -6,7 +6,7 @@ import { Sensitivity } from "./sensitivity.js";
  * Kinds of memory record in the Graphorin model. The first six are the
  * storage tiers the {@link MemoryStore} contract exposes as 1:1
  * sub-namespaces; `insight` is the derived, reflection-synthesized
- * record kind (P1-1) — it has no base-tier namespace and is persisted
+ * record kind (P1-1) - it has no base-tier namespace and is persisted
  * through the optional insight surface adapters expose. Used as the
  * discriminator for span types and the `MemoryRecord` union.
  *
@@ -14,7 +14,7 @@ import { Sensitivity } from "./sensitivity.js";
  */
 type MemoryKind = 'working' | 'session' | 'episodic' | 'semantic' | 'procedural' | 'shared' | 'insight';
 /**
- * Where a memory came from — the trust-provenance tag carried by every
+ * Where a memory came from - the trust-provenance tag carried by every
  * fact / episode / induced procedure. `user` (the human said it) and
  * `tool` (a tool the agent invoked returned it) are first-party;
  * `extraction` (consolidator distilled it from a transcript),
@@ -23,7 +23,7 @@ type MemoryKind = 'working' | 'session' | 'episodic' | 'semantic' | 'procedural'
  * trajectory, P2-2) are *derived* and therefore land quarantined by
  * default; `imported` is bulk-loaded from an external store. Used by
  * P1-4 to gate action-driving recall against memory-poisoning (MINJA /
- * MemoryGraft) — induced procedures drive *actions*, so the quarantine
+ * MemoryGraft) - induced procedures drive *actions*, so the quarantine
  * gate matters most for them.
  *
  * @stable
@@ -38,6 +38,20 @@ type MemoryProvenance = 'user' | 'tool' | 'extraction' | 'reflection' | 'inducti
  * @stable
  */
 type MemoryStatus = 'active' | 'quarantined';
+/**
+ * Principal a memory belongs to (D3) - the *who-owns-this* dimension,
+ * orthogonal to {@link MemoryProvenance} (*where-it-came-from*):
+ * `user` for user-stated content, `agent` for the agent's own
+ * inferences (consolidator extraction / reflection / induction stamp
+ * this), `shared` for records deliberately published to a multi-agent
+ * shared tier. Absent (rows written before the feature, or writers
+ * that do not care) is treated as `user` at filter time; default
+ * reads apply **no owner filter**, so behaviour is unchanged until a
+ * caller opts into a retrieval-time scope filter.
+ *
+ * @stable
+ */
+type MemoryOwner = 'user' | 'agent' | 'shared';
 /**
  * Snapshot of memory-tier counters surfaced to the model via the
  * memory-aware system prompt. Implementations live in `@graphorin/memory`;
@@ -85,7 +99,7 @@ interface MemoryRecord {
   readonly tags?: ReadonlyArray<string>;
 }
 /**
- * Working-memory block — a labeled, char-bounded slot rendered into the
+ * Working-memory block - a labeled, char-bounded slot rendered into the
  * system prompt every turn.
  *
  * @stable
@@ -113,7 +127,7 @@ interface Fact extends MemoryRecord {
    * `subject`/`object` are the graph *entities* (resolved to canonical
    * ids in `fact_entities`); `predicate` is the relation label and is
    * not itself an entity. Absent on rows written before the feature, and
-   * on plain free-text facts — they are a soft enrichment that powers
+   * on plain free-text facts - they are a soft enrichment that powers
    * one-hop expansion ({@link MemorySearchOptions} has no field; the
    * memory tier's search opts in), never a recall gate.
    */
@@ -125,7 +139,7 @@ interface Fact extends MemoryRecord {
   readonly confidence?: number;
   /**
    * Optional salience hint in `[0, 1]` for multi-signal forgetting
-   * (X-1). A *soft* signal — higher importance slows a fact's decay and
+   * (X-1). A *soft* signal - higher importance slows a fact's decay and
    * delays capacity-bounded eviction, but never gates recall and never
    * forces retention. Absent on rows written before the feature
    * (treated as neutral, `0.5`).
@@ -150,9 +164,15 @@ interface Fact extends MemoryRecord {
    * default recall.
    */
   readonly status?: MemoryStatus;
+  /**
+   * Principal dimension (D3). `'agent'` on consolidator-synthesized
+   * facts; absent ⇒ treated as `'user'` at filter time. Never gates
+   * default recall - only an explicit owner search filter reads it.
+   */
+  readonly owner?: MemoryOwner;
 }
 /**
- * Episode — a summarized stretch of past activity.
+ * Episode - a summarized stretch of past activity.
  *
  * @stable
  */
@@ -169,9 +189,11 @@ interface Episode extends MemoryRecord {
   readonly provenance?: MemoryProvenance;
   /** Retrieval-trust state (P1-4). See {@link MemoryStatus}. */
   readonly status?: MemoryStatus;
+  /** Principal dimension (D3). See {@link MemoryOwner}. */
+  readonly owner?: MemoryOwner;
 }
 /**
- * Procedural rule — a standing order activated when its `condition` matches.
+ * Procedural rule - a standing order activated when its `condition` matches.
  *
  * @stable
  */
@@ -182,14 +204,14 @@ interface Rule extends MemoryRecord {
   readonly priority: number;
   /**
    * Ordered, value-abstracted step sequence of an *induced* workflow
-   * (P2-2) — e.g. `['search for {product}', 'add {quantity} to cart',
+   * (P2-2) - e.g. `['search for {product}', 'add {quantity} to cart',
    * 'check out']`. Present only on procedures distilled from successful
    * agent trajectories; author-defined rules omit it.
    */
   readonly steps?: ReadonlyArray<string>;
   /**
    * Names of the variables abstracted from the trajectory's concrete
-   * values (P2-2) — the `{product}` / `{quantity}` placeholders that
+   * values (P2-2) - the `{product}` / `{quantity}` placeholders that
    * appear in {@link Rule.steps}. Lets a reused procedure be re-bound to
    * fresh arguments instead of replaying one run's literals.
    */
@@ -221,17 +243,19 @@ interface Rule extends MemoryRecord {
    * Absent ⇒ never counted (adapters without the column).
    */
   readonly successCount?: number;
+  /** Principal dimension (D3). `'agent'` on induced procedures. See {@link MemoryOwner}. */
+  readonly owner?: MemoryOwner;
 }
 /**
- * Insight — a higher-order observation the consolidator's reflection
+ * Insight - a higher-order observation the consolidator's reflection
  * pass (P1-1) synthesizes over recent memories ("the user has cancelled
- * three evening plans this month — they may be overcommitted"). No
+ * three evening plans this month - they may be overcommitted"). No
  * single turn states it; it is *inferred*, so it is always
  * `provenance: 'reflection'` and lands `status: 'quarantined'` (P1-4),
  * excluded from action-driving recall until validated.
  *
- * Every insight carries **mandatory citations** (`cites`) — the ids of
- * the supporting memories it was synthesized from — so a reader can
+ * Every insight carries **mandatory citations** (`cites`) - the ids of
+ * the supporting memories it was synthesized from - so a reader can
  * trace it back to evidence; this is the "trustworthy reflection"
  * mitigation against confirmation-bias loops. Insights are managed with
  * an ExpeL-style salience counter (new insights start at `2`, pruned at
@@ -245,7 +269,7 @@ interface Insight extends MemoryRecord {
   readonly text: string;
   /**
    * IDs of the supporting memories (facts / episodes) this insight was
-   * synthesized from. Always ≥ 1 — citations are mandatory; an insight
+   * synthesized from. Always ≥ 1 - citations are mandatory; an insight
    * with no traceable evidence is never persisted.
    */
   readonly cites: ReadonlyArray<string>;
@@ -265,10 +289,12 @@ interface Insight extends MemoryRecord {
    * {@link MemoryStatus}.
    */
   readonly status?: MemoryStatus;
+  /** Principal dimension (D3). Reflection-synthesized insights are `'agent'`. */
+  readonly owner?: MemoryOwner;
 }
 /**
  * Role a {@link GraphEntity} plays in a {@link Fact}'s s/p/o triple
- * (P2-1) — the `subject` or the `object`. The `predicate` is a relation
+ * (P2-1) - the `subject` or the `object`. The `predicate` is a relation
  * label, not an entity, so it has no role here.
  *
  * @stable
@@ -277,13 +303,13 @@ type EntityRole = 'subject' | 'object';
 /**
  * Canonical entity in the lightweight in-SQLite relation graph (P2-1).
  * The entity resolver (`@graphorin/memory`) deduplicates the raw
- * `subject`/`object` strings on facts into canonical entities — merging
+ * `subject`/`object` strings on facts into canonical entities - merging
  * aliases ("Anna", "Anna S.", "my sister") via lexical + embedding
- * similarity (with optional LLM adjudication) — so multi-hop recall can
+ * similarity (with optional LLM adjudication) - so multi-hop recall can
  * traverse relationships instead of fragmenting them.
  *
  * Merges are **append-only and reversible**: a merged entity is never
- * deleted — its {@link GraphEntity.mergedInto} points at the surviving
+ * deleted - its {@link GraphEntity.mergedInto} points at the surviving
  * canonical entity, every merge / unmerge is recorded in an audit
  * ledger, and `mergedInto` is single-level (it always points directly at
  * a root), so `mergedInto ?? id` is the canonical id.
@@ -324,7 +350,7 @@ interface MemorySearchOptions {
   /**
    * Include quarantined memories in the result set (P1-4). Defaults to
    * `false`: action-driving recall never returns quarantined rows. Set
-   * `true` only for the validation / inspector path — never for
+   * `true` only for the validation / inspector path - never for
    * auto-recall fed back into the model.
    */
   readonly includeQuarantined?: boolean;
@@ -333,10 +359,27 @@ interface MemorySearchOptions {
    * Point-in-time ("as of") read. When set, only records whose
    * validity interval contains this instant are returned. For facts:
    * `(valid_from IS NULL OR valid_from <= asOf) AND (valid_to IS NULL OR valid_to > asOf)`;
-   * for episodes: `started_at <= asOf`. ISO-8601. Absent ⇒ current
-   * behaviour is unchanged (every live row is eligible).
+   * for episodes: `started_at <= asOf`. ISO-8601. Absent ⇒ fact reads
+   * evaluate validity at NOW (see {@link includeSuperseded}).
    */
   readonly asOf?: string;
+  /**
+   * Include superseded / validity-expired facts in the result set
+   * (memory-retrieval-01). Defaults to `false`: a default read behaves
+   * as `asOf = now`, so a fact whose `validTo` was closed (e.g. by
+   * `supersede`) never surfaces as current - exactly what the
+   * `fact_supersede` tool promises. Set `true` only for inspector /
+   * audit paths that need the full history. Ignored when an explicit
+   * {@link asOf} is supplied.
+   */
+  readonly includeSuperseded?: boolean;
+  /**
+   * Retrieval-time principal filter (D3). When set, only records whose
+   * owner is in the requested set match; rows written before the
+   * feature (owner absent) are treated as `'user'`. Absent ⇒ no owner
+   * filter - behaviour is unchanged.
+   */
+  readonly owner?: MemoryOwner | ReadonlyArray<MemoryOwner>;
 }
 /**
  * A single retrieval hit with similarity / relevance metadata.
@@ -350,5 +393,5 @@ interface MemoryHit<TRecord extends MemoryRecord = MemoryRecord> {
   readonly signals?: Readonly<Record<string, number>>;
 }
 //#endregion
-export { Block, EntityRole, Episode, Fact, GraphEntity, Insight, MemoryHit, MemoryKind, MemoryMetadata, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, Rule };
+export { Block, EntityRole, Episode, Fact, GraphEntity, Insight, MemoryHit, MemoryKind, MemoryMetadata, MemoryOwner, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, Rule };
 //# sourceMappingURL=memory.d.ts.map

package/dist/types/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","names":[],"sources":["../../src/types/memory.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;AAwBA;AAgBA;AAUA;AAuBA;;;;AAc+B,KAvFnB,UAAA,GAuFmB,SAAA,GAAA,SAAA,GAAA,UAAA,GAAA,UAAA,GAAA,YAAA,GAAA,QAAA,GAAA,SAAA;AAS/B;AAcA;;;;;AAsDA;;;;;AAoBA;;;;AA8BwB,KA9LZ,gBAAA,GA8LY,MAAA,GAAA,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA;;;;AAmCxB;;;;;AAA6C,KAjNjC,YAAA,GAiNiC,QAAA,GAAA,aAAA;AAmC7C;AAkBA;AAuBA;AA6BA;;;;;AAIqB,UApTJ,cAAA,CAoTI;EAAQ;;;;;;;;;;;;;kBAtSX;;;;;;;;UASD,YAAA;;iBAEA;;;;wBAIO;;;;;;;;kBAQN;;;;;;;;UASD,KAAA,SAAc;;;;;;;;;;;;;UAcd,IAAA,SAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCN;;;;;;oBAMJ;;;;;;;UAQH,OAAA,SAAgB;;;;;;;;;;wBAUT;;oBAEJ;;;;;;;UAQH,IAAA,SAAa;;;;;;;;;;;mBAWX;;;;;;;uBAOI;;;;;;6BAMM;;;;;;wBAML;;;;;;;oBAOJ;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BH,OAAA,SAAgB;;;;;;;;;kBASf;;;;;;;;;;;wBAWM;;;;;oBAKJ;;;;;;;;;KAUR,UAAA;;;;;;;;;;;;;;;;;UAkBK,WAAA;;;;;;;;;;;;;;;;;;;;;;UAuBA,mBAAA;;;kBAGC;;;;;;;;;;;;;oBAUE;;;;;;;;;;;;;;;UAgBH,0BAA0B,eAAe;mBACvC;;;qBAGE,SAAS"}
+{"version":3,"file":"memory.d.ts","names":[],"sources":["../../src/types/memory.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;AAwBA;AAgBA;AAeA;AAUA;AAuBA;;;AAckB,KAtGN,UAAA,GAsGM,SAAA,GAAA,SAAA,GAAA,UAAA,GAAA,UAAA,GAAA,YAAA,GAAA,QAAA,GAAA,SAAA;;AASlB;AAcA;;;;;;AA4DA;;;;;;AAsBA;AAWmB,KAlMP,gBAAA,GAkMO,MAAA,GAAA,MAAA,GAAA,YAAA,GAAA,YAAA,GAAA,WAAA,GAAA,UAAA;;;;;;;;AAwDnB;AASkB,KAnPN,YAAA,GAmPM,QAAA,GAAA,aAAA;;;;;;AA4BlB;AAkBA;AAuBA;;;;;;AAsC8C,KA/UlC,WAAA,GA+UkC,MAAA,GAAA,OAAA,GAAA,QAAA;AAQ9C;;;;;;;;UA7UiB,cAAA;;;;;;;;;;;;;;kBAcC;;;;;;;;UASD,YAAA;;iBAEA;;;;wBAIO;;;;;;;;kBAQN;;;;;;;;UASD,KAAA,SAAc;;;;;;;;;;;;;UAcd,IAAA,SAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCN;;;;;;oBAMJ;;;;;;mBAMD;;;;;;;UAQF,OAAA,SAAgB;;;;;;;;;;wBAUT;;oBAEJ;;mBAED;;;;;;;UAQF,IAAA,SAAa;;;;;;;;;;;mBAWX;;;;;;;uBAOI;;;;;;6BAMM;;;;;;wBAML;;;;;;;oBAOJ;;;;;;;;;;mBAUD;;;;;;;;;;;;;;;;;;;UAoBF,OAAA,SAAgB;;;;;;;;;kBASf;;;;;;;;;;;wBAWM;;;;;oBAKJ;;mBAED;;;;;;;;;KAUP,UAAA;;;;;;;;;;;;;;;;;UAkBK,WAAA;;;;;;;;;;;;;;;;;;;;;;UAuBA,mBAAA;;;kBAGC;;;;;;;;;;;;;oBAUE;;;;;;;;;;;;;;;;;;;;;;;;;mBAyBD,cAAc,cAAc;;;;;;;UAQ9B,0BAA0B,eAAe;mBACvC;;;qBAGE,SAAS"}

package/dist/types/message.d.ts

@@ -31,7 +31,7 @@ interface TextContent {
 }
 /**
  * Image attachment. The `image` field accepts either raw bytes or a `URL`
- * — adapters dereference the URL when the provider only accepts inline
+ * - adapters dereference the URL when the provider only accepts inline
  * payloads.
  *
  * @stable
@@ -45,7 +45,7 @@ interface ImageContent {
 }
 /**
  * Audio attachment (e.g. voice messages). Note: voice realtime / TTS / STT
- * are out of scope for v0.1 — these messages are static blobs.
+ * are out of scope for v0.1 - these messages are static blobs.
  *
  * @stable
  */

package/dist/types/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","names":[],"sources":["../../src/types/message.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;AAYA;AAmBiB,KA/BL,cAAA,GACR,WA8ByB,GA7BzB,YA6ByB,GA5BzB,YA4ByB,GA3BzB,WA2ByB,GA1BzB,gBA0ByB;;;;;AAc7B;AAEkB,UAnCD,WAAA,CAmCC;EAAa,SAAA,IAAA,EAAA,MAAA;EAGH,SAAA,IAAA,EAAA,MAAA;EAAa;AASzC;;;;;EAiBiB,SAAA,cAAgB,CAAA,EAvDL,aAsEV,CAAA,MAAA,CAAA;AAWlB;AAYA;AAcA;;;;;;AAGiB,UApGA,YAAA,CAoGa;EAMb,SAAA,IAAA,EAAW,OAAA;EAQX,SAAA,KAAA,EAhHC,UAgHe,GAhHF,GAkHO;EAUrB,SAAA,QAAW,CAAA,EAAA,MAGU;;4BA5HV;;;;;;;;UASX,YAAA;;kBAEC,aAAa;;;4BAGH;;;;;;;;UASX,WAAA;;iBAEA,aAAa;;;;4BAIF;;;;;;;;;;UAWX,gBAAA;;;;;;;;;;;;;;;kBAeC;;4BAEU;;;;;;;;UASX,oBAAA;;;;;;;;;;;KAYL,WAAA;;;;;;;;;;;;;KAcA,OAAA,GAAU,gBAAgB,cAAc,mBAAmB;;UAGtD,aAAA;;;;;UAMA,WAAA;;sCAEqB;;;;;UAMrB,gBAAA;;sCAEqB;gCACN;;;;;;;;UASf,WAAA;;;sCAGqB"}
+{"version":3,"file":"message.d.ts","names":[],"sources":["../../src/types/message.ts"],"sourcesContent":[],"mappings":";;;;;;AAYA;;;;;;;AAYA;AAmBiB,KA/BL,cAAA,GACR,WA8ByB,GA7BzB,YA6ByB,GA5BzB,YA4ByB,GA3BzB,WA2ByB,GA1BzB,gBA0ByB;;;;;AAc7B;AAEkB,UAnCD,WAAA,CAmCC;EAAa,SAAA,IAAA,EAAA,MAAA;EAGH,SAAA,IAAA,EAAA,MAAA;EAAa;AASzC;;;;;EAiBiB,SAAA,cAAgB,CAAA,EAvDL,aAsEV,CAAA,MAAA,CAAA;AAWlB;AAYA;AAcA;;;;;;AAGiB,UApGA,YAAA,CAoGa;EAMb,SAAA,IAAA,EAAW,OAAA;EAQX,SAAA,KAAA,EAhHC,UAgHe,GAhHF,GAkHO;EAUrB,SAAA,QAAW,CAAA,EAAA,MAAA;;4BAzHA;;;;;;;;UASX,YAAA;;kBAEC,aAAa;;;4BAGH;;;;;;;;UASX,WAAA;;iBAEA,aAAa;;;;4BAIF;;;;;;;;;;UAWX,gBAAA;;;;;;;;;;;;;;;kBAeC;;4BAEU;;;;;;;;UASX,oBAAA;;;;;;;;;;;KAYL,WAAA;;;;;;;;;;;;;KAcA,OAAA,GAAU,gBAAgB,cAAc,mBAAmB;;UAGtD,aAAA;;;;;UAMA,WAAA;;sCAEqB;;;;;UAMrB,gBAAA;;sCAEqB;gCACN;;;;;;;;UASf,WAAA;;;sCAGqB"}

package/dist/types/run.d.ts

@@ -1,7 +1,8 @@
+import { ToolCall } from "./tool-call.js";
 import { Message } from "./message.js";
+import { AISpan, Tracer } from "../contracts/tracer.js";
 import { ModelUsage, Usage, UsageAccumulator } from "./usage.js";
 import { HandoffRecord } from "./handoff.js";
-import { Tracer } from "../contracts/tracer.js";
 import { CompletedToolCall, ToolApproval } from "./tool.js";
 
 //#region src/types/run.d.ts
@@ -29,6 +30,26 @@ interface RunStep {
    * Stable agent id active for this step (changes after a handoff).
    */
   readonly agentId: string;
+  /**
+   * The model response this step produced, recorded when the agent runs
+   * with `recordProviderResponses: true` (C3). Enables deterministic
+   * replay: `createReplayProvider(state)` serves these back in order so
+   * a run re-executes without live model calls.
+   */
+  readonly providerResponse?: RunStepProviderResponse;
+}
+/**
+ * Journaled model response for one step (C3, opt-in via the agent's
+ * `recordProviderResponses`). Captures the RAW model output - the text
+ * before any lateral-leak block replaced it in the transcript - so a
+ * replay reproduces the original run faithfully.
+ *
+ * @stable
+ */
+interface RunStepProviderResponse {
+  readonly modelId: string;
+  readonly text?: string;
+  readonly toolCalls?: ReadonlyArray<ToolCall>;
 }
 /**
  * Per-model usage breakdown carried alongside the aggregate
@@ -82,7 +103,7 @@ interface RunState {
    * resumed run does not start with an empty ledger that silently un-gates
    * sinks exposed before the suspend. Structurally matches
    * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security
-   * dependency); only the load-bearing flags are persisted — never the tracked
+   * dependency); only the load-bearing flags are persisted - never the tracked
    * untrusted text spans.
    */
   taintSummary?: RunTaintSummary;
@@ -91,6 +112,13 @@ interface RunState {
    * across suspend/resume so discovered tools remain in the per-step catalogue.
    */
   promotedTools?: ReadonlyArray<string>;
+  /**
+   * D6 structured plan/todo list - the agent's own working plan,
+   * journaled so it survives suspend/resume (a TodoWrite-style tool
+   * mutates it, and attention-recitation renders it back into the
+   * prompt each turn). Absent until the agent writes one.
+   */
+  todos?: ReadonlyArray<TodoItem>;
   readonly startedAt: string;
   finishedAt?: string;
   error?: RunError;
@@ -106,11 +134,30 @@ interface RunTaintSummary {
   readonly untrustedSeen: boolean;
   readonly sensitiveSeen: boolean;
   readonly untrustedSourceKinds: ReadonlyArray<string>;
+  /**
+   * C6: one-way FNV-1a hashes of normalized untrusted-span tiles. Re-arms
+   * the verbatim-carry probe after a resume at tile granularity. Hashes
+   * only - no untrusted text is ever persisted (the invariant above
+   * holds).
+   */
+  readonly spanTileHashes?: ReadonlyArray<string>;
+}
+/**
+ * One item in the agent's structured plan (D6). `status` drives both
+ * the recitation rendering and progress reporting; `id` lets a
+ * status-flip mutation target an item without rewriting the list.
+ *
+ * @stable
+ */
+interface TodoItem {
+  readonly id: string;
+  readonly content: string;
+  readonly status: 'pending' | 'in_progress' | 'completed';
 }
 /**
  * Snapshot helper used by `@graphorin/observability` aggregators to
  * convert the on-disk `usageByModel` shape into the canonical
- * {@link ModelUsage} array. Pure utility — kept in core so consumers
+ * {@link ModelUsage} array. Pure utility - kept in core so consumers
  * do not have to take an observability dependency just to flatten a
  * run-state breakdown.
  *
@@ -149,7 +196,13 @@ interface RunContext<TDeps = unknown> {
   readonly stepNumber: number;
   readonly messages: ReadonlyArray<Message>;
   readonly state: RunState;
+  /**
+   * C7: the current `agent.step` span (when the runtime traces). Spans
+   * created inside tool execution parent under it so a run's traces
+   * form one tree.
+   */
+  readonly span?: AISpan;
 }
 //#endregion
-export { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunTaintSummary, flattenUsageByModel };
+export { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunStepProviderResponse, RunTaintSummary, TodoItem, flattenUsageByModel };
 //# sourceMappingURL=run.d.ts.map

package/dist/types/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","names":[],"sources":["../../src/types/run.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAYA;AAQA;AAwBA;AAcA;AAMU,KApDE,SAAA,GAoDF,SAAA,GAAA,WAAA,GAAA,QAAA,GAAA,SAAA,GAAA,mBAAA;;;;;;;AAsBO,UAlEA,OAAA,CAkEA;EAKC,SAAA,UAAA,EAAA,MAAA;EAGR,SAAA,SAAA,EAAA,MAAA;EAAQ,SAAA,OAAA,CAAA,EAAA,MAAA;EAUD,SAAA,KAAA,CAAA,EAhFE,KAgFa;EAehB,SAAA,SAAA,EAAA,SA9Fe,iBA8FI,EAAA;EACxB;;;EACK,SAAA,OAAA,EAAA,MAAA;AAwBhB;AAeA;;;;;;;;;;;;UApHiB,oBAAA;8BACa;;;;;;;;;;;;;;UAab,QAAA;;;;;;UAMP;kBACQ;qBACG;6BACQ;qBACR;kBACH;;;;;;;;iBAQD;;;;;;;;;iBASA;;;;;kBAKC;;;UAGR;;;;;;;;;UAUO,eAAA;;;iCAGgB;;;;;;;;;;;iBAYjB,mBAAA,UACL,mCACR,cAAc;;;;;;;UAwBA,QAAA;;;;;;;;;;;;;;UAeA;;;;;iBAKA;mBACE;mBACA;kBACD;;qBAEG,cAAc;kBACjB"}
+{"version":3,"file":"run.d.ts","names":[],"sources":["../../src/types/run.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAaA;AAQA;;;AAgB8B,KAxBlB,SAAA,GAwBkB,SAAA,GAAA,WAAA,GAAA,QAAA,GAAA,SAAA,GAAA,mBAAA;;AAW9B;AAkBA;AAcA;;;AAQqB,UAnEJ,OAAA,CAmEI;EACQ,SAAA,UAAA,EAAA,MAAA;EACR,SAAA,SAAA,EAAA,MAAA;EACH,SAAA,OAAA,CAAA,EAAA,MAAA;EAQD,SAAA,KAAA,CAAA,EA1EE,KA0EF;EASA,SAAA,SAAA,EAAA,SAlFc,iBAkFd,EAAA;EAKC;;;EAUR,SAAA,OAAA,EAAA,MAAA;EAAQ;AAUlB;AAoBA;AAeA;;;EAEG,SAAA,gBAAA,CAAA,EArI2B,uBAqI3B;;AAwBH;AAeA;;;;;;;AAWkB,UA5KD,uBAAA,CA4KC;EAAQ,SAAA,OAAA,EAAA,MAAA;EAM+B,SAAA,IAAA,CAAA,EAAA,MAAA;uBA/KlC,cAAc;;;;;;;;;;;;;;UAepB,oBAAA;8BACa;;;;;;;;;;;;;;UAab,QAAA;;;;;;UAMP;kBACQ;qBACG;6BACQ;qBACR;kBACH;;;;;;;;iBAQD;;;;;;;;;iBASA;;;;;kBAKC;;;;;;;UAOR,cAAc;;;UAGd;;;;;;;;;UAUO,eAAA;;;iCAGgB;;;;;;;4BAOL;;;;;;;;;UAUX,QAAA;;;;;;;;;;;;;;iBAeD,mBAAA,UACL,mCACR,cAAc;;;;;;;UAwBA,QAAA;;;;;;;;;;;;;;UAeA;;;;;iBAKA;mBACE;mBACA;kBACD;;qBAEG,cAAc;kBACjB;;;;;;kBAAQ"}

package/dist/types/run.js

@@ -2,7 +2,7 @@
 /**
 * Snapshot helper used by `@graphorin/observability` aggregators to
 * convert the on-disk `usageByModel` shape into the canonical
-* {@link ModelUsage} array. Pure utility — kept in core so consumers
+* {@link ModelUsage} array. Pure utility - kept in core so consumers
 * do not have to take an observability dependency just to flatten a
 * run-state breakdown.
 *

package/dist/types/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","names":["out: ModelUsage[]","m: ModelUsage"],"sources":["../../src/types/run.ts"],"sourcesContent":["import type { Tracer } from '../contracts/tracer.js';\nimport type { HandoffRecord } from './handoff.js';\nimport type { Message } from './message.js';\nimport type { CompletedToolCall, ToolApproval } from './tool.js';\nimport type { ModelUsage, Usage, UsageAccumulator } from './usage.js';\n\n/**\n * Status of an in-flight or completed agent run. Append-only persistence\n * stores expose this verbatim on the `runs` table.\n *\n * @stable\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';\n\n/**\n * Single step inside an agent run. The agent runtime appends one\n * `RunStep` per provider call.\n *\n * @stable\n */\nexport interface RunStep {\n  readonly stepNumber: number;\n  readonly startedAt: string;\n  readonly endedAt?: string;\n  readonly usage?: Usage;\n  readonly toolCalls: readonly CompletedToolCall[];\n  /**\n   * Stable agent id active for this step (changes after a handoff).\n   */\n  readonly agentId: string;\n}\n\n/**\n * Per-model usage breakdown carried alongside the aggregate\n * {@link Usage} on {@link RunState}. Populated by the per-step retry\n * loop when `Agent.fallbackModels` fires; for runs that never fall\n * back, the map carries a single entry for the primary model with\n * `attemptCount: 1`.\n *\n * The aggregate `RunState.usage` is always the sum of every entry's\n * `Usage` portion (the field is asserted in tests).\n *\n * @stable\n */\nexport interface RunStateUsageByModel {\n  readonly [modelId: string]: Usage & { readonly attemptCount: number };\n}\n\n/**\n * The full, serializable state of a run. The agent runtime persists this\n * to the checkpoint store on every `awaiting_approval` boundary, so a\n * separate process can resume the run.\n *\n * The shape is intentionally JSON-stable: every nested type is plain\n * `JSON`-encodable (no `Map`, no `Set`, no `Date`).\n *\n * @stable\n */\nexport interface RunState {\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  status: RunStatus;\n  readonly steps: RunStep[];\n  readonly messages: Message[];\n  readonly pendingApprovals: ToolApproval[];\n  readonly handoffs: HandoffRecord[];\n  readonly usage: Usage;\n  /**\n   * Per-model usage breakdown. Populated by the per-step retry loop\n   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /\n   * suggested ADR-052). Backward-compat: rehydrating a serialized\n   * state that omits the field synthesizes a single-entry map for\n   * the primary model.\n   */\n  usageByModel?: RunStateUsageByModel;\n  /**\n   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a\n   * resumed run does not start with an empty ledger that silently un-gates\n   * sinks exposed before the suspend. Structurally matches\n   * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security\n   * dependency); only the load-bearing flags are persisted — never the tracked\n   * untrusted text spans.\n   */\n  taintSummary?: RunTaintSummary;\n  /**\n   * AG-19: names of deferred tools promoted by `tool_search` this run, carried\n   * across suspend/resume so discovered tools remain in the per-step catalogue.\n   */\n  promotedTools?: ReadonlyArray<string>;\n  readonly startedAt: string;\n  finishedAt?: string;\n  error?: RunError;\n}\n\n/**\n * Coarse, serializable data-flow taint summary persisted in {@link RunState}\n * across suspend/resume (AG-19). Structurally identical to\n * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.\n *\n * @stable\n */\nexport interface RunTaintSummary {\n  readonly untrustedSeen: boolean;\n  readonly sensitiveSeen: boolean;\n  readonly untrustedSourceKinds: ReadonlyArray<string>;\n}\n\n/**\n * Snapshot helper used by `@graphorin/observability` aggregators to\n * convert the on-disk `usageByModel` shape into the canonical\n * {@link ModelUsage} array. Pure utility — kept in core so consumers\n * do not have to take an observability dependency just to flatten a\n * run-state breakdown.\n *\n * @stable\n */\nexport function flattenUsageByModel(\n  byModel: RunStateUsageByModel | undefined,\n): ReadonlyArray<ModelUsage> {\n  if (byModel === undefined) return [];\n  const out: ModelUsage[] = [];\n  for (const [modelId, entry] of Object.entries(byModel)) {\n    const m: ModelUsage = {\n      modelId,\n      promptTokens: entry.promptTokens,\n      completionTokens: entry.completionTokens,\n      totalTokens: entry.totalTokens,\n      callCount: entry.attemptCount,\n      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),\n      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),\n    };\n    out.push(m);\n  }\n  return out;\n}\n\n/**\n * Failure carried by `RunState.error`. The shape mirrors the wire format\n * used by `agent.error` events.\n *\n * @stable\n */\nexport interface RunError {\n  readonly message: string;\n  readonly code: string;\n  readonly details?: unknown;\n}\n\n/**\n * Per-run dependency / context bag handed to every tool, hook and\n * provider middleware in scope. Generic over the user-defined deps shape.\n *\n * `tracer`, `signal`, `usage` and `state` are always present; everything\n * else is optional.\n *\n * @stable\n */\nexport interface RunContext<TDeps = unknown> {\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly agentId: string;\n  readonly deps: TDeps;\n  readonly tracer: Tracer;\n  readonly signal: AbortSignal;\n  readonly usage: UsageAccumulator;\n  readonly stepNumber: number;\n  readonly messages: ReadonlyArray<Message>;\n  readonly state: RunState;\n}\n"],"mappings":";;;;;;;;;;AAuHA,SAAgB,oBACd,SAC2B;AAC3B,KAAI,YAAY,OAAW,QAAO,EAAE;CACpC,MAAMA,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,QAAQ,EAAE;EACtD,MAAMC,IAAgB;GACpB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW,MAAM;GACjB,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD;AACD,MAAI,KAAK,EAAE;;AAEb,QAAO"}
+{"version":3,"file":"run.js","names":["out: ModelUsage[]","m: ModelUsage"],"sources":["../../src/types/run.ts"],"sourcesContent":["import type { Tracer } from '../contracts/tracer.js';\nimport type { HandoffRecord } from './handoff.js';\nimport type { Message } from './message.js';\nimport type { CompletedToolCall, ToolApproval } from './tool.js';\nimport type { ToolCall } from './tool-call.js';\nimport type { ModelUsage, Usage, UsageAccumulator } from './usage.js';\n\n/**\n * Status of an in-flight or completed agent run. Append-only persistence\n * stores expose this verbatim on the `runs` table.\n *\n * @stable\n */\nexport type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';\n\n/**\n * Single step inside an agent run. The agent runtime appends one\n * `RunStep` per provider call.\n *\n * @stable\n */\nexport interface RunStep {\n  readonly stepNumber: number;\n  readonly startedAt: string;\n  readonly endedAt?: string;\n  readonly usage?: Usage;\n  readonly toolCalls: readonly CompletedToolCall[];\n  /**\n   * Stable agent id active for this step (changes after a handoff).\n   */\n  readonly agentId: string;\n  /**\n   * The model response this step produced, recorded when the agent runs\n   * with `recordProviderResponses: true` (C3). Enables deterministic\n   * replay: `createReplayProvider(state)` serves these back in order so\n   * a run re-executes without live model calls.\n   */\n  readonly providerResponse?: RunStepProviderResponse;\n}\n\n/**\n * Journaled model response for one step (C3, opt-in via the agent's\n * `recordProviderResponses`). Captures the RAW model output - the text\n * before any lateral-leak block replaced it in the transcript - so a\n * replay reproduces the original run faithfully.\n *\n * @stable\n */\nexport interface RunStepProviderResponse {\n  readonly modelId: string;\n  readonly text?: string;\n  readonly toolCalls?: ReadonlyArray<ToolCall>;\n}\n\n/**\n * Per-model usage breakdown carried alongside the aggregate\n * {@link Usage} on {@link RunState}. Populated by the per-step retry\n * loop when `Agent.fallbackModels` fires; for runs that never fall\n * back, the map carries a single entry for the primary model with\n * `attemptCount: 1`.\n *\n * The aggregate `RunState.usage` is always the sum of every entry's\n * `Usage` portion (the field is asserted in tests).\n *\n * @stable\n */\nexport interface RunStateUsageByModel {\n  readonly [modelId: string]: Usage & { readonly attemptCount: number };\n}\n\n/**\n * The full, serializable state of a run. The agent runtime persists this\n * to the checkpoint store on every `awaiting_approval` boundary, so a\n * separate process can resume the run.\n *\n * The shape is intentionally JSON-stable: every nested type is plain\n * `JSON`-encodable (no `Map`, no `Set`, no `Date`).\n *\n * @stable\n */\nexport interface RunState {\n  readonly id: string;\n  readonly agentId: string;\n  readonly currentAgentId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  status: RunStatus;\n  readonly steps: RunStep[];\n  readonly messages: Message[];\n  readonly pendingApprovals: ToolApproval[];\n  readonly handoffs: HandoffRecord[];\n  readonly usage: Usage;\n  /**\n   * Per-model usage breakdown. Populated by the per-step retry loop\n   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /\n   * suggested ADR-052). Backward-compat: rehydrating a serialized\n   * state that omits the field synthesizes a single-entry map for\n   * the primary model.\n   */\n  usageByModel?: RunStateUsageByModel;\n  /**\n   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a\n   * resumed run does not start with an empty ledger that silently un-gates\n   * sinks exposed before the suspend. Structurally matches\n   * `@graphorin/security`'s `TaintLedgerSnapshot` (core takes no security\n   * dependency); only the load-bearing flags are persisted - never the tracked\n   * untrusted text spans.\n   */\n  taintSummary?: RunTaintSummary;\n  /**\n   * AG-19: names of deferred tools promoted by `tool_search` this run, carried\n   * across suspend/resume so discovered tools remain in the per-step catalogue.\n   */\n  promotedTools?: ReadonlyArray<string>;\n  /**\n   * D6 structured plan/todo list - the agent's own working plan,\n   * journaled so it survives suspend/resume (a TodoWrite-style tool\n   * mutates it, and attention-recitation renders it back into the\n   * prompt each turn). Absent until the agent writes one.\n   */\n  todos?: ReadonlyArray<TodoItem>;\n  readonly startedAt: string;\n  finishedAt?: string;\n  error?: RunError;\n}\n\n/**\n * Coarse, serializable data-flow taint summary persisted in {@link RunState}\n * across suspend/resume (AG-19). Structurally identical to\n * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.\n *\n * @stable\n */\nexport interface RunTaintSummary {\n  readonly untrustedSeen: boolean;\n  readonly sensitiveSeen: boolean;\n  readonly untrustedSourceKinds: ReadonlyArray<string>;\n  /**\n   * C6: one-way FNV-1a hashes of normalized untrusted-span tiles. Re-arms\n   * the verbatim-carry probe after a resume at tile granularity. Hashes\n   * only - no untrusted text is ever persisted (the invariant above\n   * holds).\n   */\n  readonly spanTileHashes?: ReadonlyArray<string>;\n}\n\n/**\n * One item in the agent's structured plan (D6). `status` drives both\n * the recitation rendering and progress reporting; `id` lets a\n * status-flip mutation target an item without rewriting the list.\n *\n * @stable\n */\nexport interface TodoItem {\n  readonly id: string;\n  readonly content: string;\n  readonly status: 'pending' | 'in_progress' | 'completed';\n}\n\n/**\n * Snapshot helper used by `@graphorin/observability` aggregators to\n * convert the on-disk `usageByModel` shape into the canonical\n * {@link ModelUsage} array. Pure utility - kept in core so consumers\n * do not have to take an observability dependency just to flatten a\n * run-state breakdown.\n *\n * @stable\n */\nexport function flattenUsageByModel(\n  byModel: RunStateUsageByModel | undefined,\n): ReadonlyArray<ModelUsage> {\n  if (byModel === undefined) return [];\n  const out: ModelUsage[] = [];\n  for (const [modelId, entry] of Object.entries(byModel)) {\n    const m: ModelUsage = {\n      modelId,\n      promptTokens: entry.promptTokens,\n      completionTokens: entry.completionTokens,\n      totalTokens: entry.totalTokens,\n      callCount: entry.attemptCount,\n      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),\n      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),\n    };\n    out.push(m);\n  }\n  return out;\n}\n\n/**\n * Failure carried by `RunState.error`. The shape mirrors the wire format\n * used by `agent.error` events.\n *\n * @stable\n */\nexport interface RunError {\n  readonly message: string;\n  readonly code: string;\n  readonly details?: unknown;\n}\n\n/**\n * Per-run dependency / context bag handed to every tool, hook and\n * provider middleware in scope. Generic over the user-defined deps shape.\n *\n * `tracer`, `signal`, `usage` and `state` are always present; everything\n * else is optional.\n *\n * @stable\n */\nexport interface RunContext<TDeps = unknown> {\n  readonly runId: string;\n  readonly sessionId: string;\n  readonly userId?: string;\n  readonly agentId: string;\n  readonly deps: TDeps;\n  readonly tracer: Tracer;\n  readonly signal: AbortSignal;\n  readonly usage: UsageAccumulator;\n  readonly stepNumber: number;\n  readonly messages: ReadonlyArray<Message>;\n  readonly state: RunState;\n  /**\n   * C7: the current `agent.step` span (when the runtime traces). Spans\n   * created inside tool execution parent under it so a run's traces\n   * form one tree.\n   */\n  readonly span?: import('../contracts/tracer.js').AISpan;\n}\n"],"mappings":";;;;;;;;;;AAwKA,SAAgB,oBACd,SAC2B;AAC3B,KAAI,YAAY,OAAW,QAAO,EAAE;CACpC,MAAMA,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,QAAQ,EAAE;EACtD,MAAMC,IAAgB;GACpB;GACA,cAAc,MAAM;GACpB,kBAAkB,MAAM;GACxB,aAAa,MAAM;GACnB,WAAW,MAAM;GACjB,GAAI,MAAM,oBAAoB,SAAY,EAAE,iBAAiB,MAAM,iBAAiB,GAAG,EAAE;GACzF,GAAI,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,MAAM,GAAG,EAAE;GACzD;AACD,MAAI,KAAK,EAAE;;AAEb,QAAO"}

package/dist/types/sensitivity.d.ts

@@ -2,11 +2,11 @@
 /**
  * Sensitivity tier for any piece of data flowing through Graphorin.
  *
- * - `'public'`   — non-sensitive content; safe for any provider, any sink.
- * - `'internal'` — default for user-generated content; safe for trusted
+ * - `'public'`   - non-sensitive content; safe for any provider, any sink.
+ * - `'internal'` - default for user-generated content; safe for trusted
  *   providers (loopback / private-network) but redacted for public-tls
  *   exporters and replay consumers.
- * - `'secret'`   — credentials, tokens, encryption keys; only ever stays
+ * - `'secret'`   - credentials, tokens, encryption keys; only ever stays
  *   in-process and is never serialized to the wire by default.
  *
  * @stable

package/dist/types/sensitivity.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensitivity.js","names":["SENSITIVITY_ORDER: readonly Sensitivity[]"],"sources":["../../src/types/sensitivity.ts"],"sourcesContent":["/**\n * Sensitivity tier for any piece of data flowing through Graphorin.\n *\n * - `'public'`   — non-sensitive content; safe for any provider, any sink.\n * - `'internal'` — default for user-generated content; safe for trusted\n *   providers (loopback / private-network) but redacted for public-tls\n *   exporters and replay consumers.\n * - `'secret'`   — credentials, tokens, encryption keys; only ever stays\n *   in-process and is never serialized to the wire by default.\n *\n * @stable\n */\nexport type Sensitivity = 'public' | 'internal' | 'secret';\n\n/**\n * Strict ordering used by sensitivity-aware filters\n * (`record.sensitivity ⊆ provider.acceptsSensitivity`).\n *\n * @stable\n */\nexport const SENSITIVITY_ORDER: readonly Sensitivity[] = ['public', 'internal', 'secret'] as const;\n\n/**\n * Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.\n *\n * Comparison is **subset** semantics: the record's tier must be one of the\n * tiers in `accepts` (it's not enough for the record's tier to be lower).\n * That mirrors the way provider `acceptsSensitivity` is declared in the\n * Graphorin trust matrix.\n *\n * @stable\n */\nexport function acceptsSensitivity(accepts: readonly Sensitivity[], record: Sensitivity): boolean {\n  return accepts.includes(record);\n}\n"],"mappings":";;;;;;;AAoBA,MAAaA,oBAA4C;CAAC;CAAU;CAAY;CAAS;;;;;;;;;;;AAYzF,SAAgB,mBAAmB,SAAiC,QAA8B;AAChG,QAAO,QAAQ,SAAS,OAAO"}
+{"version":3,"file":"sensitivity.js","names":["SENSITIVITY_ORDER: readonly Sensitivity[]"],"sources":["../../src/types/sensitivity.ts"],"sourcesContent":["/**\n * Sensitivity tier for any piece of data flowing through Graphorin.\n *\n * - `'public'`   - non-sensitive content; safe for any provider, any sink.\n * - `'internal'` - default for user-generated content; safe for trusted\n *   providers (loopback / private-network) but redacted for public-tls\n *   exporters and replay consumers.\n * - `'secret'`   - credentials, tokens, encryption keys; only ever stays\n *   in-process and is never serialized to the wire by default.\n *\n * @stable\n */\nexport type Sensitivity = 'public' | 'internal' | 'secret';\n\n/**\n * Strict ordering used by sensitivity-aware filters\n * (`record.sensitivity ⊆ provider.acceptsSensitivity`).\n *\n * @stable\n */\nexport const SENSITIVITY_ORDER: readonly Sensitivity[] = ['public', 'internal', 'secret'] as const;\n\n/**\n * Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.\n *\n * Comparison is **subset** semantics: the record's tier must be one of the\n * tiers in `accepts` (it's not enough for the record's tier to be lower).\n * That mirrors the way provider `acceptsSensitivity` is declared in the\n * Graphorin trust matrix.\n *\n * @stable\n */\nexport function acceptsSensitivity(accepts: readonly Sensitivity[], record: Sensitivity): boolean {\n  return accepts.includes(record);\n}\n"],"mappings":";;;;;;;AAoBA,MAAaA,oBAA4C;CAAC;CAAU;CAAY;CAAS;;;;;;;;;;;AAYzF,SAAgB,mBAAmB,SAAiC,QAA8B;AAChG,QAAO,QAAQ,SAAS,OAAO"}

package/dist/types/stop-condition.d.ts

@@ -6,7 +6,7 @@ import { RunState } from "./run.js";
  * Predicate consulted by the agent runtime after every step to decide
  * whether the loop should stop.
  *
- * Stop conditions are pure — they look at the current `RunState` and
+ * Stop conditions are pure - they look at the current `RunState` and
  * return a boolean. The runtime never re-orders or short-circuits the
  * order in which operands of `and` / `or` are evaluated, so users can
  * rely on the obvious left-to-right semantics.

package/dist/types/stop-condition.js.map

@@ -1 +1 @@
-{"version":3,"file":"stop-condition.js","names":["isTerminal: StopCondition"],"sources":["../../src/types/stop-condition.ts"],"sourcesContent":["import type { RunState } from './run.js';\n\n/**\n * Predicate consulted by the agent runtime after every step to decide\n * whether the loop should stop.\n *\n * Stop conditions are pure — they look at the current `RunState` and\n * return a boolean. The runtime never re-orders or short-circuits the\n * order in which operands of `and` / `or` are evaluated, so users can\n * rely on the obvious left-to-right semantics.\n *\n * @stable\n */\nexport interface StopCondition {\n  /** Human-friendly label included in observability spans. */\n  readonly description: string;\n  /** Returns `true` when the run should stop on this state. */\n  readonly check: (state: RunState) => boolean;\n}\n\n/**\n * Stop after `n` total steps (`stepNumber >= n`). The default condition\n * for the agent runtime is `isStepCount(50)`.\n *\n * @stable\n */\nexport function isStepCount(n: number): StopCondition {\n  if (!Number.isFinite(n) || n <= 0) {\n    throw new RangeError(`isStepCount: n must be a positive integer (got ${String(n)})`);\n  }\n  return {\n    description: `step >= ${n}`,\n    check: (state): boolean => state.steps.length >= n,\n  };\n}\n\n/**\n * Stop as soon as the most recent assistant message contains a tool call\n * with the given name.\n *\n * @stable\n */\nexport function hasToolCall(toolName: string): StopCondition {\n  return {\n    description: `tool-call:${toolName}`,\n    check: (state): boolean => {\n      for (let i = state.messages.length - 1; i >= 0; i--) {\n        const msg = state.messages[i];\n        if (msg && msg.role === 'assistant') {\n          const calls = msg.toolCalls;\n          if (calls?.some((c) => c.toolName === toolName)) {\n            return true;\n          }\n          // First assistant message without the call → not yet matched.\n          return false;\n        }\n      }\n      return false;\n    },\n  };\n}\n\n/**\n * Stop when the run reaches a terminal status.\n *\n * @stable\n */\nexport const isTerminal: StopCondition = {\n  description: 'status:terminal',\n  check: (state): boolean =>\n    state.status === 'completed' || state.status === 'failed' || state.status === 'aborted',\n};\n\n/**\n * Stop when **any** of the supplied conditions is satisfied.\n *\n * @stable\n */\nexport function or(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `or(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.some((c) => c.check(state)),\n  };\n}\n\n/**\n * Stop only when **all** of the supplied conditions are satisfied.\n *\n * @stable\n */\nexport function and(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `and(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.every((c) => c.check(state)),\n  };\n}\n\n/**\n * Negate the supplied condition.\n *\n * @stable\n */\nexport function not(condition: StopCondition): StopCondition {\n  return {\n    description: `not(${condition.description})`,\n    check: (state): boolean => !condition.check(state),\n  };\n}\n"],"mappings":";;;;;;;AA0BA,SAAgB,YAAY,GAA0B;AACpD,KAAI,CAAC,OAAO,SAAS,EAAE,IAAI,KAAK,EAC9B,OAAM,IAAI,WAAW,kDAAkD,OAAO,EAAE,CAAC,GAAG;AAEtF,QAAO;EACL,aAAa,WAAW;EACxB,QAAQ,UAAmB,MAAM,MAAM,UAAU;EAClD;;;;;;;;AASH,SAAgB,YAAY,UAAiC;AAC3D,QAAO;EACL,aAAa,aAAa;EAC1B,QAAQ,UAAmB;AACzB,QAAK,IAAI,IAAI,MAAM,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK;IACnD,MAAM,MAAM,MAAM,SAAS;AAC3B,QAAI,OAAO,IAAI,SAAS,aAAa;AAEnC,SADc,IAAI,WACP,MAAM,MAAM,EAAE,aAAa,SAAS,CAC7C,QAAO;AAGT,YAAO;;;AAGX,UAAO;;EAEV;;;;;;;AAQH,MAAaA,aAA4B;CACvC,aAAa;CACb,QAAQ,UACN,MAAM,WAAW,eAAe,MAAM,WAAW,YAAY,MAAM,WAAW;CACjF;;;;;;AAOD,SAAgB,GAAG,GAAG,YAAqD;AACzE,QAAO;EACL,aAAa,MAAM,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACnE,QAAQ,UAAmB,WAAW,MAAM,MAAM,EAAE,MAAM,MAAM,CAAC;EAClE;;;;;;;AAQH,SAAgB,IAAI,GAAG,YAAqD;AAC1E,QAAO;EACL,aAAa,OAAO,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACpE,QAAQ,UAAmB,WAAW,OAAO,MAAM,EAAE,MAAM,MAAM,CAAC;EACnE;;;;;;;AAQH,SAAgB,IAAI,WAAyC;AAC3D,QAAO;EACL,aAAa,OAAO,UAAU,YAAY;EAC1C,QAAQ,UAAmB,CAAC,UAAU,MAAM,MAAM;EACnD"}
+{"version":3,"file":"stop-condition.js","names":["isTerminal: StopCondition"],"sources":["../../src/types/stop-condition.ts"],"sourcesContent":["import type { RunState } from './run.js';\n\n/**\n * Predicate consulted by the agent runtime after every step to decide\n * whether the loop should stop.\n *\n * Stop conditions are pure - they look at the current `RunState` and\n * return a boolean. The runtime never re-orders or short-circuits the\n * order in which operands of `and` / `or` are evaluated, so users can\n * rely on the obvious left-to-right semantics.\n *\n * @stable\n */\nexport interface StopCondition {\n  /** Human-friendly label included in observability spans. */\n  readonly description: string;\n  /** Returns `true` when the run should stop on this state. */\n  readonly check: (state: RunState) => boolean;\n}\n\n/**\n * Stop after `n` total steps (`stepNumber >= n`). The default condition\n * for the agent runtime is `isStepCount(50)`.\n *\n * @stable\n */\nexport function isStepCount(n: number): StopCondition {\n  if (!Number.isFinite(n) || n <= 0) {\n    throw new RangeError(`isStepCount: n must be a positive integer (got ${String(n)})`);\n  }\n  return {\n    description: `step >= ${n}`,\n    check: (state): boolean => state.steps.length >= n,\n  };\n}\n\n/**\n * Stop as soon as the most recent assistant message contains a tool call\n * with the given name.\n *\n * @stable\n */\nexport function hasToolCall(toolName: string): StopCondition {\n  return {\n    description: `tool-call:${toolName}`,\n    check: (state): boolean => {\n      for (let i = state.messages.length - 1; i >= 0; i--) {\n        const msg = state.messages[i];\n        if (msg && msg.role === 'assistant') {\n          const calls = msg.toolCalls;\n          if (calls?.some((c) => c.toolName === toolName)) {\n            return true;\n          }\n          // First assistant message without the call → not yet matched.\n          return false;\n        }\n      }\n      return false;\n    },\n  };\n}\n\n/**\n * Stop when the run reaches a terminal status.\n *\n * @stable\n */\nexport const isTerminal: StopCondition = {\n  description: 'status:terminal',\n  check: (state): boolean =>\n    state.status === 'completed' || state.status === 'failed' || state.status === 'aborted',\n};\n\n/**\n * Stop when **any** of the supplied conditions is satisfied.\n *\n * @stable\n */\nexport function or(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `or(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.some((c) => c.check(state)),\n  };\n}\n\n/**\n * Stop only when **all** of the supplied conditions are satisfied.\n *\n * @stable\n */\nexport function and(...conditions: readonly StopCondition[]): StopCondition {\n  return {\n    description: `and(${conditions.map((c) => c.description).join(', ')})`,\n    check: (state): boolean => conditions.every((c) => c.check(state)),\n  };\n}\n\n/**\n * Negate the supplied condition.\n *\n * @stable\n */\nexport function not(condition: StopCondition): StopCondition {\n  return {\n    description: `not(${condition.description})`,\n    check: (state): boolean => !condition.check(state),\n  };\n}\n"],"mappings":";;;;;;;AA0BA,SAAgB,YAAY,GAA0B;AACpD,KAAI,CAAC,OAAO,SAAS,EAAE,IAAI,KAAK,EAC9B,OAAM,IAAI,WAAW,kDAAkD,OAAO,EAAE,CAAC,GAAG;AAEtF,QAAO;EACL,aAAa,WAAW;EACxB,QAAQ,UAAmB,MAAM,MAAM,UAAU;EAClD;;;;;;;;AASH,SAAgB,YAAY,UAAiC;AAC3D,QAAO;EACL,aAAa,aAAa;EAC1B,QAAQ,UAAmB;AACzB,QAAK,IAAI,IAAI,MAAM,SAAS,SAAS,GAAG,KAAK,GAAG,KAAK;IACnD,MAAM,MAAM,MAAM,SAAS;AAC3B,QAAI,OAAO,IAAI,SAAS,aAAa;AAEnC,SADc,IAAI,WACP,MAAM,MAAM,EAAE,aAAa,SAAS,CAC7C,QAAO;AAGT,YAAO;;;AAGX,UAAO;;EAEV;;;;;;;AAQH,MAAaA,aAA4B;CACvC,aAAa;CACb,QAAQ,UACN,MAAM,WAAW,eAAe,MAAM,WAAW,YAAY,MAAM,WAAW;CACjF;;;;;;AAOD,SAAgB,GAAG,GAAG,YAAqD;AACzE,QAAO;EACL,aAAa,MAAM,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACnE,QAAQ,UAAmB,WAAW,MAAM,MAAM,EAAE,MAAM,MAAM,CAAC;EAClE;;;;;;;AAQH,SAAgB,IAAI,GAAG,YAAqD;AAC1E,QAAO;EACL,aAAa,OAAO,WAAW,KAAK,MAAM,EAAE,YAAY,CAAC,KAAK,KAAK,CAAC;EACpE,QAAQ,UAAmB,WAAW,OAAO,MAAM,EAAE,MAAM,MAAM,CAAC;EACnE;;;;;;;AAQH,SAAgB,IAAI,WAAyC;AAC3D,QAAO;EACL,aAAa,OAAO,UAAU,YAAY;EAC1C,QAAQ,UAAmB,CAAC,UAAU,MAAM,MAAM;EACnD"}

package/dist/types/tool.d.ts

@@ -21,14 +21,14 @@ type SandboxPolicy = 'none' | 'sandboxed' | 'isolated' | 'docker';
  * metadata against this discriminator without a hard dependency on the
  * security package.
  *
- * - `'pure'`                     — no side effects of any kind.
- * - `'side-effecting-no-memory'` — observable side effects outside of
+ * - `'pure'`                     - no side effects of any kind.
+ * - `'side-effecting-no-memory'` - observable side effects outside of
  *   the framework's memory tiers (e.g. external HTTP).
- * - `'memory-aware'`             — mutates the framework's memory
+ * - `'memory-aware'`             - mutates the framework's memory
  *   tiers via the sanctioned `ctx.memory.*` surface only.
- * - `'unknown'`                  — no declaration; the runtime applies
+ * - `'unknown'`                  - no declaration; the runtime applies
  *   the audit-only baseline.
- * - `'untrusted'`                — third-party / untrusted skill code;
+ * - `'untrusted'`                - third-party / untrusted skill code;
  *   the runtime forces the strictest snapshot policy.
  *
  * @stable
@@ -40,13 +40,13 @@ type MemoryGuardTier = 'pure' | 'side-effecting-no-memory' | 'memory-aware' | 'u
  * Surfaced uniformly by the tool dispatcher, downstream session
  * cassette layers, retry middleware, and approval-policy derivations.
  *
- * - `'pure'`              — deterministic; same `(input, ctx)` always
+ * - `'pure'`              - deterministic; same `(input, ctx)` always
  *   yields the same output; no I/O of any kind.
- * - `'read-only'`         — queries external systems but never
+ * - `'read-only'`         - queries external systems but never
  *   mutates them (e.g. database SELECT, HTTP GET).
- * - `'side-effecting'`    — mutates state inside the agent's logical
+ * - `'side-effecting'`    - mutates state inside the agent's logical
  *   boundary (e.g. memory writes, cache writes).
- * - `'external-stateful'` — mutates state outside the agent's
+ * - `'external-stateful'` - mutates state outside the agent's
  *   boundary that other systems can observe (e.g. issue creation,
  *   message dispatch, payment).
  *
@@ -57,15 +57,15 @@ type SideEffectClass = 'pure' | 'read-only' | 'side-effecting' | 'external-state
  * Inbound prompt-injection sanitization policy applied to a tool's
  * result body before it reaches the conversation history.
  *
- * - `'pass-through'`              — no scan; bytes-equal forwarding
+ * - `'pass-through'`              - no scan; bytes-equal forwarding
  *   (the trusted-built-in default).
- * - `'detect-and-flag'`           — scan; emit a flag span attribute
+ * - `'detect-and-flag'`           - scan; emit a flag span attribute
  *   + audit row but do not modify the body.
- * - `'detect-and-strip'`          — replace each match with the
+ * - `'detect-and-strip'`          - replace each match with the
  *   `[REDACTED:imperative-pattern]` literal token.
- * - `'detect-and-wrap'`           — wrap the body in the
+ * - `'detect-and-wrap'`           - wrap the body in the
  *   `<<<untrusted_content>>>` envelope without stripping matches.
- * - `'detect-and-strip-and-wrap'` — both strip matches and wrap the
+ * - `'detect-and-strip-and-wrap'` - both strip matches and wrap the
  *   resulting body (the untrusted-source default).
  *
  * @stable
@@ -75,14 +75,14 @@ type InboundSanitizationPolicy = 'pass-through' | 'detect-and-flag' | 'detect-an
  * Result-envelope truncation strategy applied to a tool's assembled
  * output before it reaches the conversation history.
  *
- * - `'middle'`         — keep head and tail; insert annotation in the
+ * - `'middle'`         - keep head and tail; insert annotation in the
  *   middle (the default).
- * - `'tail'`           — keep the tail; insert annotation at the
+ * - `'tail'`           - keep the tail; insert annotation at the
  *   head.
- * - `'spill-to-file'`  — keep the head; spill the un-truncated body
+ * - `'spill-to-file'`  - keep the head; spill the un-truncated body
  *   to a per-run artifact file; insert annotation with the artifact
  *   path.
- * - `'summarize'`      — invoke the agent's configured summarizer
+ * - `'summarize'`      - invoke the agent's configured summarizer
  *   and replace the body with the summary.
  *
  * @stable
@@ -158,7 +158,7 @@ interface ToolResult<TOutput = unknown> {
   readonly durationMs: number;
   /**
    * Set when the tool's output was large enough to be stored behind a
-   * handle (the `'spill-to-file'` truncation strategy, or — later — an MCP
+   * handle (the `'spill-to-file'` truncation strategy, or - later - an MCP
    * `resource_link`) instead of being inlined in full. The runtime inlines
    * only the bounded {@link ResultHandle.preview} and lets the model fetch
    * the rest on demand via the built-in `read_result` tool. Absent for
@@ -171,14 +171,14 @@ interface ToolResult<TOutput = unknown> {
  * out of the conversation buffer rather than inlined in full. The agent
  * inlines {@link preview} (plus a retrieval hint) and registers the
  * built-in `read_result` tool so the model can page through the full
- * artifact behind {@link uri} on demand — keeping large results out of the
+ * artifact behind {@link uri} on demand - keeping large results out of the
  * context window (P1-4).
  *
  * @stable
  */
 interface ResultHandle {
   /**
-   * Opaque, run-scoped URI — e.g. `graphorin-spill:<runId>/<toolCallId>.json`
+   * Opaque, run-scoped URI - e.g. `graphorin-spill:<runId>/<toolCallId>.json`
    * for a spill artifact. Never a raw filesystem path: the reader resolves
    * it within the configured artifact root, so the model cannot use it to
    * read arbitrary files.
@@ -206,7 +206,24 @@ interface ResultHandle {
  *
  * @stable
  */
-type ToolErrorKind = 'approval_denied' | 'sandbox_violation' | 'timeout' | 'invalid_input' | 'invalid_output' | 'execution_failed' | 'unknown_tool' | 'aborted' | 'inbound_sanitization_blocked' | 'dataflow_policy_blocked' | 'rate_limited';
+type ToolErrorKind = 'approval_denied' | 'sandbox_violation' | 'timeout' | 'invalid_input' | 'invalid_output' | 'execution_failed' | 'unknown_tool' | 'aborted' | 'inbound_sanitization_blocked' | 'dataflow_policy_blocked' | 'capability_blocked' | 'rate_limited';
+/**
+ * Model-facing recovery guidance attached to a {@link ToolError} (C3).
+ * Practitioner evidence converges on these two fields being what changes
+ * model behaviour after a failure:
+ *
+ * - `'retry_later'`      - transient; the same call is expected to work
+ *                          after a pause (rate limits, timeouts).
+ * - `'check_input'`      - the arguments are wrong; re-read the schema
+ *                          and fix them before retrying.
+ * - `'try_alternative'`  - this tool/approach failed non-transiently;
+ *                          try a different tool or strategy.
+ * - `'report_to_user'`   - a policy/authorization stop; do not retry,
+ *                          surface the situation instead.
+ *
+ * @stable
+ */
+type RecoveryHint = 'retry_later' | 'check_input' | 'try_alternative' | 'report_to_user';
 /**
  * The unsuccessful outcome of a tool invocation. The model sees a textual
  * representation of `message`; the runtime sees the typed shape.
@@ -222,10 +239,18 @@ interface ToolError {
   readonly cause?: unknown;
   /** Optional remediation hint for human readers. */
   readonly hint?: string;
+  /**
+   * Whether retrying the SAME call can plausibly succeed (C3). Stamped
+   * from the error kind by the executor; the harness-side transparent
+   * retry consults it together with the tool's side-effect safety.
+   */
+  readonly recoverable?: boolean;
+  /** Model-facing recovery guidance derived from the error kind (C3). */
+  readonly recoveryHint?: RecoveryHint;
 }
 /**
  * Either a `ToolResult` or a `ToolError`. The runtime always returns one
- * of the two — there is no implicit "tool fell through" outcome.
+ * of the two - there is no implicit "tool fell through" outcome.
  *
  * @stable
  */
@@ -256,5 +281,5 @@ interface CompletedToolCall<TOutput = unknown> {
   readonly stepNumber: number;
 }
 //#endregion
-export { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy };
+export { CompletedToolCall, ContentChunk, InboundSanitizationPolicy, MemoryGuardTier, RecoveryHint, ResultHandle, SandboxPolicy, SideEffectClass, ToolApproval, ToolError, ToolErrorKind, ToolOutcome, ToolResult, ToolSource, ToolTrustClass, TruncationStrategy };
 //# sourceMappingURL=tool.d.ts.map