@tangle-network/agent-app 0.43.49 → 0.43.51

package/README.md

@@ -12,6 +12,7 @@ The substrate packages — `@tangle-network/agent-runtime`, `agent-eval`, `agent
 
 - **Structured tool side channel** — `submit_proposal` (approval-gated), `schedule_followup`, `render_ui`, `add_citation`, exposed as validated tool calls over three surfaces (HTTP route, per-turn MCP server, agent-runtime executor). No fenced-text parsing.
 - **Bounded tool loop** — `runAppToolLoop` / `streamAppToolLoop`: stream a turn → collect tool calls → dispatch → fold results back → re-run, capped. Substrate-free behind a `streamTurn` seam, so it drives a sandboxed agent, a Worker, or an in-browser copilot unchanged.
+- **Assembled chat vertical** — `createChatTurnRoutes` wires auth → thread/message store → streaming turn with buffered replay → uploads → sidecar question answering into one route factory, over `authorize` / `produce` / `store` / `interactions` seams. No hand-rolled orchestration. See [`examples/chat-app.md`](./examples/chat-app.md).
 - **Sandbox-optional** — the same tools, billing, eval, and loop work without a container. A `fetch`-only adapter maps any OpenAI-compatible stream (Tangle Router, tcloud) into the loop. See [`examples/browser-copilot.md`](./examples/browser-copilot.md).
 - **Resumable turns (sandbox-free path)** — for a browser/edge copilot streaming the Router directly, buffer a turn so a dropped tab loses nothing and a reconnecting client replays the tail. **Sandbox products don't need this** — the sandbox SDK already buffers + replays sessions (`streamPrompt` + `lastEventId`). See [`examples/resumable-turns.md`](./examples/resumable-turns.md).
 - **Composes the engine, never forks it** — `/eval` re-exports `@tangle-network/agent-eval`'s verifier; `/integrations` wraps the hub; `/tangle` and `/billing` take the tcloud client as a structural contract. Engines are **peer dependencies** — you pin the version, nothing is bundled.
@@ -96,6 +97,8 @@ const streamTurn = createOpenAICompatStreamTurn({ ...cfg, tools })
 
 The full three-transport walkthrough (Tangle Router, tcloud, Vercel AI SDK) is in [`examples/browser-copilot.md`](./examples/browser-copilot.md).
 
+Building the full **server chat vertical** instead — auth, thread/message tables, a streaming turn with buffered replay, uploads, and sidecar question answering — is the job of `createChatTurnRoutes` (`/chat-routes`) and the modules around it. The end-to-end assembly, including the durable plan/question workflow and the client composer, is in [`examples/chat-app.md`](./examples/chat-app.md).
+
 ## How it's organised
 
 One rule decides where anything lives:
@@ -128,6 +131,20 @@ Each is an independent entry point — import only what you use.
 | [`/stream`](src/stream) | SSE normalization and turn identity: `normalizeToolEvent`, `resolveChatTurn`, `encodeEvent`, message-part merging. |
 | [`/redact`](src/redact) | `redactForIngestion` — PII redaction before content leaves the boundary. |
 
+**The chat vertical** — the assembled server chat stack. Wire it with [`examples/chat-app.md`](./examples/chat-app.md).
+
+| Subpath | What it gives you |
+|---|---|
+| [`/chat-routes`](src/chat-routes) | `createChatTurnRoutes` — the assembled turn vertical: NDJSON `turn` + buffered `replay` + `running` reconnect-discovery + composed `interactions` answer endpoints, over `authorize` / `produce` / `store` seams. Plus `createSandboxChatProducer`, `createUploadRoute`, `createSandboxFileIndexRoute`, `withDurableChatProjection`, and the import-free `./wire` contract (`chatTurnRequestInit`, `ChatTurnRequestPayload`). Composes agent-runtime's `handleChatTurn`; subpath-only (not re-exported from the root). |
+| [`/chat-store`](src/chat-store) | `createChatTables` + `createChatStore` — drizzle thread/message persistence behind the `ChatStore` port, and the canonical `ChatMessagePart` parts vocabulary (`toChatMessageParts`, part guards). The drizzle store/schema is subpath-only. |
+| [`/interactions`](src/interactions) | Human-in-the-loop ask channel: `createInteractionAnswerRoute` (list/answer endpoint factory — validation, 410 mapping, duplicate-answer safety), the server sidecar client, and the shared `ChatInteraction` wire/persisted-part contract + codecs. Composes `@tangle-network/agent-interface` types. |
+| [`/durable-chat`](src/durable-chat) | Durable plan/question workflow around the authoritative channels: `createDurablePlanRoutes`, `createDurableChatScope`, `createDurableChatEventProjection`, `createDurableInteractionRoutePersistence`, the `DurablePlanStore` port, and `InMemoryDurableChatStateStore` (tests/demos only — production supplies the store). |
+| [`/plans`](src/plans) | Browser-safe durable-plan chat projection: `parsePlanSubmittedEvent`, `planToPersistedPart` / `persistedPartToPlan`, `canTransitionPlanStatus`, and the `ChatPlan` union. Byte-matches the SDK's `SandboxSession.plan()`. |
+| [`/object-store`](src/object-store) | Content-addressed durable attachment store: the `ObjectStore` port + `createR2ObjectStore`, `signObjectUrl` / `verifyObjectUrl`, `createProxiedArtifactRoute`, `objectKey`. |
+| [`/app-auth`](src/app-auth) | `createAppAuth` — better-auth config factory + request guards (`requireApiUser`) over the standard users/sessions/accounts/verifications tables; composes `/platform`'s SSO cookie minter. Optional `better-auth` peer; subpath-only. |
+| [`/sandbox`](src/sandbox) | Workspace sandbox provisioning + turn streaming: `ensureWorkspaceSandbox` / `peekWorkspaceSandbox`, `streamSandboxPrompt` / `runSandboxPrompt`, `createWorkspaceSandboxManager`, and terminal / runtime-proxy handlers. Peer `@tangle-network/sandbox`; subpath-only. |
+| [`/platform`](src/platform) | Tangle platform glue: cross-site SSO (`createTangleSsoHandlers`), request guards (`createAuthGuard`, `guardResolution`), the hub proxy, and seat billing. |
+
 The root entry (`@tangle-network/agent-app`) re-exports every module, but importing the subpath keeps your bundle to what you use.
 
 ### Missions: id shape and product columns

package/dist/assistant/index.d.ts

@@ -10,7 +10,7 @@ import '../flow-types-Cb_AblZs.js';
 import '../sandbox-terminal-BIIC__CP.js';
 import '../catalog/index.js';
 import '../harness/index.js';
-import '../file-index-b26ee-_R.js';
+import '../attachment-validation-DX2KIzMC.js';
 import '../stream-normalizer-DWvtmY6F.js';
 
 /**

package/dist/assistant/index.js

@@ -3,9 +3,9 @@ import {
   ChatMessages,
   ModelPicker,
   ProviderLogo
-} from "../chunk-O6H2WD3I.js";
+} from "../chunk-EIG7ZQW2.js";
 import "../chunk-65P3HJY3.js";
-import "../chunk-LCNY3DCM.js";
+import "../chunk-3EKOSBYL.js";
 import "../chunk-2QI7XV2T.js";
 import "../chunk-JGYOYY5D.js";
 import "../chunk-5MG74GVQ.js";

package/dist/attachment-validation-DX2KIzMC.d.ts

@@ -0,0 +1,219 @@
+import { K as FileMention } from './parts-IB-Kbb7z.js';
+
+/**
+ * `createSandboxFileIndexRoute` — server side of `@`-file-mentions
+ * (companion to sandbox-ui#184's composer mention primitive). Serves a flat,
+ * ignore-filtered listing of the workspace sandbox so `useFileMentions`
+ * (`/web-react`) can filter it client-side without a round trip per
+ * keystroke.
+ *
+ * Same seam style as `createUploadRoute`: `authorize({ request })` resolves a
+ * structural `{ tree(path, opts) }` handle (the shape of the sandbox SDK's
+ * `box.fs.tree`) — no SDK import here. `authorize` also carries the
+ * cold-box signal: a sandbox that isn't running yet answers `{ status:
+ * 'warming' }` directly, never provisions-and-waits inside this route.
+ *
+ * A box can also be running with its workspace root not yet materialised, which
+ * `authorize` cannot see; the route recognises that one signal off `fs.tree`
+ * and answers `warming` too, so every consumer gets the retry-and-wait state
+ * instead of a 500. Every other `tree()` failure propagates.
+ */
+
+/** One entry from a structural `tree()` scan. Mirrors the sandbox SDK's
+ *  `FileTreeFile` (`path`, `size`, `mtime`) — `mtime` is unused here so it's
+ *  omitted from the structural match. */
+interface SandboxTreeFile {
+    path: string;
+    size: number;
+}
+/** Structural match of the sandbox SDK's `box.fs.tree` result shape
+ *  (`FileTreeResult`). `stats.truncated` is the only stat this route reads;
+ *  the rest ride through unread on the real SDK type. */
+interface SandboxTreeResult {
+    root: string;
+    files: SandboxTreeFile[];
+    stats: {
+        truncated: boolean;
+    };
+}
+/** Structural match of the sandbox SDK's `box.fs` tree surface. */
+interface SandboxFileTreeSource {
+    tree(path: string, options?: {
+        maxDepth?: number;
+    }): Promise<SandboxTreeResult>;
+}
+interface FileIndexReadyResponse {
+    status: 'ready';
+    /** Workspace-relative entries. Same shape as `FileMention` (`./wire`) so a
+     *  client can hand a response entry straight to `fileMentionsToParts` /
+     *  `buildMentionPromptBlock` without remapping. */
+    files: FileMention[];
+    /** True when either the underlying scan truncated (SDK-side cap) or this
+     *  route's own `maxEntries` cap trimmed the filtered list. The client
+     *  should show "showing first N files" rather than imply completeness. */
+    truncated: boolean;
+    generatedAt: string;
+}
+/** Cold-box answer: no provisioning happened, no files were scanned. The
+ *  client shows a warming state and retries — this route never blocks on a
+ *  box coming up. Two situations produce it: `authorize` reporting a box that
+ *  is not running, and a running box whose workspace root does not exist yet
+ *  (see `isMissingRootError`). */
+interface FileIndexWarmingResponse {
+    status: 'warming';
+}
+type FileIndexResponse = FileIndexReadyResponse | FileIndexWarmingResponse;
+/** Short-TTL cache seam so repeat popover opens in the same session don't
+ *  re-scan the workspace. Host-provided (e.g. a KV binding); `key` is
+ *  whatever `authorize` returns as `cacheKey` — this route treats it opaquely. */
+interface FileIndexCache {
+    get(key: string): Promise<FileIndexReadyResponse | null> | FileIndexReadyResponse | null;
+    put(key: string, value: FileIndexReadyResponse, options?: {
+        ttlSeconds?: number;
+    }): Promise<void> | void;
+}
+type FileIndexAuthorization = {
+    status: 'ready';
+    /** Structural sandbox `fs` handle, usually `ensureWorkspaceSandbox(...)` → `box.fs`. */
+    fs: SandboxFileTreeSource;
+    /** Workspace root to index (e.g. `/home/agent`). */
+    root: string;
+    /** Extra ignore segments for this request, merged with the route's
+     *  defaults + `CreateSandboxFileIndexRouteOptions.ignore`. */
+    ignore?: string[];
+    /** Opaque cache key for the optional cache seam. Omit to skip caching
+     *  for this request (e.g. a workspace the host chooses not to cache). */
+    cacheKey?: string;
+} | {
+    status: 'warming';
+} | {
+    status: 'denied';
+    response: Response;
+};
+interface CreateSandboxFileIndexRouteOptions {
+    /** Authenticate the caller, resolve the sandbox `fs` handle, and signal a
+     *  cold box — never provisions or waits. */
+    authorize(args: {
+        request: Request;
+    }): Promise<FileIndexAuthorization>;
+    /** Extra ignore segments beyond the route's defaults (node_modules, .git,
+     *  dotfiles/dot-dirs, common build dirs). Matched as exact path-segment
+     *  names, same rule as the defaults. */
+    ignore?: string[];
+    /** Passed to `fs.tree` as `options.maxDepth`. Default 12. */
+    maxDepth?: number;
+    /** Hard cap on entries returned after filtering. Default 5000. */
+    maxEntries?: number;
+    /** Optional host-provided cache seam. */
+    cache?: FileIndexCache;
+    /** Cache TTL in seconds when `cache` is set. Default 20. */
+    cacheTtlSeconds?: number;
+}
+declare function createSandboxFileIndexRoute(options: CreateSandboxFileIndexRouteOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Content-based binary/text classification, shared by the attachment upload
+ * route (server) and the composer's client-side pre-validation (browser) —
+ * both sides must agree on what counts as binary before a byte ever leaves
+ * the client. Extension-based allowlists lie (a renamed `.docx`, a PNG saved
+ * as `.txt`), so classification reads the actual bytes: a magic-byte table
+ * for common binary formats first, then a UTF-8 decode attempt for
+ * everything else.
+ *
+ * Lifted near-verbatim from gtm-agent's `src/lib/binary-sniff.ts` (the
+ * source PRs hardened this against real corruption/gate bugs: gtm#584,
+ * gtm#592). Import-free by design — `/web-react` re-exports `/chat-routes`
+ * modules into browser bundles (`tests/browser-safe-subpaths.test.ts` walks
+ * the graph), so nothing here may reach a Node builtin or an engine package.
+ */
+interface SniffResult {
+    binary: boolean;
+    mime: string | null;
+}
+/** Decide whether uploaded bytes are binary or text, and identify the mime
+ *  type when it can be determined from content. Magic bytes are checked
+ *  first; anything unmatched falls back to a fatal UTF-8 decode. A NUL byte
+ *  or a decode failure means binary. Valid UTF-8 that is an SVG document is
+ *  binary (byte-identity matters for image tooling). Content that matches
+ *  nothing and does not decode as text is binary with an unknown mime —
+ *  extension-based guessing happens at the call site, not here. */
+declare function sniffBinary(bytes: Uint8Array): SniffResult;
+
+/**
+ * Shared attachment validation core — constants, type-gate, and filename
+ * sanitization used by BOTH the (server) attachment upload route and the
+ * (browser) composer's client-side pre-validation, so a rejection never
+ * differs depending on which side classified the bytes first.
+ *
+ * ≈ gtm-agent's `src/lib/attachment-limits.ts`, minus what agent-app already
+ * has (`ATTACHMENT_MAX_COUNT`/`MAX_ATTACHMENT_TOTAL_BYTES`/
+ * `attachmentTotalSizeErrorMessage` lived in `./resolve-attachments` and are
+ * re-homed here so the whole validation vocabulary — count cap, size caps,
+ * and type gate — has one address). Import-free besides `./wire`
+ * (`formatBytes`) and `./binary-sniff` (`SniffResult`): `/web-react`
+ * re-exports `/chat-routes` modules into browser bundles
+ * (`tests/browser-safe-subpaths.test.ts` walks the graph), so nothing here
+ * may reach a Node builtin or an engine package.
+ */
+
+/** Ceiling on a binary attachment's raw (pre-encoding) byte size. */
+declare const MAX_BINARY_ATTACHMENT_BYTES: number;
+/** Ceiling on a text attachment's raw byte size. Text hydrates through
+ *  inline prompt parts, a separate path that remains proxy-capped (see
+ *  `INLINE_PARTS_MAX_BYTES` in `./wire`). */
+declare const MAX_TEXT_ATTACHMENT_BYTES: number;
+/** Most files a single request may carry: the composer staging cap, the
+ *  upload route's per-request cap, and the chat body's `attachments` cap. */
+declare const ATTACHMENT_MAX_COUNT = 10;
+/** Aggregate raw-byte ceiling across one message's attachments. */
+declare const MAX_ATTACHMENT_TOTAL_BYTES: number;
+/**
+ * Accept list for the composer file picker + type validation, same grammar as
+ * the native `<input accept>` attribute. Images plus the text/doc types a
+ * product's store actually reads.
+ */
+declare const ATTACHMENT_ACCEPT = "image/*,.pdf,.txt,.md,.csv,.json,.yaml,.yml,.html";
+/** Sniffed-mime counterpart of `ATTACHMENT_ACCEPT`: the binary formats
+ *  `sniffBinary` can identify from magic bytes among the accepted types.
+ *  Values must match `sniffBinary`'s output strings verbatim, or every
+ *  upload of that format fails the type gate. */
+declare const ALLOWED_ATTACHMENT_SNIFFED_MIMES: ReadonlySet<string>;
+type AttachmentTypeCheckResult = {
+    succeeded: true;
+} | {
+    succeeded: false;
+    code: 'attachment_type_mismatch' | 'attachment_type_not_allowed';
+    message: string;
+};
+/**
+ * Cross-check a filename's extension against its sniffed content.
+ *
+ * Text content (`sniff.binary === false`) always passes here — it has no
+ * magic bytes to compare, so it rides the existing UTF-8 gate instead. For
+ * binary content: an extension with an unambiguous magic-byte family (e.g.
+ * `.pdf`) must match the sniffed mime, or the upload is a mismatch (a
+ * renamed file). Otherwise the sniffed mime must be one of `allowed`
+ * (default {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}), or the upload is
+ * rejected outright. The `allowed` param feeds a route's override seam (a
+ * product accepting a narrower or wider set than the default).
+ */
+declare function checkAttachmentType(fileName: string, sniff: SniffResult, allowed?: ReadonlySet<string>): AttachmentTypeCheckResult;
+/**
+ * Rewrite a filename into the store-path charset (`A-Za-z0-9._-` per
+ * segment) — attachment paths double as store keys, sandbox file paths, and
+ * in-message path references, none of which tolerate spaces or punctuation.
+ * Runs of unsupported characters collapse to one `-`; leading dots/dashes are
+ * stripped so the name can't read as a hidden segment. The original name is
+ * preserved separately (the returned `ChatAttachmentInput.name`), so
+ * sanitization loses nothing.
+ */
+declare function sanitizeAttachmentFileName(name: string): string;
+/** Human-readable error naming both the actual size and the limit that was
+ *  exceeded. Shared so the server route and the composer pre-check report
+ *  the same message shape. */
+declare function attachmentSizeErrorMessage(name: string, actualBytes: number, limitBytes: number): string;
+/** Human-readable error for a chat message whose combined attachments exceed
+ *  the aggregate raw-byte ceiling. */
+declare function attachmentTotalSizeErrorMessage(totalBytes: number, limitBytes: number): string;
+
+export { ALLOWED_ATTACHMENT_SNIFFED_MIMES as A, type CreateSandboxFileIndexRouteOptions as C, type FileIndexAuthorization as F, MAX_ATTACHMENT_TOTAL_BYTES as M, type SandboxFileTreeSource as S, ATTACHMENT_ACCEPT as a, ATTACHMENT_MAX_COUNT as b, type AttachmentTypeCheckResult as c, type FileIndexCache as d, type FileIndexReadyResponse as e, type FileIndexResponse as f, type FileIndexWarmingResponse as g, MAX_BINARY_ATTACHMENT_BYTES as h, MAX_TEXT_ATTACHMENT_BYTES as i, type SandboxTreeFile as j, type SandboxTreeResult as k, type SniffResult as l, attachmentSizeErrorMessage as m, attachmentTotalSizeErrorMessage as n, checkAttachmentType as o, createSandboxFileIndexRoute as p, sniffBinary as q, sanitizeAttachmentFileName as s };

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

@@ -1,12 +1,12 @@
-import { L as ChatTurnRequestPayload, M as ChatTurnPartInput, g as ChatMessagePart, N as ChatTurnFilePartInput, a as ChatAttachmentPart, f as ChatMentionPart, C as ChatAttachmentKind } from '../parts-IB-Kbb7z.js';
+import { L as ChatTurnRequestPayload, M as ChatTurnPartInput, g as ChatMessagePart, N as ChatTurnFilePartInput, a as ChatAttachmentPart, C as ChatAttachmentKind, f as ChatMentionPart } from '../parts-IB-Kbb7z.js';
 export { O as ChatAttachmentInput, e as ChatMentionKind, P as ChatTurnInputError, Q as ChatTurnTextPartInput, R as DISPATCH_MAX_MEDIA_PARTS, T as DISPATCH_MAX_PARTS, U as DISPATCH_REQUEST_MAX_BYTES, V as DISPATCH_STRUCTURAL_RESERVE_BYTES, K as FileMention, W as FileMentionsToPartsOptions, X as INLINE_PARTS_MAX_BYTES, Y as MENTION_MAX_COUNT, Z as SandboxMentionPathCheck, _ as assertPromptPartsWithinCap, $ as base64WireLen, a0 as buildMentionPromptBlock, a1 as chatTurnRequestInit, a2 as fileMentionsToParts, a3 as formatBytes, a4 as mediaTypeForMentionPath, a5 as mentionKindForPath, a6 as parseChatTurnParts, a7 as parseFileMentions, a8 as promptPartsByteSize, a9 as validateSandboxMentionPath } from '../parts-IB-Kbb7z.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-DX2KIzMC.js';
 import { ChatTurnIdentity, ChatTurnProducer } from '@tangle-network/agent-runtime';
 import { InteractionAnswerRoute, InteractionAnswerRouteOptions } from '../interactions/index.js';
 import { PersistedChatMessageForTurn } from '../stream/index.js';
 import { d as TurnEventStore } from '../turn-buffer-C9mEgoop.js';
 export { D as DEFAULT_STALE_TURN_LOCK_GRACE_MS, a as DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS, R as ReconcileStaleTurnLockOptions, b as ReconcileStaleTurnLockResult, S as StaleTurnLockSandboxProbeResult, c as StaleTurnLockSessionProbeResult, r as reconcileStaleTurnLock } from '../stale-turn-lock-C8Na1cFZ.js';
 import { J as JsonRecord } from '../stream-normalizer-DWvtmY6F.js';
-export { C as CreateSandboxFileIndexRouteOptions, F as FileIndexAuthorization, a as FileIndexCache, b as FileIndexReadyResponse, c as FileIndexResponse, d as FileIndexWarmingResponse, S as SandboxFileTreeSource, e as SandboxTreeFile, f as SandboxTreeResult, g as createSandboxFileIndexRoute } from '../file-index-b26ee-_R.js';
 import { SandboxExecChannel, PromptInputPart } from '../sandbox/index.js';
 import '@tangle-network/agent-interface';
 import '../contract-KfqJh_au.js';
@@ -442,13 +442,16 @@ declare function withDurableChatProjection(producer: ChatTurnRouteProducer, proj
  * The sink is structural (no sandbox-SDK import); products pass `box.fs`.
  *
  * @remarks Sole consumer today is the `--chat` scaffold (`create-agent-app
- * --chat` → `template-chat/src/chat.ts`), the reference multimodal path. The
- * fleet apps (gtm/tax/legal/insurance) each keep their OWN upload route into a
- * durable vault (KV, or AES-GCM-encrypted R2) — a different persistence model
- * from this route's inline-`data:`-or-ephemeral-sandbox-workspace split, so
- * they don't (and shouldn't) route through it. This stays the scaffold's proven
- * upload pattern, not a fleet primitive; keep that distinction in mind before
- * widening its surface.
+ * --chat` → `template-chat/src/chat.ts`), the reference multimodal path — its
+ * inline-`data:`-or-ephemeral-sandbox-workspace split stays the scaffold's
+ * proven upload pattern, not a fleet primitive; keep that distinction in mind
+ * before widening its surface. Fleet apps with a durable store of their own
+ * (KV, or AES-GCM-encrypted R2) no longer need to hand-roll a vault upload
+ * route: `createAttachmentUploadRoute` (`./attachment-upload`, agent-app#234)
+ * is the shared hardened path for that persistence model — a content-sniffed
+ * type gate, two-phase atomic batch writes, and per-kind/aggregate size caps,
+ * all seamed through an injected `WriteAttachmentFn`. Point readers there
+ * instead of widening this route to cover both models.
  */
 
 /** 700 KiB: base64 inflates ~4/3, so an inline part stays comfortably under
@@ -622,16 +625,6 @@ type AttachmentPathCheck = {
     succeeded: false;
     error: string;
 };
-/** Most files a single request may carry. */
-declare const ATTACHMENT_MAX_COUNT = 10;
-/** Aggregate raw-byte ceiling across one message's attachments. */
-declare const MAX_ATTACHMENT_TOTAL_BYTES: number;
-/** Human-readable error for a message whose combined attachments exceed the
- *  aggregate raw-byte ceiling. Ported to match gtm's `attachmentTotalSizeErrorMessage`
- *  (attachment-limits.ts:93-95) verbatim, via the shared {@link formatBytes} —
- *  e.g. "Attachments total 25MB; each message is limited to 25MB", not raw
- *  byte counts. */
-declare function attachmentTotalSizeErrorMessage(totalBytes: number, limitBytes: number): string;
 /**
  * Default path validator when a caller supplies none. Rejects the ways a path
  * picked in a client can escape the store root — traversal (`..` segment),
@@ -669,6 +662,83 @@ interface ResolveChatAttachmentsOptions {
  */
 declare function resolveChatAttachments(value: unknown, options: ResolveChatAttachmentsOptions): Promise<ResolveChatAttachmentsResult>;
 
+/**
+ * `createAttachmentUploadRoute` — the fleet-primitive durable-store upload
+ * route: a two-phase atomic batch (every file is validated before any file is
+ * written — a batch never partially lands), a content-sniffed type gate
+ * (`checkAttachmentType` over `sniffBinary`'s magic-byte read, not the
+ * extension or the browser-reported MIME), per-kind + aggregate byte caps,
+ * and sanitized filenames. Storage is fully seamed through the injected
+ * `WriteAttachmentFn` (`./attachment-store`) — no default store, the product
+ * owns where bytes actually live (vault, object store, …) — and auth/rate
+ * limiting is entirely the injected `authorize` seam's job: this factory
+ * never invents a 401 or 429 response, it only returns `auth.response`
+ * verbatim on failure.
+ *
+ * Lifted from gtm-agent's `src/routes/api.vault.upload.ts` (the hardening
+ * lineage other lifted modules in this vertical cite: gtm#584 binary
+ * corruption, gtm#592 sniff gate/caps, gtm#593 batch-atomic writes) and
+ * generalized the way `resolve-attachments.ts` generalized gtm's read path —
+ * the vault-specific pieces (KV vault paths, frontmatter, per-user rate
+ * limiting) are all injected seams here, while the validate-then-write phase
+ * split and the type/size gate ordering survive byte-for-byte.
+ *
+ * @remarks Sibling to, NOT an extension of, `./upload.ts`'s
+ * `createUploadRoute` — a different persistence model (durable product store
+ * vs. inline-`data:`-or-ephemeral-sandbox-workspace). See that module's doc
+ * comment for the up-to-date framing between the two.
+ */
+
+/** Outcome of the injected `authorize` seam: auth + rate limiting +
+ *  scope resolution, all in one place so a 429 rides `{ok:false, response}`
+ *  exactly like a 401 does — this factory has no rate-limit opinion of its
+ *  own. `writeAttachment` lets a single request override the option-level
+ *  store (e.g. routing per-tenant), defaulting to `options.writeAttachment`
+ *  when absent. */
+type AttachmentUploadAuthorization = {
+    ok: true;
+    scopeId: string;
+    writeAttachment?: WriteAttachmentFn;
+} | {
+    ok: false;
+    response: Response;
+};
+interface CreateAttachmentUploadRouteOptions {
+    /** Authenticate the caller, rate-limit, and resolve the store scope
+     *  (workspace/tenant id) — never a query param. */
+    authorize(args: {
+        request: Request;
+    }): Promise<AttachmentUploadAuthorization>;
+    /** Default store writer. `authorize` may override it per-request. */
+    writeAttachment: WriteAttachmentFn;
+    /** Overridable caps. Defaults come from `./attachment-validation`. */
+    limits?: {
+        /** Most files one request may carry. Default {@link ATTACHMENT_MAX_COUNT}. */
+        maxCount?: number;
+        /** Ceiling on a binary file's raw size. Default {@link MAX_BINARY_ATTACHMENT_BYTES}. */
+        maxBinaryBytes?: number;
+        /** Ceiling on a text file's raw size. Default {@link MAX_TEXT_ATTACHMENT_BYTES}. */
+        maxTextBytes?: number;
+        /** Aggregate raw-byte ceiling across the batch. Default {@link MAX_ATTACHMENT_TOTAL_BYTES}. */
+        maxTotalBytes?: number;
+    };
+    /** Attachment kinds this route accepts. Default `['image', 'file']`. */
+    allowedKinds?: ChatAttachmentKind[];
+    /** Sniffed-mime allowlist fed to `checkAttachmentType`. Default
+     *  {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}. */
+    allowedSniffedMimes?: ReadonlySet<string>;
+    /** Sanitized-name → store path. Default identity (the sanitized name IS
+     *  the path); gtm passes `vaultFolderForFileName`, a tenant product a
+     *  scope prefix. */
+    pathFor?: (name: string) => string;
+    /** Store-path validator. Default {@link defaultValidateAttachmentPath}. */
+    validatePath?: (path: string) => AttachmentPathCheck;
+    /** Last-resort media-type hook for text content the sniffer can't type.
+     *  Default {@link sniffMimeFromName}. */
+    sniffMime?: (name: string) => string;
+}
+declare function createAttachmentUploadRoute(options: CreateAttachmentUploadRouteOptions): (request: Request) => Promise<Response>;
+
 /**
  * `buildDispatchParts` — assemble the `PromptInputPart[]` a turn carrying
  * attachments and/or `@`-mentions dispatches to the sandbox. `parts[0]` is
@@ -835,4 +905,4 @@ interface PromoteAgentFilePartOptions {
 }
 declare function promoteAgentFilePart(options: PromoteAgentFilePartOptions): Promise<PromoteFilePartResult>;
 
-export { ATTACHMENT_MAX_COUNT, type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DispatchPartsOutcome, type FilePartPromotionOutcome, MAX_ATTACHMENT_TOTAL_BYTES, 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, attachmentTotalSizeErrorMessage, buildDispatchParts, bytesToBase64, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, promoteAgentFilePart, resolveChatAttachments, sanitizeUploadFilename, sniffMimeFromName, withDurableChatProjection };
+export { type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentUploadAuthorization, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DispatchPartsOutcome, type FilePartPromotionOutcome, 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, buildDispatchParts, bytesToBase64, createAttachmentUploadRoute, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, promoteAgentFilePart, resolveChatAttachments, sanitizeUploadFilename, sniffMimeFromName, withDurableChatProjection };