@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/chat-react/entry-composer.d.ts

@@ -0,0 +1,92 @@
+import { type ReactNode } from 'react';
+import { AgentComposer } from '@tangle-network/sandbox-ui/chat';
+import type { UseFileMentionsResult } from '../web-react/use-file-mentions';
+import type { ChatAttachmentInput, FileMention } from '../chat-routes/wire';
+import { type AgentSessionControlsProps } from '../web-react/agent-session-controls';
+import type { ComposerPlanModeSelection } from './types';
+export interface EntryComposerProps {
+    /** The one line above the input. Domain copy — always a product parameter. */
+    heading?: ReactNode;
+    /** Optional supporting line under the heading. */
+    subheading?: ReactNode;
+    placeholder?: string;
+    initialValue?: string;
+    sendLabel?: string;
+    disabled?: boolean;
+    /**
+     * Agent identity (backend/model/effort). Pass it and the control row renders;
+     * omit it and the composer ships without one. Omitting is a real choice for a
+     * surface with nothing to choose — it should never be an oversight, which is
+     * why this is one prop rather than a free-form slot a caller can forget.
+     *
+     * This is the CANONICAL picker cluster: `AgentSessionControls` from
+     * `/web-react` (its model menu IS the canonical `ModelPicker`). The legacy
+     * sandbox-ui adapter that used to back this prop was removed; the props
+     * mapping for migrating a stored selection lives in
+     * `docs/ui-picker-canon.md`.
+     */
+    agent?: AgentSessionControlsProps;
+    /**
+     * Product-specific behavioral controls docked on the LEFT. A mode is an
+     * on/off switch, not a value picker, so it sits apart from agent identity.
+     * For the standard plan-approval control, prefer `planMode`.
+     */
+    modes?: ReactNode;
+    /**
+     * Standard plan-approval mode. Pass only when the selected backend supports
+     * it; omitted means the control is not rendered.
+     */
+    planMode?: ComposerPlanModeSelection;
+    /**
+     * Upload endpoint for staged attachments. Omit and the attach affordance is
+     * hidden — a composer with no place to put a file must not offer one.
+     */
+    uploadUrl?: string;
+    accept?: string;
+    onAttachmentError?: (reason: string) => void;
+    onRejectFiles?: Parameters<typeof AgentComposer>[0]['onRejectFiles'];
+    /**
+     * `@`-file mentions. The hook itself is shared (`useFileMentions`), but the
+     * cold-box policy around it — whether pressing `@` is worth starting a
+     * sandbox — is a per-surface product call, so the result is injected rather
+     * than created here.
+     */
+    mentions?: UseFileMentionsResult;
+    mentionPopoverClassName?: string;
+    /** Rendered under the composer: suggestion pills, an onboarding nudge, a
+     *  disclaimer. All domain copy. */
+    footer?: ReactNode;
+    /** Block submit until a persisted selection has resolved against the catalog,
+     *  so the first turn cannot go out under the wrong model. Defaults to true. */
+    ready?: boolean;
+    onSubmit: (prompt: string, attachments: ChatAttachmentInput[], mentions: FileMention[]) => void;
+    className?: string;
+    composerClassName?: string;
+    /** Max width of the centered column. Defaults to the fleet's 820px. */
+    maxWidth?: number;
+}
+/**
+ * `EntryComposer` — the centered "what do you want to work on?" surface a
+ * product shows before a conversation exists (a new thread, an empty session,
+ * a workspace overview).
+ *
+ * It exists because three products each grew their own, and they drifted into
+ * three different capability sets rather than three different looks: one lost
+ * the attach button, one lost the model and effort pickers entirely, one
+ * hand-rolled a `<textarea>` and wired pickers from three separate packages
+ * into one row. The composer, the pickers, the attachment queue and the mention
+ * index were all ALREADY shared — what was not shared was the assembly, so
+ * every product re-derived which controls an entry surface gets, and each
+ * re-derivation dropped a different one.
+ *
+ * Mechanism lives here: layout, the attachment queue, the mention wiring, the
+ * submit gate (nothing sends while an upload is pending or failed, or before
+ * the model selection has resolved). Domain stays a parameter: `heading`,
+ * `placeholder`, `footer` (suggestion pills, disclaimers) and the selections
+ * themselves.
+ *
+ * The docked in-thread composer is NOT this component — it renders
+ * `AgentComposer` directly with the same canonical `AgentSessionControls`,
+ * because a docked composer has a transcript above it and no hero layout.
+ */
+export declare function EntryComposer({ heading, subheading, placeholder, initialValue, sendLabel, disabled, agent, modes, planMode, uploadUrl, accept, onAttachmentError, onRejectFiles, mentions, mentionPopoverClassName, footer, ready, onSubmit, className, composerClassName, maxWidth, }: EntryComposerProps): import("react").JSX.Element;

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

@@ -1,123 +1,27 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { AgentComposer } from '@tangle-network/sandbox-ui/chat';
-import { A as AgentSessionControlsProps, U as UseFileMentionsResult } from '../agent-session-controls-CmlXwp_H.js';
-import { b as ChatAttachmentInput, F as FileMention } from '../wire-DOZ-O6hD.js';
-import '../harness/index.js';
-import '@tangle-network/agent-interface';
-import '../catalog/index.js';
-
 /**
- * The plan-mode toggle state an entry surface docks beside the composer. The
- * agent-identity pickers (model / harness / effort) speak the canonical
- * `AgentSessionControls` vocabulary from `../web-react` — see "UI chrome
- * ownership (picker canon)" in AGENTS.md.
- */
-interface ComposerPlanModeSelection {
-    enabled: boolean;
-    setEnabled: (next: boolean) => void;
-    saving?: boolean;
-}
-
-interface EntryComposerProps {
-    /** The one line above the input. Domain copy — always a product parameter. */
-    heading?: ReactNode;
-    /** Optional supporting line under the heading. */
-    subheading?: ReactNode;
-    placeholder?: string;
-    initialValue?: string;
-    sendLabel?: string;
-    disabled?: boolean;
-    /**
-     * Agent identity (backend/model/effort). Pass it and the control row renders;
-     * omit it and the composer ships without one. Omitting is a real choice for a
-     * surface with nothing to choose — it should never be an oversight, which is
-     * why this is one prop rather than a free-form slot a caller can forget.
-     *
-     * This is the CANONICAL picker cluster: `AgentSessionControls` from
-     * `/web-react` (its model menu IS the canonical `ModelPicker`). The legacy
-     * sandbox-ui adapter that used to back this prop was removed; the props
-     * mapping for migrating a stored selection lives in
-     * `docs/ui-picker-canon.md`.
-     */
-    agent?: AgentSessionControlsProps;
-    /**
-     * Product-specific behavioral controls docked on the LEFT. A mode is an
-     * on/off switch, not a value picker, so it sits apart from agent identity.
-     * For the standard plan-approval control, prefer `planMode`.
-     */
-    modes?: ReactNode;
-    /**
-     * Standard plan-approval mode. Pass only when the selected backend supports
-     * it; omitted means the control is not rendered.
-     */
-    planMode?: ComposerPlanModeSelection;
-    /**
-     * Upload endpoint for staged attachments. Omit and the attach affordance is
-     * hidden — a composer with no place to put a file must not offer one.
-     */
-    uploadUrl?: string;
-    accept?: string;
-    onAttachmentError?: (reason: string) => void;
-    onRejectFiles?: Parameters<typeof AgentComposer>[0]['onRejectFiles'];
-    /**
-     * `@`-file mentions. The hook itself is shared (`useFileMentions`), but the
-     * cold-box policy around it — whether pressing `@` is worth starting a
-     * sandbox — is a per-surface product call, so the result is injected rather
-     * than created here.
-     */
-    mentions?: UseFileMentionsResult;
-    mentionPopoverClassName?: string;
-    /** Rendered under the composer: suggestion pills, an onboarding nudge, a
-     *  disclaimer. All domain copy. */
-    footer?: ReactNode;
-    /** Block submit until a persisted selection has resolved against the catalog,
-     *  so the first turn cannot go out under the wrong model. Defaults to true. */
-    ready?: boolean;
-    onSubmit: (prompt: string, attachments: ChatAttachmentInput[], mentions: FileMention[]) => void;
-    className?: string;
-    composerClassName?: string;
-    /** Max width of the centered column. Defaults to the fleet's 820px. */
-    maxWidth?: number;
-}
-/**
- * `EntryComposer` — the centered "what do you want to work on?" surface a
- * product shows before a conversation exists (a new thread, an empty session,
- * a workspace overview).
+ * `@tangle-network/agent-app/chat-react` — the chat-composer surfaces that need
+ * `@tangle-network/sandbox-ui`.
  *
- * It exists because three products each grew their own, and they drifted into
- * three different capability sets rather than three different looks: one lost
- * the attach button, one lost the model and effort pickers entirely, one
- * hand-rolled a `<textarea>` and wired pickers from three separate packages
- * into one row. The composer, the pickers, the attachment queue and the mention
- * index were all ALREADY shared — what was not shared was the assembly, so
- * every product re-derived which controls an entry surface gets, and each
- * re-derivation dropped a different one.
+ * Isolated behind its own entry for the OPTIONAL-PEER rule: sandbox-ui is an
+ * optional peer of this package, so a subpath that imports it must never be
+ * reachable from one that does not. `/web-react` stays sandbox-ui-free; anything
+ * that renders sandbox-ui's `AgentComposer` lives here. (Same rule, same shape
+ * as `/work-product-react`.)
  *
- * Mechanism lives here: layout, the attachment queue, the mention wiring, the
- * submit gate (nothing sends while an upload is pending or failed, or before
- * the model selection has resolved). Domain stays a parameter: `heading`,
- * `placeholder`, `footer` (suggestion pills, disclaimers) and the selections
- * themselves.
+ * WHY THIS EXISTS. sandbox-ui owns the composer chrome; this subpath owns the
+ * app-shell ASSEMBLY over it — which controls an entry surface gets, the
+ * submit gate. Three products each re-derived that assembly and each dropped a
+ * different control, so the same "shared" components produced three different
+ * capability sets. One assembly, three products, domain by parameter.
  *
- * The docked in-thread composer is NOT this component — it renders
- * `AgentComposer` directly with the same canonical `AgentSessionControls`,
- * because a docked composer has a transcript above it and no hero layout.
- */
-declare function EntryComposer({ heading, subheading, placeholder, initialValue, sendLabel, disabled, agent, modes, planMode, uploadUrl, accept, onAttachmentError, onRejectFiles, mentions, mentionPopoverClassName, footer, ready, onSubmit, className, composerClassName, maxWidth, }: EntryComposerProps): react.JSX.Element;
-
-interface ComposerModeControlsProps {
-    /**
-     * Plan-approval mode. Products pass it only when the selected backend can
-     * propose a plan and wait for approval; omitted means nothing renders.
-     */
-    planMode?: ComposerPlanModeSelection;
-}
-/**
- * The shared plan-mode toggle for the left side of an agent composer.
- * Plan mode is a behavioral switch, not part of the profile/backend/model/
- * thinking identity controls on the right.
+ * PICKER CANON. The agent-identity controls an `EntryComposer` renders are the
+ * canonical ones: its `agent` prop is `AgentSessionControlsProps` and the row
+ * is `/web-react`'s `AgentSessionControls`, whose model menu IS the canonical
+ * `ModelPicker` — see "UI chrome ownership (picker canon)" in AGENTS.md and
+ * `docs/ui-picker-canon.md`. The legacy `ComposerAgentControls` adapter over
+ * sandbox-ui's strip was REMOVED (it was deprecated-first); products still on
+ * it migrate per the props mapping in that doc.
  */
-declare function ComposerModeControls({ planMode }: ComposerModeControlsProps): react.JSX.Element | null;
-
-export { ComposerModeControls, type ComposerModeControlsProps, type ComposerPlanModeSelection, EntryComposer, type EntryComposerProps };
+export { EntryComposer, type EntryComposerProps } from './entry-composer';
+export { ComposerModeControls, type ComposerModeControlsProps, } from './composer-mode-controls';
+export type { ComposerPlanModeSelection } from './types';

package/dist/chat-react/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The plan-mode toggle state an entry surface docks beside the composer. The
+ * agent-identity pickers (model / harness / effort) speak the canonical
+ * `AgentSessionControls` vocabulary from `../web-react` — see "UI chrome
+ * ownership (picker canon)" in AGENTS.md.
+ */
+export interface ComposerPlanModeSelection {
+    enabled: boolean;
+    setEnabled: (next: boolean) => void;
+    saving?: boolean;
+}

package/dist/chat-routes/attachment-store.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Storage seams for the chat-attachment vertical (`resolveChatAttachments`,
+ * `buildDispatchParts`, `promoteAgentFilePart`). Structural function ports in
+ * the same style as `upload.ts`'s `SandboxUploadSink`: REQUIRED injection, no
+ * default implementation — agent-app owns the size/budget/idempotency
+ * mechanism, the product owns where the bytes actually live.
+ *
+ * One reader, two callers: `resolveChatAttachments` reads only the
+ * authoritative `size` (never trusting the client-reported size), while
+ * `buildDispatchParts` reads the inline `content` (base64 or raw bytes) to
+ * build a `data:` URI. Both fit behind ONE `ReadAttachmentFn` so a product
+ * wires a single vault/object-store adapter, not two. gtm's KV vault (stores
+ * base64 bodies) and `/object-store`'s `ObjectStore` (hands back raw bytes)
+ * both satisfy this shape.
+ */
+/**
+ * The result of reading one stored attachment. `ok:true` MUST carry the
+ * authoritative decoded byte `size` (the cap is meaningless against a
+ * client-controlled number) and, when the caller needs to inline the file,
+ * its content as `base64` and/or raw `bytes`. `mediaType` is the stored
+ * content type when the store knows it (used as the fallback when the wire
+ * part carried none). `ok:false` carries a human `reason` that SHOULD name the
+ * offending path — it is surfaced verbatim in the caller's typed outcome.
+ */
+export type AttachmentReadResult = {
+    ok: true;
+    /** Authoritative decoded byte length of the stored content. */
+    size: number;
+    /** Inline content as base64 — reused verbatim for a `data:` URI, so a
+     *  store holding already-base64 bodies never decodes-and-re-encodes. */
+    base64?: string;
+    /** Inline content as raw bytes — base64-encoded by the caller when a
+     *  `data:` URI is needed. Ignored when `base64` is present. */
+    bytes?: Uint8Array;
+    /** Stored content type, when the store tracks one. */
+    mediaType?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read one stored attachment for `scopeId` (the product's workspace/tenant
+ * key) at its store-relative `path`. Missing, deleted, or unreadable content
+ * MUST resolve to `{ ok: false, reason }`, never throw — a store failure is a
+ * per-attachment outcome the caller folds into its own typed result, not a
+ * turn-level exception.
+ */
+export type ReadAttachmentFn = (scopeId: string, path: string) => Promise<AttachmentReadResult>;
+/** Outcome of persisting one attachment. Mirrors `AttachmentReadResult`'s
+ *  `ok`/`reason` shape and `upload.ts`'s `{ ok }` convention. */
+export type AttachmentWriteResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Persist `content` for `scopeId` at `path`. `content` is either raw `bytes`
+ * or a base64 `string` — a string argument is ALWAYS base64 (never utf8), so
+ * a store that speaks base64 (gtm's vault) writes it verbatim and one that
+ * speaks bytes decodes once. Like the reader, failures resolve to
+ * `{ ok: false, reason }` rather than throwing.
+ *
+ * `opts` mirrors the vault frontmatter gtm's `writeAttachmentVaultFile`
+ * persists alongside the body (promote-file-parts.ts:181-190), so a product
+ * reimplementing that vault writer through this seam can reproduce it
+ * exactly:
+ * - `mediaType` — the resolved MIME type; gtm's frontmatter key `mime`.
+ * - `name` — the sanitized (store-path-safe) display filename; gtm passes
+ *   this only to shape its oversize message, not into frontmatter.
+ * - `originalName` — the filename as the harness/browser reported it, BEFORE
+ *   sanitization (`raw.filename ?? filename` — falls back to the sanitized
+ *   name when the source carried none); gtm's frontmatter key `originalName`.
+ *   This is the one field with no other recovery path once sanitization has
+ *   run, so it must ride the write, not be re-derived after the fact.
+ * - `size` — the authoritative decoded byte length being written; gtm's
+ *   frontmatter key `size`.
+ */
+export type WriteAttachmentFn = (scopeId: string, path: string, content: Uint8Array | string, opts: {
+    mediaType?: string;
+    name?: string;
+    originalName?: string;
+    size?: number;
+}) => Promise<AttachmentWriteResult>;

package/dist/chat-routes/attachment-upload.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `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.
+ */
+import type { ChatAttachmentKind } from './wire';
+import type { WriteAttachmentFn } from './attachment-store';
+import { type AttachmentPathCheck } from './resolve-attachments';
+/** 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. */
+export type AttachmentUploadAuthorization = {
+    ok: true;
+    scopeId: string;
+    writeAttachment?: WriteAttachmentFn;
+} | {
+    ok: false;
+    response: Response;
+};
+/** Define options to authorize, write, and limit attachment uploads in a route */
+export 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}. Narrow it to accept less than
+     *  the default (`new Set(['application/pdf'])`), or widen it to accept a
+     *  format the default refuses — macro-enabled Office packages are the
+     *  shipped case:
+     *  `new Set([...ALLOWED_ATTACHMENT_SNIFFED_MIMES, ...MACRO_ENABLED_OOXML_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;
+}
+/** Resolve an attachment upload route handler with customizable limits and validation options */
+export declare function createAttachmentUploadRoute(options: CreateAttachmentUploadRouteOptions): (request: Request) => Promise<Response>;

package/dist/chat-routes/attachment-validation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+import type { SniffResult } from './binary-sniff';
+/** Ceiling on a binary attachment's raw (pre-encoding) byte size. */
+export 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`). */
+export 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. */
+export declare const ATTACHMENT_MAX_COUNT = 10;
+/** Aggregate raw-byte ceiling across one message's attachments. */
+export 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.
+ *
+ * Every extension here is one the default {@link ALLOWED_ATTACHMENT_SNIFFED_MIMES}
+ * actually admits — a picker that offers a format the gate then rejects is a
+ * defect, so `tests/chat-routes/attachment-validation.test.ts` walks this
+ * string and proves each entry uploads.
+ */
+export declare const ATTACHMENT_ACCEPT = "image/*,.pdf,.docx,.xlsx,.pptx,.txt,.md,.csv,.json,.yaml,.yml,.html";
+/** The Office (OOXML) package mimes the default allow-list admits — the
+ *  formats professionals actually send: Word contracts, Excel workpapers,
+ *  PowerPoint decks. Admitting the format is a gate decision only; whether a
+ *  product can EXTRACT text from one is that product's concern. */
+export declare const OOXML_SNIFFED_MIMES: ReadonlySet<string>;
+/** Macro-enabled Office package mimes (`.docm`/`.xlsm`/`.pptm`), reported by
+ *  `sniffBinary` but deliberately NOT in the default allow-list: a package
+ *  carrying a VBA project is a different risk decision than a plain document,
+ *  and it is the product's to make. Opt in by widening the allow-list at the
+ *  route's `allowedSniffedMimes` seam:
+ *  `new Set([...ALLOWED_ATTACHMENT_SNIFFED_MIMES, ...MACRO_ENABLED_OOXML_SNIFFED_MIMES])`. */
+export declare const MACRO_ENABLED_OOXML_SNIFFED_MIMES: ReadonlySet<string>;
+/** Sniffed-mime counterpart of `ATTACHMENT_ACCEPT`: the binary formats
+ *  `sniffBinary` can identify from content among the accepted types.
+ *  Values must match `sniffBinary`'s output strings verbatim, or every
+ *  upload of that format fails the type gate — locked by the round-trip test
+ *  that sniffs real bytes of every mime listed here. */
+export declare const ALLOWED_ATTACHMENT_SNIFFED_MIMES: ReadonlySet<string>;
+/** Represent the result of checking an attachment's type with success or specific failure details */
+export 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).
+ */
+export 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.
+ */
+export 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. */
+export 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. */
+export declare function attachmentTotalSizeErrorMessage(totalBytes: number, limitBytes: number): string;

package/dist/chat-routes/binary-sniff.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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. Two families need more than a fixed-offset signature and
+ * get a reader of their own — ISO-BMFF brands (`sniffFtyp`) and OOXML Office
+ * packages, whose PKZIP container is shared with every other `.zip`
+ * (`sniffOoxml`).
+ *
+ * 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.
+ */
+export interface SniffResult {
+    binary: boolean;
+    mime: string | null;
+}
+/** Sniffed mime for a Word OOXML package (`.docx`). */
+export declare const OOXML_WORD_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** Sniffed mime for an Excel OOXML package (`.xlsx`). */
+export declare const OOXML_SPREADSHEET_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/** Sniffed mime for a PowerPoint OOXML package (`.pptx`). */
+export declare const OOXML_PRESENTATION_MIME = "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+/** Sniffed mime for a macro-enabled Word package (`.docm`). Reported
+ *  separately from {@link OOXML_WORD_MIME} so a package carrying a VBA project
+ *  can never be admitted under the plain-document mime: a route that wants
+ *  macro-enabled files opts in explicitly through its allowed-mime seam. */
+export declare const OOXML_WORD_MACRO_ENABLED_MIME = "application/vnd.ms-word.document.macroEnabled.12";
+/** Sniffed mime for a macro-enabled Excel package (`.xlsm`). */
+export declare const OOXML_SPREADSHEET_MACRO_ENABLED_MIME = "application/vnd.ms-excel.sheet.macroEnabled.12";
+/** Sniffed mime for a macro-enabled PowerPoint package (`.pptm`). */
+export declare const OOXML_PRESENTATION_MACRO_ENABLED_MIME = "application/vnd.ms-powerpoint.presentation.macroEnabled.12";
+/** 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. */
+export declare function sniffBinary(bytes: Uint8Array): SniffResult;

package/dist/chat-routes/completed-sandbox-turn.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Recover a detached Sandbox turn from its durable completed records.
+ *
+ * A fast detached run can finish before the live event subscriber receives
+ * every message-part event. The Sandbox still retains two exact records: a
+ * turn-id keyed result cache and the completed assistant message on the
+ * session. This adapter joins them without guessing across turns, then returns
+ * the same `DetachedTurnFinal` shape `runDetachedTurn` already consumes.
+ */
+import type { SandboxInstance } from '@tangle-network/sandbox';
+import type { DetachedTurnFinal } from './detached-turn';
+/** The official Sandbox methods needed for completed-turn recovery. */
+export type CompletedSandboxTurnSource = Pick<SandboxInstance, 'findCompletedTurn' | 'session'>;
+/** Options for resolving one exact detached turn. */
+export interface ReadCompletedSandboxTurnOptions {
+    turnId: string;
+    sessionId: string;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Read the exact completed turn. The session-level result is consulted only
+ * when the matching completed assistant message is still the latest message;
+ * otherwise that result could belong to a newer turn on the same session.
+ */
+export declare function readCompletedSandboxTurn(box: CompletedSandboxTurnSource, options: ReadCompletedSandboxTurnOptions): Promise<DetachedTurnFinal | null>;