@tangle-network/agent-app 0.43.50 → 0.43.52

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';
@@ -414,6 +414,82 @@ interface SandboxChatProducerOptions {
 }
 declare function createSandboxChatProducer(options: SandboxChatProducerOptions): ChatTurnRouteProducer;
 
+/**
+ * Detached (autonomous) turn → live buffer bridge.
+ *
+ * The interactive lane (`createChatTurnRoutes`) already streams a user-typed
+ * turn to the browser while it runs. An AUTONOMOUS turn — a mission step, a
+ * queue job, an inbound-email review — runs detached (`dispatchPrompt`/
+ * `streamPrompt` server-side so it survives no one watching) and, historically,
+ * only persisted its FINAL message. A browser opening the session mid-run saw a
+ * dead screen: the live tokens existed server-side but were never written to
+ * the turn-event buffer the client re-attach path (`listRunning` + `/replay`)
+ * reads.
+ *
+ * `runDetachedTurn` is that missing bridge, packaged. It taps the same buffer
+ * the interactive lane uses (`createBufferedTurnTap`) with the same producer
+ * mapping (`createSandboxChatProducer`), so an autonomous run is watchable
+ * token-by-token exactly like an interactive one — while staying durable
+ * (a durable driver re-invokes it after a crash; a completed turn short-circuits
+ * instead of re-streaming). Products supply only the domain seams: the raw
+ * sandbox event stream, the turn store, and the ids.
+ *
+ * This is app-shell mechanism (turn durability + live projection), not engine:
+ * it owns no loop logic and imports no SDK — the event source is an injected
+ * `AsyncIterable`.
+ */
+
+/** Authoritative final receipt for a turn whose live stream carried no usage
+ *  (some harness paths only expose tokens via the completed-turn record, e.g.
+ *  `box.findCompletedTurn(turnId)`). */
+interface DetachedTurnFinal {
+    text?: string;
+    usage?: ChatTurnUsage;
+}
+interface DetachedTurnOptions {
+    store: TurnEventStore;
+    turnId: string;
+    /** Thread/session id — recorded as the buffer scope so a browser opening the
+     *  session mid-run rediscovers this turn via `listRunning(scopeId)` after it
+     *  has lost the turnId. */
+    scopeId: string;
+    /** The raw sandbox event stream for this turn (e.g. `streamSandboxPrompt`).
+     *  Ownership of the box, prompt, tooling, and attachments stays with the
+     *  caller — this only projects the stream. */
+    events: AsyncIterable<unknown>;
+    /** Recorded on the persisted assistant message + usage receipt. */
+    model?: string;
+    /** Per-flush buffer coalescer. Default `coalesceDeltas`. */
+    coalesce?: (events: unknown[]) => unknown[];
+    /** Authoritative final receipt, consulted twice: (a) as the cached result
+     *  when the turn already completed (idempotent re-invoke), and (b) as a
+     *  fallback when a clean run's stream carried no usage/text. */
+    completedResult?: () => Promise<DetachedTurnFinal | null | undefined>;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface DetachedTurnResult {
+    /** `completed` — clean drain: persist + bill. `failed` — a terminal error
+     *  event or a thrown stream: skip billing, render an error row. */
+    state: 'completed' | 'failed';
+    text: string;
+    usage: ChatTurnUsage;
+    /** Present when `state === 'failed'`. */
+    error?: string;
+    /** True when the turn had already completed and this call returned the cached
+     *  result WITHOUT re-streaming (durable-driver retry after a crash). */
+    cached: boolean;
+}
+/**
+ * Stream a detached turn into the live turn-event buffer, durably.
+ *
+ * - Idempotent: an already-`complete` turn returns the cached result without
+ *   re-streaming (a second event sequence would collide with the buffered one).
+ * - Marks the turn `running` under `scopeId` so a mid-run browser finds it.
+ * - Settles `complete`/`error` so the client stops tailing and billing/render
+ *   can branch on `state`.
+ */
+declare function runDetachedTurn(opts: DetachedTurnOptions): Promise<DetachedTurnResult>;
+
 interface ChatRouteDurableProjection {
     observe(event: unknown): void | Promise<void>;
     materialize(): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>;
@@ -442,13 +518,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 +701,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 +738,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 +981,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 DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnResult, 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, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, withDurableChatProjection };