@tangle-network/agent-app 0.44.18 → 0.44.21

package/.claude/skills/eval-campaign/SKILL.md

@@ -1,116 +1,79 @@
 ---
 name: eval-campaign
-description: Wire a product agent's self-improvement loop (measure → optimize → gate → ship) onto the shared @tangle-network/agent-app/eval-campaign scaffold. Use when adding or refactoring any product agent's eval/ loop.
+description: Wire product measurement and improvement to Agent Eval campaigns, official optimizers, and explicit release decisions.
 ---
 
-# Wiring a product onto the eval-campaign scaffold
+# Wire Eval Campaigns
 
-You are integrating a product agent's self-improvement loop. The loop **engine already exists** in the substrate — do not rebuild it. Your job is to supply the three things only the product knows, and call one function.
+Use `@tangle-network/agent-app/eval-campaign` as the product-facing import.
+It composes Agent Eval `0.133.0`.
+Do not recreate execution, scoring, data splitting, or optimization.
 
-## Mental model (read first)
+## Choose The Entry Point
 
-`selfImprove` (from `@tangle-network/agent-eval/contract`, re-exported here) owns the entire cycle:
+| Job | Use |
+|---|---|
+| Measure one fixed agent | `runCampaign` |
+| Optimize with official GEPA | `selfImprove` with `gepaOptimizationMethod(...)` |
+| Optimize with Microsoft SkillOpt | `selfImprove` with `skillOptOptimizationMethod(...)` |
+| Adapt another text optimizer | `selfImprove` with `externalTextOptimizationMethod(...)` |
+| Let product code generate candidates | `selfImprove` with an explicit `SurfaceProposer` |
+| Compare complete methods on the same cases | `compareOptimizationMethods` |
 
-- the **train/holdout split** from a flat `scenarios` array,
-- the **proposer** (default `gepaProposer` from your `mutationPrimitives`),
-- the **held-out production gate** (default `defaultProductionGate`, `deltaThreshold` 0.05),
-- **durable provenance** + optional hosted ingest,
-- every budget/seed/storage default.
+There is no default candidate generator.
+When `budget.generations` is greater than zero, pass exactly one of `method` or `proposer`.
 
-A product brings exactly three things:
+## Supply Product Inputs
 
-1. **`scenarios`** — your corpus (personas / cases / tasks) in the substrate `Scenario` shape.
-2. **`agent`** — `(surface, scenario, ctx) => artifact`: run your agent under the current surface (a system-prompt addendum the loop optimizes) and return the artifact your judge scores. Report real cost via `ctx.cost.observe(...)` so the backend-integrity guard sees a real run.
-3. **`judge`** — score an artifact on your rubric. Use `buildEnsembleJudge` (below) for a multi-model ensemble, or hand-write a `JudgeConfig` for a bespoke composite.
-
-Everything else is a default you override only when you have a reason.
-
-## The one import
+1. Define `scenarios` with stable IDs.
+2. Implement `agent(surface, scenario, ctx)` against the real execution path.
+3. Report paid calls through `ctx.cost`.
+4. Define a `JudgeConfig`, or use `buildEnsembleJudge` for repeated independent judges.
+5. Keep method-selection cases separate from final comparison cases.
+6. Set a dollar limit and bounded concurrency.
+7. Promote only when `gateDecision` is `ship`.
 
 ```ts
 import {
-  selfImprove,
   buildEnsembleJudge,
-  type SelfImproveOptions,
-  type JudgeVerdict,
+  selfImprove,
+  type OptimizationMethod,
 } from '@tangle-network/agent-app/eval-campaign'
-```
-
-> Requires `@tangle-network/agent-eval >= 0.100.0` (peer; current published is 0.107.0). The scaffold composes the substrate downward; never import a product package from agent-eval (layering rule).
-
-## Minimal wiring (copy, then fill the three blanks)
-
-```ts
-const RUBRIC = ['accuracy', 'grounding', 'tone'] as const
-type Dim = (typeof RUBRIC)[number]
 
-const judge = buildEnsembleJudge<MyArtifact, MyScenario, Dim>({
-  name: 'my-product',
-  rubric: RUBRIC,
-  judgeReps: 3,                         // 3 uncorrelated judges → inter-rater bands
-  async scoreOne({ artifact, scenario, rep }) {
-    const model = JUDGE_MODELS[rep % JUDGE_MODELS.length]   // vary the model per rep
-    try {
-      const v = await callMyJudge(model, artifact, scenario) // → { accuracy, grounding, tone }
-      return { model, perDimension: v, rationale: v.note, costUsd: v.cost }
-    } catch (err) {
-      return { model, perDimension: null, rationale: String(err) } // failure ≠ zero
-    }
-  },
-})
-
-const result = await selfImprove<MyScenario, MyArtifact>({
-  scenarios: loadMyScenarios(),         // YOU own
-  agent: dispatchUnderSurface,          // YOU own — (surface, scenario, ctx) => artifact
-  judge,                                // built above
-  baselineSurface: '',                  // the addendum the loop optimizes (start empty)
-  mutationPrimitives: MY_DIRECTIVES,    // the optimization levers (default proposer mutates toward these)
-  runDir: process.env.MY_RUN_DIR,       // a real path → durable provenance; omit → in-memory
-  // budget / model / gate / hostedTenant all default — override only when needed
-})
-
-if (result.gate.decision === 'ship') await ship(result.winnerSurface)
+async function optimize(
+  method: OptimizationMethod<MyScenario, MyArtifact>,
+) {
+  const judge = buildEnsembleJudge<MyArtifact, MyScenario, 'accuracy'>({
+    name: 'answer-quality',
+    rubric: ['accuracy'],
+    scoreOne: scoreOneAnswer,
+  })
+
+  return selfImprove({
+    scenarios,
+    selectionScenarios,
+    agent: runUnderSurface,
+    judge,
+    baselineSurface,
+    method,
+    budget: {
+      generations: 1,
+      dollars: 10,
+      maxConcurrency: 2,
+    },
+  })
+}
 ```
 
-## `buildEnsembleJudge` contract
-
-- `scoreOne` is called `judgeReps` times per artifact; **vary the model by `rep`** so the ensemble is uncorrelated (judges sharing a base model share its bias).
-- Return `{ model, perDimension: null }` to record a judge failure **without** killing the ensemble — the reducer means over survivors.
-- The reducer (`aggregateJudgeVerdicts`) **throws only if every rep failed** → the campaign records a failed cell, never a silent zero.
-- `weights` (partial) selects-and-weights named dimensions; default is uniform.
-
-## Config reference (all `SelfImproveOptions`, all optional unless noted)
-
-| Field | Default | When to set |
-|---|---|---|
-| `scenarios` | — (required) | your corpus |
-| `agent` | — (required) | your dispatch under a surface |
-| `judge` | — (required) | `buildEnsembleJudge` or a `JudgeConfig` |
-| `baselineSurface` | — (required) | the surface the loop optimizes; start `''` |
-| `mutationPrimitives` | gepaProposer's own | your optimization levers (additive directives) |
-| `proposer` | `gepaProposer` | pass `evolutionaryProposer({ mutator })` for blind addendum rotation |
-| `gate` | `defaultProductionGate` (Δ 0.05) | `paretoSignificanceGate` for multi-objective; tune `deltaThreshold` for your rubric scale. To prove a held-out lift is real CONTENT and not just added prompt/mount FOOTPRINT, compose `neutralizationGate` (agent-eval >= 0.107.0, from `@tangle-network/agent-eval/campaign`) — a footprint-matched placebo arm. It needs `ctx.neutralizedJudgeScores` from `runImprovementLoop({ neutralize })`; `selfImprove`/this scaffold do not surface that option yet, so wire it at the `runImprovementLoop` level or re-export it in the scaffold first. |
-| `budget` | 3 gens × pop 2, 0.25 holdout | `budget.reps` (replicates → tighter CIs), `budget.promoteTopK`, `budget.holdoutScenarios` (explicit split), `budget.dollars` (cost cap) |
-| `expectUsage` | **`'assert'`** | the fail-loud backend-integrity guard. Leave at `'assert'` for real runs (a stub cell throws); set `'off'` ONLY for a deterministic offline/replay run |
-| `labeledStore` | off | capture every artifact + judge score (the dataset you ship + few-shot corpus); set `captureSource` (default `'eval-run'`) |
-| `analyzeGeneration` | — | the per-generation findings producer (EYES→HANDS) — plug a trace-analyst / HALO to refresh `ctx.findings` each round |
-| `runDir` | `mem://…` (non-durable) | a real path to persist provenance + spans |
-| `hostedTenant` | off | ship eval-run events to a hosted orchestrator |
-| `collectWorkerRecords` | — | return the per-call `RunRecord`s your agent accumulated → real backend-integrity verdict |
-| `onProgress` | — | stream baseline/generation/gate events to a UI |
-
-## Fail-loud contract (do not break)
-
-- In `agent`, report real cost via `ctx.cost.observe(costUsd, label)` + `ctx.cost.observeTokens(...)`. A dispatch that reports `{0,0}` trips `expectUsage` — that is the honest "ran against a stub" signal; never paper over it.
-- A judge failure is `perDimension: null`, never a fabricated zero.
-- Train and holdout must both be non-empty (`selfImprove` derives the split; supply enough scenarios).
-
-## Anti-patterns (these are what this scaffold deletes)
+## Reject Invalid Runs
 
-- ❌ Hand-rolling `runImprovementLoop({...})` + `emitLoopProvenance({...})` + a train/holdout split. That is ~100 lines of identical boilerplate per product. Call `selfImprove`.
-- ❌ A per-product copy of the judge-ensemble reducer (survivor-mean / disagreement / cost-sum). Use `buildEnsembleJudge` → `aggregateJudgeVerdicts`.
-- ❌ `import type` from a product package inside the scaffold or substrate (upward dependency — forbidden).
+- Reject missing or zero usage on real model calls.
+- Record a failed judge as `perDimension: null`; never invent a zero.
+- Require non-empty training and final comparison sets.
+- Never expose final comparison cases to an optimization method.
+- Inspect paired results and complete cost accounting before making a claim.
 
-## Where it lives in the product
+## Then consider
 
-One file: `eval/self-improve.ts`. It exports `runMyEval` (measure: `selfImprove` with `budget.generations = 0`, or `runCampaign`) and `runMySelfImprovement` (optimize: the wiring above). The product's harness/CLI calls these; nothing else duplicates the loop.
+- Use `measurement-validation` when the metric has not separated known-good and known-bad cases.
+- Use `surface-evolution` when the measurement is trusted and one production surface is ready to optimize.

package/.claude/skills/surface-evolution/SKILL.md

@@ -1,35 +1,41 @@
 ---
 name: surface-evolution
-description: Optimize ONE evolvable surface (a prompt section / tool config) against a validated measurement, gate winners on held-out evidence plus a critical-dimension floor, and promote without offline/online drift. Use to run an Improve loop once eval-architect + measurement-validation pass.
+description: Optimize one production agent surface with Agent Eval methods, separate data, bounded spend, and measured promotion.
 ---
 
-# Surface Evolution — run the gated loop, promote without drift
+# Evolve One Surface
 
-You are a closed-loop controller for agent quality. **Sensor** = the eval (built by `eval-architect`, certified by `measurement-validation`). **Controller** = the proposer that proposes surface rewrites. **Actuator** = promotion (writing the surface to the live agent). **Safety interlock** = the gate. The interlock is the entire point: it prefers *under-promotion* to Goodhart. A loop that ships every apparent gain is worthless; a loop that ships only evidence-backed gains is the product.
+Optimize one surface that production loads exactly as measured.
+Keep security, approval, authorization, and compliance rules outside the editable surface.
 
-The engine exists in the substrate (`@tangle-network/agent-eval/contract` `selfImprove` / `runImprovementLoop`, `gepaProposer`, `defaultProductionGate`, `neutralizationGate`, `composeGate`) — re-exported via `@tangle-network/agent-app/eval-campaign`. **Do not rebuild it.** This skill is how you wire and run it safely.
+## Run
 
-## Invariant (non-negotiable)
+1. Identify the exact source file or data object that production loads.
+2. Establish training, method-selection, and final comparison cases with no overlap.
+3. Choose one search path:
+   - Use `gepaOptimizationMethod(...)` for official GEPA.
+   - Use `skillOptOptimizationMethod(...)` for official SkillOpt.
+   - Use `externalTextOptimizationMethod(...)` for another maintained optimizer.
+   - Use `SurfaceProposer` only when product or Runtime code owns candidate generation.
+4. Pass the chosen `method` or `proposer` to `selfImprove`.
+5. Set explicit dollars, concurrency, and repetitions.
+6. Guard critical dimensions in the release policy.
+7. Pass `neutralize` when added prompt size could create a decorative lift.
+8. Promote only the exact returned winner when `gateDecision` is `ship`.
 
-1. **Optimize exactly ONE surface that production renders identically.** The artifact you mutate offline must be the artifact the live agent loads — one source, rendered both places (e.g. an evolvable prompt section materialized from a single file into the live system prompt). If offline and online diverge, the lift is fictional the moment it ships.
-2. **Gate promotion on a held-out split AND a critical-dimension floor.** Never promote a net composite gain that regresses a guarded dimension (safety, hallucination, the regulated invariant). A +10 composite that loses 30 on hallucination is a regression, not a win. **AND gate on a footprint placebo.** A held-out lift proves the candidate beat baseline; it does NOT prove the lift came from the surface's CONTENT rather than the extra prompt/mount FOOTPRINT it added. Compose `neutralizationGate` (from `@tangle-network/agent-eval/campaign`, wired via `runImprovementLoop({ neutralize })`) AFTER the significance gate — `composeGate(heldOutGate({...}), neutralizationGate({...}))` — so a candidate whose content-blanked, footprint-matched twin reproduces more than `maxDecorativeFraction` (default 0.5) of the lift is HELD as decorative, no matter how large or significant its raw lift.
-3. **Budget is a hard ceiling and cost-aware** — skip cells beyond the ceiling, never abort. The user's spend maps to generations × candidates × reps: $0.20 buys one quick generation; $50 buys a wide search with tight CIs.
-4. **Never evolve a frozen surface.** The regulated invariants — human-in-the-loop, the compliance gate, auth/RBAC — are off-limits. Declare exactly what is evolvable; everything else the loop must not touch.
+## Required Checks
 
-> Worked result (this is the skill working): a GEPA run on the legal addendum proposed a "multi-jurisdictional divergence handling" section, diagnosed from the worst *training* personas. The gate guarded `hallucination_free` (no regression) and required held-out significance. When the held-out evidence came back incomplete, it **refused to ship** — exactly right. Trust > lift.
+- Prove the metric rejects a known-bad candidate before spending on search.
+- Prove each compared cell executed and reported usage.
+- Require paired final-case evidence.
+- Reject a winner that regresses any protected dimension.
+- After promotion, compare the live bytes with the selected surface.
+- Repeat the final comparison on fresh cases before claiming a durable gain.
 
-## Judgment (figure this out per product)
+Stop when added candidates no longer improve selection results within the budget.
+If failures require new tools, data, or execution behavior, change the architecture instead of continuing prompt search.
 
-- Which surface is safe to evolve (a guidance section, a tool description, a config knob) vs frozen (the invariants above)?
-- How to scope budget to the gap — one generation to confirm a hunch, many to search a wide space?
-- When has it converged or plateaued? If surface-tuning is exhausted and the gap is architectural, escalate — don't keep spending on a surface that's maxed.
+## Then consider
 
-## Self-test
-
-- **After a promotion, the live agent renders the exact winning surface** — diff the deployed artifact against the promoted one. They must be byte-identical.
-- **The held-out lift reproduces on a fresh run** — a one-shot gain is noise until it repeats.
-- **The gate's rejections are honest** — a held verdict carries a stated reason ("0 valid paired runs", "regressed guarded dimension"), never a silent pass and never a lift over partial data.
-
-## Evolves-by
-
-Production outcomes of shipped surfaces (did the held-out lift actually hold live?) feed back into the driver's mutation priors and the gate's thresholds. A surface that lifted offline but flatlined live tells you the held-out set wasn't representative — widen it. See `skill-evolution`.
+- Use `measurement-validation` when the metric or final-case split is not yet trustworthy.
+- Use `skill-evolution` when repeated runs expose a durable improvement to this operating procedure.

package/README.md

@@ -35,15 +35,16 @@ pnpm add @tangle-network/agent-eval @tangle-network/agent-integrations
 
 | Peer | Required by | Range |
 |---|---|---|
-| `@tangle-network/agent-eval` | `/eval`, `/eval-campaign`, `/profile`, `/knowledge` | `>=0.100.0` |
-| `@tangle-network/agent-runtime` | `/runtime`, `/chat-routes` | `>=0.79.3` |
+| `@tangle-network/agent-eval` | `/eval`, `/eval-campaign`, `/profile`, `/knowledge` | `0.133.2` |
+| `@tangle-network/agent-runtime` | `/runtime`, `/chat-routes` | `0.107.4` |
 | `@tangle-network/agent-integrations` | `/integrations` | `>=0.44.0` |
-| `@tangle-network/agent-interface` | `/interactions`, `/chat-store`, `/harness` | `>=0.15.0` |
-| `@tangle-network/sandbox` | `/sandbox`, `/profile`, `/skills` | `>=0.9.7` |
-| `@tangle-network/agent-knowledge` | `/knowledge-loop` | `>=1.7.0` |
-| `@tangle-network/agent-profile-materialize` | `/skills-placement` | `>=0.6.0` |
+| `@tangle-network/agent-interface` | `/interactions`, `/chat-store`, `/harness` | `0.36.0` |
+| `@tangle-network/sandbox` | `/sandbox` | `0.15.1` |
+| `@tangle-network/agent-knowledge` | `/knowledge-loop` | `6.1.4` |
+| `@tangle-network/agent-profile-materialize` | `/skills-placement` | `0.9.0` |
+| `@tangle-network/sandbox-ui` | `/brand`, `/studio-react`, `/work-product-react` | `0.90.1` |
 
-All of these except `agent-eval`, `agent-integrations`, and `agent-interface` are declared **optional** peers, so a product that never imports the subpath installs nothing. `driveSandboxTurn` (`/sandbox`) calls `box.driveTurn`, which the SDK added in **0.10.5** — above the declared floor, so pin `@tangle-network/sandbox >= 0.10.5` yourself if you use it.
+All of these except `agent-eval`, `agent-integrations`, and `agent-interface` are declared **optional** peers, so a product that never imports the subpath installs nothing.
 
 Modules that import no engine package (`/tools`, `/web`, `/crypto`, `/redact`, `/stream`, `/billing`, `/tangle` — the last two take their client as a structural contract) need no peers.
 

package/dist/assistant/index.d.ts

@@ -4,7 +4,7 @@ import { ToolDetailRenderers, ChatUiMessage } from '../web-react/index.js';
 import '../contract-CEewO6DI.js';
 import '@tangle-network/agent-interface';
 import '../plans/index.js';
-import '../parts-S1OINlRP.js';
+import '../parts-fyPPdDdK.js';
 import '../types-DB82fktc.js';
 import '../agent-activity-C8ZG0F0M.js';
 import '../flow-types-CJxEmaRy.js';
@@ -12,7 +12,7 @@ import '../queue-vRI0Qx3X.js';
 import '../sandbox-terminal-ChNEdHF8.js';
 import '../catalog/index.js';
 import '../harness/index.js';
-import '../attachment-validation-Zw8eslhN.js';
+import '../attachment-validation-Dvc_Livy.js';
 import '../stream-normalizer-DnuqkZvw.js';
 
 /**

package/dist/assistant/index.js

@@ -3,13 +3,13 @@ import {
   ChatMessages,
   ModelPicker,
   ProviderLogo
-} from "../chunk-7SMPAAIT.js";
+} from "../chunk-PRKSYTMQ.js";
 import "../chunk-FBVLEGEG.js";
 import "../chunk-YTMKRL3L.js";
 import "../chunk-GEYACSFW.js";
 import "../chunk-HCOROIRT.js";
-import "../chunk-VM6VLJH6.js";
-import "../chunk-DV2FA2PW.js";
+import "../chunk-BI6NKSO4.js";
+import "../chunk-C3SRFZGL.js";
 import "../chunk-ZVEEWGDK.js";
 import "../chunk-5EPIPT4V.js";
 import "../chunk-3ZK5IJSW.js";

package/dist/{attachment-validation-Zw8eslhN.d.ts → attachment-validation-Dvc_Livy.d.ts}

@@ -1,4 +1,4 @@
-import { M as FileMention } from './parts-S1OINlRP.js';
+import { M as FileMention } from './parts-fyPPdDdK.js';
 
 /**
  * `createSandboxFileIndexRoute` — server side of `@`-file-mentions

package/dist/chat-routes/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ChatMessagePart, N as ChatTurnRequestPayload, O as ChatTurnPartInput, P as ChatTurnFilePartInput, b as ChatAttachmentPart, a as ChatAttachmentKind, g as ChatMentionPart } from '../parts-S1OINlRP.js';
-export { Q as ChatAttachmentInput, f as ChatMentionKind, R as ChatTurnInputError, T as ChatTurnTextPartInput, U as DISPATCH_MAX_MEDIA_PARTS, V as DISPATCH_MAX_PARTS, W as DISPATCH_REQUEST_MAX_BYTES, X as DISPATCH_STRUCTURAL_RESERVE_BYTES, M as FileMention, Y as FileMentionsToPartsOptions, Z as INLINE_PARTS_MAX_BYTES, _ as MENTION_MAX_COUNT, $ as ProducerErrorEvent, a0 as ProducerNoticeEvent, a1 as ProducerPassthroughEvent, a2 as ProducerPassthroughEventType, a3 as ProducerReasoningEvent, a4 as ProducerTextEvent, a5 as ProducerToolCallEvent, a6 as ProducerToolResultEvent, a7 as ProducerUsageEvent, a8 as ProducerWireEvent, a9 as SandboxMentionPathCheck, aa as assertPromptPartsWithinCap, ab as base64WireLen, ac as buildMentionPromptBlock, ad as chatTurnRequestInit, ae as fileMentionsToParts, af as formatBytes, ag as mediaTypeForMentionPath, ah as mentionKindForPath, ai as parseChatTurnParts, aj as parseFileMentions, ak as promptPartsByteSize, al as validateSandboxMentionPath } from '../parts-S1OINlRP.js';
-export { A as ALLOWED_ATTACHMENT_SNIFFED_MIMES, a as ATTACHMENT_ACCEPT, b as ATTACHMENT_MAX_COUNT, c as AttachmentTypeCheckResult, C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, d as FileIndexCache, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse, M as MAX_ATTACHMENT_TOTAL_BYTES, h as MAX_BINARY_ATTACHMENT_BYTES, i as MAX_TEXT_ATTACHMENT_BYTES, S as SandboxFileTreeSource, j as SandboxTreeFile, k as SandboxTreeResult, l as SniffResult, m as attachmentSizeErrorMessage, n as attachmentTotalSizeErrorMessage, o as checkAttachmentType, p as createSandboxFileIndexRoute, s as sanitizeAttachmentFileName, q as sniffBinary } from '../attachment-validation-Zw8eslhN.js';
+import { C as ChatMessagePart, N as ChatTurnRequestPayload, O as ChatTurnPartInput, P as ChatTurnFilePartInput, b as ChatAttachmentPart, a as ChatAttachmentKind, g as ChatMentionPart } from '../parts-fyPPdDdK.js';
+export { Q as ChatAttachmentInput, f as ChatMentionKind, R as ChatTurnInputError, T as ChatTurnTextPartInput, U as DISPATCH_MAX_MEDIA_PARTS, V as DISPATCH_MAX_PARTS, W as DISPATCH_REQUEST_MAX_BYTES, X as DISPATCH_STRUCTURAL_RESERVE_BYTES, M as FileMention, Y as FileMentionsToPartsOptions, Z as INLINE_PARTS_MAX_BYTES, _ as MENTION_MAX_COUNT, $ as ProducerErrorEvent, a0 as ProducerNoticeEvent, a1 as ProducerPassthroughEvent, a2 as ProducerPassthroughEventType, a3 as ProducerReasoningEvent, a4 as ProducerTextEvent, a5 as ProducerToolCallEvent, a6 as ProducerToolResultEvent, a7 as ProducerUsageEvent, a8 as ProducerWireEvent, a9 as SandboxMentionPathCheck, aa as assertPromptPartsWithinCap, ab as base64WireLen, ac as buildMentionPromptBlock, ad as chatTurnRequestInit, ae as fileMentionsToParts, af as formatBytes, ag as mediaTypeForMentionPath, ah as mentionKindForPath, ai as parseChatTurnParts, aj as parseFileMentions, ak as promptPartsByteSize, al as validateSandboxMentionPath } from '../parts-fyPPdDdK.js';
+export { A as ALLOWED_ATTACHMENT_SNIFFED_MIMES, a as ATTACHMENT_ACCEPT, b as ATTACHMENT_MAX_COUNT, c as AttachmentTypeCheckResult, C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, d as FileIndexCache, e as FileIndexReadyResponse, f as FileIndexResponse, g as FileIndexWarmingResponse, M as MAX_ATTACHMENT_TOTAL_BYTES, h as MAX_BINARY_ATTACHMENT_BYTES, i as MAX_TEXT_ATTACHMENT_BYTES, S as SandboxFileTreeSource, j as SandboxTreeFile, k as SandboxTreeResult, l as SniffResult, m as attachmentSizeErrorMessage, n as attachmentTotalSizeErrorMessage, o as checkAttachmentType, p as createSandboxFileIndexRoute, s as sanitizeAttachmentFileName, q as sniffBinary } from '../attachment-validation-Dvc_Livy.js';
 import { ChatTurnIdentity, ChatTurnProducer } from '@tangle-network/agent-runtime';
 import { InteractionAnswerRoute, InteractionAnswerRouteOptions } from '../interactions/index.js';
 import { PersistedChatMessageForTurn } from '../stream/index.js';
@@ -1262,7 +1262,8 @@ interface CreateUploadRouteOptions {
     inlineMaxBytes?: number;
     /** Hard per-file cap. Default {@link UPLOAD_MAX_FILE_BYTES}. */
     maxFileBytes?: number;
-    /** Workspace directory for path-ref files. Default `'uploads'`. */
+    /** Absolute workspace directory for path-ref files.
+     *  Default `'/workspace/uploads'`. */
     uploadDir?: string;
 }
 /** One uploaded file, ready for the composer chip and the turn body. */
@@ -1526,9 +1527,9 @@ declare function createAttachmentUploadRoute(options: CreateAttachmentUploadRout
  * blocks); each attachment or mention becomes one media part. An attachment
  * (read from the product store via the injected reader) draws the inline byte
  * budget first; a mention (read from the LIVE box) takes what is left. A file
- * inlines as a `data:` URI when it fits the remaining budget, otherwise demotes
- * to an in-box path part so the whole request stays under the proxy cap. Every
- * media part is deduped by its resolved absolute path. This module only
+ * inlines as a `data:` URI when it fits the remaining budget, otherwise uses
+ * the in-box file reference supported by the current sandbox prompt contract.
+ * Every media part is deduped by its resolved absolute path. This module only
  * produces the parts array; the caller decides when a turn dispatches parts
  * instead of a plain string.
  *
@@ -1565,6 +1566,12 @@ type SandboxMentionReadOutcome = {
 type ReadSandboxMentionFn = (box: SandboxExecChannel, absolutePath: string, options: {
     readBytes: boolean;
 }) => Promise<SandboxMentionReadOutcome>;
+/**
+ * Convert the browser-safe chat attachment contract into the current sandbox
+ * prompt contract. Images carry exactly one URL or path; generic files carry a
+ * filename and URL.
+ */
+declare function normalizeChatPromptForSandbox(prompt: string | readonly ChatTurnPartInput[]): string | PromptInputPart[];
 /** Build input parameters for dispatching chat message parts including text, attachments, mentions, and history */
 interface BuildDispatchPartsInput {
     text: string;
@@ -1583,7 +1590,7 @@ interface BuildDispatchPartsInput {
     /** The product's workspace/tenant key, passed to `readAttachment`. */
     scopeId: string;
     /** Maps an attachment's store-relative path to the in-box absolute path a
-     *  path-based part references (same seam style as `fileMentionsToParts`'s
+     *  local media reference uses (same style as `fileMentionsToParts`'s
      *  `resolvePath`). */
     resolveAttachmentPath: (path: string) => string;
     /** Maps a mention's workspace-relative path to its in-box absolute path.
@@ -1593,7 +1600,7 @@ interface BuildDispatchPartsInput {
     /** The turn's already-ensured box — required when `mentions` is non-empty
      *  (mention bytes are read from the live box, not the store). */
     box?: SandboxExecChannel;
-    /** Force every media part to a path reference, skipping all inlining. */
+    /** Force every media part to a local file reference, skipping all inlining. */
     forcePath?: boolean;
     /** REQUIRED store reader for attachment content — no default (the product
      *  owns its store; see {@link ReadAttachmentFn}). */
@@ -1693,4 +1700,4 @@ interface PromoteAgentFilePartOptions {
 /** Promote a part of an agent file with optional byte limits and MIME type detection */
 declare function promoteAgentFilePart(options: PromoteAgentFilePartOptions): Promise<PromoteFilePartResult>;
 
-export { type AssistantDraftSnapshot, type AssistantDraftStore, type AssistantDraftWriter, type AssistantDraftWriterOptions, type AssistantRowValues, type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentUploadAuthorization, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatRouteEvent, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, type ChatTurnCompleteInput, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, type ChatTurnModelFailover, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnParts, type DetachedTurnResult, type DispatchPartsOutcome, type DraftPersistenceTuning, type DraftStoredMessage, type EmptyTurnRetryInfo, type FilePartPromotionOutcome, MAX_EMPTY_TURN_RETRIES, type ModelFailoverStreamHandle, type ModelFailoverStreamOptions, type ModelFallbackInfo, type OpenModelStream, PROMOTE_MAX_FILE_BYTES, type PromoteAgentFilePartOptions, type PromoteFilePartResult, PromptInputPart, type RawAgentFilePart, type ReadAttachmentFn, type ReadSandboxMentionFn, type ResolveChatAttachmentsOptions, type ResolveChatAttachmentsResult, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, type WriteAttachmentFn, assistantRowIdForTurn, buildDispatchParts, bytesToBase64, classifyTerminalFailure, createAssistantDraftWriter, createAttachmentUploadRoute, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, isCommittingSandboxEvent, isDraftContentEvent, promoteAgentFilePart, resolveChatAttachments, resolveEmptyTurnRetries, rowIdOf, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, summarizeFailoverReason, withDurableChatProjection };
+export { type AssistantDraftSnapshot, type AssistantDraftStore, type AssistantDraftWriter, type AssistantDraftWriterOptions, type AssistantRowValues, type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentUploadAuthorization, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatRouteEvent, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, type ChatTurnCompleteInput, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, type ChatTurnModelFailover, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnParts, type DetachedTurnResult, type DispatchPartsOutcome, type DraftPersistenceTuning, type DraftStoredMessage, type EmptyTurnRetryInfo, type FilePartPromotionOutcome, MAX_EMPTY_TURN_RETRIES, type ModelFailoverStreamHandle, type ModelFailoverStreamOptions, type ModelFallbackInfo, type OpenModelStream, PROMOTE_MAX_FILE_BYTES, type PromoteAgentFilePartOptions, type PromoteFilePartResult, PromptInputPart, type RawAgentFilePart, type ReadAttachmentFn, type ReadSandboxMentionFn, type ResolveChatAttachmentsOptions, type ResolveChatAttachmentsResult, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, type WriteAttachmentFn, assistantRowIdForTurn, buildDispatchParts, bytesToBase64, classifyTerminalFailure, createAssistantDraftWriter, createAttachmentUploadRoute, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, isCommittingSandboxEvent, isDraftContentEvent, normalizeChatPromptForSandbox, promoteAgentFilePart, resolveChatAttachments, resolveEmptyTurnRetries, rowIdOf, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, summarizeFailoverReason, withDurableChatProjection };

package/dist/chat-routes/index.js

@@ -11,7 +11,7 @@ import {
   createSandboxFileIndexRoute,
   sanitizeAttachmentFileName,
   sniffBinary
-} from "../chunk-VM6VLJH6.js";
+} from "../chunk-BI6NKSO4.js";
 import {
   coalesceDeltas,
   createBufferedTurnTap,
@@ -55,7 +55,7 @@ import {
   promptPartsByteSize,
   toChatMessageParts,
   validateSandboxMentionPath
-} from "../chunk-DV2FA2PW.js";
+} from "../chunk-C3SRFZGL.js";
 import "../chunk-ZVEEWGDK.js";
 import {
   asRecord,
@@ -93,7 +93,7 @@ import {
   flattenHistory,
   readSandboxBinaryBytes,
   statSandboxFileSize
-} from "../chunk-JXIQSGOV.js";
+} from "../chunk-2ZSSOYXP.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -310,8 +310,9 @@ function validateTurnBody(body, maxInlinePartBytes) {
   const content = rawContent.trim();
   const fileParts = parseChatTurnParts(body.parts);
   const mentions = parseFileMentions(body.mentions);
-  if (!content && fileParts.length === 0 && mentions.length === 0) {
-    throw new ChatTurnInputError("Missing content (send text, parts, mentions, or any combination)");
+  const hasAttachments = Array.isArray(body.attachments) && body.attachments.length > 0;
+  if (!content && fileParts.length === 0 && mentions.length === 0 && !hasAttachments) {
+    throw new ChatTurnInputError("Missing content (send text, parts, mentions, attachments, or any combination)");
   }
   assertPromptPartsWithinCap(fileParts, maxInlinePartBytes);
   let turnId;
@@ -1693,6 +1694,14 @@ function withDurableChatProjection(producer, projection, log = (message, meta) =
 // src/chat-routes/upload.ts
 var UPLOAD_INLINE_MAX_BYTES = 700 * 1024;
 var UPLOAD_MAX_FILE_BYTES = 8 * 1024 * 1024;
+var DEFAULT_UPLOAD_DIRECTORY = "/workspace/uploads";
+function normalizeUploadDirectory(value) {
+  const withoutTrailingSlash = value.trim().replace(/\/+$/, "");
+  if (!withoutTrailingSlash.startsWith("/") || withoutTrailingSlash.length === 0) return null;
+  const segments = withoutTrailingSlash.slice(1).split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) return null;
+  return `/${segments.join("/")}`;
+}
 function sanitizeUploadFilename(name) {
   const base = name.split(/[\\/]/).pop() ?? "file";
   const safe = base.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "_");
@@ -1716,7 +1725,7 @@ function createUploadRoute(options) {
     const auth = await options.authorize({ request });
     if (!auth.ok) return auth.response;
     const sink = auth.sink ?? null;
-    const uploadDir = (auth.uploadDir ?? options.uploadDir ?? "uploads").replace(/\/+$/, "");
+    const configuredUploadDir = auth.uploadDir ?? options.uploadDir ?? DEFAULT_UPLOAD_DIRECTORY;
     let form;
     try {
       form = await request.formData();
@@ -1767,6 +1776,14 @@ function createUploadRoute(options) {
           `${name} is ${file.size}B, over the ${inlineMaxBytes}B inline cap, and no sandbox is available to hold it`
         );
       }
+      const uploadDir = normalizeUploadDirectory(configuredUploadDir);
+      if (!uploadDir) {
+        return uploadError(
+          500,
+          "INVALID_UPLOAD_DIRECTORY",
+          'uploadDir must be an absolute path without empty, "." or ".." segments'
+        );
+      }
       const path = `${uploadDir}/${id}-${name}`;
       const base64 = bytesToBase64(new Uint8Array(await file.arrayBuffer()));
       await sink.write(path, base64, { encoding: "base64" });
@@ -2179,6 +2196,7 @@ function createAttachmentUploadRoute(options) {
 }
 
 // src/chat-routes/dispatch-parts.ts
+import { pathToFileURL } from "url";
 function byteLen(value) {
   return new TextEncoder().encode(value).length;
 }
@@ -2196,10 +2214,58 @@ async function readSandboxMention(box, absolutePath, options) {
 }
 function violatesUrlPathXor(part) {
   if (part.type === "text") return false;
-  const hasUrl = typeof part.url === "string" && part.url.startsWith("data:");
-  const hasPath = typeof part.path === "string" && part.path.startsWith("/");
+  const hasUrl = typeof part.url === "string" && (part.url.startsWith("data:") || part.url.startsWith("file://"));
+  const hasPath = "path" in part && typeof part.path === "string" && part.path.startsWith("/");
+  if (part.type === "file") return !hasUrl || hasPath;
   return hasUrl === hasPath;
 }
+function sandboxFileUrl(absolutePath) {
+  if (!absolutePath.startsWith("/")) return void 0;
+  try {
+    return pathToFileURL(absolutePath).href;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeChatPromptForSandbox(prompt) {
+  if (typeof prompt === "string") return prompt;
+  return prompt.map((part) => {
+    if (part.type === "text") return part;
+    if ("content" in part) {
+      throw new ChatTurnInputError("Sandbox prompt parts do not accept inline content; provide a URL or path");
+    }
+    const url = typeof part.url === "string" && part.url.length > 0 ? part.url : void 0;
+    const path = typeof part.path === "string" && part.path.length > 0 ? part.path : void 0;
+    if (Boolean(url) === Boolean(path)) {
+      throw new ChatTurnInputError(`Sandbox ${part.type} parts require exactly one URL or path`);
+    }
+    if (path && !path.startsWith("/")) {
+      throw new ChatTurnInputError(`Sandbox ${part.type} paths must be absolute: ${path}`);
+    }
+    if (part.type === "image") {
+      return {
+        type: "image",
+        ...part.filename ? { filename: part.filename } : {},
+        ...part.mediaType ? { mediaType: part.mediaType } : {},
+        ...url ? { url } : { path }
+      };
+    }
+    const filename = part.filename?.trim();
+    if (!filename) {
+      throw new ChatTurnInputError("Sandbox file parts require a filename");
+    }
+    const fileUrl = url ?? sandboxFileUrl(path);
+    if (!fileUrl) {
+      throw new ChatTurnInputError(`Sandbox file paths must be absolute: ${path}`);
+    }
+    return {
+      type: "file",
+      filename,
+      ...part.mediaType ? { mediaType: part.mediaType } : {},
+      url: fileUrl
+    };
+  });
+}
 function readResultToBase64(read) {
   if (typeof read.base64 === "string") return read.base64;
   if (read.bytes) return bytesToBase64(read.bytes);
@@ -2270,7 +2336,11 @@ async function buildDispatchParts(input) {
       parts.push(inlinePart);
       runningInline += cost;
     } else {
-      parts.push({ type: "file", path: absPath });
+      const url = sandboxFileUrl(absPath);
+      if (!url) {
+        return { succeeded: false, error: `resolved attachment path must be absolute: ${absPath}` };
+      }
+      parts.push({ type: "file", filename: attachment.name, mediaType: fileMediaType, url });
     }
   }
   if (mentions.length > 0 && !input.box) {
@@ -2315,9 +2385,15 @@ async function buildDispatchParts(input) {
         continue;
       }
     }
-    parts.push(
-      isImage && mediaType ? { type: "image", filename: mention.name, mediaType, path: absPath } : { type: "file", path: absPath }
-    );
+    if (isImage && mediaType) {
+      parts.push({ type: "image", filename: mention.name, mediaType, path: absPath });
+    } else {
+      const url = sandboxFileUrl(absPath);
+      if (!url) {
+        return { succeeded: false, error: `resolved mention path must be absolute: ${absPath}` };
+      }
+      parts.push({ type: "file", filename: mention.name, url });
+    }
   }
   for (const part of parts) {
     if (violatesUrlPathXor(part)) {
@@ -2379,6 +2455,7 @@ export {
   isDraftContentEvent,
   mediaTypeForMentionPath,
   mentionKindForPath,
+  normalizeChatPromptForSandbox,
   parseChatTurnParts,
   parseFileMentions,
   promoteAgentFilePart,