@tangle-network/agent-app 0.43.42 → 0.43.44

package/dist/parts-1_3y2JmR.d.ts

@@ -0,0 +1,368 @@
+import { Part } from '@tangle-network/agent-interface';
+import { a as ChatInteractionField, b as ChatInteractionStatus, h as InteractionAnswers, N as NoticeKind } from './contract-KfqJh_au.js';
+import { ChatPlanPersistedPart } from './plans/index.js';
+
+/**
+ * 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[];
+    /** `@`-picked file mentions for this turn — path references into the
+     *  workspace sandbox, NOT uploads, so they travel in their own field rather
+     *  than as `parts` entries. A product whose `parts` field is already spoken
+     *  for (an attachment sentinel) can still send mentions, and mentions
+     *  persist as their own `ChatMentionPart`s so a retry rebuilds them. The
+     *  route validates this field with {@link parseFileMentions} and replaces it
+     *  on the payload with the validated, deduped list. */
+    mentions?: FileMention[];
+    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;
+/** The image/file split a mention is rendered and persisted under — the
+ *  composer pill's icon, the dispatched part's `type`, and
+ *  `ChatMentionPart.mentionKind` are all this one value. */
+type ChatMentionKind = 'image' | 'file';
+/** `image` when the path's extension is in the known image set (the same table
+ *  {@link mediaTypeForMentionPath} reads), `file` otherwise. Exported so a
+ *  client that needs only the discriminant — a pill icon, a persisted part's
+ *  `mentionKind` — never re-declares the extension table; two frozen copies of
+ *  one mime table is how one gains a format and the other doesn't. */
+declare function mentionKindForPath(path: string): ChatMentionKind;
+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;
+/** Hard cap on mentions per turn. Bounds the prompt pointer block, the
+ *  persisted parts, and whatever media budget a dispatch draws from them. */
+declare const MENTION_MAX_COUNT = 16;
+type SandboxMentionPathCheck = {
+    succeeded: true;
+} | {
+    succeeded: false;
+    error: string;
+};
+/**
+ * Validate a workspace-relative sandbox mention path. Rejects traversal (a
+ * `..` path segment), absolute paths (leading `/`), backslashes, and null
+ * bytes — the four ways a path picked in a client can escape the root the
+ * index route scanned.
+ *
+ * Spaces and unicode are deliberately ALLOWED: in-box filenames are arbitrary,
+ * and an ASCII-only charset would silently drop real files from a feature
+ * whose whole job is naming them.
+ */
+declare function validateSandboxMentionPath(path: unknown): SandboxMentionPathCheck;
+/**
+ * Validates the untyped `mentions` array off the wire, mirroring
+ * {@link parseChatTurnParts}: the typed list, or `ChatTurnInputError` (400)
+ * naming the offending entry. Never sanitizes-and-continues — a traversal path
+ * is a rejected request, not a trimmed one.
+ *
+ * A path repeated within one turn is deduped to its first occurrence rather
+ * than rejected: mentioning the same file twice is plausible user input, not
+ * an attack.
+ */
+declare function parseFileMentions(raw: unknown): FileMention[];
+/** 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[];
+
+/**
+ * The stored shape of `message.parts` — one typed vocabulary for every part a
+ * product persists into a chat transcript. NOT an ad-hoc union reverse-
+ * engineered from product schemas; each member is matched field-for-field to
+ * its canonical source:
+ *
+ * - `text` / `reasoning` / `tool`: the persisted projection `/stream`'s
+ *   `normalizePersistedPart` produces from the harness lane's
+ *   `message.part.updated` events (ADC sidecar
+ *   `apps/sidecar/src/events/session-events.ts:56` wraps the canonical part in
+ *   an `{id, sessionID, messageID}` envelope; the projection strips the
+ *   session/message ids and keeps the per-segment part id).
+ * - `file` / `image` / `step-start` / `step-finish`: the sidecar's canonical
+ *   `MessagePartSchema` members (ADC
+ *   `apps/sidecar/src/schemas/agent-schemas.ts:50-154`); `step-finish` carries
+ *   the harness's per-step usage receipt — tokens
+ *   `{total, input, output, reasoning, cache{write, read}}` + `cost` — which is
+ *   also the shape the message-level token/cost columns mirror.
+ * - `subtask`: `@tangle-network/agent-interface`'s `SubtaskPart` (a spawned
+ *   sub-agent task).
+ * - `interaction` / `notice`: the persisted-part codecs in
+ *   `/web-react`'s chat-interactions contract (`interactionToPersistedPart`,
+ *   `noticePart`) — type-only imports, one source of truth for their statuses
+ *   and field shapes.
+ * - `plan`: the durable-plan projection in `/plans`, derived from the sandbox
+ *   SDK's authoritative plan lifecycle.
+ * - `mention`: an `@`-picked reference to a file that already lives in the
+ *   workspace sandbox (`FileMention` in `/chat-routes`'s wire contract, plus
+ *   the image/file discriminant). Neither transport lane produces it — the
+ *   turn route persists it from the request's `mentions` field — but it is a
+ *   part a product persists into a transcript, so it belongs in this
+ *   vocabulary rather than in a parallel one.
+ *
+ * `@tangle-network/agent-interface` exports the canonical wire `Part` union,
+ * but its `PartBase` requires the `sessionID`/`messageID` stream envelope that
+ * is deliberately NOT persisted, so the stored union is defined here as the
+ * envelope-free projection (a type-level coverage check against the peer's
+ * `Part['type']` lives in the tests). Contribute-down candidate: if
+ * agent-interface grows envelope-free persisted-part types, re-export them
+ * here and delete these definitions.
+ *
+ * Two transport lanes serialize into this SAME stored shape:
+ * - harness lane: canonical `message.part.updated` parts, merged/normalized by
+ *   `/stream` (`mergePersistedPart`, `finalizeAssistantParts`);
+ * - router/openai-compat lane: `text_delta`/`tool_call` stream events are
+ *   mapped INTO canonical part events first (`/runtime`'s `toLoopEvents` +
+ *   `/stream`'s `normalizeToolEvent`) and then persisted identically — the
+ *   store never sees a router-specific shape.
+ */
+
+/** Start/end wall-clock millis, as normalized by `/stream`'s `normalizeTime`. */
+interface ChatPartTime {
+    start?: number;
+    end?: number;
+}
+/** `id` is the harness's per-segment identity; absent on legacy/router parts,
+ *  which collapse to a single logical text stream. Never invented client-side. */
+interface ChatTextPart {
+    type: 'text';
+    text: string;
+    id?: string;
+}
+interface ChatReasoningPart {
+    type: 'reasoning';
+    text: string;
+    id?: string;
+    time?: ChatPartTime;
+}
+/** Superset of the sidecar's status enum (`pending|running|completed|failed`)
+ *  and agent-interface's `ToolState` statuses; `error` is the persisted
+ *  terminal form `/stream`'s `normalizePersistedPart` settles on. */
+type ChatToolStatus = 'pending' | 'running' | 'completed' | 'error' | 'failed';
+interface ChatToolState {
+    status: ChatToolStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    time?: ChatPartTime;
+}
+interface ChatToolPart {
+    type: 'tool';
+    id: string;
+    tool: string;
+    callID?: string;
+    state: ChatToolState;
+}
+/** Union of the sidecar's legacy (path-based) and AI-SDK (url-based) file
+ *  shapes; response-side every field besides `type` is optional. */
+interface ChatFilePart {
+    type: 'file';
+    id?: string;
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    path?: string;
+    content?: string;
+}
+interface ChatImagePart {
+    type: 'image';
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    path?: string;
+}
+interface ChatSubtaskPart {
+    type: 'subtask';
+    prompt: string;
+    description: string;
+    agent: string;
+    id?: string;
+}
+/** OpenCode step-boundary marker — no renderable text; preserved so mappers
+ *  never coerce it into a "[object Object]" text part. */
+interface ChatStepStartPart {
+    type: 'step-start';
+}
+/** Per-step usage receipt as the harness reports it (sidecar
+ *  `StepFinishPartSchema`). The message-level token/cost columns are this
+ *  shape flattened. */
+interface ChatUsageTokens {
+    total?: number;
+    input?: number;
+    output?: number;
+    reasoning?: number;
+    cache?: {
+        write?: number;
+        read?: number;
+    };
+}
+interface ChatStepFinishPart {
+    type: 'step-finish';
+    reason?: string;
+    tokens?: ChatUsageTokens;
+    cost?: number;
+}
+/** Persisted human-in-the-loop ask — byte-matches
+ *  `interactionToPersistedPart` in `/web-react`'s chat-interactions contract. */
+interface ChatInteractionPart {
+    type: 'interaction';
+    id: string;
+    kind: string;
+    title: string;
+    body?: string;
+    answerSpec: {
+        fields: ChatInteractionField[];
+    };
+    status: ChatInteractionStatus;
+    answers?: InteractionAnswers;
+    cancelReason?: string;
+}
+type ChatPlanPart = ChatPlanPersistedPart;
+/** Persisted one-line transcript notice — byte-matches `noticePart` in
+ *  `/web-react`'s chat-interactions contract. */
+interface ChatNoticePart {
+    type: 'notice';
+    id: string;
+    noticeKind: NoticeKind;
+    text: string;
+}
+/**
+ * A file the user `@`-mentioned on this turn: a workspace-relative path into
+ * the sandbox, never bytes. `type: 'mention'` is its own discriminant
+ * precisely so it does NOT collide with the `file`/`image` attachment parts —
+ * an attachment carries content the product uploaded, a mention points at
+ * something the box already has, and a transcript renders them differently
+ * (an inline pill, not an attachment card).
+ *
+ * `path` is the identity: mentioning one file twice in a turn folds to one
+ * part. `turnId` is optional and set by products that rebuild a turn's
+ * mentions on retry.
+ */
+interface ChatMentionPart {
+    type: 'mention';
+    mentionKind: ChatMentionKind;
+    path: string;
+    name: string;
+    size?: number;
+    turnId?: string;
+}
+type ChatMessagePart = ChatTextPart | ChatReasoningPart | ChatToolPart | ChatFilePart | ChatImagePart | ChatSubtaskPart | ChatStepStartPart | ChatStepFinishPart | ChatInteractionPart | ChatNoticePart | ChatPlanPart | ChatMentionPart;
+/** Every canonical harness wire-part kind must be storable — compile-time
+ *  guarantee that a new agent-interface part kind cannot silently fall out of
+ *  the persisted vocabulary. */
+type StorableHarnessPartKind = Part['type'] & ChatMessagePart['type'];
+/**
+ * The typed projection at the `/stream` → `/chat-store` boundary. The stream
+ * normalizers (`normalizePersistedPart`/`mergePersistedPart`/
+ * `finalizeAssistantParts`) deliberately produce untyped `JsonRecord`s — they
+ * normalize wire shapes and do not own the stored vocabulary. THIS module
+ * owns it, so this is where rows gain the `ChatMessagePart` type: each entry
+ * is validated against its kind's required fields and narrowed, junk is
+ * dropped, and — enforced by the exhaustiveness check below — no storable
+ * kind can silently fall out (the step-finish/interaction trap).
+ */
+declare function toChatMessageParts(parts: Array<Record<string, unknown>>): ChatMessagePart[];
+declare function isChatToolPart(part: ChatMessagePart): part is ChatToolPart;
+declare function isChatTextPart(part: ChatMessagePart): part is ChatTextPart;
+declare function isChatInteractionPart(part: ChatMessagePart): part is ChatInteractionPart;
+declare function isChatPlanPart(part: ChatMessagePart): part is ChatPlanPart;
+declare function isChatStepFinishPart(part: ChatMessagePart): part is ChatStepFinishPart;
+/** Widened to `unknown` — unlike its siblings this guard also runs over raw
+ *  untyped stored rows (a transcript renderer reads `message.parts` before the
+ *  typed projection), which is exactly what {@link mentionPartsFromMessageParts}
+ *  needs. `path` and `name` carry the pill; a row missing either is unrenderable.
+ *
+ *  Mirrors the write contract exactly (`parseFileMention` in `/chat-routes`,
+ *  then {@link mentionInputToPart}): a blank `name` is rejected there and so is
+ *  rejected here, and `size` — optional, but typed `number` once present — is
+ *  type-checked so `'12'` or `null` cannot ride through the guard wearing a
+ *  type it does not have. Negative sizes are NOT re-rejected: the wire screens
+ *  them, `mentionInputToPart` trusts its input, and a read guard stricter than
+ *  what the writer can emit would drop rows it produced itself. */
+declare function isChatMentionPart(part: unknown): part is ChatMentionPart;
+/** Every mention part on one message, in stored order. The projection a
+ *  transcript renderer runs before deciding which mentions the message text
+ *  already shows inline (see `segmentMentionContent` in `/web-react`). */
+declare function mentionPartsFromMessageParts(parts: ReadonlyArray<Record<string, unknown>> | ReadonlyArray<ChatMessagePart> | null | undefined): ChatMentionPart[];
+/** A validated wire mention (`parseFileMentions` in `/chat-routes`) as the
+ *  part the turn route persists. An absent/non-finite `size` is DROPPED rather
+ *  than stored as `undefined`, so a stored row never carries a key that means
+ *  nothing. */
+declare function mentionInputToPart(input: FileMention): ChatMentionPart;
+
+export { type ChatTurnRequestPayload as A, type ChatTurnPartInput as B, type ChatFilePart as C, type ChatTurnFilePartInput as D, ChatTurnInputError as E, type FileMention as F, type ChatTurnTextPartInput as G, type FileMentionsToPartsOptions as H, INLINE_PARTS_MAX_BYTES as I, type SandboxMentionPathCheck as J, assertPromptPartsWithinCap as K, buildMentionPromptBlock as L, MENTION_MAX_COUNT as M, chatTurnRequestInit as N, fileMentionsToParts as O, mediaTypeForMentionPath as P, mentionKindForPath as Q, parseChatTurnParts as R, type StorableHarnessPartKind as S, parseFileMentions as T, promptPartsByteSize as U, validateSandboxMentionPath as V, type ChatImagePart as a, type ChatInteractionPart as b, type ChatMentionKind as c, type ChatMentionPart as d, type ChatMessagePart as e, type ChatNoticePart as f, type ChatPartTime as g, type ChatPlanPart as h, type ChatReasoningPart as i, type ChatStepFinishPart as j, type ChatStepStartPart as k, type ChatSubtaskPart as l, type ChatTextPart as m, type ChatToolPart as n, type ChatToolState as o, type ChatToolStatus as p, type ChatUsageTokens as q, isChatInteractionPart as r, isChatMentionPart as s, isChatPlanPart as t, isChatStepFinishPart as u, isChatTextPart as v, isChatToolPart as w, mentionInputToPart as x, mentionPartsFromMessageParts as y, toChatMessageParts as z };

package/dist/sandbox/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentProfileMcpServer, ProvisionEvent, AgentProfileFileMount, SandboxInstance, AgentProfile, StorageConfig, ScopedTokenScope, TurnDriveResult, Sandbox } from '@tangle-network/sandbox';
+import { AgentProfileMcpServer, ProvisionEvent, SandboxInstance, AgentProfileFileMount, AgentProfile, StorageConfig, ScopedTokenScope, TurnDriveResult, Sandbox } from '@tangle-network/sandbox';
 export { StorageConfig } from '@tangle-network/sandbox';
 import { a as ToolHeaderNames } from '../auth-DuptSkWh.js';
 import { f as AppToolName, c as AppToolContext } from '../types-BEOvc_ue.js';
@@ -14,6 +14,67 @@ type Outcome<T> = {
     error: Error;
 };
 
+/**
+ * Reading arbitrary bytes out of a sandbox over an exec channel that only
+ * speaks text.
+ *
+ * `box.exec` returns stdout as a string, so a binary file has to be encoded to
+ * survive the trip: `wc -c` gives the on-disk length, `base64` gives the
+ * payload, and the decoded byte count is checked against the stat. That last
+ * check is the point of the module — an exec channel that caps or clips its
+ * output still reports `exitCode: 0` with a short buffer, which decodes into a
+ * perfectly valid but TRUNCATED file. Verifying the length turns that silent
+ * corruption into a loud failure at the boundary.
+ *
+ * Both helpers return typed outcomes; callers must inspect `succeeded` before
+ * touching `value`.
+ */
+/** The `box.exec` surface these helpers use — structural, so a caller can pass
+ *  the sandbox SDK's `SandboxInstance` directly or a narrower test double. */
+interface SandboxExecChannel {
+    exec(command: string, options?: {
+        sessionId?: string;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}
+interface SandboxExecOptions {
+    /** Run inside a named session rather than the box's default one. */
+    sessionId?: string;
+}
+type SandboxFileSizeOutcome = {
+    succeeded: true;
+    value: number;
+} | {
+    succeeded: false;
+    error: string;
+};
+type SandboxFileBytesOutcome = {
+    succeeded: true;
+    value: {
+        bytes: Uint8Array;
+        size: number;
+    };
+} | {
+    succeeded: false;
+    error: string;
+};
+/** Wraps a value in single quotes for `sh`, closing and reopening the quote
+ *  around each embedded quote (`'` → `'"'"'`). Every path these helpers
+ *  interpolate into a command goes through this — in-box filenames are
+ *  arbitrary, so spaces, quotes and `$` are ordinary content, not syntax. */
+declare function shellQuote(value: string): string;
+/** Stats a sandbox file's byte length via `wc -c`. A caller enforcing a size
+ *  cap must check this BEFORE {@link readSandboxBinaryBytes}, so an oversize
+ *  file is rejected without paying for a base64 round trip of it. */
+declare function statSandboxFileSize(box: SandboxExecChannel, absolutePath: string, options?: SandboxExecOptions): Promise<SandboxFileSizeOutcome>;
+/** Reads a sandbox file as base64 and decodes it, verifying the decoded byte
+ *  length against `expectedSize` (from a prior {@link statSandboxFileSize}). A
+ *  mismatch is reported, never returned as a short buffer. */
+declare function readSandboxBinaryBytes(box: SandboxExecChannel, absolutePath: string, expectedSize: number, options?: SandboxExecOptions): Promise<SandboxFileBytesOutcome>;
+
 interface TerminalProxyIdentity {
     userId: string;
     workspaceId: string;
@@ -436,6 +497,54 @@ declare function assertProvisionPayloadWithinCap(payload: ProvisionPayloadSectio
  * every exec inside it dies on the oversized entry.
  */
 declare function assertEnvWithinLimits(env: Record<string, string>): void;
+/** What a peek can find. `not-running` carries the platform's own state string
+ *  (`stopped`, `starting`, `failed`, …) — narrowing it to a union here would
+ *  drop states the platform adds later, and every caller wants it for a log. */
+type PeekWorkspaceSandboxOutcome = {
+    status: 'running';
+    box: SandboxInstance;
+} | {
+    status: 'not-running';
+    state: string;
+    box: SandboxInstance;
+} | {
+    status: 'absent';
+};
+/**
+ * Read-only twin of {@link ensureWorkspaceSandbox}: report whether a
+ * workspace's box exists and is running, WITHOUT provisioning, resuming, or
+ * bootstrapping anything.
+ *
+ * This is what a read-mostly path needs — a file-index route's `authorize`
+ * seam, a stale-lock reconciliation, a status badge. Calling `ensure` from one
+ * of those spins a box up as a side effect of a read (legal-agent #509), and
+ * costs the caller a cold start it never asked for.
+ *
+ * Matching is on BOTH the box key and the display name, IN THAT ORDER.
+ * `client.get(id)` keys on the platform's opaque sandbox id, not the
+ * deterministic key a product derives from a workspace, and is itself a
+ * `list().find` underneath — so a lookup by identity has to list and match.
+ * Provisioning here always stamps `name` with the box key, so the key is the
+ * authoritative match; the display-name pass exists only to adopt boxes on a
+ * host that predates that convention. The order matters: a single unordered
+ * `find` returns whichever the platform happens to list first, so a stopped
+ * display-name box could shadow a running box-key one and report
+ * `not-running` for a live workspace.
+ *
+ * Unlike `ensure`, this lists ALL statuses in one call: distinguishing "no box"
+ * from "box is stopped" is the whole point, and a status-filtered list cannot.
+ *
+ * A `client.list()` rejection propagates RAW, unlike the `Outcome`-wrapping
+ * helpers `ensure` uses internally. That is deliberate: there is no honest
+ * outcome to map a listing failure onto — it is not `absent` and not
+ * `not-running`, and inventing one would have callers act on a status the
+ * platform never reported. Callers that must tolerate it say so explicitly
+ * (the stale-turn-lock policy documents "a throw is treated as unreachable").
+ */
+declare function peekWorkspaceSandbox(shell: SandboxRuntimeConfig, options: {
+    workspaceId: string;
+    userId?: string;
+}): Promise<PeekWorkspaceSandboxOutcome>;
 declare function ensureWorkspaceSandbox(shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions): Promise<SandboxInstance>;
 interface ResolvedModel {
     model: string;
@@ -549,4 +658,4 @@ declare function classifySeveredStream(event: unknown): SandboxStepTransition |
 declare function isTerminalPromptEvent(event: unknown): boolean;
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, readSecret, resetClientCache, resolveModel, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, splitDeferredProfileFiles, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, resetClientCache, resolveModel, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -34,6 +34,8 @@ import {
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
   mintTerminalProxyToken,
+  peekWorkspaceSandbox,
+  readSandboxBinaryBytes,
   readSecret,
   resetClientCache,
   resolveModel,
@@ -44,7 +46,9 @@ import {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  shellQuote,
   splitDeferredProfileFiles,
+  statSandboxFileSize,
   storeSecret,
   streamSandboxPrompt,
   syncSandboxMemberAdd,
@@ -54,7 +58,7 @@ import {
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-5GWXCSLQ.js";
+} from "../chunk-5RJNEEO2.js";
 import "../chunk-E7QYOOON.js";
 import "../chunk-PJC4NXPA.js";
 import "../chunk-7EVZUIHW.js";
@@ -97,6 +101,8 @@ export {
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
   mintTerminalProxyToken,
+  peekWorkspaceSandbox,
+  readSandboxBinaryBytes,
   readSecret,
   resetClientCache,
   resolveModel,
@@ -107,7 +113,9 @@ export {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  shellQuote,
   splitDeferredProfileFiles,
+  statSandboxFileSize,
   storeSecret,
   streamSandboxPrompt,
   syncSandboxMemberAdd,

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

@@ -5,13 +5,14 @@ export { d as ComposerAnswerDelivery, I as INTERACTION_CANCEL_EVENT, e as INTERA
 import { ChatPlan } from '../plans/index.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 { F as FileMention, d as ChatMentionPart } from '../parts-1_3y2JmR.js';
+export { c as ChatMentionKind, D as ChatTurnFilePartInput, B as ChatTurnPartInput, A as ChatTurnRequestPayload, L as buildMentionPromptBlock, N as chatTurnRequestInit, O as fileMentionsToParts, P as mediaTypeForMentionPath, x as mentionInputToPart, Q as mentionKindForPath, y as mentionPartsFromMessageParts } from '../parts-1_3y2JmR.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 FileIndexReadyResponse, c as FileIndexResponse, d as FileIndexWarmingResponse } from '../file-index-Bn6sitKb.js';
 
 type DurablePlanDecision = 'approved' | 'rejected';
 /** Stable authority receipt for the follow-up turn dispatched by a plan
@@ -608,6 +609,53 @@ interface UseFileMentionsResult {
 }
 declare function useFileMentions(options: UseFileMentionsOptions): UseFileMentionsResult;
 
+/**
+ * Transcript-side counterpart to the composer's `@`-mention primitive
+ * (sandbox-ui#184). The composer serializes a picked file into the message
+ * text as `@<path>`; this module is the exact inverse — it finds those tokens
+ * again in a PERSISTED message and splits the text so a renderer can draw a
+ * pill where the user typed one and leave the rest as prose.
+ *
+ * Pure and product-agnostic: no React, no fetch, no DOM. The only input beyond
+ * the text is the message's OWN mention parts, so one message can never render
+ * a pill for a path another message mentioned.
+ *
+ * `ChatMentionPart` and the runtime helpers `mentionInputToPart` /
+ * `mentionPartsFromMessageParts` are re-exported here from `../chat-store/parts`
+ * directly (not the `/chat-store` barrel), so a browser bundle gets the mention
+ * vocabulary and its converters without importing `/chat-store`, whose barrel
+ * pulls the drizzle peer.
+ */
+
+/** One run of a segmented message: literal prose, or a matched mention with
+ *  the part that produced it. `text` for a mention segment is the token as it
+ *  appears in the message (`@<path>`), so a renderer that ignores `part` still
+ *  reproduces the original string exactly. */
+interface MentionTextSegment {
+    type: 'text' | 'mention';
+    text: string;
+    part?: ChatMentionPart;
+}
+/**
+ * Split a message's text into plain-text and mention segments by matching
+ * `@<path>` runs against that message's own mention parts.
+ *
+ * Only a part whose exact `@<path>` token appears in `content`, at a token
+ * boundary on both sides, counts as a match; everything else — including
+ * unrelated `@` text — passes through as plain text untouched. When two parts'
+ * tokens both match at the same position (one path a prefix of another), the
+ * LONGEST token wins, so nested-looking paths split at the right boundary.
+ *
+ * Returns the matched parts alongside the segments: a caller that also renders
+ * a fallback chip row can drop the chip for anything now shown inline and keep
+ * it only for mentions the text does not actually contain (a restored draft, a
+ * queued message whose text was edited).
+ */
+declare function segmentMentionContent(content: string, parts: ReadonlyArray<ChatMentionPart>): {
+    segments: MentionTextSegment[];
+    matched: Set<ChatMentionPart>;
+};
+
 /**
  * Provider brand marks — real logo path data (simple-icons / SVG Logos, both
  * CC0) inlined so the picker shows actual provider identity instead of
@@ -1043,4 +1091,4 @@ declare function useThinkingSeconds(active: boolean): number;
  */
 declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, durableCards, 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, type ChatInteractionRestoreMode, 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 DurableChatCard, DurableChatCards, type DurableChatCardsProps, type DurableInteractionAnswerSubmitterOptions, DurablePlanCard, type DurablePlanCardProps, DurablePlanClientError, type DurablePlanCurrentInput, type DurablePlanDecision, type DurablePlanDecisionClient, type DurablePlanDecisionClientOptions, type DurablePlanDecisionInput, type DurablePlanDecisionResult, type DurablePlanFollowUpReceipt, 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, InteractionAnswers, type InteractionAttemptStore, 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, type RestoreChatInteractionsOptions, RunDrillIn, type RunDrillInProps, SeatPaywall, type SeatPaywallProps, type SmoothRevealOptions, type StreamChatOptions, type SubmitInteractionAnswer, type ToolDetailRenderers, type ToolRunRecord, type ToolRunStep, type UseChatInteractionsOptions, type UseChatInteractionsResult, type UseDurablePlanFlowOptions, type UseDurablePlanFlowResult, type UseFileMentionsOptions, type UseFileMentionsResult, type WaterfallRow, activityTone, buildAnswerData, cancelChatInteraction, consumeChatStream, createDurableInteractionAnswerSubmitter, createDurablePlanDecisionClient, createInteractionAnswerSubmitter, createMemoryInteractionAttemptStore, createSessionInteractionAttemptStore, dispatchChatStreamLine, durableChatCardsFromParts, fieldAnswer, fieldValuesFromAnswers, formatActivityCost, formatActivityDuration, formatModelCost, formatTokensPerSecond, hasSecretField, hydrateChatInteractions, interactionStatusLabels, interactionSubmissionSignature, interactionTerminalNotes, isLateAnswerableStatus, lateAnswerMessage, mergeActivityPages, nextRevealCount, pendingApprovalOf, rankFileMentions, resolveChatInteraction, responseErrorMessage, restoreChatInteractions, streamChatTurn, terminalizePendingChatInteractions, upsertChatInteraction, useChatInteractions, useDurablePlanFlow, useFileMentions, 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, type ChatInteractionRestoreMode, ChatInteractionStatus, ChatMentionPart, 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 DurableChatCard, DurableChatCards, type DurableChatCardsProps, type DurableInteractionAnswerSubmitterOptions, DurablePlanCard, type DurablePlanCardProps, DurablePlanClientError, type DurablePlanCurrentInput, type DurablePlanDecision, type DurablePlanDecisionClient, type DurablePlanDecisionClientOptions, type DurablePlanDecisionInput, type DurablePlanDecisionResult, type DurablePlanFollowUpReceipt, 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, InteractionAnswers, type InteractionAttemptStore, InteractionBadge, type InteractionBadgeVariant, InteractionCancelData, InteractionPlanCard, type InteractionPlanCardProps, InteractionQuestionCard, type InteractionQuestionCardProps, InteractionRequestWire, type InteractionSubmitResult, type MentionItem, type MentionTextSegment, MissionActivityLane, type MissionActivityLaneProps, ModelPicker, type ModelPickerProps, type ProposalApprovalHandlers, ProviderLogo, type ProviderLogoProps, QuestionOptionList, type QuestionOptionListProps, type RestoreChatInteractionsOptions, RunDrillIn, type RunDrillInProps, SeatPaywall, type SeatPaywallProps, type SmoothRevealOptions, type StreamChatOptions, type SubmitInteractionAnswer, type ToolDetailRenderers, type ToolRunRecord, type ToolRunStep, type UseChatInteractionsOptions, type UseChatInteractionsResult, type UseDurablePlanFlowOptions, type UseDurablePlanFlowResult, type UseFileMentionsOptions, type UseFileMentionsResult, type WaterfallRow, activityTone, buildAnswerData, cancelChatInteraction, consumeChatStream, createDurableInteractionAnswerSubmitter, createDurablePlanDecisionClient, createInteractionAnswerSubmitter, createMemoryInteractionAttemptStore, createSessionInteractionAttemptStore, dispatchChatStreamLine, durableChatCardsFromParts, fieldAnswer, fieldValuesFromAnswers, formatActivityCost, formatActivityDuration, formatModelCost, formatTokensPerSecond, hasSecretField, hydrateChatInteractions, interactionStatusLabels, interactionSubmissionSignature, interactionTerminalNotes, isLateAnswerableStatus, lateAnswerMessage, mergeActivityPages, nextRevealCount, pendingApprovalOf, rankFileMentions, resolveChatInteraction, responseErrorMessage, restoreChatInteractions, segmentMentionContent, streamChatTurn, terminalizePendingChatInteractions, upsertChatInteraction, useChatInteractions, useDurablePlanFlow, useFileMentions, usePending, usePopover, useSmoothText, useThinkingSeconds, waterfallLayout };