@graphorin/core 0.5.0

package/dist/contracts/oauth-server-store.d.ts

@@ -0,0 +1,81 @@
+//#region src/contracts/oauth-server-store.d.ts
+/**
+ * Persisted metadata for an OAuth server registration. The framework
+ * never stores raw token material here — the access, refresh, id, and
+ * client-secret tokens live in the {@link SecretsStore} and this
+ * record only holds the {@link SecretRef} URIs that resolve them.
+ *
+ * Schema mirrors the canonical `oauth_servers` SQLite table provided
+ * by `@graphorin/store-sqlite`.
+ *
+ * @stable
+ */
+interface OAuthServerRecord {
+  /** Stable, human-readable identifier (e.g. `'linear-mcp'`). */
+  readonly id: string;
+  /** Base URL of the OAuth-protected resource server (e.g. MCP endpoint). */
+  readonly serverUrl: string;
+  /** Authorization-server `authorization_endpoint`. */
+  readonly authorizationEndpoint?: string;
+  /** Authorization-server `token_endpoint`. */
+  readonly tokenEndpoint?: string;
+  /** Authorization-server `registration_endpoint` (RFC 7591). */
+  readonly registrationEndpoint?: string;
+  /** Authorization-server `revocation_endpoint` (RFC 7009). */
+  readonly revocationEndpoint?: string;
+  /** Authorization-server `device_authorization_endpoint` (RFC 8628). */
+  readonly deviceAuthorizationEndpoint?: string;
+  /** Issuer identifier reported in the discovery response. */
+  readonly issuer?: string;
+  /** Public client identifier; safe to log. */
+  readonly clientId: string;
+  /** {@link SecretRef} URI for the confidential-client secret. */
+  readonly clientSecretRef?: string;
+  /** {@link SecretRef} URI for the access token. */
+  readonly accessTokenRef?: string;
+  /** {@link SecretRef} URI for the refresh token. */
+  readonly refreshTokenRef?: string;
+  /** {@link SecretRef} URI for the OIDC ID token. */
+  readonly idTokenRef?: string;
+  /** Epoch milliseconds when the access token stops being valid. */
+  readonly expiresAt?: number;
+  /** Granted scopes (space-separated string per the OAuth spec). */
+  readonly scope?: string;
+  /** Redirect URI that was used during the most recent code flow. */
+  readonly redirectUri?: string;
+  /** Whether the client was registered via Dynamic Client Registration. */
+  readonly registeredVia?: 'dcr' | 'manual';
+  /** Epoch milliseconds of the last successful refresh. */
+  readonly lastRefreshedAt?: number;
+  /** Last error string captured from a failing refresh attempt. */
+  readonly lastRefreshError?: string;
+  /** Epoch milliseconds when the record was first created. */
+  readonly createdAt: number;
+  /** Epoch milliseconds when the record was last updated. */
+  readonly updatedAt: number;
+}
+/**
+ * Pluggable storage for OAuth server registrations + token metadata.
+ *
+ * The default implementation lives in `@graphorin/store-sqlite`
+ * (`oauth_servers` table). `@graphorin/security` ships an in-memory
+ * implementation that callers can use until the SQLite-backed store
+ * is wired up.
+ *
+ * @stable
+ */
+interface OAuthServerStore {
+  /** Insert or replace the record for `id`. */
+  put(record: OAuthServerRecord): Promise<void>;
+  /** Read the record for `id`, returning `null` when absent. */
+  get(id: string): Promise<OAuthServerRecord | null>;
+  /** Snapshot of all stored records, ordered by `id`. */
+  list(): Promise<ReadonlyArray<OAuthServerRecord>>;
+  /** Apply a partial update to the record at `id`. */
+  update(id: string, patch: Partial<OAuthServerRecord>): Promise<OAuthServerRecord>;
+  /** Remove the record for `id`. */
+  delete(id: string): Promise<void>;
+}
+//#endregion
+export { OAuthServerRecord, OAuthServerStore };
+//# sourceMappingURL=oauth-server-store.d.ts.map

package/dist/contracts/oauth-server-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-server-store.d.ts","names":[],"sources":["../../src/contracts/oauth-server-store.ts"],"sourcesContent":[],"mappings":";;AAWA;AAuDA;;;;;;;;;AAQ4B,UA/DX,iBAAA,CA+DW;EAAqC;EAAR,SAAA,EAAA,EAAA,MAAA;EAEnC;EAAO,SAAA,SAAA,EAAA,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAVZ,gBAAA;;cAEH,oBAAoB;;mBAEf,QAAQ;;UAEjB,QAAQ,cAAc;;4BAEJ,QAAQ,qBAAqB,QAAQ;;sBAE3C"}

package/dist/contracts/preferred-model.d.ts

@@ -0,0 +1,60 @@
+//#region src/contracts/preferred-model.d.ts
+/**
+ * Cost-tier vocabulary for declaring a preferred model on a tool or
+ * agent. Provider-agnostic at the tool-author level; the operator-side
+ * `Agent.modelTierMap?: Partial<Record<ModelHint, ModelSpec>>` mapping
+ * resolves the hint to a concrete provider per agent.
+ *
+ * The three tiers describe canonical cloud-provider price-quality
+ * envelopes circa 2026:
+ *
+ * - `'fast'`     — low-cost / low-latency / file-navigation /
+ *   parameter-extraction / low-stakes calls.
+ * - `'balanced'` — median cost-quality; the default tier for most
+ *   tools.
+ * - `'smart'`    — high-quality / high-stakes / reasoning-heavy /
+ *   summarization / code-review calls.
+ *
+ * The vocabulary is Graphorin's own design — no third-party routing-
+ * guide attribution leaks into the public surface. Per-provider
+ * dispatch lives in `@graphorin/provider/model-tier/classify.ts`.
+ *
+ * @stable
+ */
+type ModelHint = 'fast' | 'balanced' | 'smart';
+/**
+ * Discriminated string-literal triple for type-level work.
+ *
+ * @stable
+ */
+declare const MODEL_HINTS: readonly ModelHint[];
+/**
+ * Forward-declared shape of `Provider`. Re-declared here as a minimal
+ * structural type so this module stays cycle-free with respect to
+ * `./provider.ts` and downstream consumers can use `ModelSpec` without
+ * importing the heavier `Provider` interface.
+ *
+ * @internal
+ */
+interface ProviderLike {
+  readonly name: string;
+  readonly modelId: string;
+}
+/**
+ * Concrete provider declaration used at site of the per-tool hint
+ * override (Phase 07), the per-tier mapping
+ * (`Agent.modelTierMap`, Phase 12), and the agent-level fallback chain
+ * (`Agent.fallbackModels`, Phase 12).
+ *
+ * The shape is unified deliberately so operators learn one thing and
+ * use it three places.
+ *
+ * @stable
+ */
+type ModelSpec = ProviderLike | {
+  readonly provider: ProviderLike;
+  readonly model: string;
+};
+//#endregion
+export { MODEL_HINTS, ModelHint, ModelSpec, ProviderLike };
+//# sourceMappingURL=preferred-model.d.ts.map

package/dist/contracts/preferred-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferred-model.d.ts","names":[],"sources":["../../src/contracts/preferred-model.ts"],"sourcesContent":[],"mappings":";;AAsBA;AAOA;AAUA;AAgBA;;;;;;;;;;;;;;;;;;KAjCY,SAAA;;;;;;cAOC,sBAAsB;;;;;;;;;UAUlB,YAAA;;;;;;;;;;;;;;;KAgBL,SAAA,GAAY;qBAAoC"}

package/dist/contracts/preferred-model.js

@@ -0,0 +1,15 @@
+//#region src/contracts/preferred-model.ts
+/**
+* Discriminated string-literal triple for type-level work.
+*
+* @stable
+*/
+const MODEL_HINTS = [
+	"fast",
+	"balanced",
+	"smart"
+];
+
+//#endregion
+export { MODEL_HINTS };
+//# sourceMappingURL=preferred-model.js.map

package/dist/contracts/preferred-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferred-model.js","names":["MODEL_HINTS: readonly ModelHint[]"],"sources":["../../src/contracts/preferred-model.ts"],"sourcesContent":["/**\n * Cost-tier vocabulary for declaring a preferred model on a tool or\n * agent. Provider-agnostic at the tool-author level; the operator-side\n * `Agent.modelTierMap?: Partial<Record<ModelHint, ModelSpec>>` mapping\n * resolves the hint to a concrete provider per agent.\n *\n * The three tiers describe canonical cloud-provider price-quality\n * envelopes circa 2026:\n *\n * - `'fast'`     — low-cost / low-latency / file-navigation /\n *   parameter-extraction / low-stakes calls.\n * - `'balanced'` — median cost-quality; the default tier for most\n *   tools.\n * - `'smart'`    — high-quality / high-stakes / reasoning-heavy /\n *   summarization / code-review calls.\n *\n * The vocabulary is Graphorin's own design — no third-party routing-\n * guide attribution leaks into the public surface. Per-provider\n * dispatch lives in `@graphorin/provider/model-tier/classify.ts`.\n *\n * @stable\n */\nexport type ModelHint = 'fast' | 'balanced' | 'smart';\n\n/**\n * Discriminated string-literal triple for type-level work.\n *\n * @stable\n */\nexport const MODEL_HINTS: readonly ModelHint[] = ['fast', 'balanced', 'smart'] as const;\n\n/**\n * Forward-declared shape of `Provider`. Re-declared here as a minimal\n * structural type so this module stays cycle-free with respect to\n * `./provider.ts` and downstream consumers can use `ModelSpec` without\n * importing the heavier `Provider` interface.\n *\n * @internal\n */\nexport interface ProviderLike {\n  readonly name: string;\n  readonly modelId: string;\n}\n\n/**\n * Concrete provider declaration used at site of the per-tool hint\n * override (Phase 07), the per-tier mapping\n * (`Agent.modelTierMap`, Phase 12), and the agent-level fallback chain\n * (`Agent.fallbackModels`, Phase 12).\n *\n * The shape is unified deliberately so operators learn one thing and\n * use it three places.\n *\n * @stable\n */\nexport type ModelSpec = ProviderLike | { readonly provider: ProviderLike; readonly model: string };\n"],"mappings":";;;;;;AA6BA,MAAaA,cAAoC;CAAC;CAAQ;CAAY;CAAQ"}

package/dist/contracts/provider.d.ts

@@ -0,0 +1,272 @@
+import { Sensitivity } from "../types/sensitivity.js";
+import { Message } from "../types/message.js";
+import { Usage } from "../types/usage.js";
+import { ReasoningContract, ReasoningRetention } from "./reasoning-retention.js";
+
+//#region src/contracts/provider.d.ts
+
+/**
+ * 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
+ */
+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
+ */
+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;
+}
+/**
+ * Provider-call request payload.
+ *
+ * @stable
+ */
+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 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
+ */
+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
+ */
+interface ProviderResponse {
+  readonly text?: string;
+  readonly toolCalls?: ReadonlyArray<{
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+  }>;
+  readonly usage: Usage;
+  readonly finishReason: FinishReason;
+  readonly providerMetadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Reason a provider call ended.
+ *
+ * @stable
+ */
+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
+ */
+type ProviderEvent = {
+  readonly type: 'stream-start';
+  readonly metadata: ResponseMetadata;
+} | {
+  readonly type: 'reasoning-delta';
+  readonly delta: string;
+} | {
+  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
+ */
+interface ResponseMetadata {
+  readonly providerName: string;
+  readonly modelId: string;
+  readonly responseId?: string;
+  readonly createdAt?: string;
+}
+/**
+ * Provider-side error shape carried by `provider-error` events.
+ *
+ * @stable
+ */
+interface ProviderError {
+  readonly kind: ProviderErrorKind;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/** @stable */
+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
+ */
+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
+ */
+interface ToolDefinitionExample {
+  readonly input: unknown;
+  readonly output: unknown;
+  readonly comment?: string;
+}
+/**
+ * Tool selection strategy.
+ *
+ * @stable
+ */
+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
+ */
+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
+ */
+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
+ */
+type ComposeProviderMiddleware = (middlewares: ReadonlyArray<ProviderMiddleware>) => ProviderMiddleware;
+//#endregion
+export { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample };
+//# sourceMappingURL=provider.d.ts.map

package/dist/contracts/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","names":[],"sources":["../../src/contracts/provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAgBA;;;;;;;;;AAYsC,UAZrB,QAAA,CAYqB;EAOQ,SAAA,IAAA,EAAA,MAAA;EAAd,SAAA,OAAA,EAAA,MAAA;EAAa,SAAA,YAAA,EAhBpB,oBAgBoB;EAQ5B;EA6BA,MAAA,CAAA,GAAA,EAlDH,eAkDkB,CAAA,EAlDA,aAkDA,CAlDc,aAkDd,CAAA;EACG;EAAd,QAAA,CAAA,GAAA,EAhDL,eAgDK,CAAA,EAhDa,OAgDb,CAhDqB,gBAgDrB,CAAA;EACY;EAAd,WAAA,EAAA,GAAA,EA9CC,eA8CD,CAAA,EA9CmB,OA8CnB,CAAA,MAAA,CAAA;EACK;;;;;EAOF,SAAA,kBAAA,CAAA,EA/CU,aA+CV,CA/CwB,WA+CxB,CAAA;;;AAiBtB;AAaA;;;AAQyB,UA7ER,oBAAA,CA6EQ;EACc,SAAA,SAAA,EAAA,OAAA;EAAT,SAAA,WAAA,EAAA,OAAA;EAAQ,SAAA,iBAAA,EAAA,OAAA;EAQ1B,SAAA,UAAY,EAAA,OAAA;EAcZ,SAAA,gBAAa,EAAA,OAAA;EAC+B,SAAA,SAAA,EAAA,OAAA;EAUe;EAEjB,SAAA,aAAA,EAAA,MAAA;EAA8B;EACtC,SAAA,SAAA,EAAA,MAAA;EAAa;AAO3D;AAYA;AAOA;AAgBA;;;;;;EAkBsB,SAAA,iBAAA,CAAA,EAzJS,iBAyJT;;AAWtB;AAWA;AAQA;AAeA;AAaA;AAC6B,UA5MZ,eAAA,CA4MY;EAAd,SAAA,QAAA,EA3MM,aA2MN,CA3MoB,OA2MpB,CAAA;EACV,SAAA,KAAA,CAAA,EA3Mc,aA2Md,CA3M4B,cA2M5B,CAAA;EAAkB,SAAA,UAAA,CAAA,EA1MC,UA0MD;wBAzMC;;;;oBAIJ;6BACS,SAAS;sBAChB;;;;;;;;;gCASU;;;;;;;UAQf,uBAAA;;;;;;;;;;;;UAaA,gBAAA;;uBAEM;;;;;kBAKL;yBACO;8BACK,SAAS;;;;;;;KAQ3B,YAAA;;;;;;;KAcA,aAAA;;qBAC4C;;;;;;;;;;;;;;;;;;;;;;iBAUe;;;;;;;yBAEjB;kBAA8B;;;kBACtC;;;;;;;UAO7B,gBAAA;;;;;;;;;;;UAYA,aAAA;iBACA;;;;;KAML,iBAAA;;;;;;;UAgBK,cAAA;;;wBAGO,SAAS;;;;;;;0BAOP,SAAS;;;;;;;;sBAQb,cAAc;;;;;;;;;;UAWnB,qBAAA;;;;;;;;;;KAWL,UAAA;;;;;;;;;UAQK,UAAA;;;wBAGO,SAAS;;;;;;;;;;;KAYrB,kBAAA,UAA4B,aAAa;;;;;;;;;;;;KAazC,yBAAA,iBACG,cAAc,wBACxB"}

package/dist/contracts/reasoning-retention.d.ts

@@ -0,0 +1,53 @@
+//#region src/contracts/reasoning-retention.d.ts
+/**
+ * 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
+ */
+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
+ */
+type ReasoningContract = 'hidden' | 'round-trip-required' | 'optional';
+//#endregion
+export { ReasoningContract, ReasoningRetention };
+//# sourceMappingURL=reasoning-retention.d.ts.map

package/dist/contracts/reasoning-retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-retention.d.ts","names":[],"sources":["../../src/contracts/reasoning-retention.ts"],"sourcesContent":[],"mappings":";;AAsBA;AA6BA;;;;;;;;;;;;;;;;;;;;KA7BY,kBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KA6BA,iBAAA"}

package/dist/contracts/redaction-validator.d.ts

@@ -0,0 +1,59 @@
+import { Sensitivity } from "../types/sensitivity.js";
+
+//#region src/contracts/redaction-validator.d.ts
+
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+interface RedactionOutput {
+  readonly value: unknown;
+  readonly tier: Sensitivity;
+  /** List of pattern names matched while validating. */
+  readonly matched?: ReadonlyArray<string>;
+}
+//#endregion
+export { RedactionInput, RedactionOutput, RedactionValidator };
+//# sourceMappingURL=redaction-validator.d.ts.map

package/dist/contracts/redaction-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction-validator.d.ts","names":[],"sources":["../../src/contracts/redaction-validator.ts"],"sourcesContent":[],"mappings":";;;;;;AAcA;;;;;AAiBA;AAmBA;;;;UApCiB,kBAAA;;;;oBAIG;;;;;kBAKF,iBAAiB;;;;;;;UAQlB,cAAA;;;iBAGA;;;;;;;;;;;;;;;UAgBA,eAAA;;iBAEA;;qBAEI"}

package/dist/contracts/sandbox.d.ts

@@ -0,0 +1,73 @@
+//#region src/contracts/sandbox.d.ts
+/**
+ * Pluggable sandbox interface for tool / skill execution. Concrete
+ * implementations live in `@graphorin/security` (worker-threads,
+ * isolated-vm, docker, none).
+ *
+ * @stable
+ */
+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
+ */
+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
+ */
+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
+ */
+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;
+};
+//#endregion
+export { Sandbox, SandboxCode, SandboxResult, SandboxRunOptions };
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/contracts/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","names":[],"sources":["../../src/contracts/sandbox.ts"],"sourcesContent":[],"mappings":";;AAOA;;;;;;AAMK,UANY,OAAA,CAMZ;EAAO;EAUA,SAAA,EAAA,EAAA,MAAW;EAUN,GAAA,CAAA,MAAA,EAAA,OAAA,CAAiB,CAAA,IAAA,EAtBxB,WAsBwB,EAAA,IAAA,EArBxB,iBAqBwB,CArBN,MAqBM,CAAA,CAAA,EApB7B,OAoB6B,CApBrB,aAoBqB,CApBP,OAoBO,CAAA,CAAA;;;;;;AAqBlC;;;KA/BY,WAAA;;;;;;;;;;;;;;;;;UAUK;kBACC;;;;;;;;iBAQD,SAAS;;;oBAGN;;;;;;;;KASR;;mBAC8B"}

package/dist/contracts/secret-ref.d.ts

@@ -0,0 +1,26 @@
+//#region src/contracts/secret-ref.d.ts
+/**
+ * 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
+ */
+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;
+}
+//#endregion
+export { SecretRef };
+//# sourceMappingURL=secret-ref.d.ts.map

package/dist/contracts/secret-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-ref.d.ts","names":[],"sources":["../../src/contracts/secret-ref.ts"],"sourcesContent":[],"mappings":";;AAQA;;;;;;;UAAiB,SAAA;;;;;;;;;;kBAUC,SAAS"}