@tangle-network/sandbox-ui 0.104.0 → 0.105.0

package/dist/chat.d.ts

@@ -60,10 +60,9 @@ declare function ReasoningLevelPicker({ value, onChange, disabled, className, tr
 /**
  * Limits applied when staging files onto a composer.
  *
- * @deprecated Composer-only helper of the legacy AgentComposer. Use
- * ChatComposer from `@tangle-network/agent-app/web-react` — the canonical
- * composer. AgentComposer is frozen and will be removed at sandbox-ui's next
- * breaking release.
+ * Serves {@link AgentComposer}'s attachment lifecycle. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` stages files without a validation or
+ * retry step, so it has no equivalent.
  */
 interface ComposerFileValidationConfig {
     /** Reject any single file larger than this. */
@@ -81,10 +80,9 @@ interface ComposerFileValidationConfig {
 }
 /** A file that failed validation, paired with a human-readable reason.
  *
- * @deprecated Composer-only helper of the legacy AgentComposer. Use
- * ChatComposer from `@tangle-network/agent-app/web-react` — the canonical
- * composer. AgentComposer is frozen and will be removed at sandbox-ui's next
- * breaking release. */
+ * Serves {@link AgentComposer}'s attachment lifecycle. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` stages files without a validation or
+ * retry step, so it has no equivalent. */
 interface ComposerFileRejection {
     file: File;
     reason: string;
@@ -94,10 +92,9 @@ interface ComposerFileRejection {
  * grammar as the native `<input accept>` attribute. An undefined or empty
  * `accept` accepts everything.
  *
- * @deprecated Composer-only helper of the legacy AgentComposer. Use
- * ChatComposer from `@tangle-network/agent-app/web-react` — the canonical
- * composer. AgentComposer is frozen and will be removed at sandbox-ui's next
- * breaking release.
+ * Serves {@link AgentComposer}'s attachment lifecycle. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` stages files without a validation or
+ * retry step, so it has no equivalent.
  */
 declare function isAcceptedType(file: File, accept?: string): boolean;
 /**
@@ -107,10 +104,9 @@ declare function isAcceptedType(file: File, accept?: string): boolean;
  * file and the limit it broke. Pure data in, pure data out — no throwing,
  * no console noise, so callers decide how to surface rejections.
  *
- * @deprecated Composer-only helper of the legacy AgentComposer. Use
- * ChatComposer from `@tangle-network/agent-app/web-react` — the canonical
- * composer. AgentComposer is frozen and will be removed at sandbox-ui's next
- * breaking release.
+ * Serves {@link AgentComposer}'s attachment lifecycle. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` stages files without a validation or
+ * retry step, so it has no equivalent.
  */
 declare function validateComposerFiles(files: File[] | FileList, config: ComposerFileValidationConfig): {
     accepted: File[];
@@ -120,9 +116,9 @@ declare function validateComposerFiles(files: File[] | FileList, config: Compose
 /** A selectable item in the `@`-mention popover. Generic — file semantics live
  * in the consuming app, not here.
  *
- * @deprecated Part of the legacy AgentComposer API. Use ChatComposer from
- * `@tangle-network/agent-app/web-react` — the canonical composer. AgentComposer
- * is frozen and will be removed at sandbox-ui's next breaking release. */
+ * Part of the {@link AgentComposer} API. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` has no equivalent — see
+ * {@link AgentComposer} for which composer fits a surface. */
 interface MentionItem {
     id: string;
     label: string;
@@ -134,9 +130,9 @@ interface MentionItem {
  * TipTap rich input that renders mentions as atomic pills; absent ⇒ exactly
  * today's plain-textarea behavior. Data-agnostic: the app supplies items.
  *
- * @deprecated Part of the legacy AgentComposer API. Use ChatComposer from
- * `@tangle-network/agent-app/web-react` — the canonical composer. AgentComposer
- * is frozen and will be removed at sandbox-ui's next breaking release.
+ * Part of the {@link AgentComposer} API. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` has no equivalent — see
+ * {@link AgentComposer} for which composer fits a surface.
  */
 interface AgentComposerMention {
     /** The character that opens the popover. Default "@". */
@@ -159,9 +155,9 @@ interface AgentComposerMention {
 }
 /** A staged attachment shown as a chip above the input.
  *
- * @deprecated Part of the legacy AgentComposer API. Use ChatComposer from
- * `@tangle-network/agent-app/web-react` — the canonical composer. AgentComposer
- * is frozen and will be removed at sandbox-ui's next breaking release. */
+ * Part of the {@link AgentComposer} API. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` has no equivalent — see
+ * {@link AgentComposer} for which composer fits a surface. */
 interface ComposerFile {
     id: string;
     name: string;
@@ -181,9 +177,9 @@ interface ComposerFile {
 }
 /** Context the agent will see alongside the next message.
  *
- * @deprecated Part of the legacy AgentComposer API. Use ChatComposer from
- * `@tangle-network/agent-app/web-react` — the canonical composer. AgentComposer
- * is frozen and will be removed at sandbox-ui's next breaking release. */
+ * Part of the {@link AgentComposer} API. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` has no equivalent — see
+ * {@link AgentComposer} for which composer fits a surface. */
 interface ComposerContextItem {
     id: string;
     label: string;
@@ -192,11 +188,11 @@ interface ComposerContextItem {
     onRemove?: () => void;
 }
 /**
- * Props of the legacy {@link AgentComposer}.
+ * Props of {@link AgentComposer}.
  *
- * @deprecated Part of the legacy AgentComposer API. Use ChatComposer from
- * `@tangle-network/agent-app/web-react` — the canonical composer. AgentComposer
- * is frozen and will be removed at sandbox-ui's next breaking release.
+ * Part of the {@link AgentComposer} API. `ChatComposer` in
+ * `@tangle-network/agent-app/web-react` has no equivalent — see
+ * {@link AgentComposer} for which composer fits a surface.
  */
 interface AgentComposerProps {
     /** Composer text (controlled). */
@@ -288,25 +284,35 @@ interface AgentComposerProps {
     autoFocus?: boolean;
 }
 /**
- * @deprecated Use `ChatComposer` from `@tangle-network/agent-app/web-react` —
- * the canonical composer. It adds send-failure recovery, seeds, control
- * placement, floating elevation, and the circular icon send via
- * `sendVariant="icon"`. Plan a port, not a rename: 14 of the 28 props here
- * have no same-named counterpart there, among them `contextItems`, `mention`,
- * `trailing`, `maxHeight`, `minRows`, and `autoFocus`. The control model also
- * differs — this component requires `value` and `onChange` and calls
- * `onSubmit` with no arguments, while `ChatComposer` can own its draft and
- * gives the message to a refusable `onSend`. This slot-shell is frozen and
- * will be removed at sandbox-ui's next breaking release.
+ * Sibling of `ChatComposer` in `@tangle-network/agent-app/web-react`, not a
+ * predecessor of it. The two composers cover different jobs, and neither is a
+ * superset of the other, so pick by the features a surface needs.
  *
- * The canonical agent chat input: one rounded surface holding an auto-growing
+ * Reach for `AgentComposer` when the surface needs `@`-mentions (`mention`,
+ * backed by a lazily loaded rich-text input that renders mention pills),
+ * `contextItems`, or the full attachment lifecycle — `attachments` plus
+ * `onRejectFiles` and `onRetryFile`. It also owns `autoFocus`,
+ * `canSubmitAttachmentsOnly`, `trailing`, `maxHeight`, and `minRows`.
+ *
+ * Reach for `ChatComposer` when the surface is a plain send box. It owns
+ * send-failure recovery (`onSendFailed`, `sendFailureMessage`), one-shot
+ * prefill (`seed`), `controlsPlacement`, `floating`, `sendVariant`,
+ * parts-aware sends (`onSendParts`), and an uncontrolled mode
+ * (`initialValue`) — none of which exist here.
+ *
+ * Moving between them is a port, not a rename: the control models differ. This
+ * component requires `value` and `onChange` and calls `onSubmit` with no
+ * arguments, while `ChatComposer` can own its draft and hands the message to a
+ * refusable `onSend`.
+ *
+ * The input itself: one rounded surface holding an auto-growing
  * textarea and a bottom row that runs left → right — attach buttons, the
  * control strip (supplied via the required `controls` prop), trailing slot,
  * and the send button on the far right. The strip is explicit: the canonical
  * pickers are `ModelPicker` / `EffortPicker` / `AgentSessionControls` from
  * `@tangle-network/agent-app/web-react` — this component only owns the slot.
  *
- * Opt-in extras make it the superset of every app's hand-rolled composer:
+ * Opt-in extras cover what apps otherwise hand-roll:
  * file/folder attachments with drag-and-drop + chips + clipboard paste
  * (`onAttach` also gates pasting files onto the textarea, auto-naming
  * generic clipboard image blobs `pasted-image-<n>.<ext>`), a streaming Stop
@@ -323,10 +329,9 @@ declare function AgentComposer({ value, onChange, onSubmit, placeholder, disable
  * importing it never pulls the lazily-loaded editor chunk into a consumer's
  * bundle.
  *
- * @deprecated Mention-pill contract of the legacy AgentComposer mention
- * feature. Use ChatComposer from `@tangle-network/agent-app/web-react` — the
- * canonical composer. AgentComposer is frozen and will be removed at
- * sandbox-ui's next breaking release.
+ * Mention-pill contract of {@link AgentComposer}'s mention feature.
+ * `ChatComposer` in `@tangle-network/agent-app/web-react` has no mention
+ * support, so it has no equivalent.
  */
 declare const MENTION_PILL_CLASS: string;
 

package/dist/{chunk-WYMAC3T3.js → chunk-4VLVVKQZ.js}

@@ -1,6 +1,6 @@
 import {
   usePtySession
-} from "./chunk-KEYPUGS3.js";
+} from "./chunk-7KB22BLB.js";
 
 // src/terminal/terminal-view.tsx
 import "@xterm/xterm/css/xterm.css";
@@ -41,6 +41,8 @@ function TerminalView({
   subtitle = "Connected to PTY session",
   isActive = true,
   connectionId,
+  incarnationId,
+  control,
   fontSize = 13
 }) {
   const resolvedTheme = useMemo(
@@ -71,7 +73,9 @@ function TerminalView({
     apiUrl,
     token,
     onData,
-    connectionId
+    connectionId,
+    incarnationId,
+    control
   });
   useEffect(() => {
     if (!containerRef.current) return;

package/dist/{chunk-KEYPUGS3.js → chunk-7KB22BLB.js}

@@ -37,7 +37,14 @@ function createTerminalConnectionId() {
   }
   return `terminal-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
-function usePtySession({ apiUrl, token, onData, connectionId: providedConnectionId }) {
+function usePtySession({
+  apiUrl,
+  token,
+  onData,
+  connectionId: providedConnectionId,
+  incarnationId,
+  control
+}) {
   const [isConnected, setIsConnected] = useState(false);
   const [error, setError] = useState(null);
   const sessionIdRef = useRef(null);
@@ -48,6 +55,11 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
   const mountedRef = useRef(true);
   const onDataRef = useRef(onData);
   const tokenRef = useRef(token);
+  const incarnationIdRef = useRef(incarnationId);
+  const controlRef = useRef(control);
+  const exactAttachRequiredRef = useRef(
+    incarnationId !== void 0 || control !== void 0
+  );
   const connectStreamRef = useRef(null);
   const reconnectRef = useRef(null);
   const shouldDeleteSessionRef = useRef(false);
@@ -177,8 +189,17 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
         pendingWsRef.current = null;
         if (options.initOnOpen) {
           try {
+            const initIncarnationId = incarnationIdRef.current;
+            const initControl = controlRef.current;
+            if (exactAttachRequiredRef.current && (!initIncarnationId || !initControl)) {
+              throw new Error(
+                "Interactive terminal identity is incomplete"
+              );
+            }
             ws.send(JSON.stringify({
               type: "init",
+              ...initIncarnationId !== void 0 ? { incarnationId: initIncarnationId } : {},
+              ...initControl !== void 0 ? { control: initControl } : {},
               cols: colsRef.current,
               rows: rowsRef.current
             }));
@@ -267,6 +288,11 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
     });
   }, [apiUrl]);
   const connectStream = useCallback(async (sessionId) => {
+    if (exactAttachRequiredRef.current) {
+      throw new Error(
+        "Interactive terminal requires an exact WebSocket attachment"
+      );
+    }
     abortStream();
     setError(null);
     try {
@@ -354,12 +380,19 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
   }, [apiUrl, abortStream]);
   onDataRef.current = onData;
   tokenRef.current = token;
+  incarnationIdRef.current = incarnationId;
+  controlRef.current = control;
+  exactAttachRequiredRef.current = incarnationId !== void 0 || control !== void 0;
   connectStreamRef.current = connectStream;
   const connect = useCallback(async () => {
     cleanup();
     const myGen = ++connectGenRef.current;
     retryCountRef.current = 0;
     setError(null);
+    if (exactAttachRequiredRef.current && (!incarnationIdRef.current || !controlRef.current)) {
+      setError("Interactive terminal identity is incomplete");
+      return;
+    }
     try {
       const connectionId = providedConnectionId ?? createTerminalConnectionId();
       if (!mountedRef.current) return;
@@ -373,6 +406,11 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
       if (directWsOk) {
         return;
       }
+      if (exactAttachRequiredRef.current) {
+        throw new Error(
+          "Interactive terminal WebSocket attach failed; exact identity was not accepted"
+        );
+      }
       sessionIdRef.current = null;
       transportReadyRef.current = false;
       if (inputAbortRef.current) {
@@ -434,6 +472,11 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
         console.warn("Terminal resize over WS failed; falling back to HTTP", err);
       }
     }
+    if (exactAttachRequiredRef.current) {
+      throw new Error(
+        "Interactive terminal is not attached with its exact identity"
+      );
+    }
     try {
       const res = await fetch(`${apiUrl}/terminals/${sid}`, {
         method: "PATCH",
@@ -469,6 +512,16 @@ function usePtySession({ apiUrl, token, onData, connectionId: providedConnection
         }
         continue;
       }
+      if (exactAttachRequiredRef.current) {
+        for (const w of batch.waiters) {
+          w.reject(
+            new Error(
+              "Interactive terminal is not attached with its exact identity"
+            )
+          );
+        }
+        continue;
+      }
       try {
         const res = await fetch(`${apiUrl}/terminals/${sid}/input`, {
           method: "POST",

package/dist/{chunk-K5RMJOH6.js → chunk-NAWEV5UJ.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-K4Q4E7D7.js";
 import {
   TerminalView
-} from "./chunk-WYMAC3T3.js";
+} from "./chunk-4VLVVKQZ.js";
 import {
   cn
 } from "./chunk-EI44GEQ5.js";

package/dist/hooks.d.ts

@@ -1,11 +1,11 @@
 export { AgentStreamEvent, AppendUserMessageOptions, ApplySdkEventOptions, AuthUser, AutomationStreamEvent, BeginAssistantMessageOptions, BotStreamEvent, CompleteAssistantMessageOptions, ConnectionState, RealtimeSessionOptions, RealtimeSessionRegistry, RealtimeSessionRegistryProps, RealtimeSessionState, RealtimeSessionTarget, SSEEvent, SdkSessionAttachment, SdkSessionEvent, SdkSessionSeed, TaskStreamEvent, TerminalStreamEvent, UseAuthOptions, UseAuthResult, UseRunGroupsOptions, UseSSEStreamOptions, UseSSEStreamResult, UseSdkSessionOptions, UseSdkSessionReturn, UseToolCallStreamReturn, createAuthFetcher, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useLiveTime, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useToolCallStream } from '@tangle-network/ui/hooks';
+import { AgentInteractiveSessionControlClaim } from '@tangle-network/agent-interface';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { Session } from './types.js';
 export { e as SESSION_STREAM_RECONNECT_DELAY_MS, f as SendMessageOptions, S as SessionInfo, g as SessionStreamError, a as SidecarAuth, U as UseSessionStreamOptions, b as UseSessionStreamResult, c as UseSidecarAuthOptions, u as useSessionStream, d as useSidecarAuth } from './sdk-hooks-Cjt_Wq7g.js';
 import '@tangle-network/ui/types';
 import '@tangle-network/ui/stores';
 import '@tangle-network/ui/sdk-hooks';
-import '@tangle-network/agent-interface';
 
 interface UsePtySessionOptions {
     /** Base URL of the sidecar (e.g. "http://localhost:9100"). */
@@ -22,6 +22,13 @@ interface UsePtySessionOptions {
      * so the session does not survive a remount.
      */
     connectionId?: string;
+    /**
+     * Exact incarnation issued for an interactive agent session. When present,
+     * it must be sent with `control` on every WebSocket init frame.
+     */
+    incarnationId?: string;
+    /** Write claim for the exact interactive agent session. */
+    control?: AgentInteractiveSessionControlClaim;
 }
 interface UsePtySessionReturn {
     /** Whether the underlying transport is connected and receiving data. */
@@ -58,7 +65,7 @@ interface UsePtySessionReturn {
  * preserved as a fallback so the hook keeps working against
  * deployments that have not yet shipped the WS endpoint.
  */
-declare function usePtySession({ apiUrl, token, onData, connectionId: providedConnectionId }: UsePtySessionOptions): UsePtySessionReturn;
+declare function usePtySession({ apiUrl, token, onData, connectionId: providedConnectionId, incarnationId, control, }: UsePtySessionOptions): UsePtySessionReturn;
 
 /**
  * Sandbox-level telemetry collected by the sidecar from cgroup v2

package/dist/hooks.js

@@ -26,7 +26,7 @@ import {
 } from "./chunk-3GX5BSD4.js";
 import {
   usePtySession
-} from "./chunk-KEYPUGS3.js";
+} from "./chunk-7KB22BLB.js";
 import "./chunk-CZ7CSFO4.js";
 export {
   RealtimeSessionRegistry,

package/dist/index.js

@@ -153,7 +153,7 @@ import {
   buildUnifiedPatch,
   computeDiffStats,
   resolveLanguage
-} from "./chunk-K5RMJOH6.js";
+} from "./chunk-NAWEV5UJ.js";
 import {
   FileArtifactPane,
   FilePreview,
@@ -238,10 +238,10 @@ import {
   UsageChart,
   formatPrice
 } from "./chunk-OMUIPJQZ.js";
-import "./chunk-WYMAC3T3.js";
+import "./chunk-4VLVVKQZ.js";
 import {
   usePtySession
-} from "./chunk-KEYPUGS3.js";
+} from "./chunk-7KB22BLB.js";
 import {
   Avatar,
   AvatarFallback,

package/dist/terminal.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { AgentInteractiveSessionControlClaim } from '@tangle-network/agent-interface';
 
 interface TerminalTheme {
     background: string;
@@ -52,8 +53,12 @@ interface TerminalViewProps {
      * session per mount.
      */
     connectionId?: string;
+    /** Exact incarnation issued for an interactive agent session. */
+    incarnationId?: string;
+    /** Write claim for the exact interactive agent session. */
+    control?: AgentInteractiveSessionControlClaim;
 }
 declare const DEFAULT_TERMINAL_THEME: TerminalTheme;
-declare function TerminalView({ apiUrl, token, theme, title, subtitle, isActive, connectionId, fontSize, }: TerminalViewProps): React.JSX.Element;
+declare function TerminalView({ apiUrl, token, theme, title, subtitle, isActive, connectionId, incarnationId, control, fontSize, }: TerminalViewProps): React.JSX.Element;
 
 export { DEFAULT_TERMINAL_THEME, type TerminalTheme, TerminalView, type TerminalViewProps };

package/dist/terminal.js

@@ -1,8 +1,8 @@
 import {
   DEFAULT_TERMINAL_THEME,
   TerminalView
-} from "./chunk-WYMAC3T3.js";
-import "./chunk-KEYPUGS3.js";
+} from "./chunk-4VLVVKQZ.js";
+import "./chunk-7KB22BLB.js";
 import "./chunk-CZ7CSFO4.js";
 export {
   DEFAULT_TERMINAL_THEME,

package/dist/workbench.js

@@ -12,12 +12,12 @@ import {
   buildUnifiedPatch,
   computeDiffStats,
   resolveLanguage
-} from "./chunk-K5RMJOH6.js";
+} from "./chunk-NAWEV5UJ.js";
 import "./chunk-PZVUIUUW.js";
 import "./chunk-K4Q4E7D7.js";
 import "./chunk-OMUIPJQZ.js";
-import "./chunk-WYMAC3T3.js";
-import "./chunk-KEYPUGS3.js";
+import "./chunk-4VLVVKQZ.js";
+import "./chunk-7KB22BLB.js";
 import "./chunk-2XPJ2XF7.js";
 import "./chunk-RQZRXKMR.js";
 import "./chunk-BGVEHENC.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-ui",
-  "version": "0.104.0",
+  "version": "0.105.0",
   "description": "Unified UI component library for Tangle Sandbox — primitives, chat, dashboard, terminal, editor, and workspace components",
   "repository": {
     "type": "git",