@tangle-network/agent-app 0.43.40 → 0.43.42

package/dist/teams/index.js

@@ -3,15 +3,6 @@ import {
   isInviteTokenShape,
   validateInviteToken
 } from "../chunk-3SVAA3MA.js";
-import {
-  INVITATION_EXPIRY_DAYS,
-  generateInvitationToken,
-  getInvitationExpiresAt,
-  inviteUrlForToken,
-  normalizeInvitationEmail,
-  parseInvitationPermission,
-  renderInvitationEmail
-} from "../chunk-WEBBJBDH.js";
 import {
   ASSIGNABLE_WORKSPACE_ROLES,
   ORGANIZATION_ROLES,
@@ -27,6 +18,15 @@ import {
   workspaceRoleToCollaborationAccess,
   workspaceRoleToSandboxRole
 } from "../chunk-63CE7FEZ.js";
+import {
+  INVITATION_EXPIRY_DAYS,
+  generateInvitationToken,
+  getInvitationExpiresAt,
+  inviteUrlForToken,
+  normalizeInvitationEmail,
+  parseInvitationPermission,
+  renderInvitationEmail
+} from "../chunk-WEBBJBDH.js";
 export {
   ASSIGNABLE_WORKSPACE_ROLES,
   INVITATION_EXPIRY_DAYS,

package/dist/teams/invitations-api.js

@@ -2,6 +2,9 @@ import {
   SeatLimitError
 } from "../chunk-SWUVTGMR.js";
 import "../chunk-3SVAA3MA.js";
+import {
+  hasWorkspaceRole
+} from "../chunk-63CE7FEZ.js";
 import {
   generateInvitationToken,
   getInvitationExpiresAt,
@@ -9,9 +12,6 @@ import {
   normalizeInvitationEmail,
   parseInvitationPermission
 } from "../chunk-WEBBJBDH.js";
-import {
-  hasWorkspaceRole
-} from "../chunk-63CE7FEZ.js";
 
 // src/teams/invitations-api.ts
 import { and, eq, lte, sql } from "drizzle-orm";

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

@@ -1,15 +1,200 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { C as ChatInteraction, a as ChatInteractionField, b as ChatInteractionStatus, c as ChatSelectField, g as InteractionCancelData, i as InteractionRequestWire } from '../contract-DYbTzEDf.js';
-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 { a as ChatInteractionField, h as InteractionAnswers, b as ChatInteractionStatus, C as ChatInteraction, i as InteractionCancelData, c as ChatSelectField, k as InteractionRequestWire } from '../contract-KfqJh_au.js';
+export { d as ComposerAnswerDelivery, I as INTERACTION_CANCEL_EVENT, e as INTERACTION_EVENT, f as INTERACTION_RESOLVED_EVENT, g as InteractionAnswerValue, j as InteractionPersistedPart, N as NoticeKind, l as NoticePersistedPart, P as ParseInteractionAnswersResult, m as ParseInteractionResult, n as canTransitionInteractionStatus, o as cancelStatusFor, p as composerAnswerData, q as composerAnswerDeliveries, r as dedupeQuestionInteractionsByContent, s as fieldAcceptsFreeText, t as interactionFromWireRequest, u as interactionPartKey, v as interactionToPersistedPart, w as isRenderableInteractionKind, x as isSafeInteractionFieldKey, y as isTerminalInteractionStatus, z as noticePart, A as noticePartKey, B as parseInteractionAnswers, D as parseInteractionCancel, E as parseInteractionRequest, F as persistedPartToInteraction, G as questionInteractionContentSignature, H as stampInteractionAnswers } from '../contract-KfqJh_au.js';
+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 { 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';
+
+type DurablePlanDecision = 'approved' | 'rejected';
+/** Stable authority receipt for the follow-up turn dispatched by a plan
+ * decision. Consumers must make `attachFollowUp` idempotent by `receiptId`;
+ * reload and retry deliberately invoke it again. */
+interface DurablePlanFollowUpReceipt {
+    receiptId: string;
+    planId: string;
+    revision: number;
+    turnId: string;
+    state: string;
+}
+interface DurablePlanDecisionResult {
+    plan: ChatPlan;
+    followUp?: DurablePlanFollowUpReceipt;
+    idempotent: boolean;
+    projectionPending?: boolean;
+    effectPending?: boolean;
+}
+interface DurablePlanDecisionInput {
+    planId: string;
+    revision: number;
+    decision: DurablePlanDecision;
+    feedback?: string;
+}
+interface DurablePlanCurrentInput {
+    planId: string;
+    revision?: number;
+}
+interface DurablePlanDecisionClient {
+    current: (input: DurablePlanCurrentInput) => Promise<DurablePlanDecisionResult>;
+    decide: (input: DurablePlanDecisionInput) => Promise<DurablePlanDecisionResult>;
+}
+declare class DurablePlanClientError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly currentPlan?: ChatPlan | undefined;
+    constructor(message: string, status: number, code?: string | undefined, currentPlan?: ChatPlan | undefined);
+}
+interface DurablePlanDecisionClientOptions {
+    url: string | ((input: DurablePlanCurrentInput | DurablePlanDecisionInput) => string);
+    body?: Record<string, unknown> | ((input: DurablePlanDecisionInput) => Record<string, unknown>);
+    fetchImpl?: typeof fetch;
+}
+/** Browser client for the shared durable-plan route. The route URL and all
+ * product routing fields are injected; workspace/session identity is still
+ * resolved and authorized on the server. */
+declare function createDurablePlanDecisionClient(options: DurablePlanDecisionClientOptions): DurablePlanDecisionClient;
+interface UseDurablePlanFlowOptions {
+    plan: ChatPlan;
+    client: DurablePlanDecisionClient;
+    /** Must be idempotent by receipt.receiptId. */
+    attachFollowUp?: (receipt: DurablePlanFollowUpReceipt) => Promise<void> | void;
+    onUpdated?: (plan: ChatPlan) => void;
+}
+interface UseDurablePlanFlowResult {
+    plan: ChatPlan;
+    deciding: DurablePlanDecision | null;
+    restoring: boolean;
+    error: string | null;
+    decide: (decision: DurablePlanDecision, feedback?: string) => Promise<DurablePlanDecisionResult | null>;
+    restore: () => Promise<DurablePlanDecisionResult | null>;
+    clearError: () => void;
+}
+/** Shared plan decision controller. It coalesces only concurrent attachment
+ * attempts; a later retry/restore calls the consumer's idempotent transport
+ * again so a lost response cannot strand an already-dispatched follow-up. */
+declare function useDurablePlanFlow(options: UseDurablePlanFlowOptions): UseDurablePlanFlowResult;
+
+/**
+ * Shared answer-building + submit plumbing for the interaction cards
+ * (question, plan). Client-safe, no React: cards own their state, this owns
+ * the wire. Lifted from the gtm-agent fork (the most fix-absorbed of the three
+ * product copies), including the 30s submit timeout that keeps a dead route
+ * from wedging a card in "Submitting…".
+ */
+
+/** Status-badge labels for an interaction card. `cancelled`/`expired` read the
+ *  same across cards; each card supplies its own verbs for the other states
+ *  (a question is answered/declined; a plan is approved/rejected). */
+declare function interactionStatusLabels(labels: {
+    pending: string;
+    answered: string;
+    declined: string;
+}): Record<ChatInteractionStatus, string>;
+/** Terminal-state notes for an interaction card. The expiry/withdrawal lines
+ *  share one shape around the card's noun ("question"/"plan"); any extra notes
+ *  (e.g. a plan's `declined` revision line) merge on top. */
+declare function interactionTerminalNotes(noun: string, extra?: Partial<Record<ChatInteractionStatus, string>>): Partial<Record<ChatInteractionStatus, string>>;
+type FieldValues = Record<string, {
+    selected?: string[];
+    text?: string;
+    custom?: string;
+}>;
+/** Converts acknowledged, persisted answers back into the local field state
+ * consumed by the shared cards. Persisted values are authoritative: this is
+ * intentionally used only when an interaction carries `answers`, never to
+ * guess an answer from the absence of an outstanding sidecar ask. */
+declare function fieldValuesFromAnswers(fields: ChatInteractionField[], answers: InteractionAnswers | undefined): FieldValues;
+/** The submitted value for one field, or null when it has no answer yet. */
+declare function fieldAnswer(field: ChatInteractionField, values: FieldValues): InteractionData[string] | null;
+/** All required fields answered → the respond payload; else null (not
+ *  submittable yet). Optional unanswered fields are omitted. */
+declare function buildAnswerData(fields: ChatInteractionField[], values: FieldValues): InteractionData | null;
+declare function isLateAnswerableStatus(status: ChatInteractionStatus): boolean;
+/** Secrets must never leave the sidecar answer channel for the visible chat
+ *  transcript, so a secret-bearing ask cannot be late-answered. */
+declare function hasSecretField(fields: ChatInteractionField[]): boolean;
+/** Renders the late answer as a self-contained chat message: the original
+ *  question, its context, and the user's answer(s). */
+declare function lateAnswerMessage(interaction: ChatInteraction, data: InteractionData): string;
+declare const INTERACTION_SUBMIT_TIMEOUT_MS = 30000;
+declare const INTERACTION_SUBMIT_TIMEOUT_MESSAGE = "Could not reach the agent. Try again.";
+/** One card submission: which ask, resolved how, with what answers. */
+interface InteractionAnswerSubmission {
+    id: string;
+    outcome: 'accepted' | 'declined';
+    data?: InteractionData;
+}
+type InteractionSubmitResult = {
+    ok: true;
+} | {
+    ok: false;
+    expired: boolean;
+    message: string;
+};
+/** The cards' only side-effect seam: POST one resolution, report the normalized
+ *  outcome. Products bind their route URL + routing fields (workspaceId,
+ *  threadId, session path param) via `createInteractionAnswerSubmitter` or a
+ *  hand-rolled implementation. */
+type SubmitInteractionAnswer = (submission: InteractionAnswerSubmission) => Promise<InteractionSubmitResult>;
+/** Extracts the most specific error message a route returned. */
+declare function responseErrorMessage(res: Response): Promise<{
+    code?: string;
+    message: string;
+}>;
+interface InteractionAnswerSubmitterOptions {
+    /** The product's answer route (the POST half of `createInteractionAnswerRoute`).
+     *  A function when the URL carries the session (e.g. `/api/sessions/${id}/interactions`). */
+    url: string | ((submission: InteractionAnswerSubmission) => string);
+    /** Extra routing fields merged into the POST body (e.g. workspaceId, threadId). */
+    body?: Record<string, unknown> | ((submission: InteractionAnswerSubmission) => Record<string, unknown>);
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Builds the `SubmitInteractionAnswer` the cards consume: POSTs
+ * `{ ...routingFields, id, outcome, data? }` with an abortable timeout and
+ * normalizes the outcome. `expired` is the 410 path — the ask is gone
+ * (answered elsewhere, timed out, or the session moved on) and the card must
+ * flip to the same dead state a cancel event produces.
+ */
+declare function createInteractionAnswerSubmitter(options: InteractionAnswerSubmitterOptions): SubmitInteractionAnswer;
+
+type DurableChatCard = {
+    kind: 'plan';
+    key: string;
+    plan: ChatPlan;
+} | {
+    kind: 'interaction';
+    key: string;
+    interaction: ChatInteraction;
+};
+/** Converts persisted/live parts to canonical cards. Legacy interaction-plan
+ * cards are suppressed only when their raw part carries an explicit planId and
+ * revision matching a durable plan. Identical markdown alone is never proof. */
+declare function durableChatCardsFromParts(parts: Array<Record<string, unknown>>): DurableChatCard[];
+interface DurableChatCardsProps {
+    parts: Array<Record<string, unknown>>;
+    canWrite: boolean;
+    submitInteraction: SubmitInteractionAnswer;
+    decidePlan: (plan: ChatPlan, decision: DurablePlanDecision, feedback?: string) => Promise<DurablePlanDecisionResult | null>;
+    decidingPlan?: (plan: ChatPlan) => DurablePlanDecision | null;
+    planError?: (plan: ChatPlan) => string | null;
+    onInteractionResolved?: (id: string, status: Exclude<ChatInteraction['status'], 'pending'>, answers?: InteractionAnswers) => void;
+    onLateAnswer?: (message: string) => boolean | void | Promise<boolean | void>;
+    renderMarkdown?: (markdown: string) => ReactNode;
+    className?: string;
+}
+/** Ready-to-embed canonical question/plan card lane for persisted assistant
+ * parts. Apps inject transport and styling callbacks instead of rebuilding the
+ * lifecycle/render switch. */
+declare function DurableChatCards({ parts, canWrite, submitInteraction, decidePlan, decidingPlan, planError, onInteractionResolved, onLateAnswer, renderMarkdown, className, }: DurableChatCardsProps): react.JSX.Element | null;
 
 /**
  * Client-side chat-stream consumption — the NDJSON parse loop every agent
@@ -63,6 +248,10 @@ interface ChatStreamCallbacks {
      *  user", not "model working". Optional — a consumer that doesn't wire it
      *  parses the same stream unchanged. */
     onInteraction?: (interaction: ChatInteraction) => void;
+    /** A terminal withdrawal/timeout for a previously emitted interaction. */
+    onInteractionCancel?: (cancel: InteractionCancelData) => void;
+    /** A durable-plan snapshot from any plan lifecycle event. */
+    onPlan?: (plan: ChatPlan) => void;
 }
 interface ConsumeChatStreamResult {
     turnId: string | null;
@@ -165,86 +354,6 @@ interface ChatComposerProps {
 }
 declare function ChatComposer({ onSend, onSendParts, onCancel, isStreaming, disabled, placeholder, value, onValueChange, initialValue, seed, onSeedApplied, controls, controlsPlacement, onAttach, onAttachFolder, pendingFiles, onRemoveFile, accept, dropTitle, dropDescription, focusShortcut, sendLabel, className, }: ChatComposerProps): react.JSX.Element;
 
-/**
- * Shared answer-building + submit plumbing for the interaction cards
- * (question, plan). Client-safe, no React: cards own their state, this owns
- * the wire. Lifted from the gtm-agent fork (the most fix-absorbed of the three
- * product copies), including the 30s submit timeout that keeps a dead route
- * from wedging a card in "Submitting…".
- */
-
-/** Status-badge labels for an interaction card. `cancelled`/`expired` read the
- *  same across cards; each card supplies its own verbs for the other states
- *  (a question is answered/declined; a plan is approved/rejected). */
-declare function interactionStatusLabels(labels: {
-    pending: string;
-    answered: string;
-    declined: string;
-}): Record<ChatInteractionStatus, string>;
-/** Terminal-state notes for an interaction card. The expiry/withdrawal lines
- *  share one shape around the card's noun ("question"/"plan"); any extra notes
- *  (e.g. a plan's `declined` revision line) merge on top. */
-declare function interactionTerminalNotes(noun: string, extra?: Partial<Record<ChatInteractionStatus, string>>): Partial<Record<ChatInteractionStatus, string>>;
-type FieldValues = Record<string, {
-    selected?: string[];
-    text?: string;
-    custom?: string;
-}>;
-/** The submitted value for one field, or null when it has no answer yet. */
-declare function fieldAnswer(field: ChatInteractionField, values: FieldValues): InteractionData[string] | null;
-/** All required fields answered → the respond payload; else null (not
- *  submittable yet). Optional unanswered fields are omitted. */
-declare function buildAnswerData(fields: ChatInteractionField[], values: FieldValues): InteractionData | null;
-declare function isLateAnswerableStatus(status: ChatInteractionStatus): boolean;
-/** Secrets must never leave the sidecar answer channel for the visible chat
- *  transcript, so a secret-bearing ask cannot be late-answered. */
-declare function hasSecretField(fields: ChatInteractionField[]): boolean;
-/** Renders the late answer as a self-contained chat message: the original
- *  question, its context, and the user's answer(s). */
-declare function lateAnswerMessage(interaction: ChatInteraction, data: InteractionData): string;
-declare const INTERACTION_SUBMIT_TIMEOUT_MS = 30000;
-declare const INTERACTION_SUBMIT_TIMEOUT_MESSAGE = "Could not reach the agent. Try again.";
-/** One card submission: which ask, resolved how, with what answers. */
-interface InteractionAnswerSubmission {
-    id: string;
-    outcome: 'accepted' | 'declined';
-    data?: InteractionData;
-}
-type InteractionSubmitResult = {
-    ok: true;
-} | {
-    ok: false;
-    expired: boolean;
-    message: string;
-};
-/** The cards' only side-effect seam: POST one resolution, report the normalized
- *  outcome. Products bind their route URL + routing fields (workspaceId,
- *  threadId, session path param) via `createInteractionAnswerSubmitter` or a
- *  hand-rolled implementation. */
-type SubmitInteractionAnswer = (submission: InteractionAnswerSubmission) => Promise<InteractionSubmitResult>;
-/** Extracts the most specific error message a route returned. */
-declare function responseErrorMessage(res: Response): Promise<{
-    code?: string;
-    message: string;
-}>;
-interface InteractionAnswerSubmitterOptions {
-    /** The product's answer route (the POST half of `createInteractionAnswerRoute`).
-     *  A function when the URL carries the session (e.g. `/api/sessions/${id}/interactions`). */
-    url: string | ((submission: InteractionAnswerSubmission) => string);
-    /** Extra routing fields merged into the POST body (e.g. workspaceId, threadId). */
-    body?: Record<string, unknown> | ((submission: InteractionAnswerSubmission) => Record<string, unknown>);
-    timeoutMs?: number;
-    fetchImpl?: typeof fetch;
-}
-/**
- * Builds the `SubmitInteractionAnswer` the cards consume: POSTs
- * `{ ...routingFields, id, outcome, data? }` with an abortable timeout and
- * normalizes the outcome. `expired` is the 410 path — the ask is gone
- * (answered elsewhere, timed out, or the session moved on) and the card must
- * flip to the same dead state a cancel event produces.
- */
-declare function createInteractionAnswerSubmitter(options: InteractionAnswerSubmitterOptions): SubmitInteractionAnswer;
-
 type InteractionBadgeVariant = 'outline' | 'default' | 'destructive';
 declare function InteractionBadge({ variant, children }: {
     variant: InteractionBadgeVariant;
@@ -281,7 +390,7 @@ interface InteractionQuestionCardProps {
     submitAnswer: SubmitInteractionAnswer;
     /** Fired when this card resolves locally (answered, or discovered expired
      *  via a 410) so the stream/route state stays in sync. */
-    onResolved?: (id: string, status: Exclude<ChatInteractionStatus, 'pending'>) => void;
+    onResolved?: (id: string, status: Exclude<ChatInteractionStatus, 'pending'>, answers?: ChatInteraction['answers']) => void;
     /** Delivers a late answer (the ask expired/was withdrawn) as a fresh chat
      *  turn. Return/resolve `false` when the send was rejected so the card stays
      *  retryable. Omit to hide the late-answer affordance entirely. */
@@ -306,6 +415,34 @@ interface InteractionPlanCardProps {
 }
 declare function InteractionPlanCard({ interaction, canWrite, submitAnswer, onResolved, renderMarkdown, className, }: InteractionPlanCardProps): react.JSX.Element;
 
+interface DurablePlanCardProps {
+    plan: ChatPlan;
+    canWrite: boolean;
+    decide: (decision: DurablePlanDecision, feedback?: string) => Promise<DurablePlanDecisionResult | null>;
+    deciding?: DurablePlanDecision | null;
+    error?: string | null;
+    renderMarkdown?: (markdown: string) => ReactNode;
+    className?: string;
+}
+declare function DurablePlanCard({ plan, canWrite, decide, deciding, error, renderMarkdown, className, }: DurablePlanCardProps): react.JSX.Element;
+
+interface InteractionAttemptStore {
+    get(interactionId: string, submissionSignature: string): string | null;
+    set(interactionId: string, submissionSignature: string, attemptKey: string): void;
+    delete(interactionId: string, submissionSignature: string): void;
+}
+declare function createSessionInteractionAttemptStore(storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>, namespace?: string): InteractionAttemptStore;
+declare function createMemoryInteractionAttemptStore(): InteractionAttemptStore;
+declare function interactionSubmissionSignature(submission: InteractionAnswerSubmission): string;
+interface DurableInteractionAnswerSubmitterOptions extends InteractionAnswerSubmitterOptions {
+    attempts: InteractionAttemptStore;
+    createAttemptKey?: () => string;
+}
+/** Answer submitter for a durable interaction route. One opaque attempt key is
+ * retained for an ambiguous transport/5xx result and reused after reload. A
+ * changed answer has a different signature and therefore a new attempt. */
+declare function createDurableInteractionAnswerSubmitter(options: DurableInteractionAnswerSubmitterOptions): SubmitInteractionAnswer;
+
 /**
  * useChatInteractions — the interaction-state wiring every consumer of
  * `ChatStreamCallbacks.onInteraction` re-implements: an id-keyed,
@@ -335,14 +472,28 @@ declare function upsertChatInteraction(list: ChatInteraction[], interaction: Cha
  *  `expired` (reason:"timeout") or `cancelled`. */
 declare function cancelChatInteraction(list: ChatInteraction[], cancel: InteractionCancelData): ChatInteraction[];
 /** Marks one ask resolved locally (the card's `onResolved`). Forward-only. */
-declare function resolveChatInteraction(list: ChatInteraction[], id: string, status: Exclude<ChatInteractionStatus, 'pending'>): ChatInteraction[];
+declare function resolveChatInteraction(list: ChatInteraction[], id: string, status: Exclude<ChatInteractionStatus, 'pending'>, answers?: InteractionAnswers): ChatInteraction[];
 /** Settles every still-pending ask when the turn ends: `answered` for a turn
  *  that completed cleanly, `expired` for one that failed. */
 declare function terminalizePendingChatInteractions(list: ChatInteraction[], status: Extract<ChatInteractionStatus, 'answered' | 'expired'>): ChatInteraction[];
-/** Reload restore from the answer route's GET list: every listed ask is
- *  outstanding (upserted pending), and every previously-pending ask the sidecar
- *  no longer lists was resolved while we were away (settled as answered). */
-declare function restoreChatInteractions(list: ChatInteraction[], outstanding: InteractionRequestWire[]): ChatInteraction[];
+type ChatInteractionRestoreMode = 'legacy' | 'durable';
+interface RestoreChatInteractionsOptions {
+    /**
+     * `legacy` settles pending asks absent from the sidecar list as answered,
+     * preserving the pre-durable restore contract. `durable` leaves them
+     * pending because absence is ambiguous until `hydrateChatInteractions`
+     * applies the durable projection.
+     */
+    mode?: ChatInteractionRestoreMode;
+}
+/** Reload restore from the answer route's GET list. Legacy consumers retain
+ * the historical absence→answered behavior; durable consumers opt into the
+ * ambiguity-preserving mode and apply terminal parts through `hydrate`. */
+declare function restoreChatInteractions(list: ChatInteraction[], outstanding: InteractionRequestWire[], options?: RestoreChatInteractionsOptions): ChatInteraction[];
+/** Applies transcript/state-store projections after reload. Terminal state and
+ * acknowledged answer values enrich an existing pending card without relying
+ * on the sidecar's outstanding-list absence. */
+declare function hydrateChatInteractions(list: ChatInteraction[], persisted: ChatInteraction[]): ChatInteraction[];
 interface UseChatInteractionsResult {
     /** All known interactions, insertion-ordered. */
     interactions: ChatInteraction[];
@@ -353,15 +504,109 @@ interface UseChatInteractionsResult {
     /** Wire to `interaction.cancel` events. */
     applyCancel: (cancel: InteractionCancelData) => void;
     /** Wire to the cards' `onResolved`. */
-    markResolved: (id: string, status: Exclude<ChatInteractionStatus, 'pending'>) => void;
+    markResolved: (id: string, status: Exclude<ChatInteractionStatus, 'pending'>, answers?: InteractionAnswers) => void;
     /** Wire to the answer route's GET list after a reload/reconnect. */
-    restore: (outstanding: InteractionRequestWire[]) => void;
+    restore: (outstanding: InteractionRequestWire[], options?: RestoreChatInteractionsOptions) => void;
+    /** Apply durable transcript/state projections after a reload. */
+    hydrate: (persisted: ChatInteraction[]) => void;
     /** Settle still-pending asks when the turn ends. */
     terminalizePending: (status: Extract<ChatInteractionStatus, 'answered' | 'expired'>) => void;
     /** Drop everything (thread switch). */
     reset: () => void;
 }
-declare function useChatInteractions(): UseChatInteractionsResult;
+type UseChatInteractionsOptions = RestoreChatInteractionsOptions;
+declare function useChatInteractions(options?: UseChatInteractionsOptions): 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
@@ -709,6 +954,9 @@ interface ChatUiMessage extends ChatMessageMetrics {
      *  present and non-empty it is rendered in place of `content` + `toolCalls`;
      *  both remain the fallback for producers that don't segment a turn. */
     segments?: ChatMessageSegment[];
+    /** Persisted assistant parts. When `ChatMessages.durableCards` is supplied,
+     * shared plan/question cards render directly from these projections. */
+    parts?: Array<Record<string, unknown>>;
 }
 interface ChatMessagesProps {
     messages: ChatUiMessage[];
@@ -718,6 +966,9 @@ interface ChatMessagesProps {
     renderMarkdown?: (content: string) => ReactNode;
     /** Extra per-message content (artifacts, custom panels) appended after the body. */
     renderExtras?: (message: ChatUiMessage) => ReactNode;
+    /** Canonical durable plan/question card wiring. Apps inject only transport,
+     * access, and optional visual callbacks; card selection/dedupe stays shared. */
+    durableCards?: Omit<DurableChatCardsProps, 'parts' | 'renderMarkdown'>;
     userLabel?: string;
     agentLabel?: string;
     /** Render the trailing "agent is thinking" row. */
@@ -790,6 +1041,6 @@ declare function useThinkingSeconds(active: boolean): number;
  * model id, tokens/sec, and cost, plus a collapsible thinking section and
  * tool-call chips.
  */
-declare function ChatMessages({ messages, models, renderMarkdown, renderExtras, userLabel, agentLabel, loading, approval, onToolCallClick, toolRenderers, error, onRetry, renderEmpty, emptyState, header, }: ChatMessagesProps): react.JSX.Element;
+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, 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, 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 };