@graphorin/core 0.6.1 → 0.7.0

package/src/contracts/provider.ts

@@ -0,0 +1,316 @@
+import type { Message, ReasoningContentMeta } from '../types/message.js';
+import type { Sensitivity } from '../types/sensitivity.js';
+import type { ToolCall } from '../types/tool-call.js';
+import type { Usage } from '../types/usage.js';
+import type { ReasoningContract, ReasoningRetention } from './reasoning-retention.js';
+
+/**
+ * Vendor-neutral LLM provider interface. Concrete adapters live in
+ * `@graphorin/provider` (and companion packages such as
+ * `@graphorin/provider-llamacpp-node`).
+ *
+ * Every provider exposes a `name` (used in spans / logs), the `modelId`
+ * it wraps, a static `capabilities` descriptor, and the two streaming /
+ * one-shot generation methods.
+ *
+ * @stable
+ */
+export interface Provider {
+  readonly name: string;
+  readonly modelId: string;
+  readonly capabilities: ProviderCapabilities;
+
+  /** Returns an async stream of fine-grained provider events. */
+  stream(req: ProviderRequest): AsyncIterable<ProviderEvent>;
+
+  /** Convenience wrapper that consumes the stream into a single result. */
+  generate(req: ProviderRequest): Promise<ProviderResponse>;
+
+  /** Optional: provider-native input token counter. */
+  countTokens?(req: ProviderRequest): Promise<number>;
+
+  /**
+   * Sensitivity tiers this provider is allowed to receive. Used by the
+   * ContextEngine sensitivity filter (D2) and the outbound redaction
+   * middleware (D3) to decide what content is safe to forward.
+   */
+  readonly acceptsSensitivity?: ReadonlyArray<Sensitivity>;
+}
+
+/**
+ * Static capability descriptor returned by `Provider.capabilities`.
+ *
+ * @stable
+ */
+export interface ProviderCapabilities {
+  readonly streaming: boolean;
+  readonly toolCalling: boolean;
+  readonly parallelToolCalls: boolean;
+  readonly multimodal: boolean;
+  readonly structuredOutput: boolean;
+  readonly reasoning: boolean;
+  /** Total context window in tokens. */
+  readonly contextWindow: number;
+  /** Maximum output tokens. */
+  readonly maxOutput: number;
+  /**
+   * How the provider treats reasoning content across consecutive
+   * `provider.stream(...)` calls. Drives the auto-detected default
+   * {@link ReasoningRetention} value when the caller does not pass
+   * an explicit override on the request.
+   *
+   * Adapters supplied with the framework declare this field; bespoke
+   * adapters that omit it are treated as `'optional'` (conservative
+   * `'strip'` default + WARN-once on first reasoning emission).
+   */
+  readonly reasoningContract?: ReasoningContract;
+}
+
+/**
+ * Opt-in prompt-cache breakpoint policy (core-provider-02).
+ *
+ * `breakpoints: 'auto'` asks the adapter to place provider-native cache
+ * anchors around the stable request prefix: the Anthropic path (via the
+ * vercel adapter) marks the first and last conversation messages with
+ * `cache_control: { type: 'ephemeral' }` so tools + system + the stable
+ * prefix are written once and read at ~0.1x input price on subsequent
+ * steps. Providers with automatic caching (OpenAI) or no cache concept
+ * ignore the policy. `ttl` maps to Anthropic's extended cache TTL.
+ *
+ * @stable
+ */
+export interface ProviderCachePolicy {
+  readonly breakpoints: 'auto' | 'none';
+  readonly ttl?: '5m' | '1h';
+}
+
+/**
+ * Provider-call request payload.
+ *
+ * @stable
+ */
+export interface ProviderRequest {
+  readonly messages: ReadonlyArray<Message>;
+  readonly tools?: ReadonlyArray<ToolDefinition>;
+  readonly toolChoice?: ToolChoice;
+  readonly outputType?: OutputSpec;
+  readonly systemMessage?: string;
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+  readonly providerOptions?: Readonly<Record<string, unknown>>;
+  readonly cachePolicy?: ProviderCachePolicy;
+  /**
+   * C7: live parent span for the provider call. Like `signal`, this is a
+   * runtime handle (never serialized): `withTracing` parents its
+   * provider.generate/stream span under it so a run's traces form one
+   * tree instead of disconnected fragments.
+   */
+  readonly parentSpan?: import('./tracer.js').AISpan;
+  readonly metadata?: ProviderRequestMetadata;
+  /**
+   * Per-request override of the provider's auto-detected
+   * {@link ReasoningRetention} default. Only honoured when the
+   * provider declares `reasoningContract` of `'round-trip-required'`
+   * or `'optional'`; hidden-chain-of-thought providers (e.g.
+   * `'hidden'`) always strip and emit one WARN per process when an
+   * incompatible override is supplied.
+   */
+  readonly reasoningRetention?: ReasoningRetention;
+}
+
+/**
+ * Per-request metadata used by tracing and auditing layers.
+ *
+ * @stable
+ */
+export interface ProviderRequestMetadata {
+  readonly sessionId?: string;
+  readonly agentId?: string;
+  readonly userId?: string;
+  readonly runId?: string;
+  readonly stepNumber?: number;
+}
+
+/**
+ * One-shot response shape returned by `Provider.generate(...)`.
+ *
+ * @stable
+ */
+export interface ProviderResponse {
+  readonly text?: string;
+  /**
+   * Tool invocations the model requested. W-127: reuses the canonical
+   * {@link ToolCall} (the inline shape here was structurally identical
+   * and only invited drift).
+   */
+  readonly toolCalls?: ReadonlyArray<ToolCall>;
+  readonly usage: Usage;
+  readonly finishReason: FinishReason;
+  readonly providerMetadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Reason a provider call ended.
+ *
+ * @stable
+ */
+export type FinishReason =
+  | 'stop'
+  | 'length'
+  | 'tool-calls'
+  | 'content-filter'
+  | 'error'
+  | 'aborted';
+
+/**
+ * Streamed provider event. Shape matches the wire-stable subset of the
+ * provider event union - adapters hide vendor specifics.
+ *
+ * @stable
+ */
+export type ProviderEvent =
+  | { readonly type: 'stream-start'; readonly metadata: ResponseMetadata }
+  | { readonly type: 'reasoning-delta'; readonly delta: string }
+  /**
+   * Closes the current reasoning block (W-024). Deltas stay textual;
+   * this terminator carries the provider's opaque round-trip metadata
+   * (e.g. the Anthropic thinking-block `signature`, or `data` for a
+   * redacted block) so multi-step tool use with extended thinking can
+   * replay the block byte-equal on the next request. Adapters without
+   * per-block structure simply never emit it - consumers fall back to
+   * collapsing the deltas.
+   */
+  | { readonly type: 'reasoning-end'; readonly meta?: ReasoningContentMeta }
+  | { readonly type: 'text-delta'; readonly delta: string }
+  | { readonly type: 'tool-call-start'; readonly toolCallId: string; readonly toolName: string }
+  | {
+      readonly type: 'tool-call-input-delta';
+      readonly toolCallId: string;
+      readonly argsDelta: string;
+    }
+  | { readonly type: 'tool-call-end'; readonly toolCallId: string; readonly finalArgs: unknown }
+  | { readonly type: 'file'; readonly mimeType: string; readonly data: Uint8Array }
+  | { readonly type: 'source'; readonly uri: string; readonly title?: string }
+  | { readonly type: 'finish'; readonly finishReason: FinishReason; readonly usage: Usage }
+  | { readonly type: 'error'; readonly error: ProviderError };
+
+/**
+ * Metadata attached to the first `stream-start` event of a stream.
+ *
+ * @stable
+ */
+export interface ResponseMetadata {
+  readonly providerName: string;
+  readonly modelId: string;
+  readonly responseId?: string;
+  readonly createdAt?: string;
+}
+
+/**
+ * Provider-side error shape carried by `provider-error` events.
+ *
+ * @stable
+ */
+export interface ProviderError {
+  readonly kind: ProviderErrorKind;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+/** @stable */
+export type ProviderErrorKind =
+  | 'rate-limit'
+  | 'capacity'
+  | 'context-length'
+  | 'transient'
+  | 'invalid-request'
+  | 'unauthorized'
+  | 'content-filter'
+  | 'unknown';
+
+/**
+ * Tool description shipped with a provider request. Implementations
+ * convert the user's Zod schema to a JSON Schema 7 fragment.
+ *
+ * @stable
+ */
+export interface ToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  /**
+   * A5: the tool's output schema (JSON Schema), when declared. The agent runtime
+   * populates it from `Tool.outputSchema`; structured-output providers and typed
+   * code-mode use it to validate / type the tool's result. Absent when the tool
+   * declares no output schema.
+   */
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
+  /**
+   * Worked examples surfaced to the provider alongside the schema. The
+   * agent runtime populates this from the tool's `examples` when they
+   * are eagerly rendered (see `Tool.examplesEagerlyRendered`); it is
+   * bounded to ≤5 and absent when the tool declares none or defers them.
+   * Implementations MAY fold these into the model-facing tool description.
+   */
+  readonly examples?: ReadonlyArray<ToolDefinitionExample>;
+}
+
+/**
+ * A single worked example as projected onto the provider wire contract -
+ * a serializable, schema-agnostic view of a `ToolExample`. `input` /
+ * `output` carry the example's already-parsed values; `comment` is the
+ * optional rationale shown to the model.
+ *
+ * @stable
+ */
+export interface ToolDefinitionExample {
+  readonly input: unknown;
+  readonly output: unknown;
+  readonly comment?: string;
+}
+
+/**
+ * Tool selection strategy.
+ *
+ * @stable
+ */
+export type ToolChoice = 'auto' | 'required' | 'none' | { readonly tool: string };
+
+/**
+ * Output type specification for structured / typed responses. Concrete
+ * Zod-based variants live in the runtime packages.
+ *
+ * @stable
+ */
+export interface OutputSpec {
+  readonly kind: 'text' | 'structured';
+  readonly description?: string;
+  readonly jsonSchema?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Provider middleware: a function that wraps a `Provider` and returns a
+ * new `Provider` with extra behaviour (retry, fallback, redaction, …).
+ *
+ * Middleware ordering is enforced by the runtime per the documented
+ * inside-out chain (innermost adapter → ... → outermost retry / observer).
+ *
+ * @stable
+ */
+export type ProviderMiddleware = (next: Provider) => Provider;
+
+/**
+ * Type signature for the canonical middleware composer (the runtime
+ * implementation lives in `@graphorin/provider`).
+ *
+ * The concrete composer guarantees a deterministic ordering - order of
+ * arguments mirrors order of execution from outermost to innermost - and
+ * is the only blessed entry point for chaining middleware in
+ * `@graphorin/*` code (per the security-first ordering rule).
+ *
+ * @stable
+ */
+export type ComposeProviderMiddleware = (
+  middlewares: ReadonlyArray<ProviderMiddleware>,
+) => ProviderMiddleware;

package/src/contracts/reasoning-retention.ts

@@ -0,0 +1,52 @@
+/**
+ * How a provider treats reasoning content across consecutive
+ * `provider.stream(...)` calls of the same agent + same model + same
+ * run.
+ *
+ * Three independent lifecycle operations exist for reasoning content
+ * in the provider layer:
+ *
+ * 1. **Intra-loop transmission** - controlled by this enum. Default is
+ *    auto-detected per provider:
+ *    - Hidden chain-of-thought providers (e.g. OpenAI o1/o3, Google
+ *      Gemini reasoning): `'strip'`.
+ *    - Round-trip-required providers (e.g. Anthropic Claude tool-use
+ *      with thinking blocks): `'pass-through-claude'`.
+ * 2. **Sub-agent handoff transmission** - always strips reasoning
+ *    regardless of this setting; lives in
+ *    `@graphorin/sessions` handoff filters.
+ * 3. **Prompt-cache key calculation** - reasoning blocks are excluded
+ *    from cache-key hashes but included in outbound transmission.
+ *
+ * @stable
+ */
+export type ReasoningRetention =
+  /**
+   * Drop reasoning content from the next request body. Default for
+   * hidden-chain-of-thought providers and the conservative default
+   * for unknown providers.
+   */
+  | 'strip'
+  /**
+   * Round-trip Anthropic-shaped thinking blocks
+   * (`signature` / `data` / `text` fields) byte-equal to the previous
+   * assistant message.
+   */
+  | 'pass-through-claude'
+  /**
+   * Round-trip every reasoning content part the provider returns
+   * regardless of vendor shape. Useful for custom providers that
+   * declare `reasoningContract: 'optional'` and still benefit from
+   * preserving the chain.
+   */
+  | 'pass-through-all';
+
+/**
+ * Capability declaration on `ProviderCapabilities` describing how the
+ * provider treats reasoning content. The field is auto-populated per
+ * provider family by the adapter; consumers use it to infer the
+ * default {@link ReasoningRetention} value for a request.
+ *
+ * @stable
+ */
+export type ReasoningContract = 'hidden' | 'round-trip-required' | 'optional';

package/src/contracts/redaction-validator.ts

@@ -0,0 +1,56 @@
+import type { Sensitivity } from '../types/sensitivity.js';
+
+/**
+ * Wraps every observability exporter (OTLP, console, JSONL replay log,
+ * …) and refuses to forward attributes that exceed the configured
+ * sensitivity floor or that contain matched secret / PII patterns.
+ *
+ * Concrete patterns and the default policy live in
+ * `@graphorin/observability`; the interface lives here so every package
+ * (server, agent, workflow, …) can require a `RedactionValidator` in its
+ * config without taking an observability dependency.
+ *
+ * @stable
+ */
+export interface RedactionValidator {
+  /** Identifier of the policy in use (`'default-deny-internal'`, …). */
+  readonly id: string;
+  /** Lowest tier that may pass through the validator. */
+  readonly minTier: Sensitivity;
+  /**
+   * Validate (and optionally rewrite) an attribute payload. Returns the
+   * sanitized value or `null` if the entire record must be dropped.
+   */
+  validate(input: RedactionInput): RedactionOutput | null;
+}
+
+/**
+ * Input handed to `RedactionValidator.validate(...)`.
+ *
+ * @stable
+ */
+export interface RedactionInput {
+  readonly value: unknown;
+  /** Tier declared by the upstream caller for this value. */
+  readonly tier: Sensitivity;
+  /** Optional context describing where the value originated. */
+  readonly context?: {
+    readonly attribute?: string;
+    readonly spanType?: string;
+    readonly origin?: string;
+  };
+}
+
+/**
+ * Result of `RedactionValidator.validate(...)` - either the sanitized
+ * payload (possibly equal to the input) or `null` if the value must be
+ * dropped entirely.
+ *
+ * @stable
+ */
+export interface RedactionOutput {
+  readonly value: unknown;
+  readonly tier: Sensitivity;
+  /** List of pattern names matched while validating. */
+  readonly matched?: ReadonlyArray<string>;
+}

package/src/contracts/sandbox.ts

@@ -0,0 +1,70 @@
+/**
+ * Pluggable sandbox interface for tool / skill execution. Concrete
+ * implementations live in `@graphorin/security` (worker-threads,
+ * isolated-vm, docker, none).
+ *
+ * @stable
+ */
+export interface Sandbox {
+  /** Identifier of the sandbox flavor (`'worker-threads'`, `'isolated-vm'`, …). */
+  readonly id: string;
+  run<TInput, TOutput>(
+    code: SandboxCode,
+    opts: SandboxRunOptions<TInput>,
+  ): Promise<SandboxResult<TOutput>>;
+}
+
+/**
+ * Description of the code to run in the sandbox. Either a JS source
+ * string, a path to a JS file, or a fully-qualified handler reference
+ * resolved by the sandbox implementation.
+ *
+ * @stable
+ */
+export type SandboxCode =
+  | { readonly kind: 'source'; readonly source: string; readonly filename?: string }
+  | { readonly kind: 'file'; readonly path: string }
+  | { readonly kind: 'handler'; readonly module: string; readonly export: string };
+
+/**
+ * Per-call sandbox options.
+ *
+ * @stable
+ */
+export interface SandboxRunOptions<TInput = unknown> {
+  readonly input: TInput;
+  readonly timeoutMs?: number;
+  readonly maxMemoryMb?: number;
+  /**
+   * Allowlist of environment variables visible inside the sandbox.
+   * Sandboxed code never inherits the host `process.env`; entries
+   * given here are the only ones defined.
+   */
+  readonly env?: Readonly<Record<string, string>>;
+  readonly allowNetwork?: boolean;
+  readonly allowFs?: boolean;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Result of a sandboxed run. The shape mirrors the `ToolOutcome` union -
+ * the runtime maps `SandboxResult` to `ToolOutcome` after the call.
+ *
+ * @stable
+ */
+export type SandboxResult<TOutput = unknown> =
+  | { readonly ok: true; readonly output: TOutput; readonly durationMs: number }
+  | {
+      readonly ok: false;
+      readonly error: {
+        readonly kind:
+          | 'timeout'
+          | 'memory-exceeded'
+          | 'sandbox-violation'
+          | 'aborted'
+          | 'execution-failed';
+        readonly message: string;
+        readonly cause?: unknown;
+      };
+      readonly durationMs: number;
+    };

package/src/contracts/secret-ref.ts

@@ -0,0 +1,22 @@
+/**
+ * Parsed shape of a `SecretRef` URI (`scheme:[//authority]/path[?query][#fragment]`).
+ *
+ * The full grammar lives in `@graphorin/security`; the type lives here so
+ * downstream packages can carry parsed refs without a security dependency.
+ *
+ * @stable
+ */
+export interface SecretRef {
+  /** Original URI string as supplied by the caller. */
+  readonly raw: string;
+  /** Lowercased scheme (`'env'`, `'keyring'`, `'file'`, …). */
+  readonly scheme: string;
+  /** Optional authority component (e.g. `host[:port]`). */
+  readonly authority?: string;
+  /** Path component (without the leading slash for opaque schemes). */
+  readonly path: string;
+  /** Parsed query parameters (already percent-decoded). */
+  readonly query: Readonly<Record<string, string>>;
+  /** Optional fragment (e.g. JSON-Pointer for nested fields). */
+  readonly fragment?: string;
+}

package/src/contracts/secret-value.ts

@@ -0,0 +1,117 @@
+/**
+ * Cross-realm symbol used to brand `SecretValue` instances. Implementations
+ * (e.g. the wrapper class shipped from `@graphorin/security`) attach this
+ * symbol so that `isSecretValue(...)` works across realms (Worker threads,
+ * sandboxes, etc.).
+ *
+ * @stable
+ */
+export const SECRET_VALUE_BRAND: unique symbol = Symbol.for('graphorin.SecretValue');
+
+/**
+ * Well-known symbol used by `node:util.inspect()` to format the wrapper.
+ * Re-exported here so downstream packages can reference it without taking
+ * an unconditional dependency on `node:util`.
+ *
+ * Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.
+ *
+ * @stable
+ */
+export const NODEJS_INSPECT_CUSTOM: unique symbol = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Runtime-safe wrapper around an opaque secret (API key, token, password).
+ *
+ * The shape declared here is the **interface contract**: the concrete
+ * wrapper class lives in `@graphorin/security`. Downstream packages typing
+ * a parameter as `SecretValue` therefore avoid taking a security
+ * dependency.
+ *
+ * Note: `SecretValue` is **not** a TypeScript branded primitive - it is
+ * a full wrapper class with explicit leakage barriers
+ * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).
+ * Any conforming implementation must ensure that:
+ *
+ * - String coercion (`String(s)`, `` `${s}` ``, `s + ''`, …) yields a
+ *   redacted placeholder, **not** the underlying value.
+ * - JSON serialization (`JSON.stringify({ apiKey: s })`) yields a
+ *   redacted placeholder.
+ * - Inspector output (`util.inspect(s)`) yields
+ *   `'SecretValue([REDACTED])'`.
+ * - The underlying value is only reachable through `.use(fn)`,
+ *   `.useBuffer(fn)` or the audited `.reveal()` escape hatch.
+ *
+ * @stable
+ */
+export interface SecretValue {
+  /** Number of bytes in the wrapped value. Safe to log. */
+  readonly length: number;
+
+  /**
+   * Run `fn` with the unwrapped string and return its result. Preferred
+   * over `.reveal()` because it scopes the unwrapped value to a single
+   * synchronous / asynchronous turn.
+   */
+  use<T>(fn: (raw: string) => T | Promise<T>): Promise<T>;
+
+  /**
+   * Run `fn` with the unwrapped value as a `Buffer`. Useful for binary
+   * secrets (encryption keys, HMAC keys) where round-tripping through a
+   * V8 string would defeat the wrapper's hygiene.
+   */
+  useBuffer<T>(fn: (buf: Buffer) => T | Promise<T>): Promise<T>;
+
+  /**
+   * One-shot reveal as a string. Audited by the implementation. Prefer
+   * `.use(fn)` whenever possible.
+   */
+  reveal(): string;
+
+  /**
+   * Best-effort zeroization of the underlying buffer. Does not affect
+   * derived V8 strings already created via `.use(fn)` / `.reveal()`.
+   */
+  dispose(): void;
+
+  /** Cross-realm brand. Implementations set this to `SECRET_VALUE_BRAND`. */
+  readonly [SECRET_VALUE_BRAND]: true;
+
+  /** Leakage barrier for ToPrimitive coercion. Returns the placeholder. */
+  [Symbol.toPrimitive](hint: string): string | number;
+
+  /** Leakage barrier for `JSON.stringify(...)`. Returns the placeholder. */
+  toJSON(): string;
+
+  /**
+   * Leakage barrier for `node:util.inspect(...)`. Returns the placeholder
+   * (`'SecretValue([REDACTED])'`) so that REPL / `console.log` /
+   * structured-logger output never reveals the underlying value.
+   */
+  [NODEJS_INSPECT_CUSTOM](depth?: number, opts?: unknown, inspect?: unknown): string;
+}
+
+/**
+ * Static helpers expected on every concrete `SecretValue` constructor.
+ *
+ * @stable
+ */
+export interface SecretValueStatic {
+  /** Cross-realm safe type guard. */
+  isSecretValue(value: unknown): value is SecretValue;
+  /** Constant-time equality. */
+  timingSafeEquals(a: SecretValue, b: SecretValue): boolean;
+  /** Construct from a plain string. */
+  fromString(raw: string, opts?: SecretValueOptions): SecretValue;
+  /** Construct from a Node.js `Buffer`. */
+  fromBuffer(buf: Buffer, opts?: SecretValueOptions): SecretValue;
+}
+
+/**
+ * Optional metadata attached to a freshly constructed `SecretValue`.
+ *
+ * @stable
+ */
+export interface SecretValueOptions {
+  /** Free-form provenance string for the audit log. */
+  readonly source?: { readonly resolver?: string; readonly ref?: string };
+}