@graphorin/core 0.6.1 → 0.7.0

package/src/types/message.ts

@@ -0,0 +1,174 @@
+import type { ToolCall } from './tool-call.js';
+
+/**
+ * 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
+ */
+export type MessageContent =
+  | TextContent
+  | ImageContent
+  | AudioContent
+  | FileContent
+  | ReasoningContent;
+
+/**
+ * Plain UTF-8 text part. The default for textual replies and tool I/O.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export interface ReasoningContentMeta {
+  readonly provider?: string;
+  readonly signature?: string;
+  readonly data?: string;
+  readonly [extraKey: string]: unknown;
+}
+
+/**
+ * Logical role of a message in a conversation.
+ *
+ * @stable
+ */
+export 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
+ */
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+
+/** @stable */
+export interface SystemMessage {
+  readonly role: 'system';
+  readonly content: string;
+}
+
+/** @stable */
+export 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 */
+export 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 */
+export interface ToolMessage {
+  readonly role: 'tool';
+  readonly toolCallId: string;
+  readonly content: string | readonly MessageContent[];
+}

package/src/types/run.ts

@@ -0,0 +1,312 @@
+import type { Tracer } from '../contracts/tracer.js';
+import type { HandoffRecord } from './handoff.js';
+import type { Message } from './message.js';
+import type { CompletedToolCall, ToolApproval } from './tool.js';
+import type { ToolCall } from './tool-call.js';
+import type { ModelUsage, Usage, UsageAccumulator } from './usage.js';
+
+/**
+ * Status of an in-flight or completed agent run. Append-only persistence
+ * stores expose this verbatim on the `runs` table.
+ *
+ * @stable
+ */
+export type RunStatus = 'running' | 'completed' | 'failed' | 'aborted' | 'awaiting_approval';
+
+/**
+ * Single step inside an agent run. The agent runtime appends one
+ * `RunStep` per provider call.
+ *
+ * @stable
+ */
+export 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;
+  /**
+   * 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
+ */
+export interface RunStepProviderResponse {
+  readonly modelId: string;
+  readonly text?: string;
+  readonly toolCalls?: ReadonlyArray<ToolCall>;
+}
+
+/**
+ * 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
+ */
+export 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.
+ *
+ * JSON stability is guaranteed by the serializer, not by naive
+ * `JSON.stringify`: `messages` and tool-outcome `contentParts` may carry
+ * `Uint8Array | URL` payloads, which the documented wire projection
+ * (`WireRunState` via `toJsonSafeRunState`) encodes as base64 / href
+ * envelopes before stringification. No `Map`, `Set` or `Date` appears
+ * anywhere in the shape.
+ *
+ * @stable
+ */
+export interface RunState {
+  readonly id: string;
+  readonly agentId: string;
+  /**
+   * The agent whose model drives the NEXT step. During a handoff it is
+   * the target for exactly the child observation window and is restored
+   * to the parent when the child returns (W-034) - the child's identity
+   * is durably recorded in {@link RunState.handoffs}, never here.
+   */
+  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>;
+  /**
+   * 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>;
+  /**
+   * W-001: sub-agent runs parked on this (parent) run because the
+   * child suspended with `awaiting_approval`. Each entry snapshots the
+   * suspended child state; the child's pending approvals are mirrored
+   * onto this run's `pendingApprovals` with `subRunToolCallId` set to
+   * the entry's `toolCallId`. Absent until a child parks.
+   */
+  pendingSubRuns?: PendingSubRun[];
+  readonly startedAt: string;
+  finishedAt?: string;
+  error?: RunError;
+}
+
+/**
+ * One sub-agent run parked on its parent because the child suspended
+ * awaiting approvals (W-001). `state` is a JSON-compatible snapshot of
+ * the suspended child run; in serialized form (the agent package's
+ * `SerializedRunState`) it carries the child's own version-stamped,
+ * secret-redacted snapshot, recursively.
+ *
+ * @stable
+ */
+export interface PendingSubRun {
+  /** The PARENT's toolCallId of the parked handoff / sub-agent call. */
+  readonly toolCallId: string;
+  /** The parent-side tool name (`transfer_to_<name>` or the toTool name). */
+  readonly toolName: string;
+  /** The child agent's configured name (for diagnostics and usage folding). */
+  readonly targetAgentName: string;
+  /** Suspended child run state (carries the child's own pendingApprovals). */
+  readonly state: RunState;
+}
+
+/**
+ * Read-only projection of {@link RunState} handed to tools and hooks
+ * via {@link RunContext.state} (W-047). Structurally identical to
+ * `RunState` - `RunState` is assignable to it - but every property is
+ * `readonly` and every array a `ReadonlyArray`, so typed tool code
+ * cannot corrupt run bookkeeping (splice `pendingApprovals`, flip
+ * `status`, ...). This is a compile-time contract only: there is no
+ * runtime freeze. A hand-written mirror (not a generic DeepReadonly):
+ * the nested types are already readonly-typed, and keyof-parity with
+ * `RunState` is pinned by type tests.
+ *
+ * @stable
+ */
+export interface ReadonlyRunState {
+  readonly id: string;
+  readonly agentId: string;
+  readonly currentAgentId: string;
+  readonly sessionId: string;
+  readonly userId?: string;
+  readonly status: RunStatus;
+  readonly steps: ReadonlyArray<RunStep>;
+  readonly messages: ReadonlyArray<Message>;
+  readonly pendingApprovals: ReadonlyArray<ToolApproval>;
+  readonly handoffs: ReadonlyArray<HandoffRecord>;
+  readonly usage: Usage;
+  /** See {@link RunState.usageByModel}. */
+  readonly usageByModel?: RunStateUsageByModel;
+  /** See {@link RunState.taintSummary}. */
+  readonly taintSummary?: RunTaintSummary;
+  /** See {@link RunState.promotedTools}. */
+  readonly promotedTools?: ReadonlyArray<string>;
+  /** See {@link RunState.todos}. */
+  readonly todos?: ReadonlyArray<TodoItem>;
+  /** See {@link RunState.pendingSubRuns}. */
+  readonly pendingSubRuns?: ReadonlyArray<PendingSubRun>;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly 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
+ */
+export 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
+ */
+export 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
+ * do not have to take an observability dependency just to flatten a
+ * run-state breakdown.
+ *
+ * @stable
+ */
+export function flattenUsageByModel(
+  byModel: RunStateUsageByModel | undefined,
+): ReadonlyArray<ModelUsage> {
+  if (byModel === undefined) return [];
+  const out: ModelUsage[] = [];
+  for (const [modelId, entry] of Object.entries(byModel)) {
+    const m: ModelUsage = {
+      modelId,
+      promptTokens: entry.promptTokens,
+      completionTokens: entry.completionTokens,
+      totalTokens: entry.totalTokens,
+      callCount: entry.attemptCount,
+      ...(entry.reasoningTokens !== undefined ? { reasoningTokens: entry.reasoningTokens } : {}),
+      ...(entry.cost !== undefined ? { cost: entry.cost } : {}),
+    };
+    out.push(m);
+  }
+  return out;
+}
+
+/**
+ * Failure carried by `RunState.error`. The shape mirrors the wire format
+ * used by `agent.error` events.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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>;
+  /**
+   * Read-only snapshot of the run's state (W-047). Tools observe the
+   * run; they do not mutate its bookkeeping - writes to `status`,
+   * `pendingApprovals` etc. are compile errors. The runtime keeps the
+   * only mutable reference.
+   */
+  readonly state: ReadonlyRunState;
+  /**
+   * 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?: import('../contracts/tracer.js').AISpan;
+}

package/src/types/sensitivity.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ *   providers (loopback / private-network) but redacted for public-tls
+ *   exporters and replay consumers.
+ * - `'secret'`   - credentials, tokens, encryption keys; only ever stays
+ *   in-process and is never serialized to the wire by default.
+ *
+ * @stable
+ */
+export type Sensitivity = 'public' | 'internal' | 'secret';
+
+/**
+ * Strict ordering used by sensitivity-aware filters
+ * (`record.sensitivity ⊆ provider.acceptsSensitivity`).
+ *
+ * @stable
+ */
+export const SENSITIVITY_ORDER: readonly Sensitivity[] = ['public', 'internal', 'secret'] as const;
+
+/**
+ * Return `true` iff `record` is allowed to flow to a sink declaring `accepts`.
+ *
+ * Comparison is **subset** semantics: the record's tier must be one of the
+ * tiers in `accepts` (it's not enough for the record's tier to be lower).
+ * That mirrors the way provider `acceptsSensitivity` is declared in the
+ * Graphorin trust matrix.
+ *
+ * @stable
+ */
+export function acceptsSensitivity(accepts: readonly Sensitivity[], record: Sensitivity): boolean {
+  return accepts.includes(record);
+}

package/src/types/session-scope.ts

@@ -0,0 +1,18 @@
+/**
+ * Identifies a logical conversational scope: who the user is, which agent
+ * is in charge, and (when known) which session they're inside.
+ *
+ * Used as a parameter to almost every Memory / Sessions API. The agent and
+ * session fields are optional because some scopes are user-wide (e.g.
+ * shared facts attached to a user, not a particular agent).
+ *
+ * @stable
+ */
+export interface SessionScope {
+  /** Stable identifier of the user (single-user-per-process by default). */
+  readonly userId: string;
+  /** Identifier of the agent owning the scope, when applicable. */
+  readonly agentId?: string;
+  /** Identifier of the session, when applicable. */
+  readonly sessionId?: string;
+}

package/src/types/stop-condition.ts

@@ -0,0 +1,108 @@
+import type { 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
+ * 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.
+ *
+ * @stable
+ */
+export interface StopCondition {
+  /** Human-friendly label included in observability spans. */
+  readonly description: string;
+  /** Returns `true` when the run should stop on this state. */
+  readonly check: (state: RunState) => boolean;
+}
+
+/**
+ * Stop after `n` total steps (`stepNumber >= n`). The default condition
+ * for the agent runtime is `isStepCount(50)`.
+ *
+ * @stable
+ */
+export function isStepCount(n: number): StopCondition {
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new RangeError(`isStepCount: n must be a positive integer (got ${String(n)})`);
+  }
+  return {
+    description: `step >= ${n}`,
+    check: (state): boolean => state.steps.length >= n,
+  };
+}
+
+/**
+ * Stop as soon as the most recent assistant message contains a tool call
+ * with the given name.
+ *
+ * @stable
+ */
+export function hasToolCall(toolName: string): StopCondition {
+  return {
+    description: `tool-call:${toolName}`,
+    check: (state): boolean => {
+      for (let i = state.messages.length - 1; i >= 0; i--) {
+        const msg = state.messages[i];
+        if (msg && msg.role === 'assistant') {
+          const calls = msg.toolCalls;
+          if (calls?.some((c) => c.toolName === toolName)) {
+            return true;
+          }
+          // First assistant message without the call → not yet matched.
+          return false;
+        }
+      }
+      return false;
+    },
+  };
+}
+
+/**
+ * Stop when the run reaches a terminal status.
+ *
+ * @stable
+ */
+export const isTerminal: StopCondition = {
+  description: 'status:terminal',
+  check: (state): boolean =>
+    state.status === 'completed' || state.status === 'failed' || state.status === 'aborted',
+};
+
+/**
+ * Stop when **any** of the supplied conditions is satisfied.
+ *
+ * @stable
+ */
+export function or(...conditions: readonly StopCondition[]): StopCondition {
+  return {
+    description: `or(${conditions.map((c) => c.description).join(', ')})`,
+    check: (state): boolean => conditions.some((c) => c.check(state)),
+  };
+}
+
+/**
+ * Stop only when **all** of the supplied conditions are satisfied.
+ *
+ * @stable
+ */
+export function and(...conditions: readonly StopCondition[]): StopCondition {
+  return {
+    description: `and(${conditions.map((c) => c.description).join(', ')})`,
+    check: (state): boolean => conditions.every((c) => c.check(state)),
+  };
+}
+
+/**
+ * Negate the supplied condition.
+ *
+ * @stable
+ */
+export function not(condition: StopCondition): StopCondition {
+  return {
+    description: `not(${condition.description})`,
+    check: (state): boolean => !condition.check(state),
+  };
+}

package/src/types/tool-call.ts

@@ -0,0 +1,24 @@
+/**
+ * The {@link ToolCall} leaf type lives in its own module so that
+ * `message.ts` (which references `ToolCall`) and `tool.ts` (which
+ * references `MessageContent`) can both depend on it without forming a
+ * circular import. `tool.ts` re-exports `ToolCall` for backwards
+ * compatibility, so external import paths are unchanged.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A single tool invocation the model requested, normalised by the
+ * provider layer and handed to the tool executor for parallel dispatch.
+ *
+ * @stable
+ */
+export interface ToolCall {
+  /** Stable identifier the model uses to correlate input and output. */
+  readonly toolCallId: string;
+  /** Tool name as registered in the `ToolRegistry`. */
+  readonly toolName: string;
+  /** Validated input matching the tool's `inputSchema`. */
+  readonly args: unknown;
+}