@warlock.js/ai 4.4.0 → 4.6.0

package/esm/transcribe/transcribe.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcribe.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/transcribe/transcribe.ts"],"sourcesContent":["import type { BaseReport } from \"../contracts/result/base-report.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { ExecuteResult } from \"../contracts/result/execute-result.type\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type {\n  AudioInput,\n  TranscriptionModelContract,\n  TranscriptionModelPricing,\n  TranscriptionSegment,\n} from \"../contracts/transcription-model.contract\";\nimport { AIError } from \"../errors/ai-error\";\nimport { ProviderError } from \"../errors/provider-error\";\nimport type { FlowObserveOption } from \"../observe/resolve-observers\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport { computeCost } from \"../utils/compute-cost\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { stampReportLineage } from \"../utils/stamp-report-lineage\";\n\n/** Parameters for {@link transcribe}. `model` comes from `sdk.transcribe({ name })`. */\nexport type TranscribeParams = {\n  /** The STT model to transcribe with. */\n  model: TranscriptionModelContract;\n  /** The audio to transcribe (inlined base64 bytes + media type). */\n  audio: AudioInput;\n  /** BCP-47 language hint. */\n  language?: string;\n  /** Optional priming prompt (spelling/style hints). */\n  prompt?: string;\n  /** Provider response-format override (e.g. `\"verbose_json\"`). */\n  format?: string;\n  /** Cancellation handle. */\n  signal?: AbortSignal;\n  /** Observability routing — same `observe` seam as agents. */\n  observe?: FlowObserveOption;\n  /** Groups this call into a session for flat cost/trace queries. */\n  sessionId?: string;\n  /** Report node name (defaults to `\"transcription\"`). */\n  name?: string;\n  /** Provider-specific options forwarded verbatim to the adapter. */\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link transcribe} run. */\nexport type TranscriptionData = {\n  /** The full transcript text. */\n  text: string;\n  /** Timestamped segments when the provider returned them. */\n  segments?: TranscriptionSegment[];\n};\n\n/** The report node a {@link transcribe} run produces (`type: \"transcription\"`). */\nexport type TranscriptionReport = BaseReport & {\n  type: \"transcription\";\n  /** Identity of the STT model this run used. */\n  model: { name: string; provider: string };\n  /** Input audio duration in seconds, when the provider reported it. */\n  durationSeconds?: number;\n};\n\n/** Result envelope of {@link transcribe} — the uniform `{ data, error, usage, report }`. */\nexport type TranscriptionResult = ExecuteResult<TranscriptionData> & {\n  type: \"transcription\";\n  report: TranscriptionReport;\n};\n\n/**\n * Transcribe audio to text — the speech-to-text verb of the\n * output-modality track (Theme I), inverse of `ai.speech()`. Wraps a\n * {@link TranscriptionModelContract} (from `openai.transcribe(...)`) in\n * the uniform result contract:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError` on\n *   `result.error`.\n * - **Cost-truth.** `result.usage.cost` is filled per-minute\n *   (`whisper-1`) or per-token (`gpt-4o-transcribe`).\n * - **Observable.** The completed {@link TranscriptionReport} routes to\n *   any registered `Observer` via the `observe` seam.\n *\n * @example\n * const openai = new OpenAISDK({ apiKey });\n * const { data, error } = await ai.transcribe({\n *   model: openai.transcribe({ name: \"whisper-1\" }),\n *   audio: { base64, mediaType: \"audio/mpeg\", filename: \"voicemail.mp3\" },\n *   language: \"en\",\n * });\n * if (!error) console.log(data.text);\n */\nexport async function transcribe(params: TranscribeParams): Promise<TranscriptionResult> {\n  const { model, audio } = params;\n\n  const runId = generateRunId(\"transcription\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: TranscriptionData | undefined;\n  let error: AIError | undefined;\n  let status: TranscriptionReport[\"status\"] = \"completed\";\n  let durationSeconds: number | undefined;\n\n  try {\n    const response = await model.transcribe(audio, {\n      language: params.language,\n      prompt: params.prompt,\n      format: params.format,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    durationSeconds = response.durationSeconds;\n\n    if (usage.cost === undefined) {\n      const cost = computeTranscriptionCost(usage, durationSeconds, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { text: response.text, ...(response.segments ? { segments: response.segments } : {}) };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: TranscriptionReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"transcription\",\n    type: \"transcription\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    ...(durationSeconds !== undefined ? { durationSeconds } : {}),\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  await notifyObservers(params.observe, report);\n\n  return { type: \"transcription\", data, error, usage, report };\n}\n\n/**\n * Price an STT run: `perMinute × (durationSeconds / 60)` (per-minute\n * metering, attributed to `cost.input`) wins when configured, otherwise\n * the standard token math. Returns `undefined` when no usable pricing\n * is present (e.g. per-minute pricing but the provider didn't report a\n * duration).\n */\nfunction computeTranscriptionCost(\n  usage: Usage,\n  durationSeconds: number | undefined,\n  pricing: TranscriptionModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perMinute !== undefined) {\n    if (durationSeconds === undefined) {\n      return undefined;\n    }\n    return { input: (durationSeconds / 60) * pricing.perMinute, output: 0 };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,eAAsB,WAAW,QAAwD;CACvF,MAAM,EAAE,OAAO,UAAU;CAEzB,MAAM,QAAQ,cAAc,eAAe;CAC3C,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAwC;CAC5C,IAAI;CAEJ,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,WAAW,OAAO;GAC7C,UAAU,OAAO;GACjB,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,kBAAkB,SAAS;EAE3B,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,yBAAyB,OAAO,iBAAiB,MAAM,OAAO;GAC3E,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO;GAAE,MAAM,SAAS;GAAM,GAAI,SAAS,WAAW,EAAE,UAAU,SAAS,SAAS,IAAI,CAAC;EAAG;CAC9F,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAA8B;EAClC;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD,GAAI,oBAAoB,SAAY,EAAE,gBAAgB,IAAI,CAAC;EAC3D;CACF;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,MAAM,gBAAgB,OAAO,SAAS,MAAM;CAE5C,OAAO;EAAE,MAAM;EAAiB;EAAM;EAAO;EAAO;CAAO;AAC7D;;;;;;;;AASA,SAAS,yBACP,OACA,iBACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,cAAc,QAAW;EACnC,IAAI,oBAAoB,QACtB;EAEF,OAAO;GAAE,OAAQ,kBAAkB,KAAM,QAAQ;GAAW,QAAQ;EAAE;CACxE;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/esm/utils/compute-cost.d.mts

@@ -53,6 +53,22 @@ declare function computeCost(usage: Usage, pricing: ModelPricing | undefined): M
  * pricing" from "genuinely zero").
  */
 declare function accumulateCost(parent: ModelPricing | undefined, child: ModelPricing | undefined): ModelPricing | undefined;
+/**
+ * Accumulate a child {@link Usage} into a running parent total, mutating
+ * `target` in place. Scalar token channels (`input` / `output` / `total`)
+ * sum directly; the optional sub-channels (`cachedTokens`,
+ * `reasoningTokens`, `cacheWriteTokens`) accumulate only when some
+ * contributor reported them (preserving the "never reported anywhere"
+ * signal); and the cost breakdown merges via {@link accumulateCost} so a
+ * single unpriced child can never erase a priced sibling's cost.
+ *
+ * This is the ONE canonical usage rollup — every aggregator (agent,
+ * workflow, supervisor, team, planner, batch) routes through it so cost +
+ * cache/reasoning telemetry propagates identically to the top-level
+ * `result.usage`. Re-implementing a bare `input/output/total` sum at a
+ * call site silently drops those optional channels.
+ */
+declare function mergeUsage(target: Usage, child: Usage): void;
 //#endregion
-export { accumulateCost, computeCost };
+export { accumulateCost, computeCost, mergeUsage };
 //# sourceMappingURL=compute-cost.d.mts.map

package/esm/utils/compute-cost.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"compute-cost.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"mappings":";;;;;;AAuCA;;;;;;;;;;;;;;AAA0F;AAkC1F;;;;;;;;;;;;;;AAGe;;;;;iBArCC,WAAA,CAAY,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,YAAA,eAA2B,YAAA;;;;;;;;;;;;;;iBAkC9D,cAAA,CACd,MAAA,EAAQ,YAAA,cACR,KAAA,EAAO,YAAA,eACN,YAAA"}
+{"version":3,"file":"compute-cost.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"mappings":";;;;;;AAuCA;;;;;;;;;;;;;;AAA0F;AAkC1F;;;;;;;;;;;;;;AAGe;AAwDf;;;;iBA7FgB,WAAA,CAAY,KAAA,EAAO,KAAA,EAAO,OAAA,EAAS,YAAA,eAA2B,YAAA;;;;;AA6FxB;;;;;;;;;iBA3DtC,cAAA,CACd,MAAA,EAAQ,YAAA,cACR,KAAA,EAAO,YAAA,eACN,YAAA;;;;;;;;;;;;;;;;iBAwDa,UAAA,CAAW,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAO,KAAK"}

package/esm/utils/compute-cost.mjs

@@ -81,7 +81,32 @@ function sumOptional(parent, child) {
 	if (parent === void 0 && child === void 0) return;
 	return (parent ?? 0) + (child ?? 0);
 }
+/**
+* Accumulate a child {@link Usage} into a running parent total, mutating
+* `target` in place. Scalar token channels (`input` / `output` / `total`)
+* sum directly; the optional sub-channels (`cachedTokens`,
+* `reasoningTokens`, `cacheWriteTokens`) accumulate only when some
+* contributor reported them (preserving the "never reported anywhere"
+* signal); and the cost breakdown merges via {@link accumulateCost} so a
+* single unpriced child can never erase a priced sibling's cost.
+*
+* This is the ONE canonical usage rollup — every aggregator (agent,
+* workflow, supervisor, team, planner, batch) routes through it so cost +
+* cache/reasoning telemetry propagates identically to the top-level
+* `result.usage`. Re-implementing a bare `input/output/total` sum at a
+* call site silently drops those optional channels.
+*/
+function mergeUsage(target, child) {
+	target.input += child.input;
+	target.output += child.output;
+	target.total += child.total;
+	if (child.cachedTokens !== void 0) target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;
+	if (child.reasoningTokens !== void 0) target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;
+	if (child.cacheWriteTokens !== void 0) target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;
+	const mergedCost = accumulateCost(target.cost, child.cost);
+	if (mergedCost !== void 0) target.cost = mergedCost;
+}
 
 //#endregion
-export { accumulateCost, computeCost };
+export { accumulateCost, computeCost, mergeUsage };
 //# sourceMappingURL=compute-cost.mjs.map

package/esm/utils/compute-cost.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"compute-cost.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"sourcesContent":["import type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/**\n * Compute a per-channel USD cost breakdown for a single `Usage` against\n * a model's pricing table. Returns `undefined` when no pricing is\n * configured — the framework treats unpriced runs as \"cost unknown,\"\n * not \"cost zero,\" so dashboards can distinguish free-tier from\n * un-instrumented.\n *\n * **Shape mirrors `ModelPricing`** — `input`, `output`, optional\n * `cachedInput` / `cachedOutput`. Consumers needing a scalar total\n * sum the populated fields. The breakdown is the value-add: it tells\n * downstream tooling HOW the total was reached (input-vs-output\n * share, cache savings) without re-deriving against pricing tables\n * that may have shifted since the report was written.\n *\n * **Cache-aware.** `usage.cachedTokens` is the subset of `usage.input`\n * served from the provider's prompt cache and bills at\n * `pricing.cachedInput` (falls back to full `pricing.input` when the\n * provider doesn't publish a cache rate). The remaining `input -\n * cachedTokens` bills at full rate and shows up in `cost.input`. The\n * `cachedOutput` channel is reserved for Anthropic-style cache writes;\n * until an adapter populates `usage.cacheWriteTokens`, the framework\n * leaves it undefined.\n *\n * Pricing values are USD-per-million-tokens. The function divides\n * once at the end to avoid floating-point accumulation error on\n * per-token math.\n *\n * @example\n * const usage: Usage = { input: 150_000, output: 30_000, total: 180_000, cachedTokens: 90_000 };\n * const cost = computeCost(usage, { input: 0.15, output: 0.6, cachedInput: 0.075 });\n * // cost = {\n * //   input: (60_000 * 0.15) / 1e6 = 0.009,\n * //   output: (30_000 * 0.6) / 1e6 = 0.018,\n * //   cachedInput: (90_000 * 0.075) / 1e6 = 0.00675,\n * // }\n */\nexport function computeCost(usage: Usage, pricing: ModelPricing | undefined): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const cachedInput = usage.cachedTokens ?? 0;\n  const uncachedInput = Math.max(0, usage.input - cachedInput);\n\n  const cost: ModelPricing = {\n    input: (uncachedInput * pricing.input) / 1_000_000,\n    output: (usage.output * pricing.output) / 1_000_000,\n  };\n\n  if (cachedInput > 0) {\n    const cachedInputRate = pricing.cachedInput ?? pricing.input;\n    cost.cachedInput = (cachedInput * cachedInputRate) / 1_000_000;\n  }\n\n  return cost;\n}\n\n/**\n * Merge a child's cost breakdown into a running parent total. Each\n * channel (`input`, `output`, `cachedInput`, `cachedOutput`) sums\n * independently — an undefined channel on either side is treated as\n * zero contribution rather than dropping the other side's value. A\n * single unpriced child should never erase the cost of its priced\n * siblings.\n *\n * Returns the new parent breakdown, or `undefined` when neither parent\n * nor child carried any cost data (preserves the \"no priced\n * contributor has appeared yet\" signal that distinguishes \"missing\n * pricing\" from \"genuinely zero\").\n */\nexport function accumulateCost(\n  parent: ModelPricing | undefined,\n  child: ModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!child) {\n    return parent;\n  }\n\n  if (!parent) {\n    return { ...child };\n  }\n\n  const merged: ModelPricing = {\n    input: parent.input + child.input,\n    output: parent.output + child.output,\n  };\n\n  const cachedInput = sumOptional(parent.cachedInput, child.cachedInput);\n  if (cachedInput !== undefined) {\n    merged.cachedInput = cachedInput;\n  }\n\n  const cachedOutput = sumOptional(parent.cachedOutput, child.cachedOutput);\n  if (cachedOutput !== undefined) {\n    merged.cachedOutput = cachedOutput;\n  }\n\n  return merged;\n}\n\n/**\n * Add two optional numbers, treating either side's `undefined` as\n * zero — but return `undefined` when both are absent. Keeps \"this\n * channel was never reported anywhere\" distinguishable from \"this\n * channel was reported as 0.\"\n */\nfunction sumOptional(parent: number | undefined, child: number | undefined): number | undefined {\n  if (parent === undefined && child === undefined) {\n    return undefined;\n  }\n\n  return (parent ?? 0) + (child ?? 0);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAc,SAA6D;CACrG,IAAI,CAAC,SACH;CAGF,MAAM,cAAc,MAAM,gBAAgB;CAG1C,MAAM,OAAqB;EACzB,OAHoB,KAAK,IAAI,GAAG,MAAM,QAAQ,WAG1B,IAAI,QAAQ,QAAS;EACzC,QAAS,MAAM,SAAS,QAAQ,SAAU;CAC5C;CAEA,IAAI,cAAc,GAEhB,KAAK,cAAe,eADI,QAAQ,eAAe,QAAQ,SACF;CAGvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,eACd,QACA,OAC0B;CAC1B,IAAI,CAAC,OACH,OAAO;CAGT,IAAI,CAAC,QACH,OAAO,EAAE,GAAG,MAAM;CAGpB,MAAM,SAAuB;EAC3B,OAAO,OAAO,QAAQ,MAAM;EAC5B,QAAQ,OAAO,SAAS,MAAM;CAChC;CAEA,MAAM,cAAc,YAAY,OAAO,aAAa,MAAM,WAAW;CACrE,IAAI,gBAAgB,QAClB,OAAO,cAAc;CAGvB,MAAM,eAAe,YAAY,OAAO,cAAc,MAAM,YAAY;CACxE,IAAI,iBAAiB,QACnB,OAAO,eAAe;CAGxB,OAAO;AACT;;;;;;;AAQA,SAAS,YAAY,QAA4B,OAA+C;CAC9F,IAAI,WAAW,UAAa,UAAU,QACpC;CAGF,QAAQ,UAAU,MAAM,SAAS;AACnC"}
+{"version":3,"file":"compute-cost.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/compute-cost.ts"],"sourcesContent":["import type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/**\n * Compute a per-channel USD cost breakdown for a single `Usage` against\n * a model's pricing table. Returns `undefined` when no pricing is\n * configured — the framework treats unpriced runs as \"cost unknown,\"\n * not \"cost zero,\" so dashboards can distinguish free-tier from\n * un-instrumented.\n *\n * **Shape mirrors `ModelPricing`** — `input`, `output`, optional\n * `cachedInput` / `cachedOutput`. Consumers needing a scalar total\n * sum the populated fields. The breakdown is the value-add: it tells\n * downstream tooling HOW the total was reached (input-vs-output\n * share, cache savings) without re-deriving against pricing tables\n * that may have shifted since the report was written.\n *\n * **Cache-aware.** `usage.cachedTokens` is the subset of `usage.input`\n * served from the provider's prompt cache and bills at\n * `pricing.cachedInput` (falls back to full `pricing.input` when the\n * provider doesn't publish a cache rate). The remaining `input -\n * cachedTokens` bills at full rate and shows up in `cost.input`. The\n * `cachedOutput` channel is reserved for Anthropic-style cache writes;\n * until an adapter populates `usage.cacheWriteTokens`, the framework\n * leaves it undefined.\n *\n * Pricing values are USD-per-million-tokens. The function divides\n * once at the end to avoid floating-point accumulation error on\n * per-token math.\n *\n * @example\n * const usage: Usage = { input: 150_000, output: 30_000, total: 180_000, cachedTokens: 90_000 };\n * const cost = computeCost(usage, { input: 0.15, output: 0.6, cachedInput: 0.075 });\n * // cost = {\n * //   input: (60_000 * 0.15) / 1e6 = 0.009,\n * //   output: (30_000 * 0.6) / 1e6 = 0.018,\n * //   cachedInput: (90_000 * 0.075) / 1e6 = 0.00675,\n * // }\n */\nexport function computeCost(usage: Usage, pricing: ModelPricing | undefined): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  const cachedInput = usage.cachedTokens ?? 0;\n  const uncachedInput = Math.max(0, usage.input - cachedInput);\n\n  const cost: ModelPricing = {\n    input: (uncachedInput * pricing.input) / 1_000_000,\n    output: (usage.output * pricing.output) / 1_000_000,\n  };\n\n  if (cachedInput > 0) {\n    const cachedInputRate = pricing.cachedInput ?? pricing.input;\n    cost.cachedInput = (cachedInput * cachedInputRate) / 1_000_000;\n  }\n\n  return cost;\n}\n\n/**\n * Merge a child's cost breakdown into a running parent total. Each\n * channel (`input`, `output`, `cachedInput`, `cachedOutput`) sums\n * independently — an undefined channel on either side is treated as\n * zero contribution rather than dropping the other side's value. A\n * single unpriced child should never erase the cost of its priced\n * siblings.\n *\n * Returns the new parent breakdown, or `undefined` when neither parent\n * nor child carried any cost data (preserves the \"no priced\n * contributor has appeared yet\" signal that distinguishes \"missing\n * pricing\" from \"genuinely zero\").\n */\nexport function accumulateCost(\n  parent: ModelPricing | undefined,\n  child: ModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!child) {\n    return parent;\n  }\n\n  if (!parent) {\n    return { ...child };\n  }\n\n  const merged: ModelPricing = {\n    input: parent.input + child.input,\n    output: parent.output + child.output,\n  };\n\n  const cachedInput = sumOptional(parent.cachedInput, child.cachedInput);\n  if (cachedInput !== undefined) {\n    merged.cachedInput = cachedInput;\n  }\n\n  const cachedOutput = sumOptional(parent.cachedOutput, child.cachedOutput);\n  if (cachedOutput !== undefined) {\n    merged.cachedOutput = cachedOutput;\n  }\n\n  return merged;\n}\n\n/**\n * Add two optional numbers, treating either side's `undefined` as\n * zero — but return `undefined` when both are absent. Keeps \"this\n * channel was never reported anywhere\" distinguishable from \"this\n * channel was reported as 0.\"\n */\nfunction sumOptional(parent: number | undefined, child: number | undefined): number | undefined {\n  if (parent === undefined && child === undefined) {\n    return undefined;\n  }\n\n  return (parent ?? 0) + (child ?? 0);\n}\n\n/**\n * Accumulate a child {@link Usage} into a running parent total, mutating\n * `target` in place. Scalar token channels (`input` / `output` / `total`)\n * sum directly; the optional sub-channels (`cachedTokens`,\n * `reasoningTokens`, `cacheWriteTokens`) accumulate only when some\n * contributor reported them (preserving the \"never reported anywhere\"\n * signal); and the cost breakdown merges via {@link accumulateCost} so a\n * single unpriced child can never erase a priced sibling's cost.\n *\n * This is the ONE canonical usage rollup — every aggregator (agent,\n * workflow, supervisor, team, planner, batch) routes through it so cost +\n * cache/reasoning telemetry propagates identically to the top-level\n * `result.usage`. Re-implementing a bare `input/output/total` sum at a\n * call site silently drops those optional channels.\n */\nexport function mergeUsage(target: Usage, child: Usage): void {\n  target.input += child.input;\n  target.output += child.output;\n  target.total += child.total;\n\n  if (child.cachedTokens !== undefined) {\n    target.cachedTokens = (target.cachedTokens ?? 0) + child.cachedTokens;\n  }\n\n  if (child.reasoningTokens !== undefined) {\n    target.reasoningTokens = (target.reasoningTokens ?? 0) + child.reasoningTokens;\n  }\n\n  if (child.cacheWriteTokens !== undefined) {\n    target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + child.cacheWriteTokens;\n  }\n\n  const mergedCost = accumulateCost(target.cost, child.cost);\n  if (mergedCost !== undefined) {\n    target.cost = mergedCost;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,YAAY,OAAc,SAA6D;CACrG,IAAI,CAAC,SACH;CAGF,MAAM,cAAc,MAAM,gBAAgB;CAG1C,MAAM,OAAqB;EACzB,OAHoB,KAAK,IAAI,GAAG,MAAM,QAAQ,WAG1B,IAAI,QAAQ,QAAS;EACzC,QAAS,MAAM,SAAS,QAAQ,SAAU;CAC5C;CAEA,IAAI,cAAc,GAEhB,KAAK,cAAe,eADI,QAAQ,eAAe,QAAQ,SACF;CAGvD,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,eACd,QACA,OAC0B;CAC1B,IAAI,CAAC,OACH,OAAO;CAGT,IAAI,CAAC,QACH,OAAO,EAAE,GAAG,MAAM;CAGpB,MAAM,SAAuB;EAC3B,OAAO,OAAO,QAAQ,MAAM;EAC5B,QAAQ,OAAO,SAAS,MAAM;CAChC;CAEA,MAAM,cAAc,YAAY,OAAO,aAAa,MAAM,WAAW;CACrE,IAAI,gBAAgB,QAClB,OAAO,cAAc;CAGvB,MAAM,eAAe,YAAY,OAAO,cAAc,MAAM,YAAY;CACxE,IAAI,iBAAiB,QACnB,OAAO,eAAe;CAGxB,OAAO;AACT;;;;;;;AAQA,SAAS,YAAY,QAA4B,OAA+C;CAC9F,IAAI,WAAW,UAAa,UAAU,QACpC;CAGF,QAAQ,UAAU,MAAM,SAAS;AACnC;;;;;;;;;;;;;;;;AAiBA,SAAgB,WAAW,QAAe,OAAoB;CAC5D,OAAO,SAAS,MAAM;CACtB,OAAO,UAAU,MAAM;CACvB,OAAO,SAAS,MAAM;CAEtB,IAAI,MAAM,iBAAiB,QACzB,OAAO,gBAAgB,OAAO,gBAAgB,KAAK,MAAM;CAG3D,IAAI,MAAM,oBAAoB,QAC5B,OAAO,mBAAmB,OAAO,mBAAmB,KAAK,MAAM;CAGjE,IAAI,MAAM,qBAAqB,QAC7B,OAAO,oBAAoB,OAAO,oBAAoB,KAAK,MAAM;CAGnE,MAAM,aAAa,eAAe,OAAO,MAAM,MAAM,IAAI;CACzD,IAAI,eAAe,QACjB,OAAO,OAAO;AAElB"}

package/esm/utils/extract-json-lenient.d.mts

@@ -0,0 +1,42 @@
+//#region ../@warlock.js/ai/src/utils/extract-json-lenient.d.ts
+/**
+ * Lenient counterpart to {@link extractJsonPayload}, tuned for the
+ * structured-output judges that emit *corrupted* JSON — notably the
+ * Amazon Nova family, which routinely wraps its verdict in fenced
+ * ` ```json ` blocks, prepends an explanation paragraph, or trails the
+ * object with commentary.
+ *
+ * Where `extractJsonPayload` deliberately refuses the "first `{` … last
+ * `}`" heuristic (it would corrupt strict callers when prose contains
+ * stray braces), this helper *opts into* that resilience: after fence
+ * stripping it scans for the first balanced JSON object (`{…}`) or array
+ * (`[…]`) and returns just that slice. Brace/bracket counting is
+ * string-aware (it ignores braces inside JSON string literals and honors
+ * `\"` escapes), so prose-embedded braces inside the JSON's own strings
+ * don't throw off the balance.
+ *
+ * Returns the fence-stripped, trimmed text unchanged when no balanced
+ * structure is found, so the caller's `JSON.parse` still fails loudly on
+ * genuine garbage rather than this helper inventing a value.
+ *
+ * **Trade-off:** resilience over strictness. Use it only where a tolerant
+ * parse is wanted (the judge preset) — for normal structured output keep
+ * `extractJsonPayload`, which fails fast on malformed responses so real
+ * prompt/model defects surface instead of being silently papered over.
+ *
+ * @example
+ * extractJsonLenient('Here is my verdict:\n```json\n{"score":0.9}\n``` — done.');
+ * // => '{"score":0.9}'
+ *
+ * @example
+ * extractJsonLenient('The answer is {"verdict":"pass"} for sure.');
+ * // => '{"verdict":"pass"}'
+ *
+ * @example
+ * extractJsonLenient('{"valid":true}');
+ * // => '{"valid":true}'   (clean JSON passes through)
+ */
+declare function extractJsonLenient(text: string): string;
+//#endregion
+export { extractJsonLenient };
+//# sourceMappingURL=extract-json-lenient.d.mts.map

package/esm/utils/extract-json-lenient.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json-lenient.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/extract-json-lenient.ts"],"mappings":";;AAuCA;;;;AAA+C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA/B,kBAAA,CAAmB,IAAY"}

package/esm/utils/extract-json-lenient.mjs

@@ -0,0 +1,97 @@
+import { extractJsonPayload } from "./extract-json-payload.mjs";
+
+//#region ../@warlock.js/ai/src/utils/extract-json-lenient.ts
+/**
+* Lenient counterpart to {@link extractJsonPayload}, tuned for the
+* structured-output judges that emit *corrupted* JSON — notably the
+* Amazon Nova family, which routinely wraps its verdict in fenced
+* ` ```json ` blocks, prepends an explanation paragraph, or trails the
+* object with commentary.
+*
+* Where `extractJsonPayload` deliberately refuses the "first `{` … last
+* `}`" heuristic (it would corrupt strict callers when prose contains
+* stray braces), this helper *opts into* that resilience: after fence
+* stripping it scans for the first balanced JSON object (`{…}`) or array
+* (`[…]`) and returns just that slice. Brace/bracket counting is
+* string-aware (it ignores braces inside JSON string literals and honors
+* `\"` escapes), so prose-embedded braces inside the JSON's own strings
+* don't throw off the balance.
+*
+* Returns the fence-stripped, trimmed text unchanged when no balanced
+* structure is found, so the caller's `JSON.parse` still fails loudly on
+* genuine garbage rather than this helper inventing a value.
+*
+* **Trade-off:** resilience over strictness. Use it only where a tolerant
+* parse is wanted (the judge preset) — for normal structured output keep
+* `extractJsonPayload`, which fails fast on malformed responses so real
+* prompt/model defects surface instead of being silently papered over.
+*
+* @example
+* extractJsonLenient('Here is my verdict:\n```json\n{"score":0.9}\n``` — done.');
+* // => '{"score":0.9}'
+*
+* @example
+* extractJsonLenient('The answer is {"verdict":"pass"} for sure.');
+* // => '{"verdict":"pass"}'
+*
+* @example
+* extractJsonLenient('{"valid":true}');
+* // => '{"valid":true}'   (clean JSON passes through)
+*/
+function extractJsonLenient(text) {
+	const stripped = extractJsonPayload(text);
+	return sliceFirstBalanced(stripped) ?? stripped;
+}
+/**
+* Scan for the first balanced JSON object or array and return its raw
+* slice. Returns `undefined` when no opening `{`/`[` is found or the
+* structure never closes (truncated / partial output) — the caller then
+* falls back to the fence-stripped text so the failure stays visible.
+*
+* String-literal aware: braces and brackets appearing *inside* a JSON
+* string are not counted toward the balance, and a backslash escapes the
+* next character so an escaped quote (`\"`) doesn't prematurely end the
+* string scan.
+*/
+function sliceFirstBalanced(text) {
+	const start = firstOpenerIndex(text);
+	if (start === -1) return;
+	const opener = text[start];
+	const closer = opener === "{" ? "}" : "]";
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let index = start; index < text.length; index++) {
+		const char = text[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === opener) depth++;
+		else if (char === closer) {
+			depth--;
+			if (depth === 0) return text.slice(start, index + 1);
+		}
+	}
+}
+/**
+* Index of the first JSON structure opener (`{` or `[`), whichever
+* appears earliest, or `-1` when neither is present.
+*/
+function firstOpenerIndex(text) {
+	const brace = text.indexOf("{");
+	const bracket = text.indexOf("[");
+	if (brace === -1) return bracket;
+	if (bracket === -1) return brace;
+	return Math.min(brace, bracket);
+}
+
+//#endregion
+export { extractJsonLenient };
+//# sourceMappingURL=extract-json-lenient.mjs.map

package/esm/utils/extract-json-lenient.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json-lenient.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/extract-json-lenient.ts"],"sourcesContent":["import { extractJsonPayload } from \"./extract-json-payload\";\n\n/**\n * Lenient counterpart to {@link extractJsonPayload}, tuned for the\n * structured-output judges that emit *corrupted* JSON — notably the\n * Amazon Nova family, which routinely wraps its verdict in fenced\n * ` ```json ` blocks, prepends an explanation paragraph, or trails the\n * object with commentary.\n *\n * Where `extractJsonPayload` deliberately refuses the \"first `{` … last\n * `}`\" heuristic (it would corrupt strict callers when prose contains\n * stray braces), this helper *opts into* that resilience: after fence\n * stripping it scans for the first balanced JSON object (`{…}`) or array\n * (`[…]`) and returns just that slice. Brace/bracket counting is\n * string-aware (it ignores braces inside JSON string literals and honors\n * `\\\"` escapes), so prose-embedded braces inside the JSON's own strings\n * don't throw off the balance.\n *\n * Returns the fence-stripped, trimmed text unchanged when no balanced\n * structure is found, so the caller's `JSON.parse` still fails loudly on\n * genuine garbage rather than this helper inventing a value.\n *\n * **Trade-off:** resilience over strictness. Use it only where a tolerant\n * parse is wanted (the judge preset) — for normal structured output keep\n * `extractJsonPayload`, which fails fast on malformed responses so real\n * prompt/model defects surface instead of being silently papered over.\n *\n * @example\n * extractJsonLenient('Here is my verdict:\\n```json\\n{\"score\":0.9}\\n``` — done.');\n * // => '{\"score\":0.9}'\n *\n * @example\n * extractJsonLenient('The answer is {\"verdict\":\"pass\"} for sure.');\n * // => '{\"verdict\":\"pass\"}'\n *\n * @example\n * extractJsonLenient('{\"valid\":true}');\n * // => '{\"valid\":true}'   (clean JSON passes through)\n */\nexport function extractJsonLenient(text: string): string {\n  // First reuse the strict fence stripper. When the model produced a\n  // clean fenced block this already yields the exact payload, so the\n  // balanced scan below becomes a no-op pass-through.\n  const stripped = extractJsonPayload(text);\n\n  const sliced = sliceFirstBalanced(stripped);\n\n  return sliced ?? stripped;\n}\n\n/**\n * Scan for the first balanced JSON object or array and return its raw\n * slice. Returns `undefined` when no opening `{`/`[` is found or the\n * structure never closes (truncated / partial output) — the caller then\n * falls back to the fence-stripped text so the failure stays visible.\n *\n * String-literal aware: braces and brackets appearing *inside* a JSON\n * string are not counted toward the balance, and a backslash escapes the\n * next character so an escaped quote (`\\\"`) doesn't prematurely end the\n * string scan.\n */\nfunction sliceFirstBalanced(text: string): string | undefined {\n  const start = firstOpenerIndex(text);\n\n  if (start === -1) {\n    return undefined;\n  }\n\n  const opener = text[start];\n  const closer = opener === \"{\" ? \"}\" : \"]\";\n\n  let depth = 0;\n  let inString = false;\n  let escaped = false;\n\n  for (let index = start; index < text.length; index++) {\n    const char = text[index];\n\n    if (inString) {\n      if (escaped) {\n        escaped = false;\n      } else if (char === \"\\\\\") {\n        escaped = true;\n      } else if (char === '\"') {\n        inString = false;\n      }\n\n      continue;\n    }\n\n    if (char === '\"') {\n      inString = true;\n      continue;\n    }\n\n    if (char === opener) {\n      depth++;\n    } else if (char === closer) {\n      depth--;\n\n      if (depth === 0) {\n        return text.slice(start, index + 1);\n      }\n    }\n  }\n\n  // Opener with no matching close — truncated / partial output. Leave it\n  // to the caller's fallback (and its loud parse failure).\n  return undefined;\n}\n\n/**\n * Index of the first JSON structure opener (`{` or `[`), whichever\n * appears earliest, or `-1` when neither is present.\n */\nfunction firstOpenerIndex(text: string): number {\n  const brace = text.indexOf(\"{\");\n  const bracket = text.indexOf(\"[\");\n\n  if (brace === -1) {\n    return bracket;\n  }\n\n  if (bracket === -1) {\n    return brace;\n  }\n\n  return Math.min(brace, bracket);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,mBAAmB,MAAsB;CAIvD,MAAM,WAAW,mBAAmB,IAAI;CAIxC,OAFe,mBAAmB,QAEtB,KAAK;AACnB;;;;;;;;;;;;AAaA,SAAS,mBAAmB,MAAkC;CAC5D,MAAM,QAAQ,iBAAiB,IAAI;CAEnC,IAAI,UAAU,IACZ;CAGF,MAAM,SAAS,KAAK;CACpB,MAAM,SAAS,WAAW,MAAM,MAAM;CAEtC,IAAI,QAAQ;CACZ,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,KAAK,IAAI,QAAQ,OAAO,QAAQ,KAAK,QAAQ,SAAS;EACpD,MAAM,OAAO,KAAK;EAElB,IAAI,UAAU;GACZ,IAAI,SACF,UAAU;QACL,IAAI,SAAS,MAClB,UAAU;QACL,IAAI,SAAS,MAClB,WAAW;GAGb;EACF;EAEA,IAAI,SAAS,MAAK;GAChB,WAAW;GACX;EACF;EAEA,IAAI,SAAS,QACX;OACK,IAAI,SAAS,QAAQ;GAC1B;GAEA,IAAI,UAAU,GACZ,OAAO,KAAK,MAAM,OAAO,QAAQ,CAAC;EAEtC;CACF;AAKF;;;;;AAMA,SAAS,iBAAiB,MAAsB;CAC9C,MAAM,QAAQ,KAAK,QAAQ,GAAG;CAC9B,MAAM,UAAU,KAAK,QAAQ,GAAG;CAEhC,IAAI,UAAU,IACZ,OAAO;CAGT,IAAI,YAAY,IACd,OAAO;CAGT,OAAO,KAAK,IAAI,OAAO,OAAO;AAChC"}

package/esm/utils/index.d.mts

@@ -1,9 +1,11 @@
-import { accumulateCost, computeCost } from "./compute-cost.mjs";
+import { accumulateCost, computeCost, mergeUsage } from "./compute-cost.mjs";
+import { extractJsonLenient } from "./extract-json-lenient.mjs";
 import { extractJsonPayload } from "./extract-json-payload.mjs";
 import { generateRunId } from "./generate-run-id.mjs";
-import { extractJsonSchema } from "./json-schema.mjs";
+import { ExtractJsonSchemaOptions, JsonSchemaTarget, extractJsonSchema } from "./json-schema.mjs";
 import { prepareAttachmentPart } from "./prepare-attachment-part.mjs";
 import { resolveAttachment } from "./resolve-attachment.mjs";
+import { RunFrame, captureChildReport, currentRunFrame, withRunFrame, withoutRunFrame } from "./run-context.mjs";
 import { safeJsonParse } from "./safe-json-parse.mjs";
 import { LineageStamp, stampReportLineage } from "./stamp-report-lineage.mjs";
 import { approximateTokenCount } from "./token-count.mjs";

package/esm/utils/index.mjs

@@ -1,9 +1,11 @@
-import { accumulateCost, computeCost } from "./compute-cost.mjs";
+import { accumulateCost, computeCost, mergeUsage } from "./compute-cost.mjs";
 import { extractJsonPayload } from "./extract-json-payload.mjs";
+import { extractJsonLenient } from "./extract-json-lenient.mjs";
 import { generateRunId } from "./generate-run-id.mjs";
 import { extractJsonSchema } from "./json-schema.mjs";
 import { resolveAttachment } from "./resolve-attachment.mjs";
 import { prepareAttachmentPart } from "./prepare-attachment-part.mjs";
+import { captureChildReport, currentRunFrame, withRunFrame, withoutRunFrame } from "./run-context.mjs";
 import { safeJsonParse } from "./safe-json-parse.mjs";
 import { stampReportLineage } from "./stamp-report-lineage.mjs";
 import { approximateTokenCount } from "./token-count.mjs";

package/esm/utils/json-schema.d.mts

@@ -53,5 +53,5 @@ type ExtractJsonSchemaOptions = {
  */
 declare function extractJsonSchema(schema: StandardSchemaV1<unknown> | undefined, options?: ExtractJsonSchemaOptions): Record<string, unknown> | undefined;
 //#endregion
-export { extractJsonSchema };
+export { ExtractJsonSchemaOptions, JsonSchemaTarget, extractJsonSchema };
 //# sourceMappingURL=json-schema.d.mts.map

package/esm/utils/prepare-attachment-part.d.mts

@@ -1,3 +1,4 @@
+import { AttachmentPolicy } from "../contracts/attachment-policy.type.mjs";
 import { Attachment } from "../contracts/attachment.type.mjs";
 import { ContentPart } from "../contracts/content-part.type.mjs";
 
@@ -29,8 +30,16 @@ import { ContentPart } from "../contracts/content-part.type.mjs";
  * @example
  * await prepareAttachmentPart({ type: "text", source: "./notes.txt" });
  * // → { type: "text", text: "<file contents>" }
+ *
+ * **Trust boundary (S1).** Attachment references are often user-controlled,
+ * so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):
+ * remote text fetches are default-deny and, when enabled, run through the
+ * shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local
+ * reads honor an `allowedRoots` sandbox; bare-string local paths warn
+ * (staged deprecation). URL *image* attachments are passed to the provider
+ * untouched (never fetched here).
  */
-declare function prepareAttachmentPart(attachment: Attachment): Promise<ContentPart>;
+declare function prepareAttachmentPart(attachment: Attachment, policy?: AttachmentPolicy): Promise<ContentPart>;
 //#endregion
 export { prepareAttachmentPart };
 //# sourceMappingURL=prepare-attachment-part.d.mts.map

package/esm/utils/prepare-attachment-part.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-attachment-part.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"mappings":";;;;;;AA+CA;;;;;;;;;;;;;AAEsB;;;;;;;;;;;;;iBAFA,qBAAA,CACpB,UAAA,EAAY,UAAA,GACX,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"prepare-attachment-part.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"mappings":";;;;;;;AAmEA;;;;;;;;;;;;;;;;AAGsB;;;;;;;;;;;;;;;;;;iBAHA,qBAAA,CACpB,UAAA,EAAY,UAAA,EACZ,MAAA,GAAS,gBAAA,GACR,OAAA,CAAQ,WAAA"}

package/esm/utils/prepare-attachment-part.mjs

@@ -1,8 +1,10 @@
 import { InvalidRequestError } from "../errors/invalid-request-error.mjs";
+import { OutboundPolicyError } from "../errors/outbound-policy-error.mjs";
 import "../errors/index.mjs";
+import { fetchTextWithPolicy } from "../security/outbound-policy.mjs";
 import { resolveAttachment } from "./resolve-attachment.mjs";
 import { readFile } from "node:fs/promises";
-import { extname } from "node:path";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 
 //#region ../@warlock.js/ai/src/utils/prepare-attachment-part.ts
 const IMAGE_EXTENSIONS_TO_MEDIA_TYPE = {
@@ -13,6 +15,14 @@ const IMAGE_EXTENSIONS_TO_MEDIA_TYPE = {
 	".gif": "image/gif"
 };
 const TEXT_EXTENSIONS = new Set([".txt"]);
+const AUDIO_EXTENSIONS_TO_MEDIA_TYPE = {
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".m4a": "audio/mp4",
+	".ogg": "audio/ogg",
+	".weba": "audio/webm"
+};
+const PDF_EXTENSIONS = new Set([".pdf"]);
 /**
 * Convert a user-supplied `Attachment` into a provider-ready
 * `ContentPart` the model adapter can consume without doing any I/O of
@@ -40,10 +50,21 @@ const TEXT_EXTENSIONS = new Set([".txt"]);
 * @example
 * await prepareAttachmentPart({ type: "text", source: "./notes.txt" });
 * // → { type: "text", text: "<file contents>" }
+*
+* **Trust boundary (S1).** Attachment references are often user-controlled,
+* so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):
+* remote text fetches are default-deny and, when enabled, run through the
+* shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local
+* reads honor an `allowedRoots` sandbox; bare-string local paths warn
+* (staged deprecation). URL *image* attachments are passed to the provider
+* untouched (never fetched here).
 */
-async function prepareAttachmentPart(attachment) {
-	if (resolveKind(attachment) === "text") return prepareTextPart(attachment);
-	return prepareImagePart(attachment);
+async function prepareAttachmentPart(attachment, policy) {
+	const kind = resolveKind(attachment);
+	const bareString = typeof attachment === "string";
+	if (kind === "text") return prepareTextPart(attachment, policy, bareString);
+	if (kind === "image") return prepareImagePart(attachment, policy, bareString);
+	return prepareBinaryPart(attachment, kind, policy, bareString);
 }
 /**
 * Decide whether the attachment is text or image. Tagged forms win
@@ -56,14 +77,50 @@ function resolveKind(attachment) {
 	const extension = path ? extname(stripQuery(path)).toLowerCase() : "";
 	if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) return "image";
 	if (TEXT_EXTENSIONS.has(extension)) return "text";
-	throw new InvalidRequestError("Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt)");
+	if (PDF_EXTENSIONS.has(extension)) return "pdf";
+	if (AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extension]) return "audio";
+	throw new InvalidRequestError("Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text' | 'pdf' | 'audio', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt, .pdf, .mp3, .wav, .m4a, .ogg, .weba)");
+}
+/**
+* Produce a `pdf` / `audio` ContentPart (A2). URLs pass through; local
+* paths are read and base64-encoded with a media type inferred from the
+* kind (`application/pdf`) or extension (audio); inline base64 passes
+* through. Same `AttachmentPolicy` gating as image/text reads.
+*/
+async function prepareBinaryPart(attachment, kind, policy, bareString) {
+	const resolved = resolveAttachment(attachment);
+	if (resolved.type === "url") return {
+		type: kind,
+		source: { url: resolved.value }
+	};
+	if (resolved.type === "base64") return {
+		type: kind,
+		source: {
+			base64: resolved.value,
+			mediaType: resolved.mediaType
+		}
+	};
+	const mediaType = kind === "pdf" ? "application/pdf" : inferAudioMediaType(resolved.value);
+	if (!mediaType) throw new InvalidRequestError(`Cannot infer media type for ${kind} path "${resolved.value}" — use a recognized extension or pass \`{ type: '${kind}', source: { base64, mediaType } }\``, { context: { path: resolved.value } });
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
+	return {
+		type: kind,
+		source: {
+			base64: (await readFile(resolved.value)).toString("base64"),
+			mediaType
+		}
+	};
+}
+/** Infer an audio media type from a path's extension. */
+function inferAudioMediaType(path) {
+	return AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extname(stripQuery(path)).toLowerCase()];
 }
 /**
 * Produce an `image` ContentPart. URLs pass through; paths are
 * read from disk and base64-encoded with an inferred media type.
 * Inline base64 attachments pass through unchanged.
 */
-async function prepareImagePart(attachment) {
+async function prepareImagePart(attachment, policy, bareString) {
 	const inferredMediaType = isTaggedAttachment(attachment) ? void 0 : inferImageMediaType(attachment);
 	const resolved = resolveAttachment(attachment);
 	if (resolved.type === "url") return {
@@ -79,6 +136,7 @@ async function prepareImagePart(attachment) {
 	};
 	const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);
 	if (!mediaType) throw new InvalidRequestError(`Cannot infer media type for path "${resolved.value}" — use a recognized image extension or pass \`{ type: 'image', source: { base64, mediaType } }\``, { context: { path: resolved.value } });
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
 	return {
 		type: "image",
 		source: {
@@ -93,28 +151,62 @@ async function prepareImagePart(attachment) {
 * result joins the conversation as an additional text part the model
 * sees before responding.
 */
-async function prepareTextPart(attachment) {
+async function prepareTextPart(attachment, policy, bareString) {
 	const resolved = resolveAttachment(attachment);
 	if (resolved.type === "url") {
-		const response = await fetch(resolved.value);
-		if (!response.ok) throw new InvalidRequestError(`Failed to fetch text attachment "${resolved.value}" — status ${response.status}`, { context: {
+		if (!policy?.allowRemoteFetch) throw new OutboundPolicyError(`remote text attachment fetch is disabled by default — set \`attachmentPolicy.allowRemoteFetch: true\` (with an \`outbound\` policy) to fetch "${resolved.value}"`, { context: { url: resolved.value } });
+		const result = await fetchTextWithPolicy(resolved.value, policy.outbound ?? {});
+		if (!result.ok) throw new InvalidRequestError(`Failed to fetch text attachment "${resolved.value}" — status ${result.status}`, { context: {
 			url: resolved.value,
-			status: response.status
+			status: result.status
 		} });
 		return {
 			type: "text",
-			text: await response.text()
+			text: result.text
 		};
 	}
 	if (resolved.type === "base64") return {
 		type: "text",
 		text: Buffer.from(resolved.value, "base64").toString("utf8")
 	};
+	enforceLocalPathPolicy(resolved.value, bareString, policy);
 	return {
 		type: "text",
 		text: await readFile(resolved.value, "utf8")
 	};
 }
+/** Process-lifetime flag so the bare-string deprecation warns at most once. */
+let warnedBareLocalPath = false;
+/**
+* Enforce the local-file half of {@link AttachmentPolicy} (S1):
+*
+* - **Bare-string local paths** are staged for deprecation. With
+*   `allowBareLocalPaths: false` they hard-deny now; otherwise they warn
+*   once (outside tests) — the typed `StorageFile.absolutePath` route is
+*   the supported way to read a local file.
+* - **`allowedRoots` sandbox** — when set, the resolved path must live
+*   inside one of the roots, else the read is refused.
+*/
+function enforceLocalPathPolicy(path, bareString, policy) {
+	if (bareString) {
+		if (policy?.allowBareLocalPaths === false) throw new OutboundPolicyError(`local file attachment via a bare string path ("${path}") is disabled — pass a typed \`{ type, source: { absolutePath } }\` StorageFile, or set \`attachmentPolicy.allowBareLocalPaths: true\``, { context: { path } });
+		if (!warnedBareLocalPath && !process.env.VITEST && process.env.NODE_ENV !== "test") {
+			warnedBareLocalPath = true;
+			console.warn("[warlock-ai] reading a local file attachment from a bare string path is deprecated and will be denied by default in a future minor. Pass a typed `{ type, source: { absolutePath } }` StorageFile and confine reads with `attachmentPolicy.allowedRoots`.");
+		}
+	}
+	const roots = policy?.allowedRoots;
+	if (roots && roots.length > 0) {
+		const target = resolve(path);
+		if (!roots.some((root) => {
+			const rel = relative(resolve(root), target);
+			return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+		})) throw new OutboundPolicyError(`local file attachment "${path}" is outside the allowed roots`, { context: {
+			path,
+			allowedRoots: roots
+		} });
+	}
+}
 function isTaggedAttachment(attachment) {
 	return typeof attachment === "object" && attachment !== null && "type" in attachment;
 }

package/esm/utils/prepare-attachment-part.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prepare-attachment-part.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { extname } from \"node:path\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport { InvalidRequestError } from \"../errors\";\nimport { resolveAttachment } from \"./resolve-attachment\";\n\nconst IMAGE_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".png\": \"image/png\",\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".webp\": \"image/webp\",\n  \".gif\": \"image/gif\",\n};\n\nconst TEXT_EXTENSIONS = new Set([\".txt\"]);\n\ntype AttachmentKind = \"image\" | \"text\";\n\n/**\n * Convert a user-supplied `Attachment` into a provider-ready\n * `ContentPart` the model adapter can consume without doing any I/O of\n * its own.\n *\n * Kind resolution:\n * - Tagged `{ type: \"image\", source }` / `{ type: \"text\", source }`\n *   trusts the caller's intent.\n * - Shorthand (raw string / `StorageFileShape`) infers from the file\n *   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)\n *   map to `\"image\"`. `.txt` maps to `\"text\"`. Anything else throws\n *   `InvalidRequestError` — silent inference on ambiguous inputs\n *   causes silent bugs.\n *\n * Local paths are read from disk; images are base64-encoded inline,\n * text files are read as UTF-8 strings and returned as a `text`\n * `ContentPart`. Remote URLs for image attachments are passed through\n * unchanged; remote URLs for text attachments are fetched so the\n * adapter never needs network access.\n *\n * @example\n * await prepareAttachmentPart(\"./photo.png\");\n * // → { type: \"image\", source: { base64: \"...\", mediaType: \"image/png\" } }\n *\n * @example\n * await prepareAttachmentPart({ type: \"text\", source: \"./notes.txt\" });\n * // → { type: \"text\", text: \"<file contents>\" }\n */\nexport async function prepareAttachmentPart(\n  attachment: Attachment,\n): Promise<ContentPart> {\n  const kind = resolveKind(attachment);\n\n  if (kind === \"text\") {\n    return prepareTextPart(attachment);\n  }\n\n  return prepareImagePart(attachment);\n}\n\n/**\n * Decide whether the attachment is text or image. Tagged forms win\n * immediately; for shorthand we inspect the extension. Throws if the\n * shorthand doesn't look like anything we recognize.\n */\nfunction resolveKind(attachment: Attachment): AttachmentKind {\n  if (isTaggedAttachment(attachment)) {\n    return attachment.type;\n  }\n\n  const path = extractPath(attachment);\n  const extension = path ? extname(stripQuery(path)).toLowerCase() : \"\";\n\n  if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"image\";\n  }\n\n  if (TEXT_EXTENSIONS.has(extension)) {\n    return \"text\";\n  }\n\n  throw new InvalidRequestError(\n    \"Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt)\",\n  );\n}\n\n/**\n * Produce an `image` ContentPart. URLs pass through; paths are\n * read from disk and base64-encoded with an inferred media type.\n * Inline base64 attachments pass through unchanged.\n */\nasync function prepareImagePart(attachment: Attachment): Promise<ContentPart> {\n  const inferredMediaType = isTaggedAttachment(attachment)\n    ? undefined\n    : inferImageMediaType(attachment);\n\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    return { type: \"image\", source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return {\n      type: \"image\",\n      source: { base64: resolved.value, mediaType: resolved.mediaType },\n    };\n  }\n\n  const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for path \"${resolved.value}\" — use a recognized image extension or pass ` +\n        \"`{ type: 'image', source: { base64, mediaType } }`\",\n      { context: { path: resolved.value } },\n    );\n  }\n\n  const bytes = await readFile(resolved.value);\n\n  return {\n    type: \"image\",\n    source: { base64: bytes.toString(\"base64\"), mediaType },\n  };\n}\n\n/**\n * Produce a `text` ContentPart. URLs are fetched as UTF-8, paths are\n * read from disk as UTF-8, inline base64 is decoded to UTF-8. The\n * result joins the conversation as an additional text part the model\n * sees before responding.\n */\nasync function prepareTextPart(attachment: Attachment): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    const response = await fetch(resolved.value);\n\n    if (!response.ok) {\n      throw new InvalidRequestError(\n        `Failed to fetch text attachment \"${resolved.value}\" — status ${response.status}`,\n        { context: { url: resolved.value, status: response.status } },\n      );\n    }\n\n    return { type: \"text\", text: await response.text() };\n  }\n\n  if (resolved.type === \"base64\") {\n    const decoded = Buffer.from(resolved.value, \"base64\").toString(\"utf8\");\n\n    return { type: \"text\", text: decoded };\n  }\n\n  const bytes = await readFile(resolved.value, \"utf8\");\n\n  return { type: \"text\", text: bytes };\n}\n\nfunction isTaggedAttachment(\n  attachment: Attachment,\n): attachment is Extract<Attachment, { type: string }> {\n  return (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  );\n}\n\nfunction inferImageMediaType(input: unknown): string | undefined {\n  const path = extractPath(input);\n\n  if (!path) {\n    return undefined;\n  }\n\n  const extension = extname(stripQuery(path)).toLowerCase();\n\n  return IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension];\n}\n\nfunction extractPath(input: unknown): string | undefined {\n  if (typeof input === \"string\") {\n    return input;\n  }\n\n  if (typeof input === \"object\" && input !== null) {\n    const storage = input as { url?: string; absolutePath?: string };\n    return storage.url ?? storage.absolutePath;\n  }\n\n  return undefined;\n}\n\nfunction stripQuery(path: string): string {\n  const queryIndex = path.indexOf(\"?\");\n\n  return queryIndex === -1 ? path : path.slice(0, queryIndex);\n}\n"],"mappings":";;;;;;;AAOA,MAAM,iCAAyD;CAC7D,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,SAAS;CACT,QAAQ;AACV;AAEA,MAAM,kBAAkB,IAAI,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCxC,eAAsB,sBACpB,YACsB;CAGtB,IAFa,YAAY,UAElB,MAAM,QACX,OAAO,gBAAgB,UAAU;CAGnC,OAAO,iBAAiB,UAAU;AACpC;;;;;;AAOA,SAAS,YAAY,YAAwC;CAC3D,IAAI,mBAAmB,UAAU,GAC/B,OAAO,WAAW;CAGpB,MAAM,OAAO,YAAY,UAAU;CACnC,MAAM,YAAY,OAAO,QAAQ,WAAW,IAAI,CAAC,CAAC,CAAC,YAAY,IAAI;CAEnE,IAAI,+BAA+B,YACjC,OAAO;CAGT,IAAI,gBAAgB,IAAI,SAAS,GAC/B,OAAO;CAGT,MAAM,IAAI,oBACR,2KACF;AACF;;;;;;AAOA,eAAe,iBAAiB,YAA8C;CAC5E,MAAM,oBAAoB,mBAAmB,UAAU,IACnD,SACA,oBAAoB,UAAU;CAElC,MAAM,WAAW,kBAAkB,UAAU;CAE7C,IAAI,SAAS,SAAS,OACpB,OAAO;EAAE,MAAM;EAAS,QAAQ,EAAE,KAAK,SAAS,MAAM;CAAE;CAG1D,IAAI,SAAS,SAAS,UACpB,OAAO;EACL,MAAM;EACN,QAAQ;GAAE,QAAQ,SAAS;GAAO,WAAW,SAAS;EAAU;CAClE;CAGF,MAAM,YAAY,qBAAqB,oBAAoB,SAAS,KAAK;CAEzE,IAAI,CAAC,WACH,MAAM,IAAI,oBACR,qCAAqC,SAAS,MAAM,oGAEpD,EAAE,SAAS,EAAE,MAAM,SAAS,MAAM,EAAE,CACtC;CAKF,OAAO;EACL,MAAM;EACN,QAAQ;GAAE,SAAQ,MAJA,SAAS,SAAS,KAAK,EAIlB,CAAC,SAAS,QAAQ;GAAG;EAAU;CACxD;AACF;;;;;;;AAQA,eAAe,gBAAgB,YAA8C;CAC3E,MAAM,WAAW,kBAAkB,UAAU;CAE7C,IAAI,SAAS,SAAS,OAAO;EAC3B,MAAM,WAAW,MAAM,MAAM,SAAS,KAAK;EAE3C,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,oBACR,oCAAoC,SAAS,MAAM,aAAa,SAAS,UACzE,EAAE,SAAS;GAAE,KAAK,SAAS;GAAO,QAAQ,SAAS;EAAO,EAAE,CAC9D;EAGF,OAAO;GAAE,MAAM;GAAQ,MAAM,MAAM,SAAS,KAAK;EAAE;CACrD;CAEA,IAAI,SAAS,SAAS,UAGpB,OAAO;EAAE,MAAM;EAAQ,MAFP,OAAO,KAAK,SAAS,OAAO,QAAQ,CAAC,CAAC,SAAS,MAE5B;CAAE;CAKvC,OAAO;EAAE,MAAM;EAAQ,MAAM,MAFT,SAAS,SAAS,OAAO,MAAM;CAEhB;AACrC;AAEA,SAAS,mBACP,YACqD;CACrD,OACE,OAAO,eAAe,YACtB,eAAe,QACf,UAAU;AAEd;AAEA,SAAS,oBAAoB,OAAoC;CAC/D,MAAM,OAAO,YAAY,KAAK;CAE9B,IAAI,CAAC,MACH;CAKF,OAAO,+BAFW,QAAQ,WAAW,IAAI,CAAC,CAAC,CAAC,YAEE;AAChD;AAEA,SAAS,YAAY,OAAoC;CACvD,IAAI,OAAO,UAAU,UACnB,OAAO;CAGT,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM;EAC/C,MAAM,UAAU;EAChB,OAAO,QAAQ,OAAO,QAAQ;CAChC;AAGF;AAEA,SAAS,WAAW,MAAsB;CACxC,MAAM,aAAa,KAAK,QAAQ,GAAG;CAEnC,OAAO,eAAe,KAAK,OAAO,KAAK,MAAM,GAAG,UAAU;AAC5D"}
+{"version":3,"file":"prepare-attachment-part.mjs","names":["resolvePath"],"sources":["../../../../../../../@warlock.js/ai/src/utils/prepare-attachment-part.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { extname, isAbsolute, relative, resolve as resolvePath } from \"node:path\";\nimport type { AttachmentPolicy } from \"../contracts/attachment-policy.type\";\nimport type { Attachment } from \"../contracts/attachment.type\";\nimport type { ContentPart } from \"../contracts/content-part.type\";\nimport { InvalidRequestError, OutboundPolicyError } from \"../errors\";\nimport { fetchTextWithPolicy } from \"../security/outbound-policy\";\nimport { resolveAttachment } from \"./resolve-attachment\";\n\nconst IMAGE_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".png\": \"image/png\",\n  \".jpg\": \"image/jpeg\",\n  \".jpeg\": \"image/jpeg\",\n  \".webp\": \"image/webp\",\n  \".gif\": \"image/gif\",\n};\n\nconst TEXT_EXTENSIONS = new Set([\".txt\"]);\n\nconst AUDIO_EXTENSIONS_TO_MEDIA_TYPE: Record<string, string> = {\n  \".mp3\": \"audio/mpeg\",\n  \".wav\": \"audio/wav\",\n  \".m4a\": \"audio/mp4\",\n  \".ogg\": \"audio/ogg\",\n  \".weba\": \"audio/webm\",\n};\n\nconst PDF_EXTENSIONS = new Set([\".pdf\"]);\n\ntype AttachmentKind = \"image\" | \"text\" | \"pdf\" | \"audio\";\n\n/**\n * Convert a user-supplied `Attachment` into a provider-ready\n * `ContentPart` the model adapter can consume without doing any I/O of\n * its own.\n *\n * Kind resolution:\n * - Tagged `{ type: \"image\", source }` / `{ type: \"text\", source }`\n *   trusts the caller's intent.\n * - Shorthand (raw string / `StorageFileShape`) infers from the file\n *   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)\n *   map to `\"image\"`. `.txt` maps to `\"text\"`. Anything else throws\n *   `InvalidRequestError` — silent inference on ambiguous inputs\n *   causes silent bugs.\n *\n * Local paths are read from disk; images are base64-encoded inline,\n * text files are read as UTF-8 strings and returned as a `text`\n * `ContentPart`. Remote URLs for image attachments are passed through\n * unchanged; remote URLs for text attachments are fetched so the\n * adapter never needs network access.\n *\n * @example\n * await prepareAttachmentPart(\"./photo.png\");\n * // → { type: \"image\", source: { base64: \"...\", mediaType: \"image/png\" } }\n *\n * @example\n * await prepareAttachmentPart({ type: \"text\", source: \"./notes.txt\" });\n * // → { type: \"text\", text: \"<file contents>\" }\n *\n * **Trust boundary (S1).** Attachment references are often user-controlled,\n * so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):\n * remote text fetches are default-deny and, when enabled, run through the\n * shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local\n * reads honor an `allowedRoots` sandbox; bare-string local paths warn\n * (staged deprecation). URL *image* attachments are passed to the provider\n * untouched (never fetched here).\n */\nexport async function prepareAttachmentPart(\n  attachment: Attachment,\n  policy?: AttachmentPolicy,\n): Promise<ContentPart> {\n  const kind = resolveKind(attachment);\n  const bareString = typeof attachment === \"string\";\n\n  if (kind === \"text\") {\n    return prepareTextPart(attachment, policy, bareString);\n  }\n\n  if (kind === \"image\") {\n    return prepareImagePart(attachment, policy, bareString);\n  }\n\n  return prepareBinaryPart(attachment, kind, policy, bareString);\n}\n\n/**\n * Decide whether the attachment is text or image. Tagged forms win\n * immediately; for shorthand we inspect the extension. Throws if the\n * shorthand doesn't look like anything we recognize.\n */\nfunction resolveKind(attachment: Attachment): AttachmentKind {\n  if (isTaggedAttachment(attachment)) {\n    return attachment.type;\n  }\n\n  const path = extractPath(attachment);\n  const extension = path ? extname(stripQuery(path)).toLowerCase() : \"\";\n\n  if (IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"image\";\n  }\n\n  if (TEXT_EXTENSIONS.has(extension)) {\n    return \"text\";\n  }\n\n  if (PDF_EXTENSIONS.has(extension)) {\n    return \"pdf\";\n  }\n\n  if (AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extension]) {\n    return \"audio\";\n  }\n\n  throw new InvalidRequestError(\n    \"Cannot infer attachment type from input — pass an explicit `{ type: 'image' | 'text' | 'pdf' | 'audio', source: ... }` or use a recognized extension (.png, .jpg, .jpeg, .webp, .gif, .txt, .pdf, .mp3, .wav, .m4a, .ogg, .weba)\",\n  );\n}\n\n/**\n * Produce a `pdf` / `audio` ContentPart (A2). URLs pass through; local\n * paths are read and base64-encoded with a media type inferred from the\n * kind (`application/pdf`) or extension (audio); inline base64 passes\n * through. Same `AttachmentPolicy` gating as image/text reads.\n */\nasync function prepareBinaryPart(\n  attachment: Attachment,\n  kind: \"pdf\" | \"audio\",\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    return { type: kind, source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return { type: kind, source: { base64: resolved.value, mediaType: resolved.mediaType } };\n  }\n\n  const mediaType =\n    kind === \"pdf\" ? \"application/pdf\" : inferAudioMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for ${kind} path \"${resolved.value}\" — use a recognized extension or pass ` +\n        `\\`{ type: '${kind}', source: { base64, mediaType } }\\``,\n      { context: { path: resolved.value } },\n    );\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value);\n\n  return { type: kind, source: { base64: bytes.toString(\"base64\"), mediaType } };\n}\n\n/** Infer an audio media type from a path's extension. */\nfunction inferAudioMediaType(path: string): string | undefined {\n  return AUDIO_EXTENSIONS_TO_MEDIA_TYPE[extname(stripQuery(path)).toLowerCase()];\n}\n\n/**\n * Produce an `image` ContentPart. URLs pass through; paths are\n * read from disk and base64-encoded with an inferred media type.\n * Inline base64 attachments pass through unchanged.\n */\nasync function prepareImagePart(\n  attachment: Attachment,\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const inferredMediaType = isTaggedAttachment(attachment)\n    ? undefined\n    : inferImageMediaType(attachment);\n\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    // URL images are handed to the provider as a URL — the provider\n    // fetches them, not us — so there's no server-side SSRF surface here.\n    return { type: \"image\", source: { url: resolved.value } };\n  }\n\n  if (resolved.type === \"base64\") {\n    return {\n      type: \"image\",\n      source: { base64: resolved.value, mediaType: resolved.mediaType },\n    };\n  }\n\n  const mediaType = inferredMediaType ?? inferImageMediaType(resolved.value);\n\n  if (!mediaType) {\n    throw new InvalidRequestError(\n      `Cannot infer media type for path \"${resolved.value}\" — use a recognized image extension or pass ` +\n        \"`{ type: 'image', source: { base64, mediaType } }`\",\n      { context: { path: resolved.value } },\n    );\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value);\n\n  return {\n    type: \"image\",\n    source: { base64: bytes.toString(\"base64\"), mediaType },\n  };\n}\n\n/**\n * Produce a `text` ContentPart. URLs are fetched as UTF-8, paths are\n * read from disk as UTF-8, inline base64 is decoded to UTF-8. The\n * result joins the conversation as an additional text part the model\n * sees before responding.\n */\nasync function prepareTextPart(\n  attachment: Attachment,\n  policy: AttachmentPolicy | undefined,\n  bareString: boolean,\n): Promise<ContentPart> {\n  const resolved = resolveAttachment(attachment);\n\n  if (resolved.type === \"url\") {\n    // Default-deny: a remote text attachment is a server-side fetch of\n    // user-controlled input — refuse unless the app explicitly opted in,\n    // then run it through the shared OutboundPolicy (scheme/host/private-\n    // IP/max-bytes/timeout).\n    if (!policy?.allowRemoteFetch) {\n      throw new OutboundPolicyError(\n        `remote text attachment fetch is disabled by default — set \\`attachmentPolicy.allowRemoteFetch: true\\` (with an \\`outbound\\` policy) to fetch \"${resolved.value}\"`,\n        { context: { url: resolved.value } },\n      );\n    }\n\n    const result = await fetchTextWithPolicy(resolved.value, policy.outbound ?? {});\n\n    if (!result.ok) {\n      throw new InvalidRequestError(\n        `Failed to fetch text attachment \"${resolved.value}\" — status ${result.status}`,\n        { context: { url: resolved.value, status: result.status } },\n      );\n    }\n\n    return { type: \"text\", text: result.text };\n  }\n\n  if (resolved.type === \"base64\") {\n    const decoded = Buffer.from(resolved.value, \"base64\").toString(\"utf8\");\n\n    return { type: \"text\", text: decoded };\n  }\n\n  enforceLocalPathPolicy(resolved.value, bareString, policy);\n  const bytes = await readFile(resolved.value, \"utf8\");\n\n  return { type: \"text\", text: bytes };\n}\n\n/** Process-lifetime flag so the bare-string deprecation warns at most once. */\nlet warnedBareLocalPath = false;\n\n/**\n * Enforce the local-file half of {@link AttachmentPolicy} (S1):\n *\n * - **Bare-string local paths** are staged for deprecation. With\n *   `allowBareLocalPaths: false` they hard-deny now; otherwise they warn\n *   once (outside tests) — the typed `StorageFile.absolutePath` route is\n *   the supported way to read a local file.\n * - **`allowedRoots` sandbox** — when set, the resolved path must live\n *   inside one of the roots, else the read is refused.\n */\nfunction enforceLocalPathPolicy(\n  path: string,\n  bareString: boolean,\n  policy: AttachmentPolicy | undefined,\n): void {\n  if (bareString) {\n    if (policy?.allowBareLocalPaths === false) {\n      throw new OutboundPolicyError(\n        `local file attachment via a bare string path (\"${path}\") is disabled — pass a typed \\`{ type, source: { absolutePath } }\\` StorageFile, or set \\`attachmentPolicy.allowBareLocalPaths: true\\``,\n        { context: { path } },\n      );\n    }\n\n    if (!warnedBareLocalPath && !process.env.VITEST && process.env.NODE_ENV !== \"test\") {\n      warnedBareLocalPath = true;\n      console.warn(\n        \"[warlock-ai] reading a local file attachment from a bare string path is deprecated and will be denied by default in a future minor. \" +\n          \"Pass a typed `{ type, source: { absolutePath } }` StorageFile and confine reads with `attachmentPolicy.allowedRoots`.\",\n      );\n    }\n  }\n\n  const roots = policy?.allowedRoots;\n  if (roots && roots.length > 0) {\n    const target = resolvePath(path);\n    const inside = roots.some(root => {\n      const rel = relative(resolvePath(root), target);\n      return rel === \"\" || (!rel.startsWith(\"..\") && !isAbsolute(rel));\n    });\n\n    if (!inside) {\n      throw new OutboundPolicyError(\n        `local file attachment \"${path}\" is outside the allowed roots`,\n        { context: { path, allowedRoots: roots } },\n      );\n    }\n  }\n}\n\nfunction isTaggedAttachment(\n  attachment: Attachment,\n): attachment is Extract<Attachment, { type: string }> {\n  return (\n    typeof attachment === \"object\" &&\n    attachment !== null &&\n    \"type\" in attachment\n  );\n}\n\nfunction inferImageMediaType(input: unknown): string | undefined {\n  const path = extractPath(input);\n\n  if (!path) {\n    return undefined;\n  }\n\n  const extension = extname(stripQuery(path)).toLowerCase();\n\n  return IMAGE_EXTENSIONS_TO_MEDIA_TYPE[extension];\n}\n\nfunction extractPath(input: unknown): string | undefined {\n  if (typeof input === \"string\") {\n    return input;\n  }\n\n  if (typeof input === \"object\" && input !== null) {\n    const storage = input as { url?: string; absolutePath?: string };\n    return storage.url ?? storage.absolutePath;\n  }\n\n  return undefined;\n}\n\nfunction stripQuery(path: string): string {\n  const queryIndex = path.indexOf(\"?\");\n\n  return queryIndex === -1 ? path : path.slice(0, queryIndex);\n}\n"],"mappings":"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"}

package/esm/utils/resolve-attachment.d.mts

@@ -8,9 +8,10 @@ import { Attachment, ResolvedAttachment } from "../contracts/attachment.type.mjs
  *
  * Resolution rules:
  * - `{ base64, mediaType }` → `{ type: "base64", value, mediaType }`.
- * - `StorageFileShape` (`{ url?, absolutePath? }`) → URL wins over
- *   absolute path. URL becomes `{ type: "url" }`; absolute path
- *   becomes `{ type: "path" }`.
+ * - `StorageFileShape` (`{ url?, absolutePath? }`) → `absolutePath` wins
+ *   over `url` when both are present (prefer the local file over an extra
+ *   remote hop). Absolute path becomes `{ type: "path" }`; url becomes
+ *   `{ type: "url" }`.
  * - String starting with `http://` / `https://` → `{ type: "url" }`.
  * - Any other string → `{ type: "path" }`.
  * - Tagged `{ type: "image" | "text", source }` → recurses into `source`.

package/esm/utils/resolve-attachment.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-attachment.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"mappings":";;;;;AAmCA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;iBAA7D,iBAAA,CAAkB,UAAA,EAAY,UAAA,GAAa,kBAAkB"}
+{"version":3,"file":"resolve-attachment.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/utils/resolve-attachment.ts"],"mappings":";;;;;AAoCA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;;iBAA7D,iBAAA,CAAkB,UAAA,EAAY,UAAA,GAAa,kBAAkB"}

package/esm/utils/resolve-attachment.mjs

@@ -10,9 +10,10 @@ const REMOTE_URL_PATTERN = /^https?:\/\//i;
 *
 * Resolution rules:
 * - `{ base64, mediaType }` → `{ type: "base64", value, mediaType }`.
-* - `StorageFileShape` (`{ url?, absolutePath? }`) → URL wins over
-*   absolute path. URL becomes `{ type: "url" }`; absolute path
-*   becomes `{ type: "path" }`.
+* - `StorageFileShape` (`{ url?, absolutePath? }`) → `absolutePath` wins
+*   over `url` when both are present (prefer the local file over an extra
+*   remote hop). Absolute path becomes `{ type: "path" }`; url becomes
+*   `{ type: "url" }`.
 * - String starting with `http://` / `https://` → `{ type: "url" }`.
 * - Any other string → `{ type: "path" }`.
 * - Tagged `{ type: "image" | "text", source }` → recurses into `source`.