@graphorin/core 0.6.1 → 0.7.0

package/src/types/tool.ts

@@ -0,0 +1,324 @@
+import type { ToolCall } from './tool-call.js';
+
+/**
+ * Sandbox isolation level requested for a tool's `execute` method.
+ *
+ * The exact semantics live in `@graphorin/security`; downstream packages
+ * type their config field as `SandboxPolicy` so they don't take a security
+ * dependency just to type their inputs.
+ *
+ * @stable
+ */
+export type SandboxPolicy = 'none' | 'sandboxed' | 'isolated' | 'docker';
+
+/**
+ * Memory-modification guard tier requested for a tool's `execute` method.
+ *
+ * Mirrors the tier classification consumed by `@graphorin/security`'s
+ * memory-modification guard so downstream packages can type their tool
+ * 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
+ *   the framework's memory tiers (e.g. external HTTP).
+ * - `'memory-aware'`             - mutates the framework's memory
+ *   tiers via the sanctioned `ctx.memory.*` surface only.
+ * - `'unknown'`                  - no declaration; the runtime applies
+ *   the audit-only baseline.
+ * - `'untrusted'`                - third-party / untrusted skill code;
+ *   the runtime forces the strictest snapshot policy.
+ *
+ * @stable
+ */
+export type MemoryGuardTier =
+  | 'pure'
+  | 'side-effecting-no-memory'
+  | 'memory-aware'
+  | 'unknown'
+  | 'untrusted';
+
+/**
+ * Side-effect classification declared by a tool author.
+ *
+ * Surfaced uniformly by the tool dispatcher, downstream session
+ * cassette layers, retry middleware, and approval-policy derivations.
+ *
+ * - `'pure'`              - deterministic; same `(input, ctx)` always
+ *   yields the same output; no I/O of any kind.
+ * - `'read-only'`         - queries external systems but never
+ *   mutates them (e.g. database SELECT, HTTP GET).
+ * - `'side-effecting'`    - mutates state inside the agent's logical
+ *   boundary (e.g. memory writes, cache writes).
+ * - `'external-stateful'` - mutates state outside the agent's
+ *   boundary that other systems can observe (e.g. issue creation,
+ *   message dispatch, payment).
+ *
+ * @stable
+ */
+export type SideEffectClass = 'pure' | 'read-only' | 'side-effecting' | 'external-stateful';
+
+/**
+ * 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
+ *   (the trusted-built-in default).
+ * - `'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
+ *   `[REDACTED:imperative-pattern]` literal token.
+ * - `'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
+ *   resulting body (the untrusted-source default).
+ *
+ * @stable
+ */
+export type InboundSanitizationPolicy =
+  | 'pass-through'
+  | 'detect-and-flag'
+  | 'detect-and-strip'
+  | 'detect-and-wrap'
+  | 'detect-and-strip-and-wrap';
+
+/**
+ * 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 (the default).
+ * - `'tail'`           - keep the tail; insert annotation at the
+ *   head.
+ * - `'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
+ *   and replace the body with the summary.
+ *
+ * @stable
+ */
+export type TruncationStrategy = 'middle' | 'tail' | 'spill-to-file' | 'summarize';
+
+/**
+ * Trust class assigned to a registered tool. The class is computed at
+ * registration time from the registration source and the declared
+ * sandbox policy; downstream layers (sanitization, audit) read the
+ * class to pick the right default policy.
+ *
+ * @stable
+ */
+export type ToolTrustClass =
+  | 'first-party-built-in'
+  | 'first-party-user-defined'
+  | 'skill-trusted'
+  | 'skill-untrusted'
+  | 'mcp-derived'
+  | 'web-search';
+
+/**
+ * Source descriptor attached to a `Tool` registration. Mirrors the
+ * registration-time provenance the dispatcher uses to derive the
+ * trust class and to compute the four collision audit row kinds.
+ *
+ * @stable
+ */
+export type ToolSource =
+  | { readonly kind: 'first-party' }
+  | { readonly kind: 'built-in'; readonly subsystem: string }
+  | {
+      readonly kind: 'skill';
+      readonly skillName: string;
+      readonly trustLevel: 'trusted' | 'untrusted';
+    }
+  | { readonly kind: 'mcp'; readonly serverIdentity: string }
+  | { readonly kind: 'web-search'; readonly providerName: string };
+
+/**
+ * Single chunk of streamed tool content. Streaming-hint tools emit one
+ * chunk per `ctx.streamContent(...)` call; the executor concatenates
+ * the chunks into the assembled `output` per the buffer-becomes-output
+ * discipline.
+ *
+ * @stable
+ */
+export type ContentChunk =
+  | { readonly kind: 'text'; readonly text: string }
+  | { readonly kind: 'json-delta'; readonly path: string; readonly value: unknown }
+  | { readonly kind: 'image'; readonly data: Uint8Array; readonly mediaType: string };
+
+// `ToolCall` is defined in `./tool-call.ts` to break the
+// `message.ts <-> tool.ts` import cycle; re-exported here so existing
+// `@graphorin/core` import paths keep resolving `ToolCall` from this
+// module. The local import lives at the top of the file.
+export type { ToolCall };
+
+/**
+ * The successful outcome of a tool invocation, returned to the model.
+ *
+ * @stable
+ */
+export interface ToolResult<TOutput = unknown> {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly output: TOutput;
+  /**
+   * Optional content parts to append to the conversation (images, files,
+   * etc.). Tools that emit binary results use this field instead of trying
+   * to encode the binary into `output`.
+   */
+  readonly contentParts?: readonly import('./message.js').MessageContent[];
+  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
+   * `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
+   * results that were inlined directly.
+   */
+  readonly resultHandle?: ResultHandle;
+}
+
+/**
+ * An opaque, run-scoped reference to a large tool result that was stored
+ * 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
+ * context window (P1-4).
+ *
+ * @stable
+ */
+export interface ResultHandle {
+  /**
+   * 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.
+   */
+  readonly uri: string;
+  /** Backing store kind. `'spill-file'` today; `'resource-link'` is reserved for MCP (WI-13). */
+  readonly kind: 'spill-file' | 'resource-link';
+  /** A bounded preview of the full body (already inlined alongside the handle). */
+  readonly preview: string;
+  /** Total byte size of the full stored artifact, when known. */
+  readonly bytes?: number;
+  /** MIME type of the stored artifact, when known. */
+  readonly mediaType?: string;
+  /**
+   * Trust class of the tool that PRODUCED the stored body (TL-6).
+   * `read_result` re-applies inbound sanitization and dataflow
+   * provenance by this class, so an untrusted spill cannot launder to
+   * trusted through the built-in reader.
+   */
+  readonly producerTrustClass?: ToolTrustClass;
+}
+
+/**
+ * Discriminator used by `ToolError.kind`. The list is exhaustive: any new
+ * kind must extend the union here and every `assertNever` switch.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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.
+ *
+ * @stable
+ */
+export interface ToolError {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly kind: ToolErrorKind;
+  readonly message: string;
+  /** Optional underlying cause (chained errors). */
+  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.
+ *
+ * @stable
+ */
+export type ToolOutcome<TOutput = unknown> = ToolResult<TOutput> | ToolError;
+
+/**
+ * Pending approval bookkeeping: a tool that needed human confirmation
+ * before execution. Stored on `RunState.pendingApprovals` until the
+ * caller resumes the run with a granted/denied decision.
+ *
+ * @stable
+ */
+export interface ToolApproval {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly args: unknown;
+  readonly reason?: string;
+  readonly requestedAt: string;
+  /**
+   * W-001: set when this approval belongs to a PARKED sub-agent run.
+   * It is the PARENT's toolCallId of the parked handoff / sub-agent
+   * call (the `RunState.pendingSubRuns` key), never a child-local id.
+   * Operators echo it back on the matching `ApprovalDecision` so
+   * resume decisions match on the composite (toolCallId,
+   * subRunToolCallId) key - child-local toolCallIds of two different
+   * children may collide.
+   */
+  readonly subRunToolCallId?: string;
+}
+
+/**
+ * A `ToolCall` paired with its outcome and execution metadata. Captured
+ * on `RunState.completedToolCalls` after a successful or failed run.
+ *
+ * @stable
+ */
+export interface CompletedToolCall<TOutput = unknown> {
+  readonly call: ToolCall;
+  readonly outcome: ToolOutcome<TOutput>;
+  readonly stepNumber: number;
+}

package/src/types/usage.ts

@@ -0,0 +1,120 @@
+/**
+ * Token / cost metrics for a single LLM call.
+ *
+ * `cost` is optional because the framework cannot compute it without a
+ * pricing snapshot - providers/middleware fill it in (e.g. through the
+ * separate `@graphorin/pricing` package) when the snapshot is available.
+ *
+ * @stable
+ */
+export interface Usage {
+  /**
+   * Total input tokens for the call, INCLUDING any prompt-cache reads and
+   * writes (`cachedReadTokens` / `cacheWriteTokens` are informational
+   * subsets, not additions). This matches the context size the model saw.
+   */
+  promptTokens: number;
+  completionTokens: number;
+  /**
+   * Reasoning tokens billed IN ADDITION to `completionTokens` (exclusive;
+   * adapters that receive an inclusive total split it so the sum stays
+   * exact). Cost formulas may add this to the output leg without
+   * double-counting.
+   */
+  reasoningTokens?: number;
+  /**
+   * Prompt tokens served from the provider's prompt cache (a subset of
+   * `promptTokens`), billed at the discounted cache-read rate.
+   */
+  cachedReadTokens?: number;
+  /**
+   * Prompt tokens written to the provider's prompt cache this call (a
+   * subset of `promptTokens`), billed at the cache-write premium where the
+   * provider charges one (Anthropic does; OpenAI does not report writes).
+   */
+  cacheWriteTokens?: number;
+  totalTokens: number;
+  cost?: Cost;
+}
+
+/**
+ * Money figure attached to a `Usage`. Always carries a 3-letter currency
+ * code so that consumers can perform aggregation safely.
+ *
+ * @stable
+ */
+export interface Cost {
+  /**
+   * Amount in WHOLE units of `currency` - for USD that is dollars, and
+   * fractional values are expected (a typical LLM call costs a fraction
+   * of a cent, e.g. `0.0042`). This is deliberately NOT "minor units" /
+   * cents (W-045): the canonical producer -
+   * `calculateCost` in `@graphorin/pricing` - and every consumer
+   * (`CostTracker` in `@graphorin/observability`, the memory
+   * consolidator's `costUsd` budget, persisted checkpoints) already
+   * operate in whole currency units, and sub-cent per-call figures make
+   * minor units impractical. Do not divide by 100.
+   */
+  amount: number;
+  /** ISO-4217 currency code; default `'USD'`. */
+  currency: string;
+}
+
+/**
+ * Per-model breakdown used by aggregators (e.g. `CostTracker` in
+ * `@graphorin/observability`).
+ *
+ * @stable
+ */
+export interface ModelUsage {
+  modelId: string;
+  promptTokens: number;
+  completionTokens: number;
+  reasoningTokens?: number;
+  cachedReadTokens?: number;
+  cacheWriteTokens?: number;
+  totalTokens: number;
+  cost?: Cost;
+  callCount: number;
+}
+
+/**
+ * A live accumulator of token / cost figures. Implementations live in
+ * `@graphorin/observability`. The contract sits here so every package
+ * (agent, workflow, server, …) can type a parameter as `UsageAccumulator`
+ * without taking an observability dependency.
+ *
+ * @stable
+ */
+export interface UsageAccumulator {
+  /** Current rolled-up totals across every model that has been added. */
+  readonly total: Usage;
+  /** Per-model breakdown; preserves call counts for observability. */
+  readonly byModel: ReadonlyMap<string, ModelUsage>;
+
+  /** Add a single LLM-call usage record under the given model id. */
+  add(modelId: string, usage: Usage): void;
+  /** Reset the accumulator to a zeroed state. */
+  reset(): void;
+  /** Render an immutable snapshot suitable for serialization / span attrs. */
+  snapshot(): UsageSnapshot;
+}
+
+/**
+ * Immutable, JSON-serializable snapshot of a `UsageAccumulator`.
+ *
+ * @stable
+ */
+export interface UsageSnapshot {
+  readonly total: Usage;
+  readonly byModel: readonly ModelUsage[];
+}
+
+/**
+ * Returns a fresh, zeroed `Usage` value.
+ *
+ * @stable
+ */
+export function zeroUsage(): Usage {
+  return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+}

package/src/types/workflow-event.ts

@@ -0,0 +1,132 @@
+/**
+ * Discriminated union of every event produced by `Workflow.execute(...)`
+ * and `Workflow.resume(...)`.
+ *
+ * Generic over `TState` so that downstream consumers can discriminate on
+ * the workflow's typed state shape.
+ *
+ * @stable
+ */
+export type WorkflowEvent<TState = unknown> =
+  | WorkflowStartEvent
+  | WorkflowStepStartEvent<TState>
+  | WorkflowStepEndEvent<TState>
+  | WorkflowTaskStartEvent
+  | WorkflowTaskEndEvent
+  | WorkflowChannelUpdateEvent<TState>
+  | WorkflowCheckpointWrittenEvent
+  | WorkflowSuspendedEvent<TState>
+  | WorkflowResumedEvent<TState>
+  | WorkflowEndEvent<TState>
+  | WorkflowErrorEvent
+  | WorkflowCustomEvent;
+
+/** @stable */
+export interface WorkflowStartEvent {
+  readonly type: 'workflow.start';
+  readonly threadId: string;
+  readonly workflowId: string;
+}
+
+/** @stable */
+export interface WorkflowStepStartEvent<TState = unknown> {
+  readonly type: 'workflow.step.start';
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+
+/** @stable */
+export interface WorkflowStepEndEvent<TState = unknown> {
+  readonly type: 'workflow.step.end';
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+
+/** @stable */
+export interface WorkflowTaskStartEvent {
+  readonly type: 'workflow.task.start';
+  readonly stepNumber: number;
+  readonly taskId: string;
+  readonly nodeName: string;
+}
+
+/** @stable */
+export interface WorkflowTaskEndEvent {
+  readonly type: 'workflow.task.end';
+  readonly stepNumber: number;
+  readonly taskId: string;
+  readonly nodeName: string;
+  readonly status: 'completed' | 'failed' | 'paused';
+  readonly durationMs: number;
+}
+
+/** @stable */
+export interface WorkflowChannelUpdateEvent<TState = unknown> {
+  readonly type: 'workflow.channel.update';
+  readonly stepNumber: number;
+  readonly channel: keyof TState & string;
+  readonly version: number;
+  /**
+   * The merged value, carried ONLY for `ephemeral` channels
+   * (workflow-07): their values are wiped from state before the next
+   * planning round, so this event is the one place a consumer can
+   * observe them. Persistent channels omit it - read the state instead.
+   */
+  readonly value?: unknown;
+}
+
+/** @stable */
+export interface WorkflowCheckpointWrittenEvent {
+  readonly type: 'workflow.checkpoint.written';
+  readonly checkpointId: string;
+  readonly stepNumber: number;
+}
+
+/**
+ * Workflow paused - for HITL approvals or programmatic `pause(value)`
+ * calls. Carries the value passed to `pause(...)` so the caller can
+ * choose how to surface the prompt to the user.
+ *
+ * @stable
+ */
+export interface WorkflowSuspendedEvent<TState = unknown> {
+  readonly type: 'workflow.suspended';
+  readonly threadId: string;
+  readonly stepNumber: number;
+  readonly state: TState;
+  readonly value: unknown;
+}
+
+/** @stable */
+export interface WorkflowResumedEvent<TState = unknown> {
+  readonly type: 'workflow.resumed';
+  readonly threadId: string;
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+
+/** @stable */
+export interface WorkflowEndEvent<TState = unknown> {
+  readonly type: 'workflow.end';
+  readonly threadId: string;
+  readonly state: TState;
+}
+
+/** @stable */
+export interface WorkflowErrorEvent {
+  readonly type: 'workflow.error';
+  readonly threadId: string;
+  readonly error: { readonly message: string; readonly code: string };
+}
+
+/**
+ * Application-defined event emitted from inside a workflow node via
+ * `ctx.emit(name, payload)`. The runtime never produces these on its own.
+ *
+ * @stable
+ */
+export interface WorkflowCustomEvent {
+  readonly type: 'workflow.custom';
+  readonly name: string;
+  readonly payload: unknown;
+}

package/src/utils/assert-never.ts

@@ -0,0 +1,24 @@
+/**
+ * Exhaustiveness helper. Place at the end of a `switch (...)` over a
+ * discriminated union: TypeScript narrows the operand to `never` if
+ * every variant is handled. Adding a new variant later turns the call
+ * site into a compile error - the regression net for our event unions.
+ *
+ * @example
+ * ```ts
+ * function describe(event: AgentEvent): string {
+ *   switch (event.type) {
+ *     case 'agent.start': return 'started';
+ *     case 'agent.end':   return 'ended';
+ *     // ... every other variant ...
+ *     default:
+ *       return assertNever(event, 'Unhandled AgentEvent variant');
+ *   }
+ * }
+ * ```
+ *
+ * @stable
+ */
+export function assertNever(value: never, message?: string): never {
+  throw new Error(message ?? `graphorin: unhandled discriminated-union variant: ${String(value)}`);
+}

package/src/utils/async-context.ts

@@ -0,0 +1,55 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Thin typed wrapper around Node's `AsyncLocalStorage`. Used to thread a
+ * tool-execution / request-scoped context through the async stack
+ * without explicit parameter passing.
+ *
+ * The wrapper exists because:
+ * - The Node API requires a fresh `AsyncLocalStorage<T>` per scope; this
+ *   helper centralizes the construction with consistent typing.
+ * - Downstream packages (security, tools) want a single canonical
+ *   constructor so that their `getStore()` code paths share the same
+ *   identity (matters for HMR / multi-realm setups).
+ *
+ * @stable
+ */
+export interface AsyncContext<T> {
+  /** Run `fn` inside a fresh scope carrying `value`. */
+  run<R>(value: T, fn: () => R): R;
+  /** Run `fn` inside a fresh scope carrying `value` (async-friendly). */
+  runAsync<R>(value: T, fn: () => Promise<R>): Promise<R>;
+  /** Get the value of the current scope, or `undefined` outside one. */
+  get(): T | undefined;
+  /** Replace the value of the current scope (advanced; rarely needed). */
+  enterWith(value: T): void;
+  /** Exit any in-flight scope (advanced; rarely needed). */
+  disable(): void;
+}
+
+/**
+ * Construct a typed `AsyncContext`. The optional `name` is surfaced in
+ * the diagnostics channel of `AsyncLocalStorage` (debugging only).
+ *
+ * @stable
+ */
+export function createAsyncContext<T>(_name?: string): AsyncContext<T> {
+  const als = new AsyncLocalStorage<T>();
+  return {
+    run<R>(value: T, fn: () => R): R {
+      return als.run(value, fn);
+    },
+    runAsync<R>(value: T, fn: () => Promise<R>): Promise<R> {
+      return als.run(value, fn);
+    },
+    get(): T | undefined {
+      return als.getStore();
+    },
+    enterWith(value: T): void {
+      als.enterWith(value);
+    },
+    disable(): void {
+      als.disable();
+    },
+  };
+}