@graphorin/provider 0.6.0 → 0.7.0

package/src/reasoning/apply-policy.ts

@@ -0,0 +1,89 @@
+/**
+ * `applyReasoningPolicy` - given a list of `Message`s and the resolved
+ * {@link ReasoningRetention}, return a transformed list with
+ * `reasoning` content parts treated according to the policy:
+ *
+ * - `'strip'`              - drop every `reasoning` content part.
+ * - `'pass-through-claude'` - keep parts that carry Anthropic-shaped
+ *   metadata (`provider === 'anthropic'` OR a `signature` field);
+ *   drop the rest.
+ * - `'pass-through-all'`   - keep every `reasoning` content part
+ *   unchanged.
+ *
+ * The transformation is shallow: only the `assistant` role's content
+ * arrays are inspected (the only role that legitimately carries
+ * reasoning blocks).
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AssistantMessage,
+  Message,
+  MessageContent,
+  ReasoningContent,
+  ReasoningRetention,
+} from '@graphorin/core';
+
+/**
+ * Inputs to {@link applyReasoningPolicy}.
+ *
+ * @stable
+ */
+export interface ApplyReasoningPolicyInput {
+  readonly messages: ReadonlyArray<Message>;
+  readonly retention: ReasoningRetention;
+}
+
+/**
+ * Apply the resolved retention policy to the provided messages.
+ *
+ * @stable
+ */
+export function applyReasoningPolicy(input: ApplyReasoningPolicyInput): ReadonlyArray<Message> {
+  if (input.retention === 'pass-through-all') return input.messages;
+  return input.messages.map((msg) => {
+    if (msg.role !== 'assistant') return msg;
+    return rewriteAssistantMessage(msg, input.retention);
+  });
+}
+
+function rewriteAssistantMessage(
+  msg: AssistantMessage,
+  retention: ReasoningRetention,
+): AssistantMessage {
+  const content = msg.content;
+  if (typeof content === 'string') return msg;
+  const filtered: MessageContent[] = [];
+  let mutated = false;
+  for (const part of content) {
+    if (part.type !== 'reasoning') {
+      filtered.push(part);
+      continue;
+    }
+    if (retention === 'strip') {
+      mutated = true;
+      continue;
+    }
+    if (retention === 'pass-through-claude') {
+      if (isAnthropicShapedReasoning(part)) {
+        filtered.push(part);
+      } else {
+        mutated = true;
+      }
+    }
+  }
+  if (!mutated) return msg;
+  return {
+    ...msg,
+    content: filtered,
+  };
+}
+
+function isAnthropicShapedReasoning(part: ReasoningContent): boolean {
+  const meta = part.meta;
+  if (meta === undefined) return false;
+  if (meta.provider === 'anthropic') return true;
+  if (typeof meta.signature === 'string' && meta.signature.length > 0) return true;
+  return false;
+}

package/src/reasoning/classify-contract.ts

@@ -0,0 +1,120 @@
+/**
+ * `inferReasoningContract` - derive the canonical
+ * {@link ReasoningContract} value for a model id. Adapters that wrap
+ * cloud-LLM language-model values call this at construction time so
+ * the runtime can pick the correct
+ * {@link import('@graphorin/core').ReasoningRetention} default.
+ *
+ * The classifier is a pure function with the same shape as the
+ * `classifyModelTier` family: a small static rule table matched
+ * against the lowercased + prefix-stripped model id.
+ *
+ * @packageDocumentation
+ */
+
+import type { ReasoningContract } from '@graphorin/core';
+
+/**
+ * Single entry in the contract-classifier rule table.
+ *
+ * @stable
+ */
+export interface ReasoningContractRule {
+  readonly contract: ReasoningContract;
+  readonly pattern: RegExp;
+  /** Human-readable family label. */
+  readonly family: string;
+}
+
+/**
+ * Static rule table. Higher-specificity entries come first. Mirrors
+ * the per-family matrix documented for the provider layer.
+ *
+ * @stable
+ */
+export const REASONING_CONTRACT_RULES: readonly ReasoningContractRule[] = Object.freeze([
+  // Anthropic Claude families (and Bedrock-distributed equivalents).
+  {
+    contract: 'round-trip-required',
+    family: 'anthropic-claude',
+    pattern: /^claude(?:-\d|-)/,
+  },
+  {
+    contract: 'round-trip-required',
+    family: 'bedrock-claude',
+    pattern: /^anthropic\.claude/,
+  },
+  // OpenAI hidden chain-of-thought reasoning models.
+  { contract: 'hidden', family: 'openai-reasoning', pattern: /^o[1-9]\b/ },
+  { contract: 'hidden', family: 'openai-reasoning-extended', pattern: /^o[1-9][a-z-]/ },
+  // Google Gemini reasoning families (the dedicated thinking variants;
+  // the regular pro / flash families do not require round-tripping).
+  {
+    contract: 'hidden',
+    family: 'gemini-reasoning',
+    pattern: /^gemini.*(?:thinking|reasoning)/,
+  },
+]);
+
+/**
+ * Inputs to {@link inferReasoningContract}.
+ *
+ * @stable
+ */
+export interface InferReasoningContractInput {
+  readonly modelId: string;
+  readonly provider?: string;
+}
+
+/**
+ * Return the canonical {@link ReasoningContract} for a model id, or
+ * `'optional'` for unknown / Ollama / OpenAI-compatible families.
+ *
+ * @stable
+ */
+export function inferReasoningContract(input: InferReasoningContractInput): ReasoningContract {
+  if (typeof input.modelId !== 'string' || input.modelId.length === 0) {
+    return 'optional';
+  }
+  const provider = input.provider?.toLowerCase();
+  // Provider-explicit short-circuits - let cloud-LLM consumers tag
+  // their model with `provider: 'anthropic'` even when the modelId is
+  // a non-canonical alias (e.g. `legacy-thinking-router`). Prefix /
+  // substring matching because the AI SDK reports dotted provider ids
+  // (`'anthropic.messages'`, `'amazon-bedrock.messages'`), not the
+  // bare vendor name (core-provider-11).
+  if (
+    provider !== undefined &&
+    (provider.startsWith('anthropic') || provider.includes('bedrock'))
+  ) {
+    return 'round-trip-required';
+  }
+  const normalised = stripPrefix(input.modelId.toLowerCase());
+  for (const rule of REASONING_CONTRACT_RULES) {
+    if (rule.pattern.test(normalised)) return rule.contract;
+  }
+  return 'optional';
+}
+
+/**
+ * Bedrock cross-region inference-profile prefix (`us.anthropic.claude-…`,
+ * the standard way to invoke Claude on Bedrock since 2025). Stripped
+ * before pattern matching so the `^anthropic\.claude` rules still fire
+ * (core-provider-11).
+ */
+const BEDROCK_REGION_PREFIX = /^(?:us|eu|apac|jp|au|us-gov)\./;
+
+function stripPrefix(model: string): string {
+  const slash = model.indexOf('/');
+  if (slash !== -1) return model.slice(slash + 1).replace(BEDROCK_REGION_PREFIX, '');
+  const deRegioned = model.replace(BEDROCK_REGION_PREFIX, '');
+  // Bedrock ids end in ':<version>' (`anthropic.claude-...-v1:0`) - the
+  // colon there is a version separator, not a provider/model split, and
+  // the rule patterns are prefix-anchored so the suffix is harmless.
+  if (deRegioned.startsWith('anthropic.')) return deRegioned;
+  const colon = deRegioned.indexOf(':');
+  if (colon !== -1 && !deRegioned.startsWith('http')) {
+    return deRegioned.slice(colon + 1);
+  }
+  return deRegioned;
+}

package/src/reasoning/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Reasoning-content lifecycle helpers.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  type ApplyReasoningPolicyInput,
+  applyReasoningPolicy,
+} from './apply-policy.js';
+export {
+  type InferReasoningContractInput,
+  inferReasoningContract,
+  REASONING_CONTRACT_RULES,
+  type ReasoningContractRule,
+} from './classify-contract.js';
+export {
+  REASONING_RETENTION_DEFAULTS,
+  type ResolveReasoningRetentionInput,
+  resolveReasoningRetention,
+} from './retention.js';

package/src/reasoning/retention.ts

@@ -0,0 +1,64 @@
+/**
+ * Reasoning-retention resolver - picks the effective
+ * {@link ReasoningRetention} value for a request given:
+ *
+ * 1. an explicit per-request `reasoningRetention` field (highest
+ *    precedence - user override always wins),
+ * 2. an instance-level override supplied to `createProvider({...})`,
+ *    and
+ * 3. the auto-detected default derived from the adapter's declared
+ *    `capabilities.reasoningContract` (lowest precedence).
+ *
+ * @packageDocumentation
+ */
+
+import type { ReasoningContract, ReasoningRetention } from '@graphorin/core';
+
+/**
+ * Map from `ReasoningContract` to the conservative default
+ * `ReasoningRetention` value used when no override is supplied.
+ *
+ * @stable
+ */
+export const REASONING_RETENTION_DEFAULTS: Readonly<Record<ReasoningContract, ReasoningRetention>> =
+  Object.freeze({
+    hidden: 'strip',
+    'round-trip-required': 'pass-through-claude',
+    optional: 'strip',
+  });
+
+/**
+ * Inputs to {@link resolveReasoningRetention}.
+ *
+ * @stable
+ */
+export interface ResolveReasoningRetentionInput {
+  /** Explicit per-request override (highest precedence). */
+  readonly requested?: ReasoningRetention;
+  /** Instance-level override supplied to `createProvider({...})`. */
+  readonly overridden?: ReasoningRetention;
+  /** Adapter-declared capability (lowest precedence). */
+  readonly contract?: ReasoningContract;
+}
+
+/**
+ * Resolve the effective {@link ReasoningRetention} value for a single
+ * request. The resolution is precedence-driven:
+ *
+ * 1. `requested` wins if defined.
+ * 2. `overridden` wins next.
+ * 3. The default for `contract` is used if the contract is known.
+ * 4. `'strip'` is the conservative fallback when no input is supplied.
+ *
+ * @stable
+ */
+export function resolveReasoningRetention(
+  input: ResolveReasoningRetentionInput,
+): ReasoningRetention {
+  if (input.requested !== undefined) return input.requested;
+  if (input.overridden !== undefined) return input.overridden;
+  if (input.contract !== undefined) {
+    return REASONING_RETENTION_DEFAULTS[input.contract];
+  }
+  return 'strip';
+}

package/src/tool-examples.ts

@@ -0,0 +1,54 @@
+/**
+ * A1 (SOTA): fold a tool's worked `examples` into its model-facing description.
+ *
+ * `ToolDefinition` already carries `examples` on the wire (the agent projects
+ * them from `Tool.examples`), and the contract notes implementations MAY fold
+ * them into the description - but no adapter did, so the model never saw them.
+ * Anthropic reports complex-parameter accuracy jumps 72% → 90% with worked
+ * examples in the tool text. This renders them deterministically (so the tool
+ * spec stays prompt-cache-stable) and drops the now-redundant structured field.
+ *
+ * @packageDocumentation
+ */
+
+import type { ToolDefinition, ToolDefinitionExample } from '@graphorin/core';
+
+/** Render worked examples as a compact, deterministic text block. */
+function renderExamplesSection(examples: ReadonlyArray<ToolDefinitionExample>): string {
+  const lines = examples.map((ex, i) => {
+    const comment = ex.comment !== undefined ? `  // ${ex.comment}` : '';
+    return `${i + 1}. input: ${JSON.stringify(ex.input)} -> output: ${JSON.stringify(ex.output)}${comment}`;
+  });
+  return `Examples:\n${lines.join('\n')}`;
+}
+
+/**
+ * Fold each tool's `examples` into its `description` and drop the structured
+ * field. Non-destructive: a tool with no examples is returned by reference, and
+ * the whole array is returned unchanged (same reference) when nothing folds - so
+ * callers can cheaply detect a no-op.
+ */
+export function foldToolExamples(
+  tools: ReadonlyArray<ToolDefinition>,
+): ReadonlyArray<ToolDefinition> {
+  let changed = false;
+  const out = tools.map((tool): ToolDefinition => {
+    const examples = tool.examples;
+    if (examples === undefined || examples.length === 0) return tool;
+    changed = true;
+    const section = renderExamplesSection(examples);
+    const description =
+      tool.description !== undefined && tool.description.length > 0
+        ? `${tool.description}\n\n${section}`
+        : section;
+    // Rebuild without `examples` (now in the description text), preserving every
+    // other field - notably `outputSchema` (A5).
+    return {
+      name: tool.name,
+      inputSchema: tool.inputSchema,
+      description,
+      ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),
+    };
+  });
+  return changed ? out : tools;
+}

package/src/trust/classify-local-provider.ts

@@ -0,0 +1,254 @@
+/**
+ * Shared trust classifier for every `baseUrl`-driven local-LLM
+ * adapter. Emits one of four discriminant values per
+ * {@link LocalProviderTrust}:
+ *
+ * - `'loopback'`         - the URL points at the same host as the
+ *   running process (`localhost`, `127.0.0.0/8`, `::1`, or a
+ *   `unix:///path` socket).
+ * - `'private'`          - RFC 1918 / RFC 6598 / link-local /
+ *   multicast-DNS-style hostname.
+ * - `'public-tls'`       - public host AND `https://`.
+ * - `'public-cleartext'` - public host AND `http://`.
+ *
+ * The dispatcher is a pure function: it sees the URL string and
+ * nothing else. DNS resolution is deferred to the adapter layer
+ * (cross-cut DEC-149 § DNS-rebinding mitigation), where the resolved
+ * IP is re-classified on TTL expiry and the lowest-trust value wins.
+ *
+ * @packageDocumentation
+ */
+
+import type { LocalProviderTrust, Sensitivity } from '@graphorin/core';
+
+/**
+ * Result of {@link classifyLocalProvider}. Carries both the trust
+ * class and a short human-readable reason for the WARN log produced
+ * by the consuming adapter.
+ *
+ * @stable
+ */
+export interface LocalProviderClassification {
+  readonly trust: LocalProviderTrust;
+  /** One-line reason - `'loopback IP 127.0.0.1'`, `'public IP 5.6.7.8 over HTTPS'`, ... */
+  readonly reason: string;
+  /** Default `acceptsSensitivity` for this trust class. */
+  readonly acceptsSensitivity: ReadonlyArray<Sensitivity>;
+}
+
+/**
+ * Per-tier default sensitivity envelope. Lifted to a constant so
+ * downstream code (and tests) can import it without re-deriving the
+ * matrix.
+ *
+ * @stable
+ */
+export const SENSITIVITY_DEFAULTS_PER_TRUST: Readonly<
+  Record<LocalProviderTrust, ReadonlyArray<Sensitivity>>
+> = Object.freeze({
+  loopback: Object.freeze(['public', 'internal', 'secret'] as const),
+  private: Object.freeze(['public', 'internal'] as const),
+  'public-tls': Object.freeze(['public'] as const),
+  'public-cleartext': Object.freeze([] as const),
+});
+
+/**
+ * Classify a URL string into one of the four {@link LocalProviderTrust}
+ * tiers. Throws `TypeError` if the URL is unparseable so adapters
+ * fail fast at construction time (programming error; not a runtime
+ * fault).
+ *
+ * @stable
+ */
+export function classifyLocalProvider(baseUrl: string): LocalProviderClassification {
+  if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
+    throw new TypeError('classifyLocalProvider: baseUrl must be a non-empty string.');
+  }
+
+  if (baseUrl.startsWith('unix://') || baseUrl.startsWith('unix:/')) {
+    return {
+      trust: 'loopback',
+      reason: `unix domain socket (${baseUrl})`,
+      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,
+    };
+  }
+
+  let url: URL;
+  try {
+    url = new URL(baseUrl);
+  } catch (cause) {
+    throw new TypeError(`classifyLocalProvider: baseUrl '${baseUrl}' is not a valid URL.`, {
+      cause,
+    });
+  }
+
+  const protocol = url.protocol;
+  const hostname = url.hostname;
+  if (protocol !== 'http:' && protocol !== 'https:') {
+    // Custom protocols (e.g. ws://) are out of scope for the four
+    // bundled adapters; treat as private so a downstream WARN fires.
+    return {
+      trust: 'private',
+      reason: `non-HTTP protocol '${protocol}'`,
+      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,
+    };
+  }
+
+  const ipv4 = parseIpv4(hostname);
+  if (ipv4 !== null) {
+    if (isLoopbackIpv4(ipv4)) {
+      return {
+        trust: 'loopback',
+        reason: `loopback IPv4 ${hostname}`,
+        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,
+      };
+    }
+    if (isPrivateIpv4(ipv4)) {
+      return {
+        trust: 'private',
+        reason: `private IPv4 ${hostname}`,
+        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,
+      };
+    }
+    return classifyPublic(protocol, `public IPv4 ${hostname}`);
+  }
+
+  if (isIpv6(hostname)) {
+    if (isLoopbackIpv6(hostname)) {
+      return {
+        trust: 'loopback',
+        reason: `loopback IPv6 ${hostname}`,
+        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,
+      };
+    }
+    if (isPrivateIpv6(hostname)) {
+      return {
+        trust: 'private',
+        reason: `private IPv6 ${hostname}`,
+        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,
+      };
+    }
+    return classifyPublic(protocol, `public IPv6 ${hostname}`);
+  }
+
+  if (isLoopbackHostname(hostname)) {
+    return {
+      trust: 'loopback',
+      reason: `loopback hostname '${hostname}'`,
+      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,
+    };
+  }
+  if (isPrivateHostnameSuffix(hostname)) {
+    return {
+      trust: 'private',
+      reason: `private hostname suffix '${hostname}'`,
+      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,
+    };
+  }
+
+  return classifyPublic(protocol, `public hostname '${hostname}'`);
+}
+
+function classifyPublic(protocol: string, reason: string): LocalProviderClassification {
+  if (protocol === 'https:') {
+    return {
+      trust: 'public-tls',
+      reason: `${reason} over HTTPS`,
+      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST['public-tls'],
+    };
+  }
+  return {
+    trust: 'public-cleartext',
+    reason: `${reason} over HTTP`,
+    acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST['public-cleartext'],
+  };
+}
+
+function parseIpv4(hostname: string): [number, number, number, number] | null {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+  if (match === null) return null;
+  const a = Number(match[1]);
+  const b = Number(match[2]);
+  const c = Number(match[3]);
+  const d = Number(match[4]);
+  if (a > 255 || b > 255 || c > 255 || d > 255) return null;
+  return [a, b, c, d];
+}
+
+function isLoopbackIpv4(ip: readonly [number, number, number, number]): boolean {
+  return ip[0] === 127;
+}
+
+function isPrivateIpv4(ip: readonly [number, number, number, number]): boolean {
+  // RFC 1918
+  if (ip[0] === 10) return true;
+  if (ip[0] === 192 && ip[1] === 168) return true;
+  if (ip[0] === 172 && ip[1] >= 16 && ip[1] <= 31) return true;
+  // RFC 6598 (CGNAT - Tailscale-friendly)
+  if (ip[0] === 100 && ip[1] >= 64 && ip[1] <= 127) return true;
+  // Link-local
+  if (ip[0] === 169 && ip[1] === 254) return true;
+  return false;
+}
+
+function isIpv6(hostname: string): boolean {
+  const stripped =
+    hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+  return stripped.includes(':');
+}
+
+function normaliseIpv6(hostname: string): string {
+  return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+}
+
+function isLoopbackIpv6(hostname: string): boolean {
+  const norm = normaliseIpv6(hostname).toLowerCase();
+  return norm === '::1' || norm === '0:0:0:0:0:0:0:1';
+}
+
+function isPrivateIpv6(hostname: string): boolean {
+  const norm = normaliseIpv6(hostname).toLowerCase();
+  // Link-local fe80::/10
+  if (
+    norm.startsWith('fe80:') ||
+    norm.startsWith('fe8') ||
+    norm.startsWith('fe9') ||
+    norm.startsWith('fea') ||
+    norm.startsWith('feb')
+  ) {
+    return true;
+  }
+  // Unique local fc00::/7 (covers fc:: and fd::)
+  if (norm.startsWith('fc') || norm.startsWith('fd')) return true;
+  return false;
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  return lower === 'localhost' || lower === 'localhost.';
+}
+
+function isPrivateHostnameSuffix(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  return (
+    lower.endsWith('.local') ||
+    lower.endsWith('.lan') ||
+    lower.endsWith('.internal') ||
+    lower.endsWith('.home.arpa') ||
+    lower.endsWith('.intranet')
+  );
+}
+
+/**
+ * Permanent loopback classification used by in-process adapters
+ * (e.g. the `llamaCppNodeAdapter` companion package). Adapters that
+ * have no `baseUrl` declare this directly to make the source-of-truth
+ * symmetry obvious.
+ *
+ * @stable
+ */
+export const PERMANENT_LOOPBACK_CLASSIFICATION: LocalProviderClassification = Object.freeze({
+  trust: 'loopback',
+  reason: 'in-process adapter (no baseUrl)',
+  acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,
+});

package/src/trust/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Trust subsystem barrel - exports the shared classifier and the
+ * per-tier sensitivity defaults.
+ *
+ * @packageDocumentation
+ */
+
+export type { LocalProviderTrust, OllamaTrust } from '@graphorin/core';
+export {
+  classifyLocalProvider,
+  type LocalProviderClassification,
+  PERMANENT_LOOPBACK_CLASSIFICATION,
+  SENSITIVITY_DEFAULTS_PER_TRUST,
+} from './classify-local-provider.js';

package/dist/adapters/index.js

@@ -1,6 +0,0 @@
-import { llamaCppServerAdapter } from "./llamacpp-server.js";
-import { ollamaAdapter } from "./ollama.js";
-import { openAICompatibleAdapter } from "./openai-compatible.js";
-import { vercelAdapter } from "./vercel.js";
-
-export {  };