@tangle-network/agent-app 0.43.40 → 0.43.41

package/dist/file-index-Bw_IQE_G.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Wire contract between the chat client (composer + `streamChatTurn`) and the
+ * assembled server vertical (`createChatTurnRoutes`). Import-free on purpose:
+ * `/web-react` re-exports these types into browser bundles, so nothing here may
+ * reach a Node builtin or an engine package.
+ *
+ * The part shape mirrors the sandbox SDK's `PromptInputPart` structurally
+ * (text | image | file with filename/mediaType/url/path/content) — derived
+ * here, not imported, so the client bundle never touches the SDK.
+ */
+interface ChatTurnTextPartInput {
+    type: 'text';
+    text: string;
+}
+/** A non-text prompt part the upload route hands back and the client echoes
+ *  on send. `url` carries an inline `data:` URI for small files; `path` is a
+ *  sandbox workspace reference for large ones (the >1 MiB gateway body cap
+ *  makes the two-step upload mandatory). */
+interface ChatTurnFilePartInput {
+    type: 'image' | 'file';
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    path?: string;
+    content?: string;
+}
+type ChatTurnPartInput = ChatTurnTextPartInput | ChatTurnFilePartInput;
+/** POST body for the turn route. `content` may be empty when `parts` carry the
+ *  message (an image-only send). Product routing fields (workspaceId etc.) ride
+ *  alongside and are read by the product's `authorize` seam. */
+interface ChatTurnRequestPayload {
+    threadId: string;
+    content?: string;
+    /** Non-text parts from the upload route, echoed back verbatim. */
+    parts?: ChatTurnFilePartInput[];
+    model?: string;
+    effort?: 'auto' | 'low' | 'medium' | 'high';
+    harness?: string;
+    /** Client-generated idempotency key for the logical turn (retry-safe). */
+    turnId?: string;
+    [key: string]: unknown;
+}
+/** `fetch` init for the turn route — the one place the client wire shape is
+ *  serialized, so composer glue and products never drift from the server's
+ *  parser. */
+declare function chatTurnRequestInit(payload: ChatTurnRequestPayload): RequestInit;
+declare const INLINE_PARTS_MAX_BYTES = 950000;
+declare class ChatTurnInputError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare function promptPartsByteSize(parts: ChatTurnPartInput[]): number;
+/** Throws `ChatTurnInputError` (413) when the parts' inline payload would blow
+ *  the gateway cap. Path-ref parts are tiny by construction and always pass. */
+declare function assertPromptPartsWithinCap(parts: ChatTurnPartInput[], maxBytes?: number): void;
+/** A file mention resolved from the composer's `@`-picker: the
+ *  workspace-relative path plus enough metadata to build a prompt part and
+ *  pointer text. `path` is the canonical identity — the mention pill's
+ *  `MentionItem.id` for the file kind (`/web-react`'s `useFileMentions`). */
+interface FileMention {
+    path: string;
+    name: string;
+    size?: number;
+}
+/** The `image/*` mime for a mention path by extension, or `undefined` for
+ *  anything not in the known image set (dispatched as `type: 'file'`). */
+declare function mediaTypeForMentionPath(path: string): string | undefined;
+interface FileMentionsToPartsOptions {
+    /** Resolve a mention's workspace-relative path to the absolute path the
+     *  dispatched part should carry (e.g. a host prefixing the in-box vault
+     *  root). Default: identity — the path travels unchanged. */
+    resolvePath?: (path: string) => string;
+}
+/** Maps resolved file mentions to path-only `ChatTurnFilePartInput`s —
+ *  `image` vs `file` by extension, and always a `path`, never a `url` (the
+ *  url/path XOR invariant: a mention is a sandbox path reference, never
+ *  inline bytes). */
+declare function fileMentionsToParts(mentions: readonly FileMention[], opts?: FileMentionsToPartsOptions): ChatTurnFilePartInput[];
+/** The agent-facing pointer block appended to the dispatched prompt — never
+ *  persisted in message `content`. Empty array → `''` so callers can append
+ *  unconditionally. This is the sole producer of that text: the current
+ *  turn's dispatch and any history projection built from the same mention
+ *  list both route through here, so the two can't drift apart. */
+declare function buildMentionPromptBlock(mentions: readonly Pick<FileMention, 'name' | 'path'>[]): string;
+/** Validates the untyped `parts` array off the wire. Returns the typed parts
+ *  or throws `ChatTurnInputError` (400) naming the offending entry. */
+declare function parseChatTurnParts(raw: unknown): ChatTurnFilePartInput[];
+
+/**
+ * `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.
+ */
+
+/** 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. */
+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>;
+
+export { type ChatTurnRequestPayload as C, type FileIndexAuthorization as F, INLINE_PARTS_MAX_BYTES as I, type SandboxFileTreeSource as S, type ChatTurnPartInput as a, type ChatTurnFilePartInput as b, ChatTurnInputError as c, type ChatTurnTextPartInput as d, type CreateSandboxFileIndexRouteOptions as e, type FileIndexCache as f, type FileIndexReadyResponse as g, type FileIndexResponse as h, type FileIndexWarmingResponse as i, type FileMention as j, type FileMentionsToPartsOptions as k, type SandboxTreeFile as l, type SandboxTreeResult as m, assertPromptPartsWithinCap as n, buildMentionPromptBlock as o, chatTurnRequestInit as p, createSandboxFileIndexRoute as q, fileMentionsToParts as r, mediaTypeForMentionPath as s, parseChatTurnParts as t, promptPartsByteSize as u };

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

@@ -4,12 +4,13 @@ import { C as ChatInteraction, a as ChatInteractionField, b as ChatInteractionSt
 export { d as ComposerAnswerDelivery, I as INTERACTION_CANCEL_EVENT, e as INTERACTION_EVENT, f as INTERACTION_RESOLVED_EVENT, h as InteractionPersistedPart, N as NoticeKind, j as NoticePersistedPart, P as ParseInteractionResult, k as canTransitionInteractionStatus, l as cancelStatusFor, m as composerAnswerData, n as composerAnswerDeliveries, o as dedupeQuestionInteractionsByContent, p as fieldAcceptsFreeText, q as interactionFromWireRequest, r as interactionPartKey, s as interactionToPersistedPart, t as isRenderableInteractionKind, u as isSafeInteractionFieldKey, v as isTerminalInteractionStatus, w as noticePart, x as noticePartKey, y as parseInteractionCancel, z as parseInteractionRequest, A as persistedPartToInteraction, B as questionInteractionContentSignature } from '../contract-DYbTzEDf.js';
 import { InteractionData } from '@tangle-network/agent-interface';
 export { InteractionData, InteractionOutcome, InteractionRequest } from '@tangle-network/agent-interface';
+import { j as FileMention } from '../file-index-Bw_IQE_G.js';
+export { b as ChatTurnFilePartInput, a as ChatTurnPartInput, C as ChatTurnRequestPayload, g as FileIndexReadyResponse, h as FileIndexResponse, i as FileIndexWarmingResponse, o as buildMentionPromptBlock, p as chatTurnRequestInit, r as fileMentionsToParts, s as mediaTypeForMentionPath } from '../file-index-Bw_IQE_G.js';
 import { S as StepAgentActivity } from '../agent-activity-C8ZG0F0M.js';
 import { a as FlowTrace } from '../flow-types-Cb_AblZs.js';
 export { S as SandboxTerminalConnection, a as SandboxTerminalConnectionResponse, U as UseSandboxTerminalConnectionOptions, b as UseSandboxTerminalConnectionResult, t as tabTerminalConnectionId, u as useSandboxTerminalConnection } from '../sandbox-terminal-BIIC__CP.js';
 import { CatalogModel } from '../catalog/index.js';
 import { Harness } from '../harness/index.js';
-export { b as ChatTurnFilePartInput, a as ChatTurnPartInput, C as ChatTurnRequestPayload, f as chatTurnRequestInit } from '../wire-BaUF66AS.js';
 
 /**
  * Client-side chat-stream consumption — the NDJSON parse loop every agent
@@ -363,6 +364,97 @@ interface UseChatInteractionsResult {
 }
 declare function useChatInteractions(): UseChatInteractionsResult;
 
+/**
+ * `useFileMentions` — the glue a host passes straight into `AgentComposer`'s
+ * `mention` prop (`@tangle-network/sandbox-ui#184`) to wire up `@`-file
+ * mentions against `createSandboxFileIndexRoute` (`/chat-routes`).
+ *
+ * Fetches the index once per session from `indexUrl`, refreshes it in the
+ * background whenever the popover opens (a `fetchItems` call) if the cached
+ * copy has aged past `refreshAfterMs`, and answers every keystroke from an
+ * in-memory fuzzy filter — no per-keystroke network round trip. The returned
+ * `refresh()` lets a caller force a re-fetch immediately instead of waiting
+ * on `refreshAfterMs` — e.g. right after the agent creates a file mid-session.
+ *
+ * `MentionItem`/the `mention` prop shape mirror the FROZEN contract from
+ * sandbox-ui#184 structurally (no import: `/web-react` stays dependency-free
+ * beyond React, and `@tangle-network/sandbox-ui` is an optional peer).
+ */
+
+/** Mirrors sandbox-ui#184's `MentionItem` — the atomic pill's payload. For a
+ *  file mention, `id` is the workspace-relative path (the pill's stable
+ *  identity and the `@<id>` serialization sandbox-ui uses to round-trip
+ *  `value`), `label` is the display name, and `detail` carries the full path
+ *  for the popover row's secondary line. */
+interface MentionItem {
+    id: string;
+    label: string;
+    detail?: string;
+    kind?: string;
+}
+/** Mirrors sandbox-ui#184's `AgentComposerProps['mention']` shape — plug the
+ *  hook's `mention` return value straight into that prop. */
+interface ComposerMentionProp {
+    trigger?: string;
+    fetchItems(query: string): Promise<MentionItem[]>;
+    onMentionsChange?(mentions: MentionItem[]): void;
+    renderItem?(item: MentionItem): ReactNode;
+    emptyText?: string;
+}
+/**
+ * Ranks `files` against `query` (case-insensitive), capped to `limit`:
+ * name-prefix matches first, then name-substring, then path-substring.
+ * Within a tier, shorter names sort first (the more specific match), then
+ * alphabetically by path for a stable order. An empty query returns the
+ * first `limit` entries unranked — the popover's default list before typing.
+ * Pure and dependency-free (no fuzzy-match library) so it's cheap enough to
+ * re-run on every keystroke against a 10k-entry index.
+ */
+declare function rankFileMentions(files: readonly FileMention[], query: string, limit: number): FileMention[];
+/** Max popover results per query — enough to show a useful spread of matches
+ *  without pushing the fuzzy-filtered list past what a popover can usefully
+ *  render in one screen. */
+declare const DEFAULT_MENTION_LIMIT = 20;
+/** How long a `ready` index is served before a background refetch — long
+ *  enough that a full session's worth of popover opens don't repeatedly hit
+ *  the index endpoint, short enough that a stale listing doesn't linger too
+ *  far past workspace file changes. Callers who need the index current right
+ *  now (e.g. just after the agent creates a file) call `refresh()` instead of
+ *  waiting on this window. */
+declare const INDEX_REFRESH_AFTER_MS: number;
+/** Popover empty-state copy for a `ready` index whose query matched nothing.
+ *  Loading/warming/error states have their own copy — see `emptyTextFor`. */
+declare const DEFAULT_MENTION_EMPTY_TEXT = "No matching files";
+interface UseFileMentionsOptions {
+    /** GET endpoint returning `FileIndexResponse` (a `createSandboxFileIndexRoute`). */
+    indexUrl: string;
+    /** Max popover results per query. Default {@link DEFAULT_MENTION_LIMIT}. */
+    limit?: number;
+    /** How long a `ready` index is served without a background refetch.
+     *  Default {@link INDEX_REFRESH_AFTER_MS}. */
+    refreshAfterMs?: number;
+    /** `fetch` override for tests / non-global-fetch hosts. Default `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Text shown in the popover's empty state once the index is loaded and
+     *  the query matched nothing. Default {@link DEFAULT_MENTION_EMPTY_TEXT}. */
+    emptyText?: string;
+}
+interface UseFileMentionsResult {
+    /** Spread straight into `AgentComposer`'s `mention` prop. */
+    mention: ComposerMentionProp;
+    /** The files currently referenced by mentions in the composer's value —
+     *  the send-body list (map through `fileMentionsToParts`). */
+    mentions: FileMention[];
+    /** Drop all currently-referenced mentions (e.g. after a successful send). */
+    clearMentions: () => void;
+    /** Force a re-fetch of the index right now, ignoring `refreshAfterMs` — for
+     *  example right after the agent creates a file mid-session, so the next
+     *  popover open sees it. Dedupes against an already-in-flight load rather
+     *  than firing a second request. */
+    refresh: () => Promise<void>;
+}
+declare function useFileMentions(options: UseFileMentionsOptions): UseFileMentionsResult;
+
 /**
  * Provider brand marks — real logo path data (simple-icons / SVG Logos, both
  * CC0) inlined so the picker shows actual provider identity instead of
@@ -792,4 +884,4 @@ declare function useThinkingSeconds(active: boolean): number;
  */
 declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, approval, onToolCallClick, toolRenderers, error, onRetry, renderEmpty, emptyState, header, }: ChatMessagesProps): react.JSX.Element;
 
-export { type ActivityTone, type AgentActivityPage, AgentActivityPanel, type AgentActivityPanelProps, type AgentActivityRecord, AgentSessionControls, type AgentSessionControlsProps, CatalogModel, ChatComposer, type ChatComposerProps, type ChatEmptyDoor, ChatEmptyState, type ChatEmptyStateProps, ChatInteraction, ChatInteractionField, ChatInteractionStatus, type ChatMessageMetrics, type ChatMessageSegment, ChatMessages, type ChatMessagesProps, ChatSelectField, type ChatStreamCallbacks, type ChatStreamToolCall, type ChatStreamToolResult, type ChatToolCallInfo, type ChatUiMessage, type ComposerFile, type ComposerFilePart, type ConsumeChatStreamResult, DEFAULT_EFFORT_LEVELS, type EffortLevel, EffortPicker, type EffortPickerProps, type FieldValues, FlowWaterfall, type FlowWaterfallProps, INTERACTION_SUBMIT_TIMEOUT_MESSAGE, INTERACTION_SUBMIT_TIMEOUT_MS, InteractionActionButton, type InteractionAnswerSubmission, type InteractionAnswerSubmitterOptions, InteractionBadge, type InteractionBadgeVariant, InteractionCancelData, InteractionPlanCard, type InteractionPlanCardProps, InteractionQuestionCard, type InteractionQuestionCardProps, InteractionRequestWire, type InteractionSubmitResult, MissionActivityLane, type MissionActivityLaneProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, ProviderLogo, type ProviderLogoProps, QuestionOptionList, type QuestionOptionListProps, RunDrillIn, type RunDrillInProps, SeatPaywall, type SeatPaywallProps, type SmoothRevealOptions, type StreamChatOptions, type SubmitInteractionAnswer, type ToolDetailRenderers, type ToolRunRecord, type ToolRunStep, type UseChatInteractionsResult, type WaterfallRow, activityTone, buildAnswerData, cancelChatInteraction, consumeChatStream, createInteractionAnswerSubmitter, dispatchChatStreamLine, fieldAnswer, formatActivityCost, formatActivityDuration, formatModelCost, formatTokensPerSecond, hasSecretField, interactionStatusLabels, interactionTerminalNotes, isLateAnswerableStatus, lateAnswerMessage, mergeActivityPages, nextRevealCount, pendingApprovalOf, resolveChatInteraction, responseErrorMessage, restoreChatInteractions, streamChatTurn, terminalizePendingChatInteractions, upsertChatInteraction, useChatInteractions, usePending, usePopover, useSmoothText, useThinkingSeconds, waterfallLayout };
+export { type ActivityTone, type AgentActivityPage, AgentActivityPanel, type AgentActivityPanelProps, type AgentActivityRecord, AgentSessionControls, type AgentSessionControlsProps, CatalogModel, ChatComposer, type ChatComposerProps, type ChatEmptyDoor, ChatEmptyState, type ChatEmptyStateProps, ChatInteraction, ChatInteractionField, ChatInteractionStatus, type ChatMessageMetrics, type ChatMessageSegment, ChatMessages, type ChatMessagesProps, ChatSelectField, type ChatStreamCallbacks, type ChatStreamToolCall, type ChatStreamToolResult, type ChatToolCallInfo, type ChatUiMessage, type ComposerFile, type ComposerFilePart, type ComposerMentionProp, type ConsumeChatStreamResult, DEFAULT_EFFORT_LEVELS, DEFAULT_MENTION_EMPTY_TEXT, DEFAULT_MENTION_LIMIT, type EffortLevel, EffortPicker, type EffortPickerProps, type FieldValues, FileMention, FlowWaterfall, type FlowWaterfallProps, INDEX_REFRESH_AFTER_MS, INTERACTION_SUBMIT_TIMEOUT_MESSAGE, INTERACTION_SUBMIT_TIMEOUT_MS, InteractionActionButton, type InteractionAnswerSubmission, type InteractionAnswerSubmitterOptions, InteractionBadge, type InteractionBadgeVariant, InteractionCancelData, InteractionPlanCard, type InteractionPlanCardProps, InteractionQuestionCard, type InteractionQuestionCardProps, InteractionRequestWire, type InteractionSubmitResult, type MentionItem, MissionActivityLane, type MissionActivityLaneProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, ProviderLogo, type ProviderLogoProps, QuestionOptionList, type QuestionOptionListProps, RunDrillIn, type RunDrillInProps, SeatPaywall, type SeatPaywallProps, type SmoothRevealOptions, type StreamChatOptions, type SubmitInteractionAnswer, type ToolDetailRenderers, type ToolRunRecord, type ToolRunStep, type UseChatInteractionsResult, type UseFileMentionsOptions, type UseFileMentionsResult, type WaterfallRow, activityTone, buildAnswerData, cancelChatInteraction, consumeChatStream, createInteractionAnswerSubmitter, dispatchChatStreamLine, fieldAnswer, formatActivityCost, formatActivityDuration, formatModelCost, formatTokensPerSecond, hasSecretField, interactionStatusLabels, interactionTerminalNotes, isLateAnswerableStatus, lateAnswerMessage, mergeActivityPages, nextRevealCount, pendingApprovalOf, rankFileMentions, resolveChatInteraction, responseErrorMessage, restoreChatInteractions, streamChatTurn, terminalizePendingChatInteractions, upsertChatInteraction, useChatInteractions, useFileMentions, usePending, usePopover, useSmoothText, useThinkingSeconds, waterfallLayout };

package/dist/web-react/index.js

@@ -5,8 +5,11 @@ import {
   ChatEmptyState,
   ChatMessages,
   DEFAULT_EFFORT_LEVELS,
+  DEFAULT_MENTION_EMPTY_TEXT,
+  DEFAULT_MENTION_LIMIT,
   EffortPicker,
   FlowWaterfall,
+  INDEX_REFRESH_AFTER_MS,
   INTERACTION_SUBMIT_TIMEOUT_MESSAGE,
   INTERACTION_SUBMIT_TIMEOUT_MS,
   InteractionActionButton,
@@ -38,6 +41,7 @@ import {
   mergeActivityPages,
   nextRevealCount,
   pendingApprovalOf,
+  rankFileMentions,
   resolveChatInteraction,
   responseErrorMessage,
   restoreChatInteractions,
@@ -45,19 +49,23 @@ import {
   terminalizePendingChatInteractions,
   upsertChatInteraction,
   useChatInteractions,
+  useFileMentions,
   usePending,
   usePopover,
   useSmoothText,
   useThinkingSeconds,
   waterfallLayout
-} from "../chunk-D4HB72W2.js";
+} from "../chunk-KM766NN3.js";
 import {
   tabTerminalConnectionId,
   useSandboxTerminalConnection
 } from "../chunk-65P3HJY3.js";
 import {
-  chatTurnRequestInit
-} from "../chunk-5SV5PSU7.js";
+  buildMentionPromptBlock,
+  chatTurnRequestInit,
+  fileMentionsToParts,
+  mediaTypeForMentionPath
+} from "../chunk-2EO7CPL3.js";
 import "../chunk-2QI7XV2T.js";
 import {
   INTERACTION_CANCEL_EVENT,
@@ -90,8 +98,11 @@ export {
   ChatEmptyState,
   ChatMessages,
   DEFAULT_EFFORT_LEVELS,
+  DEFAULT_MENTION_EMPTY_TEXT,
+  DEFAULT_MENTION_LIMIT,
   EffortPicker,
   FlowWaterfall,
+  INDEX_REFRESH_AFTER_MS,
   INTERACTION_CANCEL_EVENT,
   INTERACTION_EVENT,
   INTERACTION_RESOLVED_EVENT,
@@ -109,6 +120,7 @@ export {
   SeatPaywall,
   activityTone,
   buildAnswerData,
+  buildMentionPromptBlock,
   canTransitionInteractionStatus,
   cancelChatInteraction,
   cancelStatusFor,
@@ -121,6 +133,7 @@ export {
   dispatchChatStreamLine,
   fieldAcceptsFreeText,
   fieldAnswer,
+  fileMentionsToParts,
   formatActivityCost,
   formatActivityDuration,
   formatModelCost,
@@ -136,6 +149,7 @@ export {
   isSafeInteractionFieldKey,
   isTerminalInteractionStatus,
   lateAnswerMessage,
+  mediaTypeForMentionPath,
   mergeActivityPages,
   nextRevealCount,
   noticePart,
@@ -145,6 +159,7 @@ export {
   pendingApprovalOf,
   persistedPartToInteraction,
   questionInteractionContentSignature,
+  rankFileMentions,
   resolveChatInteraction,
   responseErrorMessage,
   restoreChatInteractions,
@@ -153,6 +168,7 @@ export {
   terminalizePendingChatInteractions,
   upsertChatInteraction,
   useChatInteractions,
+  useFileMentions,
   usePending,
   usePopover,
   useSandboxTerminalConnection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.43.40",
+  "version": "0.43.41",
   "packageManager": "pnpm@10.33.4",
   "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
   "keywords": [

package/dist/chunk-5SV5PSU7.js

@@ -1,80 +0,0 @@
-// src/chat-routes/wire.ts
-function chatTurnRequestInit(payload) {
-  return {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(payload)
-  };
-}
-var INLINE_PARTS_MAX_BYTES = 95e4;
-var ChatTurnInputError = class extends Error {
-  constructor(message, status = 400, code = "INVALID_CHAT_TURN") {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.name = "ChatTurnInputError";
-  }
-  status;
-  code;
-};
-function partByteSize(part) {
-  let bytes = 0;
-  if (part.type === "text") return part.text.length;
-  if (part.url) bytes += part.url.length;
-  if (part.content) bytes += part.content.length;
-  if (part.path) bytes += part.path.length;
-  return bytes;
-}
-function promptPartsByteSize(parts) {
-  return parts.reduce((total, part) => total + partByteSize(part), 0);
-}
-function assertPromptPartsWithinCap(parts, maxBytes = INLINE_PARTS_MAX_BYTES) {
-  const total = promptPartsByteSize(parts);
-  if (total <= maxBytes) return;
-  const largest = [...parts].sort((a, b) => partByteSize(b) - partByteSize(a))[0];
-  const largestName = largest && largest.type !== "text" ? largest.filename ?? largest.path ?? largest.type : "text";
-  throw new ChatTurnInputError(
-    `Inline prompt parts total ${total}B, over the ${maxBytes}B budget (largest: ${largestName}, ${largest ? partByteSize(largest) : 0}B). Upload large files through the upload route so they travel as sandbox path references.`,
-    413,
-    "PROMPT_PARTS_TOO_LARGE"
-  );
-}
-function parseChatTurnParts(raw) {
-  if (raw === void 0 || raw === null) return [];
-  if (!Array.isArray(raw)) throw new ChatTurnInputError("parts must be an array");
-  return raw.map((entry, index) => {
-    const part = entry;
-    if (!part || typeof part !== "object") {
-      throw new ChatTurnInputError(`parts[${index}] must be an object`);
-    }
-    if (part.type !== "image" && part.type !== "file") {
-      throw new ChatTurnInputError(`parts[${index}].type must be 'image' or 'file'`);
-    }
-    for (const key of ["filename", "mediaType", "url", "path", "content"]) {
-      if (part[key] !== void 0 && typeof part[key] !== "string") {
-        throw new ChatTurnInputError(`parts[${index}].${key} must be a string`);
-      }
-    }
-    if (!part.url && !part.path && !part.content) {
-      throw new ChatTurnInputError(`parts[${index}] needs a url, path, or content`);
-    }
-    return {
-      type: part.type,
-      ...part.filename !== void 0 ? { filename: part.filename } : {},
-      ...part.mediaType !== void 0 ? { mediaType: part.mediaType } : {},
-      ...part.url !== void 0 ? { url: part.url } : {},
-      ...part.path !== void 0 ? { path: part.path } : {},
-      ...part.content !== void 0 ? { content: part.content } : {}
-    };
-  });
-}
-
-export {
-  chatTurnRequestInit,
-  INLINE_PARTS_MAX_BYTES,
-  ChatTurnInputError,
-  promptPartsByteSize,
-  assertPromptPartsWithinCap,
-  parseChatTurnParts
-};
-//# sourceMappingURL=chunk-5SV5PSU7.js.map

package/dist/chunk-5SV5PSU7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/chat-routes/wire.ts"],"sourcesContent":["/**\n * Wire contract between the chat client (composer + `streamChatTurn`) and the\n * assembled server vertical (`createChatTurnRoutes`). Import-free on purpose:\n * `/web-react` re-exports these types into browser bundles, so nothing here may\n * reach a Node builtin or an engine package.\n *\n * The part shape mirrors the sandbox SDK's `PromptInputPart` structurally\n * (text | image | file with filename/mediaType/url/path/content) — derived\n * here, not imported, so the client bundle never touches the SDK.\n */\n\nexport interface ChatTurnTextPartInput {\n  type: 'text'\n  text: string\n}\n\n/** A non-text prompt part the upload route hands back and the client echoes\n *  on send. `url` carries an inline `data:` URI for small files; `path` is a\n *  sandbox workspace reference for large ones (the >1 MiB gateway body cap\n *  makes the two-step upload mandatory). */\nexport interface ChatTurnFilePartInput {\n  type: 'image' | 'file'\n  filename?: string\n  mediaType?: string\n  url?: string\n  path?: string\n  content?: string\n}\n\nexport type ChatTurnPartInput = ChatTurnTextPartInput | ChatTurnFilePartInput\n\n/** POST body for the turn route. `content` may be empty when `parts` carry the\n *  message (an image-only send). Product routing fields (workspaceId etc.) ride\n *  alongside and are read by the product's `authorize` seam. */\nexport interface ChatTurnRequestPayload {\n  threadId: string\n  content?: string\n  /** Non-text parts from the upload route, echoed back verbatim. */\n  parts?: ChatTurnFilePartInput[]\n  model?: string\n  effort?: 'auto' | 'low' | 'medium' | 'high'\n  harness?: string\n  /** Client-generated idempotency key for the logical turn (retry-safe). */\n  turnId?: string\n  [key: string]: unknown\n}\n\n/** `fetch` init for the turn route — the one place the client wire shape is\n *  serialized, so composer glue and products never drift from the server's\n *  parser. */\nexport function chatTurnRequestInit(payload: ChatTurnRequestPayload): RequestInit {\n  return {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify(payload),\n  }\n}\n\n// ── inline-part byte budget ─────────────────────────────────────────────────\n//\n// The sandbox gateway caps request bodies at 1 MiB; a turn body whose inline\n// `data:` parts exceed it dies at the gateway with an opaque 413. Enforce the\n// budget at the route boundary instead, with headroom for the JSON envelope\n// (same fail-loud-at-the-choke-point style as /sandbox's provision-payload and\n// env-size gates).\n\nexport const INLINE_PARTS_MAX_BYTES = 950_000\n\nexport class ChatTurnInputError extends Error {\n  constructor(message: string, readonly status = 400, readonly code = 'INVALID_CHAT_TURN') {\n    super(message)\n    this.name = 'ChatTurnInputError'\n  }\n}\n\nfunction partByteSize(part: ChatTurnPartInput): number {\n  let bytes = 0\n  if (part.type === 'text') return part.text.length\n  if (part.url) bytes += part.url.length\n  if (part.content) bytes += part.content.length\n  if (part.path) bytes += part.path.length\n  return bytes\n}\n\nexport function promptPartsByteSize(parts: ChatTurnPartInput[]): number {\n  return parts.reduce((total, part) => total + partByteSize(part), 0)\n}\n\n/** Throws `ChatTurnInputError` (413) when the parts' inline payload would blow\n *  the gateway cap. Path-ref parts are tiny by construction and always pass. */\nexport function assertPromptPartsWithinCap(\n  parts: ChatTurnPartInput[],\n  maxBytes = INLINE_PARTS_MAX_BYTES,\n): void {\n  const total = promptPartsByteSize(parts)\n  if (total <= maxBytes) return\n  const largest = [...parts].sort((a, b) => partByteSize(b) - partByteSize(a))[0]\n  const largestName = largest && largest.type !== 'text' ? largest.filename ?? largest.path ?? largest.type : 'text'\n  throw new ChatTurnInputError(\n    `Inline prompt parts total ${total}B, over the ${maxBytes}B budget (largest: ${largestName}, ${largest ? partByteSize(largest) : 0}B). ` +\n      'Upload large files through the upload route so they travel as sandbox path references.',\n    413,\n    'PROMPT_PARTS_TOO_LARGE',\n  )\n}\n\n/** Validates the untyped `parts` array off the wire. Returns the typed parts\n *  or throws `ChatTurnInputError` (400) naming the offending entry. */\nexport function parseChatTurnParts(raw: unknown): ChatTurnFilePartInput[] {\n  if (raw === undefined || raw === null) return []\n  if (!Array.isArray(raw)) throw new ChatTurnInputError('parts must be an array')\n  return raw.map((entry, index) => {\n    const part = entry as Record<string, unknown> | null\n    if (!part || typeof part !== 'object') {\n      throw new ChatTurnInputError(`parts[${index}] must be an object`)\n    }\n    if (part.type !== 'image' && part.type !== 'file') {\n      throw new ChatTurnInputError(`parts[${index}].type must be 'image' or 'file'`)\n    }\n    for (const key of ['filename', 'mediaType', 'url', 'path', 'content'] as const) {\n      if (part[key] !== undefined && typeof part[key] !== 'string') {\n        throw new ChatTurnInputError(`parts[${index}].${key} must be a string`)\n      }\n    }\n    if (!part.url && !part.path && !part.content) {\n      throw new ChatTurnInputError(`parts[${index}] needs a url, path, or content`)\n    }\n    return {\n      type: part.type,\n      ...(part.filename !== undefined ? { filename: part.filename as string } : {}),\n      ...(part.mediaType !== undefined ? { mediaType: part.mediaType as string } : {}),\n      ...(part.url !== undefined ? { url: part.url as string } : {}),\n      ...(part.path !== undefined ? { path: part.path as string } : {}),\n      ...(part.content !== undefined ? { content: part.content as string } : {}),\n    }\n  })\n}\n"],"mappings":";AAkDO,SAAS,oBAAoB,SAA8C;AAChF,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,IAC9C,MAAM,KAAK,UAAU,OAAO;AAAA,EAC9B;AACF;AAUO,IAAM,yBAAyB;AAE/B,IAAM,qBAAN,cAAiC,MAAM;AAAA,EAC5C,YAAY,SAA0B,SAAS,KAAc,OAAO,qBAAqB;AACvF,UAAM,OAAO;AADuB;AAAuB;AAE3D,SAAK,OAAO;AAAA,EACd;AAAA,EAHsC;AAAA,EAAuB;AAI/D;AAEA,SAAS,aAAa,MAAiC;AACrD,MAAI,QAAQ;AACZ,MAAI,KAAK,SAAS,OAAQ,QAAO,KAAK,KAAK;AAC3C,MAAI,KAAK,IAAK,UAAS,KAAK,IAAI;AAChC,MAAI,KAAK,QAAS,UAAS,KAAK,QAAQ;AACxC,MAAI,KAAK,KAAM,UAAS,KAAK,KAAK;AAClC,SAAO;AACT;AAEO,SAAS,oBAAoB,OAAoC;AACtE,SAAO,MAAM,OAAO,CAAC,OAAO,SAAS,QAAQ,aAAa,IAAI,GAAG,CAAC;AACpE;AAIO,SAAS,2BACd,OACA,WAAW,wBACL;AACN,QAAM,QAAQ,oBAAoB,KAAK;AACvC,MAAI,SAAS,SAAU;AACvB,QAAM,UAAU,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,EAAE,CAAC;AAC9E,QAAM,cAAc,WAAW,QAAQ,SAAS,SAAS,QAAQ,YAAY,QAAQ,QAAQ,QAAQ,OAAO;AAC5G,QAAM,IAAI;AAAA,IACR,6BAA6B,KAAK,eAAe,QAAQ,sBAAsB,WAAW,KAAK,UAAU,aAAa,OAAO,IAAI,CAAC;AAAA,IAElI;AAAA,IACA;AAAA,EACF;AACF;AAIO,SAAS,mBAAmB,KAAuC;AACxE,MAAI,QAAQ,UAAa,QAAQ,KAAM,QAAO,CAAC;AAC/C,MAAI,CAAC,MAAM,QAAQ,GAAG,EAAG,OAAM,IAAI,mBAAmB,wBAAwB;AAC9E,SAAO,IAAI,IAAI,CAAC,OAAO,UAAU;AAC/B,UAAM,OAAO;AACb,QAAI,CAAC,QAAQ,OAAO,SAAS,UAAU;AACrC,YAAM,IAAI,mBAAmB,SAAS,KAAK,qBAAqB;AAAA,IAClE;AACA,QAAI,KAAK,SAAS,WAAW,KAAK,SAAS,QAAQ;AACjD,YAAM,IAAI,mBAAmB,SAAS,KAAK,kCAAkC;AAAA,IAC/E;AACA,eAAW,OAAO,CAAC,YAAY,aAAa,OAAO,QAAQ,SAAS,GAAY;AAC9E,UAAI,KAAK,GAAG,MAAM,UAAa,OAAO,KAAK,GAAG,MAAM,UAAU;AAC5D,cAAM,IAAI,mBAAmB,SAAS,KAAK,KAAK,GAAG,mBAAmB;AAAA,MACxE;AAAA,IACF;AACA,QAAI,CAAC,KAAK,OAAO,CAAC,KAAK,QAAQ,CAAC,KAAK,SAAS;AAC5C,YAAM,IAAI,mBAAmB,SAAS,KAAK,iCAAiC;AAAA,IAC9E;AACA,WAAO;AAAA,MACL,MAAM,KAAK;AAAA,MACX,GAAI,KAAK,aAAa,SAAY,EAAE,UAAU,KAAK,SAAmB,IAAI,CAAC;AAAA,MAC3E,GAAI,KAAK,cAAc,SAAY,EAAE,WAAW,KAAK,UAAoB,IAAI,CAAC;AAAA,MAC9E,GAAI,KAAK,QAAQ,SAAY,EAAE,KAAK,KAAK,IAAc,IAAI,CAAC;AAAA,MAC5D,GAAI,KAAK,SAAS,SAAY,EAAE,MAAM,KAAK,KAAe,IAAI,CAAC;AAAA,MAC/D,GAAI,KAAK,YAAY,SAAY,EAAE,SAAS,KAAK,QAAkB,IAAI,CAAC;AAAA,IAC1E;AAAA,EACF,CAAC;AACH;","names":[]}