@tangle-network/agent-app 0.44.1 → 0.44.3

package/dist/{chunk-KFTRTOT2.js → chunk-CHLOH4DG.js}

@@ -9,6 +9,7 @@ var UPSTREAM_UNAVAILABLE_CODES = [
   "service_unavailable"
 ];
 var UPSTREAM_UNAVAILABLE_STATUSES = [429, 500, 502, 503, 504];
+var REQUEST_ERROR_STATUSES = [400, 401, 403, 405, 413, 422];
 var UPSTREAM_UNAVAILABLE_MESSAGES = [
   "bad gateway",
   "service unavailable",
@@ -19,8 +20,33 @@ var UPSTREAM_UNAVAILABLE_MESSAGES = [
   "quota exceeded",
   "rate limit",
   "overloaded",
-  "temporarily unavailable"
+  "temporarily unavailable",
+  // Model-SCOPED unavailability. A different model in the chain can still
+  // serve, so this belongs here and not with the client errors. Measured on a
+  // real box 2026-07-27: the sandbox now reports an unservable model as a
+  // terminal `error` whose data is `{"message":"Session error:
+  // {\"error\":{\"name\":\"UnknownError\",\"data\":{\"message\":\"Model not
+  // found: openai-compat/zai/glm-4.7.\"}}}"}` — no `code`, no numeric status,
+  // and none of the fragments above. The shipped live product-path proof went
+  // red on exactly this: `usedFallback:false`, `failed:true`, an error row to
+  // the customer where a fallback was available and would have answered.
+  "model not found",
+  "is not currently available"
 ];
+var HTTP_STATUS_HINT_PATTERNS = [
+  /\berror\s+code:?\s*([1-5]\d{2})\b/i,
+  /\bhttp(?:\/[\d.]+)?[\s:]\s*([1-5]\d{2})\b/i,
+  /\bstatus(?:\s*code)?[\s:=]\s*([1-5]\d{2})\b/i,
+  /\b(?:returned|responded(?:\s+with)?)\s+([1-5]\d{2})\b/i,
+  /\b([1-5]\d{2})\s+(?:bad\s+gateway|service\s+unavailable|gateway\s+time-?out|internal\s+server\s+error|too\s+many\s+requests)\b/i
+];
+function readHttpStatusHint(text) {
+  for (const pattern of HTTP_STATUS_HINT_PATTERNS) {
+    const match = pattern.exec(text);
+    if (match?.[1]) return Number(match[1]);
+  }
+  return void 0;
+}
 function readString(source, key) {
   const value = source[key];
   return typeof value === "string" && value.trim().length > 0 ? value : void 0;
@@ -39,6 +65,11 @@ function isUpstreamUnavailable(signal) {
   }
   const message = readString(record, "message") ?? readString(record, "error") ?? (nestedRecord ? readString(nestedRecord, "message") : void 0);
   if (!message) return false;
+  const hinted = readHttpStatusHint(message);
+  if (hinted !== void 0) {
+    if (UPSTREAM_UNAVAILABLE_STATUSES.includes(hinted)) return true;
+    if (REQUEST_ERROR_STATUSES.includes(hinted)) return false;
+  }
   const lowered = message.toLowerCase();
   return UPSTREAM_UNAVAILABLE_MESSAGES.some((fragment) => lowered.includes(fragment));
 }
@@ -103,9 +134,10 @@ function buildModelChain(preferred, fallbacks) {
 export {
   UPSTREAM_UNAVAILABLE_CODES,
   UPSTREAM_UNAVAILABLE_STATUSES,
+  readHttpStatusHint,
   isUpstreamUnavailable,
   ModelFailoverExhaustedError,
   runWithModelFailover,
   buildModelChain
 };
-//# sourceMappingURL=chunk-KFTRTOT2.js.map
+//# sourceMappingURL=chunk-CHLOH4DG.js.map

package/dist/chunk-CHLOH4DG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/model-resolution/failover.ts"],"sourcesContent":["/**\n * Model failover — the answer to \"one upstream hit a quota wall and the customer\n * got a Bad Gateway even though the router had abundant healthy capacity\".\n *\n * This is deliberately NOT a health probe. Probing before every turn buys a\n * round-trip of latency on the happy path and still races the outage (a model\n * healthy at probe time can 502 a second later). Failover is REACTIVE: run the\n * preferred model, and on an upstream-outage signal move to the next model in\n * the chain. Zero added latency when the preferred model works.\n *\n * Two facts drive the design, both measured against a live box during the\n * 2026-07-25 Anthropic/DeepSeek outage:\n *\n * 1. An outage is NOT always a thrown error. The sandbox resolves with a\n *    payload — `{ success: false, errorCode: 'provider_inference_unavailable' }`\n *    — so a classifier that only inspects `catch` misses the customer-visible\n *    case entirely. `isUpstreamUnavailable` inspects resolved values too.\n * 2. Catalog membership is NOT liveness. The router's `/v1/models` still listed\n *    every dead model during the outage, so `validateChatModelId` admitted\n *    `claude-sonnet-4-6` while every call to it returned 502. Nothing upstream\n *    of the actual call can be trusted to tell you a model is serving.\n *\n * Substrate-free: the caller injects `run`, so this composes with a sandbox\n * turn, a router chat completion, or a test fake without importing any of them.\n */\n\n/**\n * Error codes that mean \"this model's upstream is unavailable — a different\n * model may still work\". Deliberately excludes codes that would fail identically\n * on every model (bad request, auth, content filter): retrying those down a\n * chain burns latency and money to reach the same failure.\n */\nexport const UPSTREAM_UNAVAILABLE_CODES: readonly string[] = [\n  'provider_inference_unavailable',\n  'upstream_unavailable',\n  'insufficient_quota',\n  'model_not_available',\n  'server_error',\n  'bad_gateway',\n  'service_unavailable',\n]\n\n/** HTTP statuses that indicate an upstream capacity/availability problem. */\nexport const UPSTREAM_UNAVAILABLE_STATUSES: readonly number[] = [429, 500, 502, 503, 504]\n\n/**\n * Statuses that mean the REQUEST is wrong, so every model in the chain would\n * fail on it identically. Listed explicitly rather than as \"any 4xx\" because\n * 404 is NOT one of them: a model the endpoint cannot find is model-scoped, and\n * the next model in the chain may well be there. 429 is absent for the same\n * reason in reverse — it is a capacity signal and lives in the list above.\n */\nconst REQUEST_ERROR_STATUSES: readonly number[] = [400, 401, 403, 405, 413, 422]\n\n/**\n * Message fragments emitted by real upstreams during this class of outage.\n * Matched case-insensitively as a last resort, after code and status.\n */\nconst UPSTREAM_UNAVAILABLE_MESSAGES: readonly string[] = [\n  'bad gateway',\n  'service unavailable',\n  'inference temporarily unavailable',\n  'provider inference is unavailable',\n  'insufficient balance',\n  'usage limits',\n  'quota exceeded',\n  'rate limit',\n  'overloaded',\n  'temporarily unavailable',\n  // Model-SCOPED unavailability. A different model in the chain can still\n  // serve, so this belongs here and not with the client errors. Measured on a\n  // real box 2026-07-27: the sandbox now reports an unservable model as a\n  // terminal `error` whose data is `{\"message\":\"Session error:\n  // {\\\"error\\\":{\\\"name\\\":\\\"UnknownError\\\",\\\"data\\\":{\\\"message\\\":\\\"Model not\n  // found: openai-compat/zai/glm-4.7.\\\"}}}\"}` — no `code`, no numeric status,\n  // and none of the fragments above. The shipped live product-path proof went\n  // red on exactly this: `usedFallback:false`, `failed:true`, an error row to\n  // the customer where a fallback was available and would have answered.\n  'model not found',\n  'is not currently available',\n]\n\n/**\n * Textual forms an HTTP status arrives in when NO numeric field carries it.\n *\n * The case that forced this is the Cloudflare EDGE 502. Captured verbatim from\n * `router.tangle.tools` on 2026-07-27 17:48:12 GMT (cf-ray\n * `a21d793899f6cef3-DEN`): `HTTP/2 502`, `content-type: text/plain;\n * charset=UTF-8`, a 16-byte body reading `error code: 502\\n`, `server:\n * cloudflare`, and **zero `x-tangle-*` headers** where a healthy 200 from the\n * same endpoint carries nine of them. Zero means the origin never executed —\n * so the router's own upstream failover, which lives inside the origin,\n * structurally cannot fire. Only a client OUTSIDE the edge can rescue that\n * turn, which is why this classifier has to recognize a failure shape that\n * nobody upstream will ever label for it.\n *\n * Every pattern below matches a string a real producer emits:\n * - `error code: 502` — Cloudflare's edge body (the capture above).\n * - `(HTTP 502)` — `src/runtime/openai-stream.ts` wrapping a non-ok response.\n * - `returned 502` — `src/runtime/model-catalog.ts`.\n * - `failed with status 502` — `src/turn-stream/adapters.ts`.\n * - `502 Bad Gateway` — an HTTP/1.1 status line. HTTP/2 carries no reason\n *   phrase at all, which is precisely why matching the phrase alone (the\n *   `'bad gateway'` fragment below) read the capture as a non-outage.\n */\nconst HTTP_STATUS_HINT_PATTERNS: readonly RegExp[] = [\n  /\\berror\\s+code:?\\s*([1-5]\\d{2})\\b/i,\n  /\\bhttp(?:\\/[\\d.]+)?[\\s:]\\s*([1-5]\\d{2})\\b/i,\n  /\\bstatus(?:\\s*code)?[\\s:=]\\s*([1-5]\\d{2})\\b/i,\n  /\\b(?:returned|responded(?:\\s+with)?)\\s+([1-5]\\d{2})\\b/i,\n  /\\b([1-5]\\d{2})\\s+(?:bad\\s+gateway|service\\s+unavailable|gateway\\s+time-?out|internal\\s+server\\s+error|too\\s+many\\s+requests)\\b/i,\n]\n\n/**\n * The HTTP status a message states in prose, or `undefined` when it states\n * none. Deliberately NOT \"any three digits in the string\" — an unanchored digit\n * scan would read a token count or a duration as a status.\n */\nexport function readHttpStatusHint(text: string): number | undefined {\n  for (const pattern of HTTP_STATUS_HINT_PATTERNS) {\n    const match = pattern.exec(text)\n    if (match?.[1]) return Number(match[1])\n  }\n  return undefined\n}\n\nfunction readString(source: Record<string, unknown>, key: string): string | undefined {\n  const value = source[key]\n  return typeof value === 'string' && value.trim().length > 0 ? value : undefined\n}\n\n/**\n * True when `signal` — a thrown error OR a resolved result payload — indicates\n * the model's upstream is unavailable and another model is worth trying.\n *\n * Checked in order of decreasing confidence: explicit code, HTTP status, then\n * message text. A resolved payload only counts as a failure when it carries an\n * explicit failure marker (`success: false`, or an `error`/`errorCode` field) —\n * a successful result is never misread as an outage.\n */\nexport function isUpstreamUnavailable(signal: unknown): boolean {\n  if (signal === null || typeof signal !== 'object') return false\n  const record = signal as Record<string, unknown>\n\n  // A resolved payload that explicitly reports success is never an outage.\n  if (record.success === true) return false\n\n  const nested = record.error\n  const nestedRecord = nested !== null && typeof nested === 'object' ? (nested as Record<string, unknown>) : undefined\n\n  const code =\n    readString(record, 'errorCode') ??\n    readString(record, 'code') ??\n    (nestedRecord ? (readString(nestedRecord, 'code') ?? readString(nestedRecord, 'type')) : undefined)\n  if (code && UPSTREAM_UNAVAILABLE_CODES.includes(code)) return true\n\n  for (const key of ['status', 'statusCode', 'httpStatus']) {\n    const value = record[key]\n    if (typeof value === 'number' && UPSTREAM_UNAVAILABLE_STATUSES.includes(value)) return true\n  }\n\n  const message =\n    readString(record, 'message') ??\n    readString(record, 'error') ??\n    (nestedRecord ? readString(nestedRecord, 'message') : undefined)\n  if (!message) return false\n\n  // A status carried as PROSE, checked before the fragment list because it is\n  // the stronger signal and it cuts BOTH ways. An edge 502 names no exception\n  // type and sets no numeric field, so without this the shipped classifier read\n  // `error code: 502` as a non-outage and handed the customer a Bad Gateway\n  // instead of trying the next model — the exact failure the router cannot\n  // rescue from inside its own origin.\n  const hinted = readHttpStatusHint(message)\n  if (hinted !== undefined) {\n    if (UPSTREAM_UNAVAILABLE_STATUSES.includes(hinted)) return true\n    // An explicit REQUEST-error status is decisive the OTHER way. A 400\n    // carrying a validation message must surface rather than walk the chain,\n    // even when its body happens to contain a word from the fragment list —\n    // the router's own `Function tools with reasoning_effort are not supported`\n    // 400 is a request-shaping bug that fails identically on every model.\n    if (REQUEST_ERROR_STATUSES.includes(hinted)) return false\n  }\n\n  const lowered = message.toLowerCase()\n  return UPSTREAM_UNAVAILABLE_MESSAGES.some((fragment) => lowered.includes(fragment))\n}\n\n/** One model tried, and how it went. */\nexport interface ModelFailoverAttempt {\n  model: string\n  ok: boolean\n  /** Why this model was abandoned. Absent when `ok`. */\n  reason?: string\n}\n\n/** The outcome of a failover run: the value plus the full attempt trail. */\nexport interface ModelFailoverResult<T> {\n  value: T\n  /** The model that actually produced `value`. */\n  model: string\n  attempts: ModelFailoverAttempt[]\n  /** True when the preferred (first) model did not serve the request. */\n  usedFallback: boolean\n}\n\n/** Every model in the chain failed; carries the trail for logging. */\nexport class ModelFailoverExhaustedError extends Error {\n  readonly attempts: ModelFailoverAttempt[]\n  constructor(attempts: ModelFailoverAttempt[]) {\n    const trail = attempts.map((a) => `${a.model}: ${a.reason ?? 'failed'}`).join(' | ')\n    super(`All ${attempts.length} model(s) failed. ${trail}`)\n    this.name = 'ModelFailoverExhaustedError'\n    this.attempts = attempts\n  }\n}\n\n/** Inputs to {@link runWithModelFailover}. */\nexport interface RunWithModelFailoverInput<T> {\n  /** Preferred model first, then fallbacks in descending preference. */\n  models: readonly string[]\n  /** Executes one turn with the given model. */\n  run: (model: string) => Promise<T>\n  /**\n   * Classifies a resolved result as an upstream outage. Defaults to\n   * {@link isUpstreamUnavailable}, which understands the sandbox's\n   * `{ success: false, errorCode }` payload.\n   */\n  isUnavailableResult?: (result: T) => boolean\n  /** Classifies a thrown error. Defaults to {@link isUpstreamUnavailable}. */\n  isUnavailableError?: (error: unknown) => boolean\n  /** Observability hook fired each time a model is abandoned. */\n  onFallback?: (attempt: ModelFailoverAttempt, nextModel: string) => void\n}\n\nfunction describe(signal: unknown): string {\n  if (signal instanceof Error) return signal.message\n  if (signal !== null && typeof signal === 'object') {\n    const record = signal as Record<string, unknown>\n    const message = readString(record, 'error') ?? readString(record, 'message') ?? readString(record, 'errorCode')\n    if (message) return message\n  }\n  return String(signal)\n}\n\n/**\n * Run `run` against the first model in `models` that does not report an upstream\n * outage, falling through the chain in order.\n *\n * A non-outage failure (bad request, auth, content filter) is re-thrown\n * immediately rather than retried down the chain — those fail identically on\n * every model, so walking the chain would only multiply latency and spend.\n *\n * @throws ModelFailoverExhaustedError when every model reports an outage.\n */\nexport async function runWithModelFailover<T>(\n  input: RunWithModelFailoverInput<T>,\n): Promise<ModelFailoverResult<T>> {\n  const models = input.models.map((m) => m.trim()).filter((m) => m.length > 0)\n  if (models.length === 0) throw new Error('runWithModelFailover requires at least one model')\n\n  const isUnavailableResult = input.isUnavailableResult ?? ((r: T) => isUpstreamUnavailable(r))\n  const isUnavailableError = input.isUnavailableError ?? isUpstreamUnavailable\n  const attempts: ModelFailoverAttempt[] = []\n\n  for (let index = 0; index < models.length; index += 1) {\n    const model = models[index]!\n    let result: T\n    try {\n      result = await input.run(model)\n    } catch (error) {\n      if (!isUnavailableError(error)) throw error\n      const attempt: ModelFailoverAttempt = { model, ok: false, reason: describe(error) }\n      attempts.push(attempt)\n      const next = models[index + 1]\n      if (next) input.onFallback?.(attempt, next)\n      continue\n    }\n\n    if (isUnavailableResult(result)) {\n      const attempt: ModelFailoverAttempt = { model, ok: false, reason: describe(result) }\n      attempts.push(attempt)\n      const next = models[index + 1]\n      if (next) input.onFallback?.(attempt, next)\n      continue\n    }\n\n    attempts.push({ model, ok: true })\n    return { value: result, model, attempts, usedFallback: index > 0 }\n  }\n\n  throw new ModelFailoverExhaustedError(attempts)\n}\n\n/**\n * Build a failover chain: the preferred model first, then `fallbacks`, with\n * duplicates removed so a model is never retried twice in one turn.\n */\nexport function buildModelChain(preferred: string, fallbacks: readonly string[]): string[] {\n  const chain: string[] = []\n  for (const model of [preferred, ...fallbacks]) {\n    const cleaned = typeof model === 'string' ? model.trim() : ''\n    if (cleaned.length > 0 && !chain.includes(cleaned)) chain.push(cleaned)\n  }\n  return chain\n}\n"],"mappings":"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","names":[]}

package/dist/{failover-H0x12kY3.d.ts → failover-D-3UXXTb.d.ts}

@@ -32,6 +32,12 @@
 declare const UPSTREAM_UNAVAILABLE_CODES: readonly string[];
 /** HTTP statuses that indicate an upstream capacity/availability problem. */
 declare const UPSTREAM_UNAVAILABLE_STATUSES: readonly number[];
+/**
+ * The HTTP status a message states in prose, or `undefined` when it states
+ * none. Deliberately NOT "any three digits in the string" — an unanchored digit
+ * scan would read a token count or a duration as a status.
+ */
+declare function readHttpStatusHint(text: string): number | undefined;
 /**
  * True when `signal` — a thrown error OR a resolved result payload — indicates
  * the model's upstream is unavailable and another model is worth trying.
@@ -97,4 +103,4 @@ declare function runWithModelFailover<T>(input: RunWithModelFailoverInput<T>): P
  */
 declare function buildModelChain(preferred: string, fallbacks: readonly string[]): string[];
 
-export { type ModelFailoverAttempt as M, type RunWithModelFailoverInput as R, UPSTREAM_UNAVAILABLE_CODES as U, ModelFailoverExhaustedError as a, type ModelFailoverResult as b, UPSTREAM_UNAVAILABLE_STATUSES as c, buildModelChain as d, isUpstreamUnavailable as i, runWithModelFailover as r };
+export { type ModelFailoverAttempt as M, type RunWithModelFailoverInput as R, UPSTREAM_UNAVAILABLE_CODES as U, ModelFailoverExhaustedError as a, type ModelFailoverResult as b, UPSTREAM_UNAVAILABLE_STATUSES as c, buildModelChain as d, runWithModelFailover as e, isUpstreamUnavailable as i, readHttpStatusHint as r };

package/dist/model-resolution/index.d.ts

@@ -1,4 +1,4 @@
-export { M as ModelFailoverAttempt, a as ModelFailoverExhaustedError, b as ModelFailoverResult, R as RunWithModelFailoverInput, U as UPSTREAM_UNAVAILABLE_CODES, c as UPSTREAM_UNAVAILABLE_STATUSES, d as buildModelChain, i as isUpstreamUnavailable, r as runWithModelFailover } from '../failover-H0x12kY3.js';
+export { M as ModelFailoverAttempt, a as ModelFailoverExhaustedError, b as ModelFailoverResult, R as RunWithModelFailoverInput, U as UPSTREAM_UNAVAILABLE_CODES, c as UPSTREAM_UNAVAILABLE_STATUSES, d as buildModelChain, i as isUpstreamUnavailable, r as readHttpStatusHint, e as runWithModelFailover } from '../failover-D-3UXXTb.js';
 
 /**
  * Canonical chat-model resolution — identical across every agent app.

package/dist/model-resolution/index.js

@@ -4,8 +4,9 @@ import {
   UPSTREAM_UNAVAILABLE_STATUSES,
   buildModelChain,
   isUpstreamUnavailable,
+  readHttpStatusHint,
   runWithModelFailover
-} from "../chunk-KFTRTOT2.js";
+} from "../chunk-CHLOH4DG.js";
 
 // src/model-resolution/index.ts
 function canonicalModelId(model) {
@@ -84,6 +85,7 @@ export {
   cleanModelId,
   isUpstreamUnavailable,
   isWellFormedModelId,
+  readHttpStatusHint,
   resolveChatModel,
   runWithModelFailover,
   validateChatModelId

package/dist/model-resolution/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Canonical chat-model resolution — identical across every agent app.\n *\n * The ONLY per-app inputs are DATA, never logic: the default model, the\n * allowlist, the env value the deployment set, and the catalog-fetch loader.\n * The logic is one precedence ladder + one fail-closed validator that every\n * product uses the same way — there is no per-product variant, no env-var name\n * baked in, and no backend dimension (router-vs-sandbox is the harness/dispatch\n * concern, not model resolution; a sandbox's provider default lives in the\n * sandbox subpath).\n *\n * - resolveChatModel: request > workspace > env > default. The product reads its\n *   own deploy env var and passes the VALUE as `envModel`; the shell knows no\n *   env-var names. Source is canonical: 'request' | 'workspace' | 'env' | 'default'.\n * - validateChatModelId: fail-closed. Admit an id that is in the allowlist, or\n *   equals the operator-set env model, or is served by the live router catalog\n *   (exact, or a bare id resolved to its canonical id when the suffix is unique).\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\n/** Define possible origins for the chat model configuration values */\nexport type ChatModelSource = 'request' | 'workspace' | 'env' | 'default'\n\n/** Resolve a chat model with its identifier and source information */\nexport interface ResolvedChatModel {\n  model: string\n  source: ChatModelSource\n}\n\n/** Represent successful chat model validation with a true status and a validated string value */\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\n/** Describe a failed chat model validation result with an error message */\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\n/** Resolve the outcome of validating a chat model as either success or failure */\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\n/** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */\nexport interface ResolveChatModelInput {\n  /** Per-request override (highest precedence). */\n  requestModel?: string\n  /** Persisted workspace-pinned model. */\n  workspaceModel?: string\n  /** The value the deployment's model env var holds (the product reads its own\n   *  var name and passes the value — the shell stays env-var-name agnostic). */\n  envModel?: string\n  /** Final fallback (the product's default, typically profile.model.default). */\n  defaultModel: string\n}\n\n/** Resolve the chat-turn model by the one canonical precedence. Blank values are\n *  treated as absent. */\nexport function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel {\n  const request = cleanModelId(input.requestModel)\n  if (request) return { model: request, source: 'request' }\n  const workspace = cleanModelId(input.workspaceModel)\n  if (workspace) return { model: workspace, source: 'workspace' }\n  const env = cleanModelId(input.envModel)\n  if (env) return { model: env, source: 'env' }\n  return { model: input.defaultModel, source: 'default' }\n}\n\n/** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */\nexport interface ValidateChatModelIdInput {\n  /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */\n  allowlist?: Iterable<string>\n  /** The operator-set env model value — always admitted (operator-trusted). */\n  envModel?: string\n  /** Catalog loader; required to reach the catalog path. */\n  loadModels?: LoadModels\n  /** Catalog endpoint base; required to reach the catalog path. */\n  routerBaseUrl?: string\n}\n\n/**\n * Fail-closed model-id validation. Accepts an id only when it is well-formed AND\n * (in the allowlist, or equals the operator-set env model, or served by the live\n * catalog). A bare id (no provider prefix) resolves to its canonical id only when\n * the suffix is unique across the catalog — an ambiguous suffix is rejected\n * rather than silently assigned a provider.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  input: ValidateChatModelIdInput,\n): Promise<ChatModelValidationResult> {\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n\n  const allowed = new Set(input.allowlist ?? [])\n  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  // The operator-set env model is trusted without a catalog round-trip.\n  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned }\n\n  if (!input.loadModels || typeof input.routerBaseUrl !== 'string' || input.routerBaseUrl.length === 0) {\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await input.loadModels(input.routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (ids.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  if (!cleaned.includes('/')) {\n    const canonicalBySuffix = new Map<string, string[]>()\n    for (const model of catalog) {\n      if (typeof model.id !== 'string' || !model.id.trim()) continue\n      const canonical = canonicalModelId(model)\n      if (!canonical.includes('/')) continue\n      const suffix = canonical.split('/').slice(1).join('/')\n      const entries = canonicalBySuffix.get(suffix)\n      if (entries) entries.push(canonical)\n      else canonicalBySuffix.set(suffix, [canonical])\n    }\n    const matches = canonicalBySuffix.get(cleaned)\n    if (matches && matches.length === 1) return { succeeded: true, value: matches[0]! }\n  }\n\n  return { succeeded: false, error: `Model is not available: ${cleaned}` }\n}\n\n/** Resolve and return a trimmed string model ID or undefined for invalid or empty input */\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\n/** Validate if a model ID string conforms to length and character format requirements */\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\n/** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n  return [...ids]\n}\n\n// Reactive failover for the case validation cannot catch: a model that IS in the\n// catalog but whose upstream is down. Catalog membership is not liveness.\nexport {\n  isUpstreamUnavailable,\n  runWithModelFailover,\n  buildModelChain,\n  ModelFailoverExhaustedError,\n  UPSTREAM_UNAVAILABLE_CODES,\n  UPSTREAM_UNAVAILABLE_STATUSES,\n  type ModelFailoverAttempt,\n  type ModelFailoverResult,\n  type RunWithModelFailoverInput,\n} from './failover'\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Canonical chat-model resolution — identical across every agent app.\n *\n * The ONLY per-app inputs are DATA, never logic: the default model, the\n * allowlist, the env value the deployment set, and the catalog-fetch loader.\n * The logic is one precedence ladder + one fail-closed validator that every\n * product uses the same way — there is no per-product variant, no env-var name\n * baked in, and no backend dimension (router-vs-sandbox is the harness/dispatch\n * concern, not model resolution; a sandbox's provider default lives in the\n * sandbox subpath).\n *\n * - resolveChatModel: request > workspace > env > default. The product reads its\n *   own deploy env var and passes the VALUE as `envModel`; the shell knows no\n *   env-var names. Source is canonical: 'request' | 'workspace' | 'env' | 'default'.\n * - validateChatModelId: fail-closed. Admit an id that is in the allowlist, or\n *   equals the operator-set env model, or is served by the live router catalog\n *   (exact, or a bare id resolved to its canonical id when the suffix is unique).\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\n/** Define possible origins for the chat model configuration values */\nexport type ChatModelSource = 'request' | 'workspace' | 'env' | 'default'\n\n/** Resolve a chat model with its identifier and source information */\nexport interface ResolvedChatModel {\n  model: string\n  source: ChatModelSource\n}\n\n/** Represent successful chat model validation with a true status and a validated string value */\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\n/** Describe a failed chat model validation result with an error message */\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\n/** Resolve the outcome of validating a chat model as either success or failure */\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\n/** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */\nexport interface ResolveChatModelInput {\n  /** Per-request override (highest precedence). */\n  requestModel?: string\n  /** Persisted workspace-pinned model. */\n  workspaceModel?: string\n  /** The value the deployment's model env var holds (the product reads its own\n   *  var name and passes the value — the shell stays env-var-name agnostic). */\n  envModel?: string\n  /** Final fallback (the product's default, typically profile.model.default). */\n  defaultModel: string\n}\n\n/** Resolve the chat-turn model by the one canonical precedence. Blank values are\n *  treated as absent. */\nexport function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel {\n  const request = cleanModelId(input.requestModel)\n  if (request) return { model: request, source: 'request' }\n  const workspace = cleanModelId(input.workspaceModel)\n  if (workspace) return { model: workspace, source: 'workspace' }\n  const env = cleanModelId(input.envModel)\n  if (env) return { model: env, source: 'env' }\n  return { model: input.defaultModel, source: 'default' }\n}\n\n/** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */\nexport interface ValidateChatModelIdInput {\n  /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */\n  allowlist?: Iterable<string>\n  /** The operator-set env model value — always admitted (operator-trusted). */\n  envModel?: string\n  /** Catalog loader; required to reach the catalog path. */\n  loadModels?: LoadModels\n  /** Catalog endpoint base; required to reach the catalog path. */\n  routerBaseUrl?: string\n}\n\n/**\n * Fail-closed model-id validation. Accepts an id only when it is well-formed AND\n * (in the allowlist, or equals the operator-set env model, or served by the live\n * catalog). A bare id (no provider prefix) resolves to its canonical id only when\n * the suffix is unique across the catalog — an ambiguous suffix is rejected\n * rather than silently assigned a provider.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  input: ValidateChatModelIdInput,\n): Promise<ChatModelValidationResult> {\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n\n  const allowed = new Set(input.allowlist ?? [])\n  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  // The operator-set env model is trusted without a catalog round-trip.\n  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned }\n\n  if (!input.loadModels || typeof input.routerBaseUrl !== 'string' || input.routerBaseUrl.length === 0) {\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await input.loadModels(input.routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (ids.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  if (!cleaned.includes('/')) {\n    const canonicalBySuffix = new Map<string, string[]>()\n    for (const model of catalog) {\n      if (typeof model.id !== 'string' || !model.id.trim()) continue\n      const canonical = canonicalModelId(model)\n      if (!canonical.includes('/')) continue\n      const suffix = canonical.split('/').slice(1).join('/')\n      const entries = canonicalBySuffix.get(suffix)\n      if (entries) entries.push(canonical)\n      else canonicalBySuffix.set(suffix, [canonical])\n    }\n    const matches = canonicalBySuffix.get(cleaned)\n    if (matches && matches.length === 1) return { succeeded: true, value: matches[0]! }\n  }\n\n  return { succeeded: false, error: `Model is not available: ${cleaned}` }\n}\n\n/** Resolve and return a trimmed string model ID or undefined for invalid or empty input */\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\n/** Validate if a model ID string conforms to length and character format requirements */\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\n/** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n  return [...ids]\n}\n\n// Reactive failover for the case validation cannot catch: a model that IS in the\n// catalog but whose upstream is down. Catalog membership is not liveness.\nexport {\n  isUpstreamUnavailable,\n  readHttpStatusHint,\n  runWithModelFailover,\n  buildModelChain,\n  ModelFailoverExhaustedError,\n  UPSTREAM_UNAVAILABLE_CODES,\n  UPSTREAM_UNAVAILABLE_STATUSES,\n  type ModelFailoverAttempt,\n  type ModelFailoverResult,\n  type RunWithModelFailoverInput,\n} from './failover'\n"],"mappings":"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","names":[]}

package/dist/runtime/index.js

@@ -84,7 +84,9 @@ async function* streamChatCompletions(doFetch, url, apiKey, body) {
   });
   if (!res.ok || !res.body) {
     const text = res.body ? await res.text().catch(() => "") : "";
-    throw new Error(`OpenAI-compat stream failed (HTTP ${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    const error = new Error(`OpenAI-compat stream failed (HTTP ${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    Object.assign(error, { status: res.status });
+    throw error;
   }
   const reader = res.body.getReader();
   const decoder = new TextDecoder();

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/runtime/openai-stream.ts","../../src/runtime/certified-delivery.ts","../../src/runtime/surface-profile.ts","../../src/runtime/loop.ts"],"sourcesContent":["/**\n * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.\n *\n * `streamAppToolLoop` takes a `streamTurn` seam that yields `LoopEvent`s. A\n * sandboxed agent produces those from its container; a browser/edge copilot\n * instead calls a model directly. The Tangle Router, the tcloud SDK, and most\n * providers all speak the OpenAI Chat Completions streaming shape — so the ONE\n * reusable piece is assembling that stream (content deltas + FRAGMENTED\n * tool-call deltas) into `LoopEvent`s. That assembly is the boilerplate every\n * copilot would re-write (and get wrong — OpenAI streams tool-call arguments in\n * pieces across chunks).\n *\n * This does NOT implement an HTTP client beyond a minimal `fetch` + SSE reader\n * (browser/edge/Node-safe, zero deps). For richer transport use the tcloud SDK\n * or the Vercel AI SDK and pipe their stream through {@link toLoopEvents}.\n */\nimport type { LoopEvent, LoopMessage, LoopToolCall } from './loop'\n\n/** Minimal OpenAI Chat Completions streaming chunk (structural — no `openai` dep). */\nexport interface OpenAIStreamChunk {\n  choices?: Array<{\n    delta?: {\n      content?: string | null\n      /** Reasoning deltas — DeepSeek/router use `reasoning_content`; some proxies use `thinking`. */\n      reasoning_content?: string | null\n      thinking?: string | null\n      tool_calls?: Array<{\n        index: number\n        id?: string\n        function?: { name?: string; arguments?: string }\n      }>\n    }\n    finish_reason?: string | null\n  }>\n  /** Final-chunk token accounting (requires `stream_options.include_usage`). */\n  usage?: {\n    prompt_tokens?: number\n    completion_tokens?: number\n  } | null\n}\n\ninterface PartialToolCall {\n  id?: string\n  name: string\n  args: string\n}\n\n/**\n * Map an OpenAI-compat streaming chunk iterator to `LoopEvent`s: each content\n * delta → a `text` event; tool-call deltas are accumulated by index across\n * chunks and emitted as one complete `tool_call` event when the stream finishes\n * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than\n * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.\n */\nexport async function* toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent> {\n  const calls = new Map<number, PartialToolCall>()\n  for await (const chunk of chunks) {\n    // Usage rides the final chunk, which has an empty choices array — handle\n    // it before the choice guard.\n    if (chunk.usage?.prompt_tokens != null || chunk.usage?.completion_tokens != null) {\n      yield {\n        type: 'usage',\n        usage: {\n          promptTokens: chunk.usage.prompt_tokens ?? 0,\n          completionTokens: chunk.usage.completion_tokens ?? 0,\n        },\n      }\n    }\n    const choice = chunk.choices?.[0]\n    if (!choice) continue\n    const content = choice.delta?.content\n    if (content) yield { type: 'text', text: content }\n    const reasoning = choice.delta?.reasoning_content ?? choice.delta?.thinking\n    if (reasoning) yield { type: 'reasoning', text: reasoning }\n    for (const tc of choice.delta?.tool_calls ?? []) {\n      const cur = calls.get(tc.index) ?? { name: '', args: '' }\n      if (tc.id) cur.id = tc.id\n      if (tc.function?.name) cur.name += tc.function.name\n      if (tc.function?.arguments) cur.args += tc.function.arguments\n      calls.set(tc.index, cur)\n    }\n  }\n  for (const [, c] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {\n    if (!c.name) continue\n    yield { type: 'tool_call', call: { toolCallId: c.id, toolName: c.name, args: safeParse(c.args) } satisfies LoopToolCall }\n  }\n}\n\nfunction safeParse(s: string): Record<string, unknown> {\n  if (!s.trim()) return {}\n  try {\n    const v = JSON.parse(s)\n    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {}\n  } catch {\n    return {}\n  }\n}\n\n/** Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools */\nexport interface OpenAICompatStreamTurnOptions {\n  /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */\n  baseUrl: string\n  apiKey: string\n  model: string\n  /** OpenAI tool definitions — pass `buildAppToolOpenAITools(taxonomy)` so the\n   *  model can call the app tools. Omit for a tool-free copilot. */\n  tools?: unknown[]\n  temperature?: number\n  fetchImpl?: typeof fetch\n  /** Extra body fields (e.g. `max_tokens`). */\n  extraBody?: Record<string, unknown>\n}\n\n/**\n * Build a `streamTurn` that calls an OpenAI-compatible `/chat/completions`\n * endpoint (Tangle Router / tcloud / any compat provider) with `stream: true`\n * and yields `LoopEvent`s via {@link toLoopEvents}. Browser/edge/Node-safe —\n * just `fetch` + an SSE reader. Drop straight into `streamAppToolLoop`:\n *\n *   const cfg = resolveTangleModelConfig()                 // or { baseUrl, apiKey, model }\n *   streamAppToolLoop({ streamTurn: createOpenAICompatStreamTurn({ ...cfg, tools }), executeToolCall, ... })\n */\nexport function createOpenAICompatStreamTurn(\n  opts: OpenAICompatStreamTurnOptions,\n): (messages: LoopMessage[]) => AsyncIterable<LoopEvent> {\n  const base = opts.baseUrl.replace(/\\/+$/, '')\n  const doFetch = opts.fetchImpl ?? fetch\n  return (messages) =>\n    toLoopEvents(\n      streamChatCompletions(doFetch, `${base}/chat/completions`, opts.apiKey, {\n        model: opts.model,\n        messages,\n        stream: true,\n        stream_options: { include_usage: true },\n        ...(opts.tools && opts.tools.length > 0 ? { tools: opts.tools } : {}),\n        ...(opts.temperature != null ? { temperature: opts.temperature } : {}),\n        ...opts.extraBody,\n      }),\n    )\n}\n\n/** Stream + parse an OpenAI-compat SSE response into chunks. Tolerates `data:`\n *  framing, multi-line buffers, and the terminal `[DONE]`. */\nasync function* streamChatCompletions(\n  doFetch: typeof fetch,\n  url: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n): AsyncIterable<OpenAIStreamChunk> {\n  const res = await doFetch(url, {\n    method: 'POST',\n    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', Accept: 'text/event-stream' },\n    body: JSON.stringify(body),\n  })\n  if (!res.ok || !res.body) {\n    const text = res.body ? await res.text().catch(() => '') : ''\n    throw new Error(`OpenAI-compat stream failed (HTTP ${res.status})${text ? `: ${text.slice(0, 200)}` : ''}`)\n  }\n  const reader = res.body.getReader()\n  const decoder = new TextDecoder()\n  let buffer = ''\n  for (;;) {\n    const { done, value } = await reader.read()\n    if (done) break\n    buffer += decoder.decode(value, { stream: true })\n    const lines = buffer.split('\\n')\n    buffer = lines.pop() ?? ''\n    for (const line of lines) {\n      const trimmed = line.trim()\n      if (!trimmed.startsWith('data:')) continue\n      const data = trimmed.slice(5).trim()\n      if (data === '[DONE]') return\n      try {\n        yield JSON.parse(data) as OpenAIStreamChunk\n      } catch {\n        /* skip a partial/garbled SSE frame */\n      }\n    }\n  }\n}\n","/**\n * `createCertifiedDelivery` — the delivery truck for Tangle Intelligence.\n *\n * Pulls a tenant's CERTIFIED `AgentProfile` from the deployed plane\n * (`GET /v1/profiles/:target/composed`) and applies it to the agent's resolved\n * surfaces each turn, so an approved improvement reaches the running agent with\n * NO redeploy. This is the `composeProfile` transform `createAgentRuntime`\n * accepts — opt-in per product, fail-closed, cached + refreshed.\n *\n * Profile-WIDE by design (not prompt-only): the composed profile carries every\n * promoted artifact type keyed by kind. What's folded where:\n *   - `prompt-surface` + `skill` → the system prompt (via `composeCertifiedPrompt`).\n *   - `tool` artifacts that carry an OpenAI tool definition → `extraTools`\n *     (advertised to the model; the matching executor is supplied by the product\n *     via `executeOtherTool`). Until a `tool` artifact carries a runnable def,\n *     it is surfaced (see `current()`) but not advertised — advertising a tool\n *     with no executor would make the model call into a dead end.\n *   - `mcp` / `memory` / `rag` artifacts materialize as servers/files and deliver\n *     through the SANDBOX-provisioning seam, not this in-process one. The full\n *     certified profile is exposed via `current()` so that seam can consume it.\n *\n * Substrate boundary: THIS module imports `@tangle-network/agent-runtime`; the\n * `createAgentRuntime` core does not (it only consumes the generic transform).\n */\n\nimport {\n  composeCertifiedPrompt,\n  type CertifiedProfile,\n  pullCertified,\n} from '@tangle-network/agent-runtime/intelligence'\nimport type { ResolvedAgentProfile } from './agent'\n\nconst defaultRefreshMs = 300_000\n\n/** Define configuration options for delivering certified artifacts to a specified tenant target */\nexport interface CertifiedDeliveryConfig {\n  /** The tenant target whose certified artifacts to deliver (the agent id). */\n  target: string\n  /** Bearer for the plane. Reads `TANGLE_API_KEY` when omitted. */\n  apiKey?: string\n  /** Plane base URL. Reads `TANGLE_INTELLIGENCE_URL` then the public plane. */\n  baseUrl?: string\n  /** Min interval between certified-profile pulls. Default 5m. */\n  refreshMs?: number\n  /** fetch impl (tests / non-global-fetch runtimes). */\n  fetchImpl?: typeof fetch\n}\n\n/** Resolve and manage certified profiles with refresh and composition capabilities */\nexport interface CertifiedDelivery {\n  /** The `composeProfile` transform to pass to `createAgentRuntime`. Applies the\n   *  cached certified profile to the base surfaces; refreshes on the cadence. */\n  composeProfile(base: ResolvedAgentProfile): Promise<ResolvedAgentProfile>\n  /** Force a pull now (ignores the refresh window). Best-effort. */\n  refresh(): Promise<void>\n  /** The certified profile currently in effect (null = none promoted / pull\n   *  failed). Lets the sandbox-provisioning seam deliver the file/server\n   *  artifact types this in-process seam doesn't. */\n  current(): CertifiedProfile | null\n}\n\n/**\n * Build a certified-delivery transform for one agent target. Fail-closed: a pull\n * error or 404 keeps the last-known certified profile (or null), and the agent\n * runs on its base surfaces — it never breaks because Intelligence is down.\n */\nexport function createCertifiedDelivery(config: CertifiedDeliveryConfig): CertifiedDelivery {\n  const refreshMs = config.refreshMs ?? defaultRefreshMs\n  let certified: CertifiedProfile | null = null\n  let lastPullAt = 0\n  let inflight: Promise<void> | null = null\n\n  async function refresh(force = false): Promise<void> {\n    if (!force && Date.now() - lastPullAt < refreshMs) return\n    if (inflight) return inflight\n    inflight = (async () => {\n      const outcome = await pullCertified({\n        target: config.target,\n        apiKey: config.apiKey,\n        baseUrl: config.baseUrl,\n        fetchImpl: config.fetchImpl,\n      })\n      lastPullAt = Date.now()\n      // Only replace on a real pull; a 404/error keeps the last-known profile.\n      if (outcome.succeeded) certified = outcome.value\n    })()\n    try {\n      await inflight\n    } finally {\n      inflight = null\n    }\n  }\n\n  return {\n    async composeProfile(base) {\n      await refresh()\n      return {\n        // prompt-surface + skill fold into the system prompt.\n        systemPrompt: composeCertifiedPrompt(base.systemPrompt, certified),\n        // Certified `tool` artifacts deliver here once they carry a runnable\n        // OpenAI def + the product wires the executor; until then pass through.\n        extraTools: base.extraTools,\n      }\n    },\n    refresh: () => refresh(true),\n    current: () => certified,\n  }\n}\n","/**\n * Surface-scoped profile overlay — the seam letting any product page (a\n * sequence editor, a brief composer, a dataset view) add MCP servers, a prompt\n * addendum, and permission tightening to the workspace agent profile for turns\n * initiated FROM that surface, without the chat orchestrator knowing any\n * surface's specifics. The orchestrator resolves `(kind, ctx)` through a\n * registry the REQUEST HANDLER constructs per request (construction is a Map\n * build — cheap) and merges the result into the base profile it was about to\n * send to the sandbox. Per-request construction is the trust mechanism, not an\n * optimization target: each `build()` closes over server-trusted request state\n * (env bindings, secrets, the AUTHENTICATED user/workspace), which on Workers\n * exists only per request — a startup-built registry would force identity\n * through the untrusted client `ctx`.\n *\n * SECURITY INVARIANT: the surface `kind` and the ids inside `ctx` arrive on\n * the client request and are pure ROUTING data — never trusted content, never\n * identity. Identity comes from the closure (see above). The registered\n * `build()` runs server-side only: it validates the routing ids against the\n * product's access control, then mints its own URLs and capability tokens from\n * server configuration (`buildHttpMcpServer` + `createCapabilityToken` in\n * ../tools). A client can therefore never inject an arbitrary MCP url, header,\n * or token into the agent profile: the overlay's `mcp` values are typed as\n * {@link SurfaceMcpServer} (= the server-built `AppToolMcpServer` entry shape),\n * and only build() constructs them.\n */\n\nimport type { AppToolMcpServer } from '../tools/mcp'\n\n/** Sandbox permission posture values, ranked deny > ask > allow for merging. */\nexport type SurfacePermissionValue = 'allow' | 'ask' | 'deny'\n\n/** The only MCP entry shape an overlay may carry: the server-built bridge\n *  entry from ../tools/mcp (transport, url, headers, and capability token all\n *  assembled server-side). The alias exists so overlay authors reach for the\n *  builders in ../tools rather than hand-rolling `{ url: ctx.url }` shapes\n *  that would let request data become a dialable endpoint. */\nexport type SurfaceMcpServer = AppToolMcpServer\n\n/** What one surface contributes to the agent profile for a single turn. */\nexport interface SurfaceOverlay {\n  /** MCP servers to mount for this turn, keyed by tool-routing name. Names\n   *  must not collide with the base profile's — see {@link mergeSurfaceOverlay}. */\n  mcp?: Record<string, SurfaceMcpServer>\n  /** Appended to the base system-prompt addendum with a blank-line separator. */\n  promptAddendum?: string\n  /** Per-key posture the surface wants for its turns. Merging is monotone\n   *  fail-closed: the stricter of base/overlay wins, so a surface can tighten\n   *  the workspace posture but never relax it. */\n  permissions?: Record<string, SurfacePermissionValue>\n}\n\n/**\n * One registered surface kind. `TCtx` is the shape build() expects — a CLAIM\n * about the client payload, not a guarantee: the registry hands build() the\n * request's `ctx` unvalidated, so build() must treat every field as an\n * untrusted id (resolve it through access control that throws on a bad or\n * foreign id) before minting anything from it.\n */\nexport interface SurfaceKindDefinition<TCtx> {\n  kind: string\n  build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>\n}\n\n/** The variance-erased form a registry accepts (`build` is contravariant in\n *  `TCtx`, so every concrete definition is assignable to this). */\nexport type AnySurfaceKind = SurfaceKindDefinition<never>\n\n/**\n * Declare one surface kind. The `kind` string is the client-visible routing\n * key (e.g. `'sequences'`); `build` is the server-side factory that turns a\n * validated ctx into the overlay for one turn.\n */\nexport function defineSurfaceKind<TCtx>(opts: {\n  kind: string\n  build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>\n}): SurfaceKindDefinition<TCtx> {\n  if (typeof opts.kind !== 'string' || opts.kind.length === 0 || /\\s/.test(opts.kind)) {\n    throw new Error(`surface kind must be a non-empty string without whitespace (got ${JSON.stringify(opts.kind)})`)\n  }\n  if (typeof opts.build !== 'function') {\n    throw new Error(`surface kind '${opts.kind}' requires a build function`)\n  }\n  return { kind: opts.kind, build: opts.build }\n}\n\n/** Resolve and build the overlay for a given surface kind within a turn context */\nexport interface SurfaceRegistry {\n  /** Build the overlay for one turn. Throws on an unknown kind — an unknown\n   *  surface is a routing bug (client and server registries drifted), and\n   *  silently returning an empty overlay would strip the surface's tools from\n   *  the turn with no signal anywhere. Build errors propagate unwrapped. */\n  resolve(kind: string, ctx: unknown): Promise<SurfaceOverlay>\n}\n\n/**\n * Assemble the product's surface registry from its registered kinds. Duplicate\n * kinds throw at construction: two builders behind one routing key would make\n * the mounted toolset depend on registration order.\n */\nexport function createSurfaceRegistry(kinds: readonly AnySurfaceKind[]): SurfaceRegistry {\n  const byKind = new Map<string, AnySurfaceKind>()\n  for (const definition of kinds) {\n    if (byKind.has(definition.kind)) {\n      throw new Error(`duplicate surface kind '${definition.kind}' — each kind must be registered exactly once`)\n    }\n    byKind.set(definition.kind, definition)\n  }\n\n  return {\n    async resolve(kind, ctx) {\n      const definition = byKind.get(kind)\n      if (!definition) {\n        const known = [...byKind.keys()].join(', ') || '(none)'\n        throw new Error(\n          `unknown surface kind '${kind}' — registered kinds: ${known}. ` +\n            'An unknown surface is a routing bug: register the kind via defineSurfaceKind before clients can reference it.',\n        )\n      }\n      // The trust boundary where static ctx typing ends: the request payload is\n      // handed to build() as-is, and build() validates it (see SurfaceKindDefinition).\n      const overlay = await definition.build(ctx as never)\n      assertSurfaceOverlay(overlay, `surface kind '${kind}'`)\n      return overlay\n    },\n  }\n}\n\n/** Base-profile slice the merge reads/writes. Real callers pass their full\n *  profile object; every field outside this slice passes through untouched. */\nexport interface SurfaceMergeBase {\n  mcp?: Record<string, unknown>\n  systemPromptAddendum?: string\n  permissions?: Record<string, SurfacePermissionValue>\n}\n\nconst PERMISSION_SEVERITY: Record<SurfacePermissionValue, number> = { allow: 0, ask: 1, deny: 2 }\n\n/**\n * Merge one surface overlay into a base profile, returning a new object\n * (the base is never mutated; untouched nested records are shared by\n * reference).\n *\n * - `mcp`: overlay servers are added under their own names. A name already\n *   present on the base THROWS — a collision is two servers claiming one\n *   routing name, and renaming either silently would corrupt tool routing for\n *   whichever caller expected the original binding.\n * - `systemPromptAddendum`: the overlay's `promptAddendum` appends after a\n *   blank-line separator (no separator when the base has no addendum).\n * - `permissions`: per key the STRICTER value wins (deny > ask > allow). A\n *   surface can tighten the base posture for its turns; a base 'deny' survives\n *   any overlay.\n */\nexport function mergeSurfaceOverlay<TBase extends SurfaceMergeBase>(\n  base: TBase,\n  overlay: SurfaceOverlay,\n): TBase & SurfaceMergeBase {\n  assertSurfaceOverlay(overlay, 'surface overlay')\n  const merged: SurfaceMergeBase = { ...base }\n\n  if (overlay.mcp && Object.keys(overlay.mcp).length > 0) {\n    const baseMcp = base.mcp ?? {}\n    const collisions = Object.keys(overlay.mcp).filter((name) => name in baseMcp)\n    if (collisions.length > 0) {\n      throw new Error(\n        `surface overlay MCP name collision: ${collisions.map((n) => `'${n}'`).join(', ')} already exist on the base profile. ` +\n          'Two servers cannot claim one name — give the surface server a distinct name.',\n      )\n    }\n    merged.mcp = { ...baseMcp, ...overlay.mcp }\n  }\n\n  if (overlay.promptAddendum !== undefined) {\n    merged.systemPromptAddendum = base.systemPromptAddendum\n      ? `${base.systemPromptAddendum}\\n\\n${overlay.promptAddendum}`\n      : overlay.promptAddendum\n  }\n\n  if (overlay.permissions && Object.keys(overlay.permissions).length > 0) {\n    const permissions: Record<string, SurfacePermissionValue> = { ...(base.permissions ?? {}) }\n    for (const [key, value] of Object.entries(overlay.permissions)) {\n      const existing = permissions[key]\n      permissions[key] =\n        existing === undefined || PERMISSION_SEVERITY[value] > PERMISSION_SEVERITY[existing] ? value : existing\n    }\n    merged.permissions = permissions\n  }\n\n  // merged began as a shallow copy of base; only the three slice fields were\n  // replaced, so the intersection type is the true shape.\n  return merged as TBase & SurfaceMergeBase\n}\n\n/** Reject overlays a build() (or hand-rolled caller) malformed, with the exact\n *  field named: a relative MCP url, a blank addendum, or an off-vocabulary\n *  permission would otherwise surface only as an opaque sandbox failure. */\nfunction assertSurfaceOverlay(overlay: SurfaceOverlay, label: string): void {\n  if (overlay.promptAddendum !== undefined) {\n    if (typeof overlay.promptAddendum !== 'string' || overlay.promptAddendum.trim().length === 0) {\n      throw new Error(`${label}: promptAddendum must be a non-blank string when provided`)\n    }\n  }\n  if (overlay.mcp !== undefined) {\n    for (const [name, server] of Object.entries(overlay.mcp)) {\n      if (name.trim().length === 0) throw new Error(`${label}: MCP server names must be non-empty`)\n      if (server.transport !== 'http') {\n        throw new Error(`${label}: MCP server '${name}' must use transport 'http' (got ${JSON.stringify((server as { transport?: unknown }).transport)})`)\n      }\n      let parsed: URL\n      try {\n        parsed = new URL(server.url)\n      } catch {\n        throw new Error(`${label}: MCP server '${name}' url must be an absolute URL (got ${JSON.stringify(server.url)})`)\n      }\n      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n        throw new Error(`${label}: MCP server '${name}' url must be http(s) (got ${JSON.stringify(server.url)})`)\n      }\n    }\n  }\n  if (overlay.permissions !== undefined) {\n    for (const [key, value] of Object.entries(overlay.permissions)) {\n      if (!(value in PERMISSION_SEVERITY)) {\n        throw new Error(`${label}: permission '${key}' must be 'allow' | 'ask' | 'deny' (got ${JSON.stringify(value)})`)\n      }\n    }\n  }\n}\n","/**\n * The bounded agent tool-loop — owned by `@tangle-network/agent-runtime`.\n *\n * A model turn may emit tool calls (integration-hub actions, the app tools from\n * `../tools`, delegation). The loop streams a turn, collects the executable tool\n * calls, dispatches each, appends the results to history in OpenAI\n * function-calling shape, and re-runs so the model reads them — bounded by\n * `maxToolTurns`, a wall-clock `deadlineMs`, and a `maxCostUsd` budget.\n *\n * The history shape is the OpenAI function-calling contract: the assistant turn\n * that emitted tool calls is preserved as an `assistant` message carrying its\n * `tool_calls` array, and each result is its own `{ role: 'tool', tool_call_id,\n * content }` message keyed to the call. A strict model (Claude, and any\n * OpenAI-compatible provider that validates tool history) needs this to read its\n * own tool use back; folding results into a `user` message makes such models\n * re-issue the same call in a loop.\n *\n * The loop is substrate-owned (`runToolLoop` / `streamToolLoop`); the app\n * supplies `streamTurn` (wrapping its model endpoint) and `executeToolCall`\n * (routing to its integration + app-tool executors). The app-facing names below\n * are 1:1 aliases of the canonical symbols, kept so this package's consumers and\n * the in-package `createAgentRuntime` read against a single, stable vocabulary.\n *\n * This is the LEAF the runtime barrel and its children both import — keeping the\n * tool-loop vocabulary out of any import cycle. The barrel re-exports it.\n */\n\nexport {\n  runToolLoop as runAppToolLoop,\n  streamToolLoop as streamAppToolLoop,\n} from '@tangle-network/agent-runtime'\nexport type {\n  ToolLoopCall as LoopToolCall,\n  ToolLoopAssistantToolCall as LoopAssistantToolCall,\n  ToolLoopMessage as LoopMessage,\n  ToolLoopEvent,\n  ToolLoopStopReason,\n  ToolLoopResult,\n  RunToolLoopOptions as AppToolLoopOptions,\n  StreamToolLoopOptions as StreamAppToolLoopOptions,\n  StreamToolLoopYield as StreamLoopYield,\n} from '@tangle-network/agent-runtime'\n\n/**\n * Events the app's OpenAI-compat stream adapter ({@link toLoopEvents}) yields.\n *\n * This is the app's own `Raw` event type for the streaming loop — the canonical\n * `streamToolLoop<Raw>` is generic over it. It widens the substrate's\n * tool-loop event with `reasoning` (DeepSeek/router `reasoning_content` /\n * `thinking` deltas, rendered as thinking sections) and `usage` (per-message\n * token accounting) — neither belongs in the substrate's loop contract, so they\n * stay here. The adapter maps each into the `streamTurn` seam; `text` and\n * `tool_call` drive the loop, `reasoning` / `usage` pass through to the UI.\n */\nexport type LoopEvent =\n  | { type: 'text'; text: string }\n  | { type: 'reasoning'; text: string }\n  | { type: 'tool_call'; call: import('@tangle-network/agent-runtime').ToolLoopCall }\n  | { type: 'usage'; usage: { promptTokens: number; completionTokens: number } }\n  | { type: 'other'; event: unknown }\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/runtime/openai-stream.ts","../../src/runtime/certified-delivery.ts","../../src/runtime/surface-profile.ts","../../src/runtime/loop.ts"],"sourcesContent":["/**\n * OpenAI-compatible stream → `LoopEvent` adapter, for NON-sandbox copilots.\n *\n * `streamAppToolLoop` takes a `streamTurn` seam that yields `LoopEvent`s. A\n * sandboxed agent produces those from its container; a browser/edge copilot\n * instead calls a model directly. The Tangle Router, the tcloud SDK, and most\n * providers all speak the OpenAI Chat Completions streaming shape — so the ONE\n * reusable piece is assembling that stream (content deltas + FRAGMENTED\n * tool-call deltas) into `LoopEvent`s. That assembly is the boilerplate every\n * copilot would re-write (and get wrong — OpenAI streams tool-call arguments in\n * pieces across chunks).\n *\n * This does NOT implement an HTTP client beyond a minimal `fetch` + SSE reader\n * (browser/edge/Node-safe, zero deps). For richer transport use the tcloud SDK\n * or the Vercel AI SDK and pipe their stream through {@link toLoopEvents}.\n */\nimport type { LoopEvent, LoopMessage, LoopToolCall } from './loop'\n\n/** Minimal OpenAI Chat Completions streaming chunk (structural — no `openai` dep). */\nexport interface OpenAIStreamChunk {\n  choices?: Array<{\n    delta?: {\n      content?: string | null\n      /** Reasoning deltas — DeepSeek/router use `reasoning_content`; some proxies use `thinking`. */\n      reasoning_content?: string | null\n      thinking?: string | null\n      tool_calls?: Array<{\n        index: number\n        id?: string\n        function?: { name?: string; arguments?: string }\n      }>\n    }\n    finish_reason?: string | null\n  }>\n  /** Final-chunk token accounting (requires `stream_options.include_usage`). */\n  usage?: {\n    prompt_tokens?: number\n    completion_tokens?: number\n  } | null\n}\n\ninterface PartialToolCall {\n  id?: string\n  name: string\n  args: string\n}\n\n/**\n * Map an OpenAI-compat streaming chunk iterator to `LoopEvent`s: each content\n * delta → a `text` event; tool-call deltas are accumulated by index across\n * chunks and emitted as one complete `tool_call` event when the stream finishes\n * (arguments JSON-parsed; an empty/garbled args string yields `{}` rather than\n * throwing). Works for the Tangle Router, tcloud, or any OpenAI-compat source.\n */\nexport async function* toLoopEvents(chunks: AsyncIterable<OpenAIStreamChunk>): AsyncIterable<LoopEvent> {\n  const calls = new Map<number, PartialToolCall>()\n  for await (const chunk of chunks) {\n    // Usage rides the final chunk, which has an empty choices array — handle\n    // it before the choice guard.\n    if (chunk.usage?.prompt_tokens != null || chunk.usage?.completion_tokens != null) {\n      yield {\n        type: 'usage',\n        usage: {\n          promptTokens: chunk.usage.prompt_tokens ?? 0,\n          completionTokens: chunk.usage.completion_tokens ?? 0,\n        },\n      }\n    }\n    const choice = chunk.choices?.[0]\n    if (!choice) continue\n    const content = choice.delta?.content\n    if (content) yield { type: 'text', text: content }\n    const reasoning = choice.delta?.reasoning_content ?? choice.delta?.thinking\n    if (reasoning) yield { type: 'reasoning', text: reasoning }\n    for (const tc of choice.delta?.tool_calls ?? []) {\n      const cur = calls.get(tc.index) ?? { name: '', args: '' }\n      if (tc.id) cur.id = tc.id\n      if (tc.function?.name) cur.name += tc.function.name\n      if (tc.function?.arguments) cur.args += tc.function.arguments\n      calls.set(tc.index, cur)\n    }\n  }\n  for (const [, c] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {\n    if (!c.name) continue\n    yield { type: 'tool_call', call: { toolCallId: c.id, toolName: c.name, args: safeParse(c.args) } satisfies LoopToolCall }\n  }\n}\n\nfunction safeParse(s: string): Record<string, unknown> {\n  if (!s.trim()) return {}\n  try {\n    const v = JSON.parse(s)\n    return v && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {}\n  } catch {\n    return {}\n  }\n}\n\n/** Define options for configuring an OpenAI-compatible streaming chat turn including API details and tools */\nexport interface OpenAICompatStreamTurnOptions {\n  /** OpenAI-compat base URL (e.g. the Tangle Router `https://router.tangle.tools/v1`). */\n  baseUrl: string\n  apiKey: string\n  model: string\n  /** OpenAI tool definitions — pass `buildAppToolOpenAITools(taxonomy)` so the\n   *  model can call the app tools. Omit for a tool-free copilot. */\n  tools?: unknown[]\n  temperature?: number\n  fetchImpl?: typeof fetch\n  /** Extra body fields (e.g. `max_tokens`). */\n  extraBody?: Record<string, unknown>\n}\n\n/**\n * Build a `streamTurn` that calls an OpenAI-compatible `/chat/completions`\n * endpoint (Tangle Router / tcloud / any compat provider) with `stream: true`\n * and yields `LoopEvent`s via {@link toLoopEvents}. Browser/edge/Node-safe —\n * just `fetch` + an SSE reader. Drop straight into `streamAppToolLoop`:\n *\n *   const cfg = resolveTangleModelConfig()                 // or { baseUrl, apiKey, model }\n *   streamAppToolLoop({ streamTurn: createOpenAICompatStreamTurn({ ...cfg, tools }), executeToolCall, ... })\n */\nexport function createOpenAICompatStreamTurn(\n  opts: OpenAICompatStreamTurnOptions,\n): (messages: LoopMessage[]) => AsyncIterable<LoopEvent> {\n  const base = opts.baseUrl.replace(/\\/+$/, '')\n  const doFetch = opts.fetchImpl ?? fetch\n  return (messages) =>\n    toLoopEvents(\n      streamChatCompletions(doFetch, `${base}/chat/completions`, opts.apiKey, {\n        model: opts.model,\n        messages,\n        stream: true,\n        stream_options: { include_usage: true },\n        ...(opts.tools && opts.tools.length > 0 ? { tools: opts.tools } : {}),\n        ...(opts.temperature != null ? { temperature: opts.temperature } : {}),\n        ...opts.extraBody,\n      }),\n    )\n}\n\n/** Stream + parse an OpenAI-compat SSE response into chunks. Tolerates `data:`\n *  framing, multi-line buffers, and the terminal `[DONE]`. */\nasync function* streamChatCompletions(\n  doFetch: typeof fetch,\n  url: string,\n  apiKey: string,\n  body: Record<string, unknown>,\n): AsyncIterable<OpenAIStreamChunk> {\n  const res = await doFetch(url, {\n    method: 'POST',\n    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', Accept: 'text/event-stream' },\n    body: JSON.stringify(body),\n  })\n  if (!res.ok || !res.body) {\n    const text = res.body ? await res.text().catch(() => '') : ''\n    const error = new Error(`OpenAI-compat stream failed (HTTP ${res.status})${text ? `: ${text.slice(0, 200)}` : ''}`)\n    // Stamp the NUMERIC status. `isUpstreamUnavailable` (`/model-resolution`)\n    // reads a numeric field first and prose only as a backstop, and a\n    // Cloudflare EDGE 502 gives it nothing else to read: `content-type:\n    // text/plain`, a body of `error code: 502`, and none of the router's own\n    // `x-tangle-*` headers, because the origin never ran. Carrying the status\n    // as data keeps THIS path — the browser/edge copilot lane, which calls the\n    // router directly — out of the string-matching business entirely.\n    Object.assign(error, { status: res.status })\n    throw error\n  }\n  const reader = res.body.getReader()\n  const decoder = new TextDecoder()\n  let buffer = ''\n  for (;;) {\n    const { done, value } = await reader.read()\n    if (done) break\n    buffer += decoder.decode(value, { stream: true })\n    const lines = buffer.split('\\n')\n    buffer = lines.pop() ?? ''\n    for (const line of lines) {\n      const trimmed = line.trim()\n      if (!trimmed.startsWith('data:')) continue\n      const data = trimmed.slice(5).trim()\n      if (data === '[DONE]') return\n      try {\n        yield JSON.parse(data) as OpenAIStreamChunk\n      } catch {\n        /* skip a partial/garbled SSE frame */\n      }\n    }\n  }\n}\n","/**\n * `createCertifiedDelivery` — the delivery truck for Tangle Intelligence.\n *\n * Pulls a tenant's CERTIFIED `AgentProfile` from the deployed plane\n * (`GET /v1/profiles/:target/composed`) and applies it to the agent's resolved\n * surfaces each turn, so an approved improvement reaches the running agent with\n * NO redeploy. This is the `composeProfile` transform `createAgentRuntime`\n * accepts — opt-in per product, fail-closed, cached + refreshed.\n *\n * Profile-WIDE by design (not prompt-only): the composed profile carries every\n * promoted artifact type keyed by kind. What's folded where:\n *   - `prompt-surface` + `skill` → the system prompt (via `composeCertifiedPrompt`).\n *   - `tool` artifacts that carry an OpenAI tool definition → `extraTools`\n *     (advertised to the model; the matching executor is supplied by the product\n *     via `executeOtherTool`). Until a `tool` artifact carries a runnable def,\n *     it is surfaced (see `current()`) but not advertised — advertising a tool\n *     with no executor would make the model call into a dead end.\n *   - `mcp` / `memory` / `rag` artifacts materialize as servers/files and deliver\n *     through the SANDBOX-provisioning seam, not this in-process one. The full\n *     certified profile is exposed via `current()` so that seam can consume it.\n *\n * Substrate boundary: THIS module imports `@tangle-network/agent-runtime`; the\n * `createAgentRuntime` core does not (it only consumes the generic transform).\n */\n\nimport {\n  composeCertifiedPrompt,\n  type CertifiedProfile,\n  pullCertified,\n} from '@tangle-network/agent-runtime/intelligence'\nimport type { ResolvedAgentProfile } from './agent'\n\nconst defaultRefreshMs = 300_000\n\n/** Define configuration options for delivering certified artifacts to a specified tenant target */\nexport interface CertifiedDeliveryConfig {\n  /** The tenant target whose certified artifacts to deliver (the agent id). */\n  target: string\n  /** Bearer for the plane. Reads `TANGLE_API_KEY` when omitted. */\n  apiKey?: string\n  /** Plane base URL. Reads `TANGLE_INTELLIGENCE_URL` then the public plane. */\n  baseUrl?: string\n  /** Min interval between certified-profile pulls. Default 5m. */\n  refreshMs?: number\n  /** fetch impl (tests / non-global-fetch runtimes). */\n  fetchImpl?: typeof fetch\n}\n\n/** Resolve and manage certified profiles with refresh and composition capabilities */\nexport interface CertifiedDelivery {\n  /** The `composeProfile` transform to pass to `createAgentRuntime`. Applies the\n   *  cached certified profile to the base surfaces; refreshes on the cadence. */\n  composeProfile(base: ResolvedAgentProfile): Promise<ResolvedAgentProfile>\n  /** Force a pull now (ignores the refresh window). Best-effort. */\n  refresh(): Promise<void>\n  /** The certified profile currently in effect (null = none promoted / pull\n   *  failed). Lets the sandbox-provisioning seam deliver the file/server\n   *  artifact types this in-process seam doesn't. */\n  current(): CertifiedProfile | null\n}\n\n/**\n * Build a certified-delivery transform for one agent target. Fail-closed: a pull\n * error or 404 keeps the last-known certified profile (or null), and the agent\n * runs on its base surfaces — it never breaks because Intelligence is down.\n */\nexport function createCertifiedDelivery(config: CertifiedDeliveryConfig): CertifiedDelivery {\n  const refreshMs = config.refreshMs ?? defaultRefreshMs\n  let certified: CertifiedProfile | null = null\n  let lastPullAt = 0\n  let inflight: Promise<void> | null = null\n\n  async function refresh(force = false): Promise<void> {\n    if (!force && Date.now() - lastPullAt < refreshMs) return\n    if (inflight) return inflight\n    inflight = (async () => {\n      const outcome = await pullCertified({\n        target: config.target,\n        apiKey: config.apiKey,\n        baseUrl: config.baseUrl,\n        fetchImpl: config.fetchImpl,\n      })\n      lastPullAt = Date.now()\n      // Only replace on a real pull; a 404/error keeps the last-known profile.\n      if (outcome.succeeded) certified = outcome.value\n    })()\n    try {\n      await inflight\n    } finally {\n      inflight = null\n    }\n  }\n\n  return {\n    async composeProfile(base) {\n      await refresh()\n      return {\n        // prompt-surface + skill fold into the system prompt.\n        systemPrompt: composeCertifiedPrompt(base.systemPrompt, certified),\n        // Certified `tool` artifacts deliver here once they carry a runnable\n        // OpenAI def + the product wires the executor; until then pass through.\n        extraTools: base.extraTools,\n      }\n    },\n    refresh: () => refresh(true),\n    current: () => certified,\n  }\n}\n","/**\n * Surface-scoped profile overlay — the seam letting any product page (a\n * sequence editor, a brief composer, a dataset view) add MCP servers, a prompt\n * addendum, and permission tightening to the workspace agent profile for turns\n * initiated FROM that surface, without the chat orchestrator knowing any\n * surface's specifics. The orchestrator resolves `(kind, ctx)` through a\n * registry the REQUEST HANDLER constructs per request (construction is a Map\n * build — cheap) and merges the result into the base profile it was about to\n * send to the sandbox. Per-request construction is the trust mechanism, not an\n * optimization target: each `build()` closes over server-trusted request state\n * (env bindings, secrets, the AUTHENTICATED user/workspace), which on Workers\n * exists only per request — a startup-built registry would force identity\n * through the untrusted client `ctx`.\n *\n * SECURITY INVARIANT: the surface `kind` and the ids inside `ctx` arrive on\n * the client request and are pure ROUTING data — never trusted content, never\n * identity. Identity comes from the closure (see above). The registered\n * `build()` runs server-side only: it validates the routing ids against the\n * product's access control, then mints its own URLs and capability tokens from\n * server configuration (`buildHttpMcpServer` + `createCapabilityToken` in\n * ../tools). A client can therefore never inject an arbitrary MCP url, header,\n * or token into the agent profile: the overlay's `mcp` values are typed as\n * {@link SurfaceMcpServer} (= the server-built `AppToolMcpServer` entry shape),\n * and only build() constructs them.\n */\n\nimport type { AppToolMcpServer } from '../tools/mcp'\n\n/** Sandbox permission posture values, ranked deny > ask > allow for merging. */\nexport type SurfacePermissionValue = 'allow' | 'ask' | 'deny'\n\n/** The only MCP entry shape an overlay may carry: the server-built bridge\n *  entry from ../tools/mcp (transport, url, headers, and capability token all\n *  assembled server-side). The alias exists so overlay authors reach for the\n *  builders in ../tools rather than hand-rolling `{ url: ctx.url }` shapes\n *  that would let request data become a dialable endpoint. */\nexport type SurfaceMcpServer = AppToolMcpServer\n\n/** What one surface contributes to the agent profile for a single turn. */\nexport interface SurfaceOverlay {\n  /** MCP servers to mount for this turn, keyed by tool-routing name. Names\n   *  must not collide with the base profile's — see {@link mergeSurfaceOverlay}. */\n  mcp?: Record<string, SurfaceMcpServer>\n  /** Appended to the base system-prompt addendum with a blank-line separator. */\n  promptAddendum?: string\n  /** Per-key posture the surface wants for its turns. Merging is monotone\n   *  fail-closed: the stricter of base/overlay wins, so a surface can tighten\n   *  the workspace posture but never relax it. */\n  permissions?: Record<string, SurfacePermissionValue>\n}\n\n/**\n * One registered surface kind. `TCtx` is the shape build() expects — a CLAIM\n * about the client payload, not a guarantee: the registry hands build() the\n * request's `ctx` unvalidated, so build() must treat every field as an\n * untrusted id (resolve it through access control that throws on a bad or\n * foreign id) before minting anything from it.\n */\nexport interface SurfaceKindDefinition<TCtx> {\n  kind: string\n  build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>\n}\n\n/** The variance-erased form a registry accepts (`build` is contravariant in\n *  `TCtx`, so every concrete definition is assignable to this). */\nexport type AnySurfaceKind = SurfaceKindDefinition<never>\n\n/**\n * Declare one surface kind. The `kind` string is the client-visible routing\n * key (e.g. `'sequences'`); `build` is the server-side factory that turns a\n * validated ctx into the overlay for one turn.\n */\nexport function defineSurfaceKind<TCtx>(opts: {\n  kind: string\n  build: (ctx: TCtx) => SurfaceOverlay | Promise<SurfaceOverlay>\n}): SurfaceKindDefinition<TCtx> {\n  if (typeof opts.kind !== 'string' || opts.kind.length === 0 || /\\s/.test(opts.kind)) {\n    throw new Error(`surface kind must be a non-empty string without whitespace (got ${JSON.stringify(opts.kind)})`)\n  }\n  if (typeof opts.build !== 'function') {\n    throw new Error(`surface kind '${opts.kind}' requires a build function`)\n  }\n  return { kind: opts.kind, build: opts.build }\n}\n\n/** Resolve and build the overlay for a given surface kind within a turn context */\nexport interface SurfaceRegistry {\n  /** Build the overlay for one turn. Throws on an unknown kind — an unknown\n   *  surface is a routing bug (client and server registries drifted), and\n   *  silently returning an empty overlay would strip the surface's tools from\n   *  the turn with no signal anywhere. Build errors propagate unwrapped. */\n  resolve(kind: string, ctx: unknown): Promise<SurfaceOverlay>\n}\n\n/**\n * Assemble the product's surface registry from its registered kinds. Duplicate\n * kinds throw at construction: two builders behind one routing key would make\n * the mounted toolset depend on registration order.\n */\nexport function createSurfaceRegistry(kinds: readonly AnySurfaceKind[]): SurfaceRegistry {\n  const byKind = new Map<string, AnySurfaceKind>()\n  for (const definition of kinds) {\n    if (byKind.has(definition.kind)) {\n      throw new Error(`duplicate surface kind '${definition.kind}' — each kind must be registered exactly once`)\n    }\n    byKind.set(definition.kind, definition)\n  }\n\n  return {\n    async resolve(kind, ctx) {\n      const definition = byKind.get(kind)\n      if (!definition) {\n        const known = [...byKind.keys()].join(', ') || '(none)'\n        throw new Error(\n          `unknown surface kind '${kind}' — registered kinds: ${known}. ` +\n            'An unknown surface is a routing bug: register the kind via defineSurfaceKind before clients can reference it.',\n        )\n      }\n      // The trust boundary where static ctx typing ends: the request payload is\n      // handed to build() as-is, and build() validates it (see SurfaceKindDefinition).\n      const overlay = await definition.build(ctx as never)\n      assertSurfaceOverlay(overlay, `surface kind '${kind}'`)\n      return overlay\n    },\n  }\n}\n\n/** Base-profile slice the merge reads/writes. Real callers pass their full\n *  profile object; every field outside this slice passes through untouched. */\nexport interface SurfaceMergeBase {\n  mcp?: Record<string, unknown>\n  systemPromptAddendum?: string\n  permissions?: Record<string, SurfacePermissionValue>\n}\n\nconst PERMISSION_SEVERITY: Record<SurfacePermissionValue, number> = { allow: 0, ask: 1, deny: 2 }\n\n/**\n * Merge one surface overlay into a base profile, returning a new object\n * (the base is never mutated; untouched nested records are shared by\n * reference).\n *\n * - `mcp`: overlay servers are added under their own names. A name already\n *   present on the base THROWS — a collision is two servers claiming one\n *   routing name, and renaming either silently would corrupt tool routing for\n *   whichever caller expected the original binding.\n * - `systemPromptAddendum`: the overlay's `promptAddendum` appends after a\n *   blank-line separator (no separator when the base has no addendum).\n * - `permissions`: per key the STRICTER value wins (deny > ask > allow). A\n *   surface can tighten the base posture for its turns; a base 'deny' survives\n *   any overlay.\n */\nexport function mergeSurfaceOverlay<TBase extends SurfaceMergeBase>(\n  base: TBase,\n  overlay: SurfaceOverlay,\n): TBase & SurfaceMergeBase {\n  assertSurfaceOverlay(overlay, 'surface overlay')\n  const merged: SurfaceMergeBase = { ...base }\n\n  if (overlay.mcp && Object.keys(overlay.mcp).length > 0) {\n    const baseMcp = base.mcp ?? {}\n    const collisions = Object.keys(overlay.mcp).filter((name) => name in baseMcp)\n    if (collisions.length > 0) {\n      throw new Error(\n        `surface overlay MCP name collision: ${collisions.map((n) => `'${n}'`).join(', ')} already exist on the base profile. ` +\n          'Two servers cannot claim one name — give the surface server a distinct name.',\n      )\n    }\n    merged.mcp = { ...baseMcp, ...overlay.mcp }\n  }\n\n  if (overlay.promptAddendum !== undefined) {\n    merged.systemPromptAddendum = base.systemPromptAddendum\n      ? `${base.systemPromptAddendum}\\n\\n${overlay.promptAddendum}`\n      : overlay.promptAddendum\n  }\n\n  if (overlay.permissions && Object.keys(overlay.permissions).length > 0) {\n    const permissions: Record<string, SurfacePermissionValue> = { ...(base.permissions ?? {}) }\n    for (const [key, value] of Object.entries(overlay.permissions)) {\n      const existing = permissions[key]\n      permissions[key] =\n        existing === undefined || PERMISSION_SEVERITY[value] > PERMISSION_SEVERITY[existing] ? value : existing\n    }\n    merged.permissions = permissions\n  }\n\n  // merged began as a shallow copy of base; only the three slice fields were\n  // replaced, so the intersection type is the true shape.\n  return merged as TBase & SurfaceMergeBase\n}\n\n/** Reject overlays a build() (or hand-rolled caller) malformed, with the exact\n *  field named: a relative MCP url, a blank addendum, or an off-vocabulary\n *  permission would otherwise surface only as an opaque sandbox failure. */\nfunction assertSurfaceOverlay(overlay: SurfaceOverlay, label: string): void {\n  if (overlay.promptAddendum !== undefined) {\n    if (typeof overlay.promptAddendum !== 'string' || overlay.promptAddendum.trim().length === 0) {\n      throw new Error(`${label}: promptAddendum must be a non-blank string when provided`)\n    }\n  }\n  if (overlay.mcp !== undefined) {\n    for (const [name, server] of Object.entries(overlay.mcp)) {\n      if (name.trim().length === 0) throw new Error(`${label}: MCP server names must be non-empty`)\n      if (server.transport !== 'http') {\n        throw new Error(`${label}: MCP server '${name}' must use transport 'http' (got ${JSON.stringify((server as { transport?: unknown }).transport)})`)\n      }\n      let parsed: URL\n      try {\n        parsed = new URL(server.url)\n      } catch {\n        throw new Error(`${label}: MCP server '${name}' url must be an absolute URL (got ${JSON.stringify(server.url)})`)\n      }\n      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n        throw new Error(`${label}: MCP server '${name}' url must be http(s) (got ${JSON.stringify(server.url)})`)\n      }\n    }\n  }\n  if (overlay.permissions !== undefined) {\n    for (const [key, value] of Object.entries(overlay.permissions)) {\n      if (!(value in PERMISSION_SEVERITY)) {\n        throw new Error(`${label}: permission '${key}' must be 'allow' | 'ask' | 'deny' (got ${JSON.stringify(value)})`)\n      }\n    }\n  }\n}\n","/**\n * The bounded agent tool-loop — owned by `@tangle-network/agent-runtime`.\n *\n * A model turn may emit tool calls (integration-hub actions, the app tools from\n * `../tools`, delegation). The loop streams a turn, collects the executable tool\n * calls, dispatches each, appends the results to history in OpenAI\n * function-calling shape, and re-runs so the model reads them — bounded by\n * `maxToolTurns`, a wall-clock `deadlineMs`, and a `maxCostUsd` budget.\n *\n * The history shape is the OpenAI function-calling contract: the assistant turn\n * that emitted tool calls is preserved as an `assistant` message carrying its\n * `tool_calls` array, and each result is its own `{ role: 'tool', tool_call_id,\n * content }` message keyed to the call. A strict model (Claude, and any\n * OpenAI-compatible provider that validates tool history) needs this to read its\n * own tool use back; folding results into a `user` message makes such models\n * re-issue the same call in a loop.\n *\n * The loop is substrate-owned (`runToolLoop` / `streamToolLoop`); the app\n * supplies `streamTurn` (wrapping its model endpoint) and `executeToolCall`\n * (routing to its integration + app-tool executors). The app-facing names below\n * are 1:1 aliases of the canonical symbols, kept so this package's consumers and\n * the in-package `createAgentRuntime` read against a single, stable vocabulary.\n *\n * This is the LEAF the runtime barrel and its children both import — keeping the\n * tool-loop vocabulary out of any import cycle. The barrel re-exports it.\n */\n\nexport {\n  runToolLoop as runAppToolLoop,\n  streamToolLoop as streamAppToolLoop,\n} from '@tangle-network/agent-runtime'\nexport type {\n  ToolLoopCall as LoopToolCall,\n  ToolLoopAssistantToolCall as LoopAssistantToolCall,\n  ToolLoopMessage as LoopMessage,\n  ToolLoopEvent,\n  ToolLoopStopReason,\n  ToolLoopResult,\n  RunToolLoopOptions as AppToolLoopOptions,\n  StreamToolLoopOptions as StreamAppToolLoopOptions,\n  StreamToolLoopYield as StreamLoopYield,\n} from '@tangle-network/agent-runtime'\n\n/**\n * Events the app's OpenAI-compat stream adapter ({@link toLoopEvents}) yields.\n *\n * This is the app's own `Raw` event type for the streaming loop — the canonical\n * `streamToolLoop<Raw>` is generic over it. It widens the substrate's\n * tool-loop event with `reasoning` (DeepSeek/router `reasoning_content` /\n * `thinking` deltas, rendered as thinking sections) and `usage` (per-message\n * token accounting) — neither belongs in the substrate's loop contract, so they\n * stay here. The adapter maps each into the `streamTurn` seam; `text` and\n * `tool_call` drive the loop, `reasoning` / `usage` pass through to the UI.\n */\nexport type LoopEvent =\n  | { type: 'text'; text: string }\n  | { type: 'reasoning'; text: string }\n  | { type: 'tool_call'; call: import('@tangle-network/agent-runtime').ToolLoopCall }\n  | { type: 'usage'; usage: { promptTokens: number; completionTokens: number } }\n  | { type: 'other'; event: unknown }\n"],"mappings":"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","names":[]}

package/dist/work-product/index.d.ts

@@ -207,9 +207,14 @@ declare function workProductTrustInputs<D extends string = string>(records: read
 /** Max entries per `upsert_evidence`/`flag_exception` call — keeps each call a
  *  small batch the model can correct precisely on a named-index failure. */
 declare const MAX_WORK_PRODUCT_BATCH = 50;
-/** The shell's one generic platform check: every material target has ≥1
- *  evidence row. Recorded as `QualityCheck{source:'platform'}`. */
+/** Platform check: every material target has ≥1 evidence row. Recorded as
+ *  `QualityCheck{source:'platform'}`. */
 declare const EVIDENCE_COVERAGE_CHECK = "evidence_coverage";
+/** Platform check: how many evidence entries carry a quote the shell PROVED
+ *  occurs in the source it names. Recorded when `readSourceText` is wired, so
+ *  a reviewer reads the strength of the lineage off the row itself rather than
+ *  trusting that a quote was checked. */
+declare const QUOTE_VERIFICATION_CHECK = "quote_verification";
 /** Domain seams for the three work-product tools — every domain word is a
  *  parameter; the shell bakes none. */
 interface WorkProductToolConfig {
@@ -222,6 +227,20 @@ interface WorkProductToolConfig {
      *  (vault stat / attachment lookup). A dangling ref is a `ToolInputError`
      *  naming the entry index — lineage can never point at nothing. */
     resolveSourceRef: (ref: string, ctx: AppToolContext) => Promise<boolean>;
+    /** Fail-loud QUOTE verification: return the source document's TEXT for a
+     *  ref so the shell can prove each `locator.quote` occurs in it verbatim.
+     *  Wiring this turns the gate ON — a quote that does not occur is a
+     *  `ToolInputError` naming the entry index, so the model re-extracts from
+     *  the document instead of persisting invented lineage.
+     *
+     *  Return `null` ONLY when the ref genuinely has no extractable text (an
+     *  image scan, an opaque blob). The gate is fail-CLOSED on `null`: a quote
+     *  that cannot be checked is refused, because "unverifiable" and "verified"
+     *  must never look the same to a reviewer. Such an entry is still recordable
+     *  without `locator.quote` — `claim` carries the assertion.
+     *
+     *  Omit the seam entirely and no quote is checked. */
+    readSourceText?: (ref: string, ctx: AppToolContext) => Promise<string | null>;
     /** The material targets the platform coverage check requires evidence for.
      *  Product-owned vocabulary; omit to skip the coverage gate. */
     materialTargets?: (artifact: WorkProductArtifact) => string[];
@@ -239,6 +258,41 @@ interface WorkProductToolConfig {
  *  MCP server / HTTP handler / runtime executor. */
 declare function buildWorkProductTools(config: WorkProductToolConfig): AppToolDefinition[];
 
+/**
+ * Verbatim quote verification — the lineage gate.
+ *
+ * An evidence `locator.quote` is the reviewer's click target: it must land on
+ * text that is actually in the document the entry names. Nothing here is
+ * fuzzy. The only latitude is representational — the same characters written
+ * differently by a PDF extractor, a text transcription, or a model repeating
+ * what it read: Unicode compatibility forms, curly quotes, the several dash
+ * codepoints, non-breaking spaces, and run-length whitespace. A quote that
+ * still does not occur after that is not a formatting difference; it is text
+ * the document does not contain.
+ *
+ * Deliberately NOT tolerated, because each one re-opens the hole this closes:
+ * case (a quote is a quote), token subsets, edit distance, word-overlap
+ * scoring, and "the numbers match" heuristics. A fabricated quote and a real
+ * one differ by exactly the thing a fuzzy matcher forgives.
+ */
+/**
+ * Fold a string to the form both sides of a quote comparison are measured in.
+ * Composition and presentation only: NFKC, one dash, one apostrophe, one
+ * double quote, runs of any whitespace to a single space, trimmed. Case is
+ * PRESERVED — lowercasing would let "Box 1" match "box 1", and a citation
+ * that cannot reproduce capitalization did not read the document.
+ */
+declare function normalizeQuoteText(value: string): string;
+/**
+ * Does `quote` occur in `sourceText`? Exact substring first (the common case,
+ * and free); the normalized comparison second, for the representational
+ * differences above. Nothing else.
+ *
+ * An empty or whitespace-only quote is NOT a match — it would otherwise be a
+ * substring of every document and pass the gate vacuously.
+ */
+declare function sourceContainsQuote(sourceText: string, quote: string): boolean;
+
 /**
  * Framework-neutral work-product review endpoints — the
  * `createInteractionAnswerRoute` factory pattern: web-standard
@@ -328,4 +382,4 @@ interface WorkProductRoutes {
 /** Create the work-product review endpoints over the store port and product seams */
 declare function createWorkProductRoutes(options: WorkProductRoutesOptions): WorkProductRoutes;
 
-export { type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QualityCheck, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, isWorkProductTerminal, stampProvenance, validateWorkProductVerdictBody, workProductTrustInputs };
+export { type CreateWorkProductInput, EVIDENCE_COVERAGE_CHECK, EvidenceEntry, ExceptionEntry, type FinalizeWorkProductProvenanceInput, type InMemoryWorkProductStore, MAX_WORK_PRODUCT_BATCH, QUOTE_VERIFICATION_CHECK, QualityCheck, type SubmitWorkProductInput, TrustItem, WorkProductArtifact, WorkProductAuditEvent, type WorkProductAuthorizeArgs, type WorkProductOutcome, WorkProductPersistedPart, WorkProductProvenance, type WorkProductProvenanceBase, WorkProductRecord, type WorkProductRouteAuthorization, type WorkProductRoutes, type WorkProductRoutesOptions, type WorkProductService, type WorkProductServiceOptions, WorkProductStatus, WorkProductStorePort, type WorkProductToolConfig, type WorkProductVerdictBody, type WorkProductVerdictInput, buildWorkProductTools, canTransitionWorkProduct, createInMemoryWorkProductStore, createWorkProductRoutes, createWorkProductService, finalizeWorkProductProvenance, isWorkProductTerminal, normalizeQuoteText, sourceContainsQuote, stampProvenance, validateWorkProductVerdictBody, workProductTrustInputs };

package/dist/work-product/index.js

@@ -387,9 +387,27 @@ function workProductTrustInputs(records, verdictsFor) {
   return items;
 }
 
+// src/work-product/quote.ts
+var WHITESPACE = /[\s\p{Zs}\u2028\u2029\u200b-\u200d\ufeff]+/gu;
+var DASHES = /[\u2010-\u2015\u2212\ufe58\ufe63\uff0d]/gu;
+var SINGLE_QUOTES = /[\u2018\u2019\u201a\u201b\u2032\u2035\u00b4`]/gu;
+var DOUBLE_QUOTES = /[\u201c\u201d\u201e\u201f\u2033\u2036\u00ab\u00bb]/gu;
+function normalizeQuoteText(value) {
+  return value.normalize("NFKC").replace(DASHES, "-").replace(SINGLE_QUOTES, "'").replace(DOUBLE_QUOTES, '"').replace(WHITESPACE, " ").trim();
+}
+function sourceContainsQuote(sourceText, quote) {
+  const trimmed = quote.trim();
+  if (trimmed.length === 0) return false;
+  if (sourceText.includes(trimmed)) return true;
+  const normalizedQuote = normalizeQuoteText(quote);
+  if (normalizedQuote.length === 0) return false;
+  return normalizeQuoteText(sourceText).includes(normalizedQuote);
+}
+
 // src/work-product/tools.ts
 var MAX_WORK_PRODUCT_BATCH = 50;
 var EVIDENCE_COVERAGE_CHECK = "evidence_coverage";
+var QUOTE_VERIFICATION_CHECK = "quote_verification";
 async function unwrap(run, code) {
   let outcome = await run();
   if (!outcome.succeeded && outcome.conflict) outcome = await run();
@@ -434,6 +452,50 @@ async function resolveDraft(service, config, scopeKey, ctx) {
     provenance: stampProvenance(config.provenance(ctx), config.now)
   });
 }
+async function assertQuotesOccurInSources(config, entries, ctx) {
+  const readSourceText = config.readSourceText;
+  if (!readSourceText) return;
+  const texts = /* @__PURE__ */ new Map();
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const quote = entry.locator.quote;
+    if (quote === void 0 || quote.trim().length === 0) continue;
+    if (!texts.has(entry.sourceRef)) texts.set(entry.sourceRef, await readSourceText(entry.sourceRef, ctx));
+    const text = texts.get(entry.sourceRef);
+    if (text === null || text === void 0) {
+      throw new ToolInputError(
+        "unverifiable_quote",
+        `entries[${index}].locator.quote: "${entry.sourceRef}" has no readable text, so the quote cannot be verified. Record the entry without locator.quote and state the basis in claim.`
+      );
+    }
+    if (!sourceContainsQuote(text, quote)) {
+      throw new ToolInputError(
+        "quote_not_found",
+        `entries[${index}].locator.quote: ${JSON.stringify(quote)} does not occur in "${entry.sourceRef}". Copy the supporting line character-for-character out of that document, or \u2014 if this value is COMPUTED rather than read \u2014 omit locator.quote and state the computation in claim.`
+      );
+    }
+  }
+}
+async function summarizeQuoteVerification(config, evidence, ctx) {
+  const readSourceText = config.readSourceText;
+  if (!readSourceText) return void 0;
+  const texts = /* @__PURE__ */ new Map();
+  let verified = 0;
+  let withoutQuote = 0;
+  const failed = [];
+  for (const entry of evidence) {
+    const quote = entry.locator.quote;
+    if (quote === void 0 || quote.trim().length === 0) {
+      withoutQuote += 1;
+      continue;
+    }
+    if (!texts.has(entry.sourceRef)) texts.set(entry.sourceRef, await readSourceText(entry.sourceRef, ctx));
+    const text = texts.get(entry.sourceRef);
+    if (typeof text === "string" && sourceContainsQuote(text, quote)) verified += 1;
+    else failed.push(entry.id);
+  }
+  return { verified, withoutQuote, failed };
+}
 function buildWorkProductTools(config) {
   const service = createWorkProductService({
     store: config.store,
@@ -461,7 +523,10 @@ function buildWorkProductTools(config) {
                 properties: {
                   page: { type: "number" },
                   range: { type: "string", description: "Free-form location: 'L120-L134' | 'B7' | '\xB64'." },
-                  quote: { type: "string", description: "Verbatim supporting quote." }
+                  quote: {
+                    type: "string",
+                    description: "Verbatim supporting quote \u2014 copied character-for-character out of the source, not retyped, reformatted, or summarised. The platform checks it occurs in the document and REFUSES the entry if it does not. For a value you COMPUTED rather than read, omit this field and state the computation in claim."
+                  }
                 }
               },
               target: { type: "string", description: "Artifact field/claim this evidence supports." },
@@ -492,6 +557,7 @@ function buildWorkProductTools(config) {
           );
         }
       }
+      await assertQuotesOccurInSources(config, entries, ctx);
       const draft = await resolveDraft(service, config, scopeKey, ctx);
       const record = await unwrap(() => service.upsertEvidence(draft.id, entries), "evidence_rejected");
       return { workProductId: record.id, version: record.version, evidenceCount: record.evidence.length };
@@ -619,6 +685,24 @@ function buildWorkProductTools(config) {
         );
       }
       const checks = [...agentChecks];
+      const quotes = await summarizeQuoteVerification(config, draft.evidence, ctx);
+      if (quotes) {
+        const quoted = quotes.verified + quotes.failed.length;
+        checks.unshift({
+          id: QUOTE_VERIFICATION_CHECK,
+          name: QUOTE_VERIFICATION_CHECK,
+          passed: quotes.failed.length === 0,
+          detail: quotes.failed.length === 0 ? `${quotes.verified}/${quoted} quoted evidence entries verified against their source; ${quotes.withoutQuote} recorded without a quote` : `Unverifiable quotes on: ${quotes.failed.join(", ")}`,
+          source: "platform"
+        });
+        if (quotes.failed.length > 0) {
+          await unwrap(() => service.recordChecks(draft.id, checks), "checks_rejected");
+          throw new ToolInputError(
+            "quote_verification_failed",
+            `Cannot submit: ${quotes.failed.length} evidence entr${quotes.failed.length === 1 ? "y quotes" : "ies quote"} text that does not occur in the source named (${quotes.failed.join(", ")}). Re-emit each with a quote copied character-for-character from that document, or without locator.quote if the value is computed.`
+          );
+        }
+      }
       if (config.materialTargets) {
         const targets = config.materialTargets(artifact);
         const covered = new Set(draft.evidence.map((entry) => entry.target));
@@ -750,6 +834,7 @@ function createWorkProductRoutes(options) {
 export {
   EVIDENCE_COVERAGE_CHECK,
   MAX_WORK_PRODUCT_BATCH,
+  QUOTE_VERIFICATION_CHECK,
   buildWorkProductTools,
   canTransitionWorkProduct,
   createInMemoryWorkProductStore,
@@ -758,6 +843,7 @@ export {
   finalizeWorkProductProvenance,
   isWorkProductStatus,
   isWorkProductTerminal,
+  normalizeQuoteText,
   parseAgentCheckInput,
   parseArtifactInput,
   parseEvidenceInput,
@@ -765,6 +851,7 @@ export {
   parseReviewQueueItem,
   persistedPartToWorkProduct,
   projectReviewQueue,
+  sourceContainsQuote,
   stampProvenance,
   unresolvedBlockingExceptions,
   validateWorkProductVerdictBody,