@volter-ai-dev/supercode-ui 0.1.42 → 0.1.43

package/README.md

@@ -128,6 +128,11 @@ Hosts do not need to fork the messenger to connect their own object model:
     draft: 'Inspect this selection',
     context: [selectedObject.asTranscriptContext()],
   }}
+  composerCommand={{
+    id: browserCapture.revision,
+    action: 'attach',
+    attachments: browserCapture.asTranscriptAttachment(),
+  }}
   contextCandidates={visibleObjects.map(asTranscriptContext)}
   components={{ ContextCandidate: ObjectPreview }}
   slots={{ beforeSessions: ProjectThreads }}
@@ -135,7 +140,11 @@ Hosts do not need to fork the messenger to connect their own object model:
 ```
 
 `navigation` is an event, not duplicated router state: change its `id` to open a conversation or
-prefill either an existing or new one, while `onViewChange` observes user navigation. Context candidates use the exact
+prefill either an existing or new one, while `onViewChange` observes user navigation.
+`composerCommand` is a separate event-like host seam: `focus` focuses the active composer and
+`attach` appends bounded context without replacing its draft or existing attachments. On New Chat,
+an attachment selects the compatible headless lane when the remembered terminal lane cannot carry
+structured context. Context candidates use the exact
 bounded `TranscriptAttachment` envelope sent to the harness; a custom candidate component changes
 presentation without inventing a second context protocol. `beforeSessions` and `afterSessions`
 place host-owned rows inside the same searchable scroller. `confirmIntent` runs before resume,

package/components.mjs

@@ -1317,7 +1317,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -1329,6 +1329,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -1370,6 +1371,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);
@@ -2696,7 +2717,7 @@ function ChatHeader({ state, adapter, pendingStatus, actionPending, onBack, onNe
     onClose ? /* @__PURE__ */ jsx10("button", { type: "button", "aria-label": "Close", onClick: onClose, children: /* @__PURE__ */ jsx10(UiIcon, { name: "close", size: 18 }) }) : null
   ] });
 }
-function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation }) {
+function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation, composerCommand }) {
   const Header = slots.header;
   const HeaderActions = slots.headerActions;
   const memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`;
@@ -2823,11 +2844,11 @@ function Chat({ state, adapter, onBack, onNew, onClose, components, slots, label
     /* @__PURE__ */ jsx10(Conversation, { state: actionState, adapter: trackedAdapter, components, slots, memoryKey, pending: pendingMessage, unreadAfterMessages }, memoryKey),
     /* @__PURE__ */ jsx10(ContinuationBar, { state: actionState, adapter: trackedAdapter, labels }),
     /* @__PURE__ */ jsx10(Advisory, { state: actionState, adapter: trackedAdapter, value: state.interopSettings?.advisories[0] ?? null, onReview: (recommendedChange) => setSettings({ recommendedChange }) }),
-    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx10(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
+    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx10(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, command: composerCommand, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
     settings ? /* @__PURE__ */ jsx10(SettingsPanel, { state: actionState, adapter: trackedAdapter, value: state.interopSettings, recommendedChange: settings.recommendedChange, onClose: () => setSettings(null) }) : null
   ] });
 }
-function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation }) {
+function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation, composerCommand }) {
   const startable = state.harnesses.filter((item) => item.startable);
   const startableKey = startable.map((item) => `${item.id}:${item.launchModes?.join(",")}:${item.preferredLaunchMode ?? ""}`).join("\0");
   const remembered = newChatMemory.get(memoryKey) ?? { harness: startable[0]?.id ?? "", draft: "", context: [], images: [], modes: {} };
@@ -2841,6 +2862,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
   const [dragging, setDragging] = useState6(false);
   const [pickerError, setPickerError] = useState6(null);
   const startSequence = useRef7(0);
+  const lastComposerCommand = useRef7(null);
   const textarea = useRef7(null);
   const selectedHarness = startable.find((item) => item.id === harness) ?? null;
   const Picker = components.HarnessPicker ?? HarnessPicker;
@@ -2884,6 +2906,32 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     remember({ harness: nextHarness, draft: nextDraft, context: nextContext, images: nextImages });
     textarea.current?.focus({ preventScroll: true });
   }, [navigation?.id]);
+  useEffect8(() => {
+    if (!composerCommand || composerCommand.id === lastComposerCommand.current) return;
+    lastComposerCommand.current = composerCommand.id;
+    if (composerCommand.action === "attach") {
+      if (mode === "terminal" && !launchModes.includes("headless")) {
+        setPickerError("Terminal starts currently accept text only. Choose Chat to attach context or images.");
+      } else {
+        try {
+          const attachments = partitionAttachments(composerCommand.attachments);
+          if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+          if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+          const nextContext = mergeContext(context, attachments.context);
+          const nextImages = mergeImages(images, attachments.images);
+          const nextModes = mode === "terminal" ? { ...modes, [harness]: "headless" } : modes;
+          if (nextModes !== modes) setModes(nextModes);
+          setContext(nextContext);
+          setImages(nextImages);
+          setPickerError(null);
+          remember({ context: nextContext, images: nextImages, modes: nextModes });
+        } catch (error) {
+          setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+        }
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [composerCommand?.id]);
   const pickContext = () => {
     if (mode === "terminal" || !adapter.pickContext || picking || context.length >= MAX_CONTEXT_ITEMS && images.length >= MAX_IMAGE_ITEMS) return;
     setPicking(true);
@@ -3041,7 +3089,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     ] })
   ] });
 }
-function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
+function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, composerCommand = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
   const state = useMemo3(() => normalizeUiState(stateInput), [stateInput]);
   const contextCandidates = useMemo3(() => normalizeAttachmentCandidates(candidatesInput), [candidatesInput]);
   const copy = { ...DEFAULT_LABELS, ...labels };
@@ -3112,7 +3160,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setNewNavigation(null);
       setView("new");
     }, onClose: adapter.onClose ? close : void 0, components, labels: copy, memoryKey, slots, headerActions: HeaderActions }) : null,
-    view === "new" ? /* @__PURE__ */ jsx10(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation }) : null,
+    view === "new" ? /* @__PURE__ */ jsx10(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation, composerCommand }) : null,
     view === "chat" ? /* @__PURE__ */ jsx10(Chat, { state, adapter, onBack: () => {
       setListFocus(state.attached?.key ?? listFocus);
       setView("list");
@@ -3121,7 +3169,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setChatNavigation(null);
       setNewNavigation(null);
       setView("new");
-    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null }) : null,
+    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null, composerCommand }) : null,
     opening ? /* @__PURE__ */ jsxs9("div", { className: "scui-opening", role: "status", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx10(HarnessLogo, { id: opening.harness, size: 34 }),
       /* @__PURE__ */ jsxs9("span", { children: [

package/composer.mjs

@@ -318,7 +318,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -330,6 +330,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -371,6 +372,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);

package/embed.mjs

@@ -1283,7 +1283,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -1295,6 +1295,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -1336,6 +1337,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);
@@ -2616,7 +2637,7 @@ function ChatHeader({ state, adapter, pendingStatus, actionPending, onBack, onNe
     onClose ? /* @__PURE__ */ jsx9("button", { type: "button", "aria-label": "Close", onClick: onClose, children: /* @__PURE__ */ jsx9(UiIcon, { name: "close", size: 18 }) }) : null
   ] });
 }
-function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation }) {
+function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation, composerCommand }) {
   const Header = slots.header;
   const HeaderActions = slots.headerActions;
   const memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`;
@@ -2743,11 +2764,11 @@ function Chat({ state, adapter, onBack, onNew, onClose, components, slots, label
     /* @__PURE__ */ jsx9(Conversation, { state: actionState, adapter: trackedAdapter, components, slots, memoryKey, pending: pendingMessage, unreadAfterMessages }, memoryKey),
     /* @__PURE__ */ jsx9(ContinuationBar, { state: actionState, adapter: trackedAdapter, labels }),
     /* @__PURE__ */ jsx9(Advisory, { state: actionState, adapter: trackedAdapter, value: state.interopSettings?.advisories[0] ?? null, onReview: (recommendedChange) => setSettings({ recommendedChange }) }),
-    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
+    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, command: composerCommand, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
     settings ? /* @__PURE__ */ jsx9(SettingsPanel, { state: actionState, adapter: trackedAdapter, value: state.interopSettings, recommendedChange: settings.recommendedChange, onClose: () => setSettings(null) }) : null
   ] });
 }
-function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation }) {
+function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation, composerCommand }) {
   const startable = state.harnesses.filter((item) => item.startable);
   const startableKey = startable.map((item) => `${item.id}:${item.launchModes?.join(",")}:${item.preferredLaunchMode ?? ""}`).join("\0");
   const remembered = newChatMemory.get(memoryKey) ?? { harness: startable[0]?.id ?? "", draft: "", context: [], images: [], modes: {} };
@@ -2761,6 +2782,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
   const [dragging, setDragging] = useState6(false);
   const [pickerError, setPickerError] = useState6(null);
   const startSequence = useRef7(0);
+  const lastComposerCommand = useRef7(null);
   const textarea = useRef7(null);
   const selectedHarness = startable.find((item) => item.id === harness) ?? null;
   const Picker = components.HarnessPicker ?? HarnessPicker;
@@ -2804,6 +2826,32 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     remember({ harness: nextHarness, draft: nextDraft, context: nextContext, images: nextImages });
     textarea.current?.focus({ preventScroll: true });
   }, [navigation?.id]);
+  useEffect8(() => {
+    if (!composerCommand || composerCommand.id === lastComposerCommand.current) return;
+    lastComposerCommand.current = composerCommand.id;
+    if (composerCommand.action === "attach") {
+      if (mode === "terminal" && !launchModes.includes("headless")) {
+        setPickerError("Terminal starts currently accept text only. Choose Chat to attach context or images.");
+      } else {
+        try {
+          const attachments = partitionAttachments(composerCommand.attachments);
+          if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+          if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+          const nextContext = mergeContext(context, attachments.context);
+          const nextImages = mergeImages(images, attachments.images);
+          const nextModes = mode === "terminal" ? { ...modes, [harness]: "headless" } : modes;
+          if (nextModes !== modes) setModes(nextModes);
+          setContext(nextContext);
+          setImages(nextImages);
+          setPickerError(null);
+          remember({ context: nextContext, images: nextImages, modes: nextModes });
+        } catch (error) {
+          setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+        }
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [composerCommand?.id]);
   const pickContext = () => {
     if (mode === "terminal" || !adapter.pickContext || picking || context.length >= MAX_CONTEXT_ITEMS && images.length >= MAX_IMAGE_ITEMS) return;
     setPicking(true);
@@ -2961,7 +3009,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     ] })
   ] });
 }
-function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
+function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, composerCommand = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
   const state = useMemo3(() => normalizeUiState(stateInput), [stateInput]);
   const contextCandidates = useMemo3(() => normalizeAttachmentCandidates(candidatesInput), [candidatesInput]);
   const copy = { ...DEFAULT_LABELS, ...labels };
@@ -3032,7 +3080,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setNewNavigation(null);
       setView("new");
     }, onClose: adapter.onClose ? close : void 0, components, labels: copy, memoryKey, slots, headerActions: HeaderActions }) : null,
-    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation }) : null,
+    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation, composerCommand }) : null,
     view === "chat" ? /* @__PURE__ */ jsx9(Chat, { state, adapter, onBack: () => {
       setListFocus(state.attached?.key ?? listFocus);
       setView("list");
@@ -3041,7 +3089,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setChatNavigation(null);
       setNewNavigation(null);
       setView("new");
-    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null }) : null,
+    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null, composerCommand }) : null,
     opening ? /* @__PURE__ */ jsxs8("div", { className: "scui-opening", role: "status", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx9(HarnessLogo, { id: opening.harness, size: 34 }),
       /* @__PURE__ */ jsxs8("span", { children: [

package/index.d.ts

@@ -483,6 +483,11 @@ export type MessengerNavigation =
   | { id: string | number; view: 'chat'; sessionKey: string; draft?: string; context?: TranscriptContext[]; images?: Array<TranscriptImage & { url: string }> }
   | { id: string | number; view: 'new'; harness?: HarnessId; draft?: string; context?: TranscriptContext[]; images?: Array<TranscriptImage & { url: string }> };
 
+/** Event-like host command that focuses the active composer or appends context without replacing its draft. */
+export type MessengerComposerCommand =
+  | { id: string | number; action: 'focus' }
+  | { id: string | number; action: 'attach'; attachments: TranscriptAttachment | TranscriptAttachment[] };
+
 export interface MessengerProps {
   state: SupercodeUiState | unknown;
   adapter: UiAdapter;
@@ -490,6 +495,8 @@ export interface MessengerProps {
   initialView?: 'list' | 'chat' | 'new';
   /** Event-like host navigation. Change `id` to issue a new request. */
   navigation?: MessengerNavigation | null;
+  /** Event-like composer command. Change `id` to focus or append attachments to the current draft. */
+  composerCommand?: MessengerComposerCommand | null;
   onViewChange?(view: 'list' | 'chat' | 'new'): void;
   /** Deliberate host-provided items that can be attached without opening a picker. */
   contextCandidates?: TranscriptAttachment[];
@@ -549,7 +556,7 @@ export function Conversation(props: { state: SupercodeUiState; adapter: UiAdapte
 export function SessionRow(props: { row: SessionRowModel; state: SupercodeUiState; adapter: UiAdapter; now?: number; onOpen(row: SessionRowModel): void }): VNode;
 export function SessionList(props: { state: SupercodeUiState; adapter: UiAdapter; onOpen(row: SessionRowModel): void; onNew?(): void; onClose?(): void; components?: MessengerComponents; slots?: MessengerSlots; labels?: MessengerLabels; focusKey?: string | null; memoryKey?: string; headerActions?: MessengerSlots['headerActions'] }): VNode;
 export function ContinuationBar(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels }): VNode | null;
-export function Composer(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels; memoryKey?: string; pendingStatus?: PendingMessageModel['status'] | 'editing' | null; restoreDraft?: { id: string | number; text: string; context?: TranscriptContext[]; images?: TranscriptImage[] } | null; contextCandidates?: TranscriptAttachment[]; components?: Pick<MessengerComponents, 'ContextCandidate'>; onPending?(text: string, context?: TranscriptContext[], images?: TranscriptImage[]): void; onDraftRestored?(id: string | number): void }): VNode;
+export function Composer(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels; memoryKey?: string; pendingStatus?: PendingMessageModel['status'] | 'editing' | null; restoreDraft?: { id: string | number; text: string; context?: TranscriptContext[]; images?: TranscriptImage[] } | null; command?: MessengerComposerCommand | null; contextCandidates?: TranscriptAttachment[]; components?: Pick<MessengerComponents, 'ContextCandidate'>; onPending?(text: string, context?: TranscriptContext[], images?: TranscriptImage[]): void; onDraftRestored?(id: string | number): void }): VNode;
 export function SupercodeMessenger(props: MessengerProps): VNode;
 
 export interface MountedMessenger {

package/messenger.mjs

@@ -1280,7 +1280,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -1292,6 +1292,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -1333,6 +1334,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);
@@ -2613,7 +2634,7 @@ function ChatHeader({ state, adapter, pendingStatus, actionPending, onBack, onNe
     onClose ? /* @__PURE__ */ jsx9("button", { type: "button", "aria-label": "Close", onClick: onClose, children: /* @__PURE__ */ jsx9(UiIcon, { name: "close", size: 18 }) }) : null
   ] });
 }
-function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation }) {
+function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation, composerCommand }) {
   const Header = slots.header;
   const HeaderActions = slots.headerActions;
   const memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`;
@@ -2740,11 +2761,11 @@ function Chat({ state, adapter, onBack, onNew, onClose, components, slots, label
     /* @__PURE__ */ jsx9(Conversation, { state: actionState, adapter: trackedAdapter, components, slots, memoryKey, pending: pendingMessage, unreadAfterMessages }, memoryKey),
     /* @__PURE__ */ jsx9(ContinuationBar, { state: actionState, adapter: trackedAdapter, labels }),
     /* @__PURE__ */ jsx9(Advisory, { state: actionState, adapter: trackedAdapter, value: state.interopSettings?.advisories[0] ?? null, onReview: (recommendedChange) => setSettings({ recommendedChange }) }),
-    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
+    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, command: composerCommand, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
     settings ? /* @__PURE__ */ jsx9(SettingsPanel, { state: actionState, adapter: trackedAdapter, value: state.interopSettings, recommendedChange: settings.recommendedChange, onClose: () => setSettings(null) }) : null
   ] });
 }
-function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation }) {
+function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation, composerCommand }) {
   const startable = state.harnesses.filter((item) => item.startable);
   const startableKey = startable.map((item) => `${item.id}:${item.launchModes?.join(",")}:${item.preferredLaunchMode ?? ""}`).join("\0");
   const remembered = newChatMemory.get(memoryKey) ?? { harness: startable[0]?.id ?? "", draft: "", context: [], images: [], modes: {} };
@@ -2758,6 +2779,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
   const [dragging, setDragging] = useState6(false);
   const [pickerError, setPickerError] = useState6(null);
   const startSequence = useRef7(0);
+  const lastComposerCommand = useRef7(null);
   const textarea = useRef7(null);
   const selectedHarness = startable.find((item) => item.id === harness) ?? null;
   const Picker = components.HarnessPicker ?? HarnessPicker;
@@ -2801,6 +2823,32 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     remember({ harness: nextHarness, draft: nextDraft, context: nextContext, images: nextImages });
     textarea.current?.focus({ preventScroll: true });
   }, [navigation?.id]);
+  useEffect8(() => {
+    if (!composerCommand || composerCommand.id === lastComposerCommand.current) return;
+    lastComposerCommand.current = composerCommand.id;
+    if (composerCommand.action === "attach") {
+      if (mode === "terminal" && !launchModes.includes("headless")) {
+        setPickerError("Terminal starts currently accept text only. Choose Chat to attach context or images.");
+      } else {
+        try {
+          const attachments = partitionAttachments(composerCommand.attachments);
+          if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+          if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+          const nextContext = mergeContext(context, attachments.context);
+          const nextImages = mergeImages(images, attachments.images);
+          const nextModes = mode === "terminal" ? { ...modes, [harness]: "headless" } : modes;
+          if (nextModes !== modes) setModes(nextModes);
+          setContext(nextContext);
+          setImages(nextImages);
+          setPickerError(null);
+          remember({ context: nextContext, images: nextImages, modes: nextModes });
+        } catch (error) {
+          setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+        }
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [composerCommand?.id]);
   const pickContext = () => {
     if (mode === "terminal" || !adapter.pickContext || picking || context.length >= MAX_CONTEXT_ITEMS && images.length >= MAX_IMAGE_ITEMS) return;
     setPicking(true);
@@ -2958,7 +3006,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     ] })
   ] });
 }
-function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
+function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, composerCommand = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
   const state = useMemo3(() => normalizeUiState(stateInput), [stateInput]);
   const contextCandidates = useMemo3(() => normalizeAttachmentCandidates(candidatesInput), [candidatesInput]);
   const copy = { ...DEFAULT_LABELS, ...labels };
@@ -3029,7 +3077,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setNewNavigation(null);
       setView("new");
     }, onClose: adapter.onClose ? close : void 0, components, labels: copy, memoryKey, slots, headerActions: HeaderActions }) : null,
-    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation }) : null,
+    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation, composerCommand }) : null,
     view === "chat" ? /* @__PURE__ */ jsx9(Chat, { state, adapter, onBack: () => {
       setListFocus(state.attached?.key ?? listFocus);
       setView("list");
@@ -3038,7 +3086,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setChatNavigation(null);
       setNewNavigation(null);
       setView("new");
-    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null }) : null,
+    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null, composerCommand }) : null,
     opening ? /* @__PURE__ */ jsxs8("div", { className: "scui-opening", role: "status", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx9(HarnessLogo, { id: opening.harness, size: 34 }),
       /* @__PURE__ */ jsxs8("span", { children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter-ai-dev/supercode-ui",
-  "version": "0.1.42",
+  "version": "0.1.43",
   "type": "module",
   "description": "Composable default UI kit for Supercode-powered coding-agent experiences",
   "exports": {

package/react/components.mjs

@@ -1317,7 +1317,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -1329,6 +1329,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -1370,6 +1371,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);
@@ -2696,7 +2717,7 @@ function ChatHeader({ state, adapter, pendingStatus, actionPending, onBack, onNe
     onClose ? /* @__PURE__ */ jsx10("button", { type: "button", "aria-label": "Close", onClick: onClose, children: /* @__PURE__ */ jsx10(UiIcon, { name: "close", size: 18 }) }) : null
   ] });
 }
-function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation }) {
+function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation, composerCommand }) {
   const Header = slots.header;
   const HeaderActions = slots.headerActions;
   const memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`;
@@ -2823,11 +2844,11 @@ function Chat({ state, adapter, onBack, onNew, onClose, components, slots, label
     /* @__PURE__ */ jsx10(Conversation, { state: actionState, adapter: trackedAdapter, components, slots, memoryKey, pending: pendingMessage, unreadAfterMessages }, memoryKey),
     /* @__PURE__ */ jsx10(ContinuationBar, { state: actionState, adapter: trackedAdapter, labels }),
     /* @__PURE__ */ jsx10(Advisory, { state: actionState, adapter: trackedAdapter, value: state.interopSettings?.advisories[0] ?? null, onReview: (recommendedChange) => setSettings({ recommendedChange }) }),
-    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx10(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
+    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx10(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, command: composerCommand, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
     settings ? /* @__PURE__ */ jsx10(SettingsPanel, { state: actionState, adapter: trackedAdapter, value: state.interopSettings, recommendedChange: settings.recommendedChange, onClose: () => setSettings(null) }) : null
   ] });
 }
-function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation }) {
+function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation, composerCommand }) {
   const startable = state.harnesses.filter((item) => item.startable);
   const startableKey = startable.map((item) => `${item.id}:${item.launchModes?.join(",")}:${item.preferredLaunchMode ?? ""}`).join("\0");
   const remembered = newChatMemory.get(memoryKey) ?? { harness: startable[0]?.id ?? "", draft: "", context: [], images: [], modes: {} };
@@ -2841,6 +2862,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
   const [dragging, setDragging] = useState6(false);
   const [pickerError, setPickerError] = useState6(null);
   const startSequence = useRef7(0);
+  const lastComposerCommand = useRef7(null);
   const textarea = useRef7(null);
   const selectedHarness = startable.find((item) => item.id === harness) ?? null;
   const Picker = components.HarnessPicker ?? HarnessPicker;
@@ -2884,6 +2906,32 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     remember({ harness: nextHarness, draft: nextDraft, context: nextContext, images: nextImages });
     textarea.current?.focus({ preventScroll: true });
   }, [navigation?.id]);
+  useEffect8(() => {
+    if (!composerCommand || composerCommand.id === lastComposerCommand.current) return;
+    lastComposerCommand.current = composerCommand.id;
+    if (composerCommand.action === "attach") {
+      if (mode === "terminal" && !launchModes.includes("headless")) {
+        setPickerError("Terminal starts currently accept text only. Choose Chat to attach context or images.");
+      } else {
+        try {
+          const attachments = partitionAttachments(composerCommand.attachments);
+          if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+          if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+          const nextContext = mergeContext(context, attachments.context);
+          const nextImages = mergeImages(images, attachments.images);
+          const nextModes = mode === "terminal" ? { ...modes, [harness]: "headless" } : modes;
+          if (nextModes !== modes) setModes(nextModes);
+          setContext(nextContext);
+          setImages(nextImages);
+          setPickerError(null);
+          remember({ context: nextContext, images: nextImages, modes: nextModes });
+        } catch (error) {
+          setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+        }
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [composerCommand?.id]);
   const pickContext = () => {
     if (mode === "terminal" || !adapter.pickContext || picking || context.length >= MAX_CONTEXT_ITEMS && images.length >= MAX_IMAGE_ITEMS) return;
     setPicking(true);
@@ -3041,7 +3089,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     ] })
   ] });
 }
-function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
+function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, composerCommand = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
   const state = useMemo3(() => normalizeUiState(stateInput), [stateInput]);
   const contextCandidates = useMemo3(() => normalizeAttachmentCandidates(candidatesInput), [candidatesInput]);
   const copy = { ...DEFAULT_LABELS, ...labels };
@@ -3112,7 +3160,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setNewNavigation(null);
       setView("new");
     }, onClose: adapter.onClose ? close : void 0, components, labels: copy, memoryKey, slots, headerActions: HeaderActions }) : null,
-    view === "new" ? /* @__PURE__ */ jsx10(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation }) : null,
+    view === "new" ? /* @__PURE__ */ jsx10(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation, composerCommand }) : null,
     view === "chat" ? /* @__PURE__ */ jsx10(Chat, { state, adapter, onBack: () => {
       setListFocus(state.attached?.key ?? listFocus);
       setView("list");
@@ -3121,7 +3169,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setChatNavigation(null);
       setNewNavigation(null);
       setView("new");
-    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null }) : null,
+    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null, composerCommand }) : null,
     opening ? /* @__PURE__ */ jsxs9("div", { className: "scui-opening", role: "status", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx10(HarnessLogo, { id: opening.harness, size: 34 }),
       /* @__PURE__ */ jsxs9("span", { children: [

package/react/composer.mjs

@@ -318,7 +318,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -330,6 +330,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -371,6 +372,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);

package/react/index.d.ts

@@ -11,6 +11,7 @@ import type {
   HarnessSettingsPanelProps,
   HarnessOption,
   MessengerLabels,
+  MessengerComposerCommand,
   MessengerNavigation,
   PendingMessageModel,
   SessionActivity,
@@ -41,6 +42,7 @@ export type {
   HarnessSettingsPanelProps,
   HarnessOption,
   MessengerLabels,
+  MessengerComposerCommand,
   MessengerNavigation,
   PendingMessageModel,
   SessionActivity,
@@ -90,6 +92,7 @@ export interface MessengerProps {
   class?: string;
   initialView?: 'list' | 'chat' | 'new';
   navigation?: MessengerNavigation | null;
+  composerCommand?: MessengerComposerCommand | null;
   onViewChange?(view: 'list' | 'chat' | 'new'): void;
   contextCandidates?: TranscriptAttachment[];
   labels?: Partial<MessengerLabels>;
@@ -122,5 +125,5 @@ export function Conversation(props: { state: SupercodeUiState; adapter: UiAdapte
 export function SessionRow(props: { row: SessionRowModel; state: SupercodeUiState; adapter: UiAdapter; now?: number; onOpen(row: SessionRowModel): void }): ReactElement;
 export function SessionList(props: { state: SupercodeUiState; adapter: UiAdapter; onOpen(row: SessionRowModel): void; onNew?(): void; onClose?(): void; components?: MessengerComponents; slots?: MessengerSlots; labels?: MessengerLabels; focusKey?: string | null; memoryKey?: string; headerActions?: MessengerSlots['headerActions'] }): ReactElement;
 export function ContinuationBar(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels }): ReactElement | null;
-export function Composer(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels; memoryKey?: string; pendingStatus?: PendingMessageModel['status'] | 'editing' | null; restoreDraft?: { id: string | number; text: string; context?: TranscriptContext[]; images?: TranscriptImage[] } | null; contextCandidates?: TranscriptAttachment[]; components?: Pick<MessengerComponents, 'ContextCandidate'>; onPending?(text: string, context?: TranscriptContext[], images?: TranscriptImage[]): void; onDraftRestored?(id: string | number): void }): ReactElement;
+export function Composer(props: { state: SupercodeUiState; adapter: UiAdapter; labels?: MessengerLabels; memoryKey?: string; pendingStatus?: PendingMessageModel['status'] | 'editing' | null; restoreDraft?: { id: string | number; text: string; context?: TranscriptContext[]; images?: TranscriptImage[] } | null; command?: MessengerComposerCommand | null; contextCandidates?: TranscriptAttachment[]; components?: Pick<MessengerComponents, 'ContextCandidate'>; onPending?(text: string, context?: TranscriptContext[], images?: TranscriptImage[]): void; onDraftRestored?(id: string | number): void }): ReactElement;
 export function SupercodeMessenger(props: MessengerProps): ReactElement;

package/react/messenger.mjs

@@ -1280,7 +1280,7 @@ function ContinuationBar({ state, adapter, labels = DEFAULT_LABELS }) {
     ] })
   ] });
 }
-function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
+function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`, pendingStatus = null, restoreDraft = null, command = null, contextCandidates = [], components = {}, onPending, onDraftRestored }) {
   const remembered = composerMemory.get(memoryKey) ?? { draft: state.savedDraft, context: [], images: [], queue: [] };
   const [draft, setDraft] = useState2(remembered.draft);
   const [context, setContext] = useState2(remembered.context ?? []);
@@ -1292,6 +1292,7 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
   const [dragging, setDragging] = useState2(false);
   const [pickerError, setPickerError] = useState2(null);
   const textarea = useRef2(null);
+  const lastCommand = useRef2(null);
   useAutosizeTextarea(textarea, draft);
   const remember = (nextDraft, nextContext, nextImages, nextQueue) => boundedSet(composerMemory, memoryKey, { draft: nextDraft, context: nextContext, images: nextImages, queue: nextQueue });
   useEffect2(() => {
@@ -1333,6 +1334,26 @@ function Composer({ state, adapter, labels = DEFAULT_LABELS, memoryKey = state.a
     textarea.current?.focus({ preventScroll: true });
     onDraftRestored?.(restoreDraft.id);
   }, [onDraftRestored, restoreDraft?.id]);
+  useEffect2(() => {
+    if (!command || command.id === lastCommand.current) return;
+    lastCommand.current = command.id;
+    if (command.action === "attach") {
+      try {
+        const attachments = partitionAttachments(command.attachments);
+        if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+        if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+        const nextContext = mergeContext(context, attachments.context);
+        const nextImages = mergeImages(images, attachments.images);
+        setContext(nextContext);
+        setImages(nextImages);
+        setPickerError(null);
+        remember(draft, nextContext, nextImages, queue);
+      } catch (error) {
+        setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [command?.id]);
   useEffect2(() => {
     const timer = setTimeout(() => adapter.onIntent({ action: "draft", text: draft }), 250);
     return () => clearTimeout(timer);
@@ -2613,7 +2634,7 @@ function ChatHeader({ state, adapter, pendingStatus, actionPending, onBack, onNe
     onClose ? /* @__PURE__ */ jsx9("button", { type: "button", "aria-label": "Close", onClick: onClose, children: /* @__PURE__ */ jsx9(UiIcon, { name: "close", size: 18 }) }) : null
   ] });
 }
-function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation }) {
+function Chat({ state, adapter, onBack, onNew, onClose, components, slots, labels, contextCandidates, navigation, composerCommand }) {
   const Header = slots.header;
   const HeaderActions = slots.headerActions;
   const memoryKey = state.attached?.key || `${state.harness}:${state.workspace}`;
@@ -2740,11 +2761,11 @@ function Chat({ state, adapter, onBack, onNew, onClose, components, slots, label
     /* @__PURE__ */ jsx9(Conversation, { state: actionState, adapter: trackedAdapter, components, slots, memoryKey, pending: pendingMessage, unreadAfterMessages }, memoryKey),
     /* @__PURE__ */ jsx9(ContinuationBar, { state: actionState, adapter: trackedAdapter, labels }),
     /* @__PURE__ */ jsx9(Advisory, { state: actionState, adapter: trackedAdapter, value: state.interopSettings?.advisories[0] ?? null, onReview: (recommendedChange) => setSettings({ recommendedChange }) }),
-    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
+    state.mode !== "mirror" || state.canSend ? /* @__PURE__ */ jsx9(Composer, { state: actionState, adapter: trackedAdapter, labels, memoryKey, pendingStatus: pending?.status ?? null, restoreDraft, command: composerCommand, contextCandidates, components, onDraftRestored: (id) => setRestoreDraft((value) => value?.id === id ? null : value), onPending: beginPending }, memoryKey) : null,
     settings ? /* @__PURE__ */ jsx9(SettingsPanel, { state: actionState, adapter: trackedAdapter, value: state.interopSettings, recommendedChange: settings.recommendedChange, onClose: () => setSettings(null) }) : null
   ] });
 }
-function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation }) {
+function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation, composerCommand }) {
   const startable = state.harnesses.filter((item) => item.startable);
   const startableKey = startable.map((item) => `${item.id}:${item.launchModes?.join(",")}:${item.preferredLaunchMode ?? ""}`).join("\0");
   const remembered = newChatMemory.get(memoryKey) ?? { harness: startable[0]?.id ?? "", draft: "", context: [], images: [], modes: {} };
@@ -2758,6 +2779,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
   const [dragging, setDragging] = useState6(false);
   const [pickerError, setPickerError] = useState6(null);
   const startSequence = useRef7(0);
+  const lastComposerCommand = useRef7(null);
   const textarea = useRef7(null);
   const selectedHarness = startable.find((item) => item.id === harness) ?? null;
   const Picker = components.HarnessPicker ?? HarnessPicker;
@@ -2801,6 +2823,32 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     remember({ harness: nextHarness, draft: nextDraft, context: nextContext, images: nextImages });
     textarea.current?.focus({ preventScroll: true });
   }, [navigation?.id]);
+  useEffect8(() => {
+    if (!composerCommand || composerCommand.id === lastComposerCommand.current) return;
+    lastComposerCommand.current = composerCommand.id;
+    if (composerCommand.action === "attach") {
+      if (mode === "terminal" && !launchModes.includes("headless")) {
+        setPickerError("Terminal starts currently accept text only. Choose Chat to attach context or images.");
+      } else {
+        try {
+          const attachments = partitionAttachments(composerCommand.attachments);
+          if (context.length + attachments.context.length > MAX_CONTEXT_ITEMS) throw new Error(`Attach at most ${MAX_CONTEXT_ITEMS} text items.`);
+          if (images.length + attachments.images.length > MAX_IMAGE_ITEMS) throw new Error(`Attach at most ${MAX_IMAGE_ITEMS} images.`);
+          const nextContext = mergeContext(context, attachments.context);
+          const nextImages = mergeImages(images, attachments.images);
+          const nextModes = mode === "terminal" ? { ...modes, [harness]: "headless" } : modes;
+          if (nextModes !== modes) setModes(nextModes);
+          setContext(nextContext);
+          setImages(nextImages);
+          setPickerError(null);
+          remember({ context: nextContext, images: nextImages, modes: nextModes });
+        } catch (error) {
+          setPickerError(error instanceof Error ? error.message : "Could not attach context.");
+        }
+      }
+    }
+    textarea.current?.focus({ preventScroll: true });
+  }, [composerCommand?.id]);
   const pickContext = () => {
     if (mode === "terminal" || !adapter.pickContext || picking || context.length >= MAX_CONTEXT_ITEMS && images.length >= MAX_IMAGE_ITEMS) return;
     setPicking(true);
@@ -2958,7 +3006,7 @@ function NewChat({ state, adapter, onBack, onClose, onStarted, labels, memoryKey
     ] })
   ] });
 }
-function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
+function SupercodeMessenger({ state: stateInput, adapter, class: className = "", initialView, navigation = null, composerCommand = null, onViewChange, contextCandidates: candidatesInput = [], labels, components = {}, slots = {} }) {
   const state = useMemo3(() => normalizeUiState(stateInput), [stateInput]);
   const contextCandidates = useMemo3(() => normalizeAttachmentCandidates(candidatesInput), [candidatesInput]);
   const copy = { ...DEFAULT_LABELS, ...labels };
@@ -3029,7 +3077,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setNewNavigation(null);
       setView("new");
     }, onClose: adapter.onClose ? close : void 0, components, labels: copy, memoryKey, slots, headerActions: HeaderActions }) : null,
-    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation }) : null,
+    view === "new" ? /* @__PURE__ */ jsx9(NewChat, { state, adapter, onBack: () => setView("list"), onClose: adapter.onClose ? close : void 0, onStarted: (mode) => setView(mode === "terminal" ? "list" : "chat"), labels: copy, memoryKey, headerActions: HeaderActions, contextCandidates, components, navigation: newNavigation, composerCommand }) : null,
     view === "chat" ? /* @__PURE__ */ jsx9(Chat, { state, adapter, onBack: () => {
       setListFocus(state.attached?.key ?? listFocus);
       setView("list");
@@ -3038,7 +3086,7 @@ function SupercodeMessenger({ state: stateInput, adapter, class: className = "",
       setChatNavigation(null);
       setNewNavigation(null);
       setView("new");
-    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null }) : null,
+    }, onClose: adapter.onClose ? close : void 0, components, slots, labels: copy, contextCandidates, navigation: chatNavigation?.sessionKey === state.attached?.key ? chatNavigation : null, composerCommand }) : null,
     opening ? /* @__PURE__ */ jsxs8("div", { className: "scui-opening", role: "status", "aria-busy": "true", children: [
       /* @__PURE__ */ jsx9(HarnessLogo, { id: opening.harness, size: 34 }),
       /* @__PURE__ */ jsxs8("span", { children: [