@tangle-network/agent-app 0.43.46 → 0.43.48

package/dist/chat-routes/index.js

@@ -2,19 +2,17 @@ import {
   createSandboxFileIndexRoute
 } from "../chunk-LCNY3DCM.js";
 import {
-  asRecord,
-  asString,
+  DEFAULT_STALE_TURN_LOCK_GRACE_MS,
+  DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS,
+  reconcileStaleTurnLock
+} from "../chunk-BQV42AFK.js";
+import {
   coalesceDeltas,
   createBufferedTurnTap,
-  finalizeAssistantParts,
-  getPartKey,
-  mergePersistedPart,
   normalizeClientTurnId,
-  normalizePersistedPart,
-  normalizeToolEvent,
   replayTurnEvents,
   resolveChatTurn
-} from "../chunk-4AUQIAYU.js";
+} from "../chunk-23LUHHHN.js";
 import {
   createInteractionAnswerRoute
 } from "../chunk-6KVH5SP5.js";
@@ -23,12 +21,20 @@ import {
 } from "../chunk-HFC4BTWJ.js";
 import {
   ChatTurnInputError,
+  DISPATCH_MAX_MEDIA_PARTS,
+  DISPATCH_MAX_PARTS,
+  DISPATCH_REQUEST_MAX_BYTES,
+  DISPATCH_STRUCTURAL_RESERVE_BYTES,
   INLINE_PARTS_MAX_BYTES,
   MENTION_MAX_COUNT,
   assertPromptPartsWithinCap,
+  attachmentInputToPart,
+  attachmentKindForMime,
+  base64WireLen,
   buildMentionPromptBlock,
   chatTurnRequestInit,
   fileMentionsToParts,
+  formatBytes,
   mediaTypeForMentionPath,
   mentionInputToPart,
   mentionKindForPath,
@@ -37,7 +43,16 @@ import {
   promptPartsByteSize,
   toChatMessageParts,
   validateSandboxMentionPath
-} from "../chunk-6E2XJSCT.js";
+} from "../chunk-JGYOYY5D.js";
+import {
+  asRecord,
+  asString,
+  finalizeAssistantParts,
+  getPartKey,
+  mergePersistedPart,
+  normalizePersistedPart,
+  normalizeToolEvent
+} from "../chunk-5MG74GVQ.js";
 import {
   cancelStatusFor,
   interactionPartKey,
@@ -50,6 +65,17 @@ import {
   parsePlanSubmittedEvent,
   planToPersistedPart
 } from "../chunk-SIXYZ2FB.js";
+import {
+  flattenHistory,
+  readSandboxBinaryBytes,
+  statSandboxFileSize
+} from "../chunk-5RJNEEO2.js";
+import "../chunk-E7QYOOON.js";
+import "../chunk-PJC4NXPA.js";
+import "../chunk-7EVZUIHW.js";
+import "../chunk-S5SRJJQG.js";
+import "../chunk-7W5XSTUF.js";
+import "../chunk-MFRCM32T.js";
 
 // src/chat-routes/turn-routes.ts
 import { deriveExecutionId, handleChatTurn } from "@tangle-network/agent-runtime";
@@ -499,99 +525,6 @@ function concatStreams(streams) {
   });
 }
 
-// src/chat-routes/stale-turn-lock.ts
-var DEFAULT_STALE_TURN_LOCK_GRACE_MS = 5 * 60 * 1e3;
-var DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS = 60 * 1e3;
-function messageOf(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-async function reconcileStaleTurnLock(options) {
-  let sandbox;
-  try {
-    sandbox = await options.probeSandbox();
-  } catch (err) {
-    return forceReleaseUnreachable(options, {
-      unreachableReason: "SANDBOX_PROBE_FAILED",
-      unreachableDetail: messageOf(err)
-    });
-  }
-  if (sandbox.status !== "running") {
-    return forceReleaseUnreachable(options, {
-      unreachableReason: sandbox.status === "absent" ? "SANDBOX_ABSENT" : "SANDBOX_NOT_RUNNING",
-      ...sandbox.status === "not-running" && sandbox.state !== void 0 ? { sandboxState: sandbox.state } : {}
-    });
-  }
-  const observedAt = (options.now ?? Date.now)();
-  let session;
-  try {
-    session = await options.probeSession();
-  } catch (err) {
-    return forceReleaseUnreachable(options, {
-      unreachableReason: "SESSION_PROBE_FAILED",
-      unreachableDetail: messageOf(err)
-    });
-  }
-  if (!session.reachable) {
-    return forceReleaseUnreachable(options, {
-      unreachableReason: "SESSION_UNREACHABLE",
-      ...session.reason !== void 0 ? { sessionProbeError: session.reason } : {}
-    });
-  }
-  const diagnostics = {
-    sandboxReachable: true,
-    sessionTerminal: session.terminal,
-    ...session.diagnostics ?? {}
-  };
-  if (!session.terminal) return { released: false, diagnostics };
-  const terminalGraceMs = options.terminalGraceMs ?? DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS;
-  const lockAgeMs = observedAt - options.lockStartedAt;
-  if (lockAgeMs < terminalGraceMs) {
-    const log = options.log ?? ((message, meta) => console.warn(message, meta));
-    const withheld = {
-      ...diagnostics,
-      lockAgeMs,
-      terminalReleaseGraceMs: terminalGraceMs,
-      terminalReleaseWithheld: "LOCK_WITHIN_TERMINAL_GRACE_PERIOD"
-    };
-    log("[chat-routes] stale turn lock held: terminal verdict but lock is younger than the registration window", {
-      ...options.context ?? {},
-      ...withheld
-    });
-    return { released: false, diagnostics: withheld };
-  }
-  const released = await options.release({ observedAt });
-  return {
-    released,
-    diagnostics: { ...diagnostics, lockAgeMs, terminalReleaseGraceMs: terminalGraceMs, released, observedAt }
-  };
-}
-async function forceReleaseUnreachable(options, reason) {
-  const log = options.log ?? ((message, meta) => console.warn(message, meta));
-  const graceMs = options.graceMs ?? DEFAULT_STALE_TURN_LOCK_GRACE_MS;
-  const at = (options.now ?? Date.now)();
-  const lockAgeMs = at - options.lockStartedAt;
-  const diagnostics = {
-    ...reason,
-    sandboxReachable: false,
-    lockAgeMs,
-    forceReleaseGraceMs: graceMs
-  };
-  if (lockAgeMs < graceMs) {
-    log("[chat-routes] stale turn lock held: sandbox unreachable but lock is inside the grace period", {
-      ...options.context ?? {},
-      ...diagnostics
-    });
-    return { released: false, diagnostics: { ...diagnostics, forceReleaseWithheld: "LOCK_WITHIN_GRACE_PERIOD" } };
-  }
-  const released = await options.release({ observedAt: at });
-  log("[chat-routes] force-released stale turn lock: sandbox unreachable, no turn can be executing", {
-    ...options.context ?? {},
-    ...diagnostics,
-    released
-  });
-  return { released, diagnostics: { ...diagnostics, forceReleased: released } };
-}
-
 // src/chat-routes/sandbox-producer.ts
 function textDelta(tracker, key, part, rawDelta) {
   const explicit = typeof rawDelta === "string" ? rawDelta : void 0;
@@ -640,6 +573,7 @@ function createSandboxChatProducer(options) {
   const announcedTools = /* @__PURE__ */ new Set();
   const settledTools = /* @__PURE__ */ new Set();
   let stepCounter = 0;
+  const promotedFileParts = /* @__PURE__ */ new Map();
   function recordPersistedPart(part, delta, keyOverride) {
     const persisted = normalizePersistedPart(part);
     if (!persisted) return;
@@ -711,6 +645,33 @@ function createSandboxChatProducer(options) {
           recordPersistedPart(part, void 0, `step-start:#${stepCounter}`);
           continue;
         }
+        if (partType === "file" && options.promoteFilePart) {
+          const promote = options.promoteFilePart;
+          const rawId = asString(part.id);
+          const rawUrl = asString(part.url);
+          const memoKey = rawId ? `id:${rawId}` : rawUrl ? `url:${rawUrl}` : void 0;
+          const attempt = () => Promise.resolve().then(() => promote(part)).catch((err) => {
+            const reason = err instanceof Error ? err.message : String(err);
+            log("[chat-routes] file part promotion threw", { key: memoKey ?? "(keyless)", error: reason });
+            return { succeeded: false, reason };
+          });
+          let pending;
+          if (memoKey) {
+            pending = promotedFileParts.get(memoKey) ?? attempt();
+            promotedFileParts.set(memoKey, pending);
+          } else {
+            pending = attempt();
+          }
+          const outcome = await pending;
+          if (outcome.succeeded) {
+            recordPersistedPart(outcome.part, void 0, outcome.key);
+          } else if (outcome.part) {
+            recordPersistedPart(outcome.part, void 0, outcome.key);
+          } else {
+            recordPersistedPart(part, void 0);
+          }
+          continue;
+        }
         recordPersistedPart(part, void 0);
         continue;
       }
@@ -933,15 +894,459 @@ function createUploadRoute(options) {
     return Response.json({ files: uploaded });
   };
 }
+
+// src/chat-routes/resolve-attachments.ts
+var ATTACHMENT_MAX_COUNT = 10;
+var MAX_ATTACHMENT_TOTAL_BYTES = 25 * 1024 * 1024;
+var MAX_ATTACHMENT_NAME_LENGTH = 256;
+function attachmentTotalSizeErrorMessage(totalBytes, limitBytes) {
+  return `Attachments total ${formatBytes(totalBytes)}; each message is limited to ${formatBytes(limitBytes)}`;
+}
+function isAttachmentKind(value) {
+  return value === "image" || value === "file";
+}
+var CONTROL_CHARS = /[\x00-\x1F\x7F]/;
+function defaultValidateAttachmentPath(path) {
+  if (path.includes("\0")) return { succeeded: false, error: "attachment path must not contain null bytes" };
+  if (path.includes("\\")) return { succeeded: false, error: "attachment path must not contain backslashes" };
+  if (CONTROL_CHARS.test(path)) return { succeeded: false, error: "attachment path must not contain control characters" };
+  if (path.startsWith("/")) return { succeeded: false, error: "attachment path must be store-relative, not absolute" };
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "..")) {
+    return { succeeded: false, error: 'attachment path must not contain ".." segments' };
+  }
+  if (segments.some((segment) => segment.startsWith("."))) {
+    return { succeeded: false, error: "attachment path must not contain a hidden (dotfile) segment" };
+  }
+  return { succeeded: true };
+}
+function parseAttachmentInput(value, index, validatePath) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { succeeded: false, error: `attachments[${index}] must be an object` };
+  }
+  const record = value;
+  const path = record.path;
+  if (typeof path !== "string" || !path) {
+    return { succeeded: false, error: `attachments[${index}].path must be a non-empty string` };
+  }
+  const name = record.name;
+  if (typeof name !== "string" || !name.trim()) {
+    return { succeeded: false, error: `attachments[${index}].name must be a non-empty string` };
+  }
+  if (name.length > MAX_ATTACHMENT_NAME_LENGTH) {
+    return { succeeded: false, error: `attachments[${index}].name must not exceed ${MAX_ATTACHMENT_NAME_LENGTH} characters` };
+  }
+  if (CONTROL_CHARS.test(name)) {
+    return { succeeded: false, error: `attachments[${index}].name must not contain control characters` };
+  }
+  const size = record.size;
+  if (typeof size !== "number" || !Number.isFinite(size)) {
+    return { succeeded: false, error: `attachments[${index}].size must be a finite number` };
+  }
+  if (size < 0) {
+    return { succeeded: false, error: `attachments[${index}].size must not be negative` };
+  }
+  const mediaType = record.mediaType;
+  if (typeof mediaType !== "string") {
+    return { succeeded: false, error: `attachments[${index}].mediaType must be a string` };
+  }
+  const kind = record.kind;
+  if (!isAttachmentKind(kind)) {
+    return { succeeded: false, error: `attachments[${index}].kind must be "image" or "file"` };
+  }
+  const pathCheck = validatePath(path);
+  if (!pathCheck.succeeded) return { succeeded: false, error: pathCheck.error };
+  return { succeeded: true, value: { path, name, size, mediaType, kind } };
+}
+async function resolveChatAttachments(value, options) {
+  const maxCount = options.maxCount ?? ATTACHMENT_MAX_COUNT;
+  const maxTotalBytes = options.maxTotalBytes ?? MAX_ATTACHMENT_TOTAL_BYTES;
+  const validatePath = options.validatePath ?? defaultValidateAttachmentPath;
+  if (value === void 0 || value === null) return { succeeded: true, value: [] };
+  if (!Array.isArray(value)) return { succeeded: false, error: "attachments must be an array" };
+  if (value.length > maxCount) {
+    return { succeeded: false, error: `attachments must not exceed ${maxCount} entries` };
+  }
+  const inputs = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (let index = 0; index < value.length; index += 1) {
+    const parsed = parseAttachmentInput(value[index], index, validatePath);
+    if (!parsed.succeeded) return parsed;
+    if (seenPaths.has(parsed.value.path)) {
+      return { succeeded: false, error: `attachments must not repeat a path: ${parsed.value.path}` };
+    }
+    seenPaths.add(parsed.value.path);
+    inputs.push(parsed.value);
+  }
+  const advisoryTotal = inputs.reduce((sum, input) => sum + input.size, 0);
+  if (advisoryTotal > maxTotalBytes) {
+    return { succeeded: false, error: attachmentTotalSizeErrorMessage(advisoryTotal, maxTotalBytes) };
+  }
+  let totalStoredBytes = 0;
+  for (const input of inputs) {
+    const read = await options.readAttachment(options.scopeId, input.path);
+    if (!read.ok) return { succeeded: false, error: read.reason };
+    totalStoredBytes += read.size;
+    if (totalStoredBytes > maxTotalBytes) {
+      return { succeeded: false, error: attachmentTotalSizeErrorMessage(totalStoredBytes, maxTotalBytes) };
+    }
+    input.size = read.size;
+  }
+  return { succeeded: true, value: inputs.map(attachmentInputToPart) };
+}
+
+// src/chat-routes/dispatch-parts.ts
+function byteLen(value) {
+  return new TextEncoder().encode(value).length;
+}
+async function readSandboxMention(box, absolutePath, options) {
+  const stat = await statSandboxFileSize(box, absolutePath);
+  if (!stat.succeeded) {
+    return { succeeded: false, error: `mentioned sandbox file missing or unreadable: ${absolutePath} \u2014 ${stat.error}` };
+  }
+  if (!options.readBytes) return { succeeded: true, value: { size: stat.value } };
+  const read = await readSandboxBinaryBytes(box, absolutePath, stat.value);
+  if (!read.succeeded) {
+    return { succeeded: false, error: `mentioned sandbox file read failed: ${absolutePath} \u2014 ${read.error}` };
+  }
+  return { succeeded: true, value: { size: stat.value, base64: bytesToBase64(read.value.bytes) } };
+}
+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("/");
+  return hasUrl === hasPath;
+}
+function readResultToBase64(read) {
+  if (typeof read.base64 === "string") return read.base64;
+  if (read.bytes) return bytesToBase64(read.bytes);
+  return void 0;
+}
+async function buildDispatchParts(input) {
+  const readMention = input.readSandboxMention ?? readSandboxMention;
+  const resolveMentionPath = input.resolveMentionPath ?? input.resolveAttachmentPath;
+  const forcePath = input.forcePath ?? false;
+  const mentions = input.mentions ?? [];
+  const requestMaxBytes = input.requestMaxBytes ?? DISPATCH_REQUEST_MAX_BYTES;
+  const structuralReserveBytes = input.structuralReserveBytes ?? DISPATCH_STRUCTURAL_RESERVE_BYTES;
+  const maxParts = input.maxParts ?? DISPATCH_MAX_PARTS;
+  const parts = [{ type: "text", text: input.text }];
+  const emittedAbsPaths = /* @__PURE__ */ new Set();
+  const flattenedForSizing = flattenHistory(input.text, input.history);
+  const inlineBudget = requestMaxBytes - base64WireLen(byteLen(flattenedForSizing)) - byteLen(JSON.stringify(input.systemPrompt)) - input.profileWireBytes - structuralReserveBytes;
+  let runningInline = 0;
+  for (const attachment of input.attachments) {
+    if (!attachment.path) {
+      return { succeeded: false, error: `attachment path must be non-empty: ${attachment.name}` };
+    }
+    let read;
+    try {
+      read = await input.readAttachment(input.scopeId, attachment.path);
+    } catch (err) {
+      return {
+        succeeded: false,
+        error: `attachment store read failed: ${attachment.path} \u2014 ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    if (!read.ok) return { succeeded: false, error: read.reason };
+    const base64 = readResultToBase64(read);
+    if (base64 === void 0) {
+      return { succeeded: false, error: `attachment store read produced no content: ${attachment.path}` };
+    }
+    const mediaType = attachment.mediaType ?? read.mediaType;
+    if (attachment.type === "image" && !mediaType) {
+      return { succeeded: false, error: `attachment is missing a mediaType required for an image data URI: ${attachment.path}` };
+    }
+    const absPath = input.resolveAttachmentPath(attachment.path);
+    emittedAbsPaths.add(absPath);
+    if (attachment.type === "image") {
+      const inlinePart2 = {
+        type: "image",
+        filename: attachment.name,
+        mediaType,
+        url: `data:${mediaType};base64,${base64}`
+      };
+      const cost2 = byteLen(JSON.stringify(inlinePart2));
+      if (!forcePath && runningInline + cost2 <= inlineBudget) {
+        parts.push(inlinePart2);
+        runningInline += cost2;
+      } else {
+        parts.push({ type: "image", filename: attachment.name, mediaType, path: absPath });
+      }
+      continue;
+    }
+    const fileMediaType = mediaType ?? "application/octet-stream";
+    const inlinePart = {
+      type: "file",
+      filename: attachment.name,
+      mediaType: fileMediaType,
+      url: `data:${fileMediaType};base64,${base64}`
+    };
+    const cost = byteLen(JSON.stringify(inlinePart));
+    if (!forcePath && runningInline + cost <= inlineBudget) {
+      parts.push(inlinePart);
+      runningInline += cost;
+    } else {
+      parts.push({ type: "file", path: absPath });
+    }
+  }
+  if (mentions.length > 0 && !input.box) {
+    return { succeeded: false, error: "internal error: sandbox mentions require a box to read from" };
+  }
+  for (const mention of mentions) {
+    if (!mention.path) {
+      return { succeeded: false, error: `mention path must be non-empty: ${mention.name}` };
+    }
+    const absPath = resolveMentionPath(mention.path);
+    if (emittedAbsPaths.has(absPath)) continue;
+    emittedAbsPaths.add(absPath);
+    const isImage = mention.mentionKind === "image";
+    const mediaType = isImage ? mediaTypeForMentionPath(mention.path) : void 0;
+    let stat;
+    try {
+      stat = await readMention(input.box, absPath, { readBytes: false });
+    } catch (err) {
+      return { succeeded: false, error: `mention read failed: ${absPath} \u2014 ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (!stat.succeeded) return { succeeded: false, error: stat.error };
+    const projectedInlineCost = base64WireLen(stat.value.size) + byteLen(JSON.stringify({ type: "image", filename: mention.name, mediaType: mediaType ?? "", url: "" }));
+    if (isImage && mediaType && !forcePath && runningInline + projectedInlineCost <= inlineBudget) {
+      let read;
+      try {
+        read = await readMention(input.box, absPath, { readBytes: true });
+      } catch (err) {
+        return { succeeded: false, error: `mention read failed: ${absPath} \u2014 ${err instanceof Error ? err.message : String(err)}` };
+      }
+      if (!read.succeeded) return { succeeded: false, error: read.error };
+      if (!read.value.base64) return { succeeded: false, error: `mentioned image produced no bytes: ${absPath}` };
+      const inlinePart = {
+        type: "image",
+        filename: mention.name,
+        mediaType,
+        url: `data:${mediaType};base64,${read.value.base64}`
+      };
+      const cost = byteLen(JSON.stringify(inlinePart));
+      if (runningInline + cost <= inlineBudget) {
+        parts.push(inlinePart);
+        runningInline += cost;
+        continue;
+      }
+    }
+    parts.push(
+      isImage && mediaType ? { type: "image", filename: mention.name, mediaType, path: absPath } : { type: "file", path: absPath }
+    );
+  }
+  for (const part of parts) {
+    if (violatesUrlPathXor(part)) {
+      return { succeeded: false, error: "internal error: emitted media part violates the url/path exclusivity invariant" };
+    }
+  }
+  const textPartSize = base64WireLen(byteLen(flattenedForSizing));
+  const mediaPartsSize = parts.slice(1).reduce((total, part) => total + byteLen(JSON.stringify(part)), 0);
+  const systemPromptSize = byteLen(JSON.stringify(input.systemPrompt));
+  if (textPartSize + mediaPartsSize + systemPromptSize + input.profileWireBytes + structuralReserveBytes > requestMaxBytes) {
+    return { succeeded: false, error: "dispatch parts exceed the sandbox proxy request cap even after path demotion" };
+  }
+  if (parts.length > maxParts) {
+    return { succeeded: false, error: `dispatch parts exceed the sidecar per-request cap of ${maxParts}` };
+  }
+  return { succeeded: true, value: parts };
+}
+
+// src/chat-routes/promote-file-part.ts
+var PROMOTE_MAX_FILE_BYTES = 10 * 1024 * 1024;
+var EXT_TO_MIME = {
+  md: "text/markdown",
+  markdown: "text/markdown",
+  txt: "text/plain",
+  log: "text/plain",
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  json: "application/json",
+  yaml: "text/yaml",
+  yml: "text/yaml",
+  xml: "application/xml",
+  html: "text/html",
+  htm: "text/html",
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  heic: "image/heic",
+  heif: "image/heif",
+  svg: "image/svg+xml",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  m4a: "audio/mp4",
+  aac: "audio/aac"
+};
+function sniffMimeFromName(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase();
+  if (!ext) return "text/plain";
+  return EXT_TO_MIME[ext] ?? "text/plain";
+}
+function sanitizeAttachmentFileName(name) {
+  const sanitized = name.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[.-]+/, "");
+  return sanitized || "file";
+}
+function base64ToBytes(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function parseDataUrl(url) {
+  const match = /^data:[^,]*,([\s\S]*)$/.exec(url);
+  if (!match) return null;
+  return { base64: /;base64,/i.test(url), data: match[1] ?? "" };
+}
+function dataUrlMime(url) {
+  if (!url) return void 0;
+  const match = /^data:([^;,]+)[;,]/.exec(url);
+  return match ? match[1] : void 0;
+}
+function basenameFromUrl(url) {
+  if (!url || url.startsWith("data:")) return void 0;
+  const withoutQuery = url.split(/[?#]/)[0] ?? url;
+  const segments = withoutQuery.split("/").filter(Boolean);
+  return segments[segments.length - 1] || void 0;
+}
+function resolveFileUrlPath(url) {
+  const withoutScheme = url.startsWith("file://") ? url.slice("file://".length) : url;
+  try {
+    return { succeeded: true, path: decodeURIComponent(withoutScheme) };
+  } catch (err) {
+    return { succeeded: false, reason: `malformed file path: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+function oversizeReason(filename, actual, limit) {
+  return `${filename} is ${formatBytes(actual)}; attachments are limited to ${formatBytes(limit)}`;
+}
+function resolveDataUrlBytes(url, filename, maxBytes) {
+  const parsed = parseDataUrl(url);
+  if (!parsed) return { succeeded: false, reason: "malformed data URI" };
+  let bytes;
+  try {
+    bytes = parsed.base64 ? base64ToBytes(parsed.data) : new TextEncoder().encode(decodeURIComponent(parsed.data));
+  } catch (err) {
+    return { succeeded: false, reason: `failed to decode data URI: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (bytes.byteLength > maxBytes) {
+    return { succeeded: false, reason: oversizeReason(filename, bytes.byteLength, maxBytes) };
+  }
+  return { succeeded: true, bytes };
+}
+async function resolveSandboxFileBytes(input) {
+  const stat = await statSandboxFileSize(input.box, input.path, { sessionId: input.sessionId });
+  if (!stat.succeeded) {
+    return { succeeded: false, reason: `could not stat agent file: ${stat.error}` };
+  }
+  if (stat.value > input.maxBytes) {
+    return { succeeded: false, reason: oversizeReason(input.filename, stat.value, input.maxBytes) };
+  }
+  const read = await readSandboxBinaryBytes(input.box, input.path, stat.value, { sessionId: input.sessionId });
+  if (!read.succeeded) {
+    return { succeeded: false, reason: `could not read agent file: ${read.error}` };
+  }
+  return { succeeded: true, bytes: read.value.bytes };
+}
+async function resolveBytes(input) {
+  const url = input.raw.url;
+  if (!url) return { succeeded: false, reason: "the file part carries no url" };
+  if (url.startsWith("data:")) return resolveDataUrlBytes(url, input.filename, input.maxBytes);
+  const isSandboxPath = url.startsWith("file://") || url.startsWith("/");
+  if (!isSandboxPath) return { succeeded: false, reason: `unsupported file URL scheme: ${url}` };
+  if (!input.box) return { succeeded: false, reason: "no sandbox to read agent file" };
+  const resolvedPath = resolveFileUrlPath(url);
+  if (!resolvedPath.succeeded) return resolvedPath;
+  return resolveSandboxFileBytes({
+    path: resolvedPath.path,
+    box: input.box,
+    sessionId: input.sessionId,
+    filename: input.filename,
+    maxBytes: input.maxBytes
+  });
+}
+async function hash8(seed) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(seed));
+  return Array.from(new Uint8Array(digest).slice(0, 4)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function defaultBuildAttachmentPath(args) {
+  const extensionMatch = /\.[A-Za-z0-9]+$/.exec(args.filename);
+  const extension = extensionMatch ? extensionMatch[0] : "";
+  const base = extension ? args.filename.slice(0, -extension.length) : args.filename;
+  return `uploads/agent/${args.date}/${base}-${args.hash8}${extension}`;
+}
+async function promoteAgentFilePart(options) {
+  const maxBytes = options.maxBytes ?? PROMOTE_MAX_FILE_BYTES;
+  const sniffMime = options.sniffMime ?? sniffMimeFromName;
+  const buildAttachmentPath = options.buildAttachmentPath ?? defaultBuildAttachmentPath;
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const filename = sanitizeAttachmentFileName(
+    options.raw.filename ?? basenameFromUrl(options.raw.url) ?? "agent-file"
+  );
+  const resolved = await resolveBytes({
+    raw: options.raw,
+    box: options.box,
+    sessionId: options.sessionId,
+    filename,
+    maxBytes
+  });
+  if (!resolved.succeeded) return { succeeded: false, filename, reason: resolved.reason };
+  const mediaType = options.raw.mediaType ?? options.raw.mime ?? dataUrlMime(options.raw.url) ?? sniffMime(filename);
+  const kind = attachmentKindForMime(mediaType);
+  const digest = await hash8(options.raw.id ?? options.raw.url ?? filename);
+  const date = now().toISOString().split("T")[0] ?? "";
+  const path = buildAttachmentPath({ filename, hash8: digest, date, mediaType, kind });
+  let written;
+  try {
+    written = await options.writeAttachment(options.scopeId, path, resolved.bytes, {
+      mediaType,
+      name: filename,
+      originalName: options.raw.filename ?? filename,
+      size: resolved.bytes.byteLength
+    });
+  } catch (err) {
+    return { succeeded: false, filename, reason: err instanceof Error ? err.message : String(err) };
+  }
+  if (!written.ok) return { succeeded: false, filename, reason: written.reason };
+  return {
+    succeeded: true,
+    part: {
+      type: kind,
+      path,
+      name: filename,
+      size: resolved.bytes.byteLength,
+      mediaType
+    }
+  };
+}
 export {
+  ATTACHMENT_MAX_COUNT,
   ChatTurnInputError,
   DEFAULT_STALE_TURN_LOCK_GRACE_MS,
   DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS,
+  DISPATCH_MAX_MEDIA_PARTS,
+  DISPATCH_MAX_PARTS,
+  DISPATCH_REQUEST_MAX_BYTES,
+  DISPATCH_STRUCTURAL_RESERVE_BYTES,
   INLINE_PARTS_MAX_BYTES,
+  MAX_ATTACHMENT_TOTAL_BYTES,
   MENTION_MAX_COUNT,
+  PROMOTE_MAX_FILE_BYTES,
   UPLOAD_INLINE_MAX_BYTES,
   UPLOAD_MAX_FILE_BYTES,
   assertPromptPartsWithinCap,
+  attachmentTotalSizeErrorMessage,
+  base64WireLen,
+  buildDispatchParts,
   buildMentionPromptBlock,
   bytesToBase64,
   chatTurnRequestInit,
@@ -949,14 +1354,19 @@ export {
   createSandboxChatProducer,
   createSandboxFileIndexRoute,
   createUploadRoute,
+  defaultValidateAttachmentPath,
   fileMentionsToParts,
+  formatBytes,
   mediaTypeForMentionPath,
   mentionKindForPath,
   parseChatTurnParts,
   parseFileMentions,
+  promoteAgentFilePart,
   promptPartsByteSize,
   reconcileStaleTurnLock,
+  resolveChatAttachments,
   sanitizeUploadFilename,
+  sniffMimeFromName,
   validateSandboxMentionPath,
   withDurableChatProjection
 };