@graphorin/core 0.5.0

package/dist/types/memory.d.ts

@@ -0,0 +1,354 @@
+import { Sensitivity } from "./sensitivity.js";
+
+//#region src/types/memory.d.ts
+
+/**
+ * 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
+ * through the optional insight surface adapters expose. Used as the
+ * discriminator for span types and the `MemoryRecord` union.
+ *
+ * @stable
+ */
+type MemoryKind = 'working' | 'session' | 'episodic' | 'semantic' | 'procedural' | 'shared' | 'insight';
+/**
+ * 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),
+ * `reflection` (a synthesis pass inferred it), and `induction` (an
+ * AWM-style pass distilled a reusable workflow from a successful agent
+ * 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
+ * gate matters most for them.
+ *
+ * @stable
+ */
+type MemoryProvenance = 'user' | 'tool' | 'extraction' | 'reflection' | 'induction' | 'imported';
+/**
+ * Retrieval-trust state of a memory. `active` rows are eligible for
+ * default recall; `quarantined` rows are persisted and auditable but
+ * excluded from action-driving recall until explicitly validated (P1-4).
+ * Quarantine is a *retrieval gate*, never a delete.
+ *
+ * @stable
+ */
+type MemoryStatus = 'active' | 'quarantined';
+/**
+ * Snapshot of memory-tier counters surfaced to the model via the
+ * memory-aware system prompt. Implementations live in `@graphorin/memory`;
+ * the type sits here so the agent runtime can include it in its
+ * `RunContext` without a memory dependency.
+ *
+ * @stable
+ */
+interface MemoryMetadata {
+  /** Total number of facts in the user's semantic memory. */
+  readonly factCount: number;
+  /** Number of episodes stored for the user. */
+  readonly episodeCount: number;
+  /** Number of past messages indexed for retrieval. */
+  readonly messageCount: number;
+  /** Active rules count (after context filtering). */
+  readonly activeRuleCount: number;
+  /** Number of declared working blocks. */
+  readonly workingBlockCount: number;
+  /** Last consolidator run, ISO-8601, if any. */
+  readonly lastConsolidatedAt?: string;
+  /** Optional, free-form metadata tags surfaced to the model. */
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Marker shared by every memory record. Concrete records (`Block`,
+ * `Fact`, `Episode`, `Rule`, message rows) all extend it.
+ *
+ * @stable
+ */
+interface MemoryRecord {
+  readonly id: string;
+  readonly kind: MemoryKind;
+  readonly userId: string;
+  readonly agentId?: string;
+  readonly sessionId?: string;
+  readonly sensitivity: Sensitivity;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+  /**
+   * Soft-delete tombstone. Append-only stores set this instead of removing
+   * rows, so prior history is preserved per principle 8.
+   */
+  readonly deletedAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * Working-memory block — a labeled, char-bounded slot rendered into the
+ * system prompt every turn.
+ *
+ * @stable
+ */
+interface Block extends MemoryRecord {
+  readonly kind: 'working';
+  readonly label: string;
+  readonly description?: string;
+  readonly value: string;
+  readonly charLimit: number;
+  readonly readOnly?: boolean;
+}
+/**
+ * Single semantic-memory fact: an atomic statement about the user / world.
+ *
+ * @stable
+ */
+interface Fact extends MemoryRecord {
+  readonly kind: 'semantic';
+  readonly text: string;
+  /**
+   * Structured `(subject, predicate, object)` triple for the in-SQLite
+   * relation graph (P2-1). The consolidator's extraction prompt emits
+   * these; first-party `remember({ text })` writes usually omit them.
+   * `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
+   * one-hop expansion ({@link MemorySearchOptions} has no field; the
+   * memory tier's search opts in), never a recall gate.
+   */
+  readonly subject?: string;
+  /** Relation label of the {@link Fact.subject}→{@link Fact.object} triple (P2-1). */
+  readonly predicate?: string;
+  /** Object entity of the s/p/o triple (P2-1). See {@link Fact.subject}. */
+  readonly object?: string;
+  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
+   * delays capacity-bounded eviction, but never gates recall and never
+   * forces retention. Absent on rows written before the feature
+   * (treated as neutral, `0.5`).
+   */
+  readonly importance?: number;
+  /** Bi-temporal: when the fact became true, ISO-8601. */
+  readonly validFrom?: string;
+  /** Bi-temporal: when the fact stopped being true, ISO-8601. */
+  readonly validTo?: string;
+  /** ID of the fact this one supersedes, if any. */
+  readonly supersedes?: string;
+  /** ID of the fact that supersedes this one, if any. */
+  readonly supersededBy?: string;
+  /**
+   * Trust-provenance tag (P1-4). Absent on rows written before the
+   * feature; treated as first-party (`active`) when missing.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4). Defaults to `active`; derived /
+   * injection-flagged writes land `quarantined` and are excluded from
+   * default recall.
+   */
+  readonly status?: MemoryStatus;
+}
+/**
+ * Episode — a summarized stretch of past activity.
+ *
+ * @stable
+ */
+interface Episode extends MemoryRecord {
+  readonly kind: 'episodic';
+  readonly summary: string;
+  /** ISO-8601 of the earliest event in the episode. */
+  readonly startedAt: string;
+  /** ISO-8601 of the latest event in the episode. */
+  readonly endedAt: string;
+  /** Optional importance score in `[0, 1]`. */
+  readonly importance?: number;
+  /** Trust-provenance tag (P1-4). See {@link MemoryProvenance}. */
+  readonly provenance?: MemoryProvenance;
+  /** Retrieval-trust state (P1-4). See {@link MemoryStatus}. */
+  readonly status?: MemoryStatus;
+}
+/**
+ * Procedural rule — a standing order activated when its `condition` matches.
+ *
+ * @stable
+ */
+interface Rule extends MemoryRecord {
+  readonly kind: 'procedural';
+  readonly text: string;
+  readonly condition?: string;
+  readonly priority: number;
+  /**
+   * Ordered, value-abstracted step sequence of an *induced* workflow
+   * (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
+   * appear in {@link Rule.steps}. Lets a reused procedure be re-bound to
+   * fresh arguments instead of replaying one run's literals.
+   */
+  readonly variables?: ReadonlyArray<string>;
+  /**
+   * Voyager-style verifiable success criteria stored alongside an induced
+   * procedure (P2-2) so a reuse can *self-verify* its outcome instead of
+   * trusting the procedure blindly. Author-defined rules omit it.
+   */
+  readonly successCriteria?: ReadonlyArray<string>;
+  /**
+   * Trust-provenance tag (P1-4 / P2-2). Induced procedures are
+   * `'induction'`; author-defined rules omit it (treated first-party).
+   * See {@link MemoryProvenance}.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4 / P2-2). Induced procedures land
+   * `'quarantined'` and are excluded from activation (they must not drive
+   * actions) until validated; author-defined rules omit it (treated
+   * `'active'`). See {@link MemoryStatus}.
+   */
+  readonly status?: MemoryStatus;
+  /**
+   * Demonstrated-success counter (MCON-2 part 4). Incremented by
+   * `ProceduralMemory.recordOutcome(...)` on each verified successful
+   * reuse; drives promotion-by-demonstrated-success for quarantined
+   * induced procedures once the configured threshold is reached.
+   * Absent ⇒ never counted (adapters without the column).
+   */
+  readonly successCount?: number;
+}
+/**
+ * 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
+ * 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
+ * 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
+ * `≤ 0`) and are retrieval-ranked **below** the primary facts they cite.
+ *
+ * @stable
+ */
+interface Insight extends MemoryRecord {
+  readonly kind: 'insight';
+  /** The synthesized higher-order observation. */
+  readonly text: string;
+  /**
+   * IDs of the supporting memories (facts / episodes) this insight was
+   * synthesized from. Always ≥ 1 — citations are mandatory; an insight
+   * with no traceable evidence is never persisted.
+   */
+  readonly cites: ReadonlyArray<string>;
+  /**
+   * ExpeL-style salience counter. New insights start at `2`; a
+   * maintenance pass up-/down-votes on subsequent corroboration /
+   * contradiction and prunes (soft-deletes) insights at `≤ 0`.
+   */
+  readonly salience: number;
+  /**
+   * Trust-provenance tag (P1-4). Reflection-synthesized insights are
+   * `'reflection'`. See {@link MemoryProvenance}.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4). Insights land `'quarantined'`. See
+   * {@link MemoryStatus}.
+   */
+  readonly status?: MemoryStatus;
+}
+/**
+ * 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
+ * label, not an entity, so it has no role here.
+ *
+ * @stable
+ */
+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
+ * aliases ("Anna", "Anna S.", "my sister") via lexical + embedding
+ * 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
+ * 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.
+ *
+ * @stable
+ */
+interface GraphEntity {
+  readonly id: string;
+  readonly userId: string;
+  /** Display name as first observed (the surface form that minted it). */
+  readonly name: string;
+  /** Case/space-folded key used for lexical dedup + the canonical unique index. */
+  readonly normalizedName: string;
+  /**
+   * Canonical pointer. `undefined` ⇒ this entity is itself a root.
+   * Otherwise it is the id of the surviving entity this one was merged
+   * into; single-level by construction, so `mergedInto ?? id` resolves
+   * the canonical id without a recursive walk.
+   */
+  readonly mergedInto?: string;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+}
+/**
+ * Search options shared across memory tiers.
+ *
+ * @stable
+ */
+interface MemorySearchOptions {
+  readonly query: string;
+  readonly topK?: number;
+  readonly tags?: ReadonlyArray<string>;
+  readonly dateRange?: {
+    readonly from?: string;
+    readonly to?: string;
+  };
+  readonly includeArchived?: boolean;
+  /**
+   * 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
+   * auto-recall fed back into the model.
+   */
+  readonly includeQuarantined?: boolean;
+  readonly signal?: AbortSignal;
+  /**
+   * 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).
+   */
+  readonly asOf?: string;
+}
+/**
+ * A single retrieval hit with similarity / relevance metadata.
+ *
+ * @stable
+ */
+interface MemoryHit<TRecord extends MemoryRecord = MemoryRecord> {
+  readonly record: TRecord;
+  readonly score: number;
+  /** Optional source signals contributing to `score` (BM25, vec, RRF, …). */
+  readonly signals?: Readonly<Record<string, number>>;
+}
+//#endregion
+export { Block, EntityRole, Episode, Fact, GraphEntity, Insight, MemoryHit, MemoryKind, MemoryMetadata, MemoryProvenance, MemoryRecord, MemorySearchOptions, MemoryStatus, Rule };
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/message.d.ts

@@ -0,0 +1,162 @@
+import { ToolCall } from "./tool-call.js";
+
+//#region src/types/message.d.ts
+
+/**
+ * A single multimodal content part attached to a chat-style message.
+ *
+ * The discriminated union is exhaustive: every variant carries a literal
+ * `type` field used by both the runtime and the type system to pick the
+ * branch. New variants must be added to all three of: this union, every
+ * `assertNever` switch in the codebase, and the wire-stable adapters.
+ *
+ * @stable
+ */
+type MessageContent = TextContent | ImageContent | AudioContent | FileContent | ReasoningContent;
+/**
+ * Plain UTF-8 text part. The default for textual replies and tool I/O.
+ *
+ * @stable
+ */
+interface TextContent {
+  readonly type: 'text';
+  readonly text: string;
+  /**
+   * Optional opaque trace of the agent-runtime decisions that produced
+   * this content part. Bounded-length, no PII, no secret values.
+   * Round-tripped bytes-equal through `Session.push / list / export /
+   * import`. See `@graphorin/sessions` commentary-phase sanitization.
+   */
+  readonly causalityChain?: ReadonlyArray<string>;
+}
+/**
+ * Image attachment. The `image` field accepts either raw bytes or a `URL`
+ * — adapters dereference the URL when the provider only accepts inline
+ * payloads.
+ *
+ * @stable
+ */
+interface ImageContent {
+  readonly type: 'image';
+  readonly image: Uint8Array | URL;
+  readonly mimeType?: string;
+  /** See {@link TextContent.causalityChain}. */
+  readonly causalityChain?: ReadonlyArray<string>;
+}
+/**
+ * Audio attachment (e.g. voice messages). Note: voice realtime / TTS / STT
+ * are out of scope for v0.1 — these messages are static blobs.
+ *
+ * @stable
+ */
+interface AudioContent {
+  readonly type: 'audio';
+  readonly audio: Uint8Array | URL;
+  readonly mimeType?: string;
+  /** See {@link TextContent.causalityChain}. */
+  readonly causalityChain?: ReadonlyArray<string>;
+}
+/**
+ * Generic file attachment (PDF, CSV, …). `mimeType` is mandatory because
+ * many providers gate file ingestion on it.
+ *
+ * @stable
+ */
+interface FileContent {
+  readonly type: 'file';
+  readonly file: Uint8Array | URL;
+  readonly mimeType: string;
+  readonly filename?: string;
+  /** See {@link TextContent.causalityChain}. */
+  readonly causalityChain?: ReadonlyArray<string>;
+}
+/**
+ * Reasoning content emitted by reasoning-capable models. Stored
+ * separately from `text` so that consumers can choose to hide / strip
+ * it (per the streaming-first principle and the replay-redaction
+ * policy).
+ *
+ * @stable
+ */
+interface ReasoningContent {
+  readonly type: 'reasoning';
+  readonly text: string;
+  /**
+   * Provider-specific opaque metadata that MUST round-trip byte-equal
+   * when the effective `reasoningRetention` is not `'strip'`. The
+   * field is provider-supplied protocol payload, not user content,
+   * and is therefore exempt from prompt-redaction scanning.
+   *
+   * Anthropic Claude tool-use thinking blocks supply
+   * `{ provider: 'anthropic', signature, data? }`; other providers
+   * are free to populate whatever opaque keys their wire contract
+   * requires. Adapters that do not need round-tripping omit this
+   * field entirely.
+   */
+  readonly meta?: ReasoningContentMeta;
+  /** See {@link TextContent.causalityChain}. */
+  readonly causalityChain?: ReadonlyArray<string>;
+}
+/**
+ * Opaque metadata round-tripped on `ReasoningContent`. Adapter-defined
+ * keys; consumers must NOT introspect or modify the contents.
+ *
+ * @stable
+ */
+interface ReasoningContentMeta {
+  readonly provider?: string;
+  readonly signature?: string;
+  readonly data?: string;
+  readonly [extraKey: string]: unknown;
+}
+/**
+ * Logical role of a message in a conversation.
+ *
+ * @stable
+ */
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * Chat message. The shape is provider-agnostic: adapters convert it to /
+ * from the wire format.
+ *
+ * - System messages must be plain strings (multimodal system messages are
+ *   not in the v0.1 surface).
+ * - Assistant messages may carry `toolCalls` alongside their content.
+ * - Tool messages carry the originating `toolCallId` so the model can
+ *   correlate the response to its previous request.
+ *
+ * @stable
+ */
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+/** @stable */
+interface SystemMessage {
+  readonly role: 'system';
+  readonly content: string;
+}
+/** @stable */
+interface UserMessage {
+  readonly role: 'user';
+  readonly content: string | readonly MessageContent[];
+  /** Multi-agent attribution: which user persona this came from, if any. */
+  readonly userId?: string;
+}
+/** @stable */
+interface AssistantMessage {
+  readonly role: 'assistant';
+  readonly content: string | readonly MessageContent[];
+  readonly toolCalls?: readonly ToolCall[];
+  /**
+   * Multi-agent attribution: which agent produced this message. Required
+   * by the multi-agent crew acceptance criteria.
+   */
+  readonly agentId?: string;
+}
+/** @stable */
+interface ToolMessage {
+  readonly role: 'tool';
+  readonly toolCallId: string;
+  readonly content: string | readonly MessageContent[];
+}
+//#endregion
+export { AssistantMessage, AudioContent, FileContent, ImageContent, Message, MessageContent, MessageRole, ReasoningContent, ReasoningContentMeta, SystemMessage, TextContent, ToolMessage, UserMessage };
+//# sourceMappingURL=message.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/run.d.ts

@@ -0,0 +1,155 @@
+import { Message } from "./message.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
+
+/**
+ * Status of an in-flight or completed agent run. Append-only persistence
+ * stores expose this verbatim on the `runs` table.
+ *
+ * @stable
+ */
+type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';
+/**
+ * Single step inside an agent run. The agent runtime appends one
+ * `RunStep` per provider call.
+ *
+ * @stable
+ */
+interface RunStep {
+  readonly stepNumber: number;
+  readonly startedAt: string;
+  readonly endedAt?: string;
+  readonly usage?: Usage;
+  readonly toolCalls: readonly CompletedToolCall[];
+  /**
+   * Stable agent id active for this step (changes after a handoff).
+   */
+  readonly agentId: string;
+}
+/**
+ * Per-model usage breakdown carried alongside the aggregate
+ * {@link Usage} on {@link RunState}. Populated by the per-step retry
+ * loop when `Agent.fallbackModels` fires; for runs that never fall
+ * back, the map carries a single entry for the primary model with
+ * `attemptCount: 1`.
+ *
+ * The aggregate `RunState.usage` is always the sum of every entry's
+ * `Usage` portion (the field is asserted in tests).
+ *
+ * @stable
+ */
+interface RunStateUsageByModel {
+  readonly [modelId: string]: Usage & {
+    readonly attemptCount: number;
+  };
+}
+/**
+ * The full, serializable state of a run. The agent runtime persists this
+ * to the checkpoint store on every `awaiting_approval` boundary, so a
+ * separate process can resume the run.
+ *
+ * The shape is intentionally JSON-stable: every nested type is plain
+ * `JSON`-encodable (no `Map`, no `Set`, no `Date`).
+ *
+ * @stable
+ */
+interface RunState {
+  readonly id: string;
+  readonly agentId: string;
+  readonly currentAgentId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  status: RunStatus;
+  readonly steps: RunStep[];
+  readonly messages: Message[];
+  readonly pendingApprovals: ToolApproval[];
+  readonly handoffs: HandoffRecord[];
+  readonly usage: Usage;
+  /**
+   * Per-model usage breakdown. Populated by the per-step retry loop
+   * when `Agent.fallbackModels` fires (RB-48 / suggested DEC-164 /
+   * suggested ADR-052). Backward-compat: rehydrating a serialized
+   * state that omits the field synthesizes a single-entry map for
+   * the primary model.
+   */
+  usageByModel?: RunStateUsageByModel;
+  /**
+   * AG-19: coarse data-flow taint summary, carried across suspend/resume so a
+   * 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
+   * untrusted text spans.
+   */
+  taintSummary?: RunTaintSummary;
+  /**
+   * AG-19: names of deferred tools promoted by `tool_search` this run, carried
+   * across suspend/resume so discovered tools remain in the per-step catalogue.
+   */
+  promotedTools?: ReadonlyArray<string>;
+  readonly startedAt: string;
+  finishedAt?: string;
+  error?: RunError;
+}
+/**
+ * Coarse, serializable data-flow taint summary persisted in {@link RunState}
+ * across suspend/resume (AG-19). Structurally identical to
+ * `@graphorin/security`'s `TaintLedgerSnapshot`; carries no untrusted text.
+ *
+ * @stable
+ */
+interface RunTaintSummary {
+  readonly untrustedSeen: boolean;
+  readonly sensitiveSeen: boolean;
+  readonly untrustedSourceKinds: ReadonlyArray<string>;
+}
+/**
+ * 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
+ * do not have to take an observability dependency just to flatten a
+ * run-state breakdown.
+ *
+ * @stable
+ */
+declare function flattenUsageByModel(byModel: RunStateUsageByModel | undefined): ReadonlyArray<ModelUsage>;
+/**
+ * Failure carried by `RunState.error`. The shape mirrors the wire format
+ * used by `agent.error` events.
+ *
+ * @stable
+ */
+interface RunError {
+  readonly message: string;
+  readonly code: string;
+  readonly details?: unknown;
+}
+/**
+ * Per-run dependency / context bag handed to every tool, hook and
+ * provider middleware in scope. Generic over the user-defined deps shape.
+ *
+ * `tracer`, `signal`, `usage` and `state` are always present; everything
+ * else is optional.
+ *
+ * @stable
+ */
+interface RunContext<TDeps = unknown> {
+  readonly runId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly agentId: string;
+  readonly deps: TDeps;
+  readonly tracer: Tracer;
+  readonly signal: AbortSignal;
+  readonly usage: UsageAccumulator;
+  readonly stepNumber: number;
+  readonly messages: ReadonlyArray<Message>;
+  readonly state: RunState;
+}
+//#endregion
+export { RunContext, RunError, RunState, RunStateUsageByModel, RunStatus, RunStep, RunTaintSummary, flattenUsageByModel };
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +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"}