@agent-native/toolkit 0.16.2 → 0.16.4

package/src/composer/PromptComposer.tsx

@@ -36,6 +36,7 @@ import {
   PROMPT_DOCUMENT_ATTACHMENT_ACCEPT,
   TextAttachmentAdapter,
 } from "./attachment-accept.js";
+import type { ComposerTerminalModeControl } from "./ComposerPlusMenu.js";
 import { isPastedTextAttachmentName } from "./pasted-text.js";
 import { PastedTextChip } from "./PastedTextChip.js";
 import { escapePromptAttachmentAttribute } from "./prompt-attachments.js";
@@ -85,6 +86,8 @@ export interface PromptComposerProps {
   ) => void | Promise<void>;
   placeholder?: string;
   disabled?: boolean;
+  /** Called when a host-gated composer is clicked while it is disabled. */
+  onDisabledClick?: () => void;
   /** Override the generic document attachment cap for a multipart host. */
   maxDocumentAttachmentBytes?: number;
   /** Label used in the visible document attachment limit error. */
@@ -112,7 +115,9 @@ export interface PromptComposerProps {
    * Controls the shared "+" affordance. Defaults to upload-only for standalone
    * prompt forms; chat surfaces can opt into the full sidebar menu.
    */
-  plusMenuMode?: "full" | "upload-only" | "hidden";
+  plusMenuMode?: "full" | "upload-only" | "terminal" | "hidden";
+  /** Controls the terminal-specific plus menu when `plusMenuMode` is terminal. */
+  terminalModeControl?: ComposerTerminalModeControl;
   /**
    * Include extension creation in the full "+" menu. Defaults to false.
    */
@@ -156,6 +161,8 @@ export interface PromptComposerProps {
   availableAgents?: ComposerAgentOption[];
   /** Selected agent runtime identifier. */
   selectedAgent?: string;
+  /** Show only the selected agent in the model control. */
+  agentOnly?: boolean;
   /** Callback when the user picks an agent runtime. */
   onAgentChange?: (agent: string) => void;
   /** Called when the shared model picker opens or closes. */
@@ -491,6 +498,7 @@ function PromptComposerInner({
   onSubmit,
   placeholder,
   disabled,
+  onDisabledClick,
   maxDocumentAttachmentBytes,
   documentAttachmentLimitLabel,
   autoFocus,
@@ -506,6 +514,7 @@ function PromptComposerInner({
   voiceEnabled = DEFAULT_VOICE_DICTATION_ENABLED,
   attachmentsEnabled = true,
   plusMenuMode,
+  terminalModeControl,
   extensionTools = false,
   initialText,
   initialTextKey,
@@ -529,6 +538,7 @@ function PromptComposerInner({
   onEffortChange,
   availableAgents,
   selectedAgent,
+  agentOnly = false,
   onAgentChange,
   onModelSelectorOpenChange,
   modelStatusChecksEnabled,
@@ -643,12 +653,13 @@ function PromptComposerInner({
         <BuilderSetupCard
           onConnected={handleBuilderConnected}
           bouncePulse={missingKeyBouncePulse}
+          attached
           fullWidth
           layout="sidebar"
         />
       ) : null}
       {missingApiKey && useInlineMissingKeySetup && BuilderSetupContent ? (
-        <div className="mb-2 rounded-md border border-border/80 bg-background/80 p-2.5 text-start shadow-sm">
+        <div className="agent-builder-setup-inline--attached mb-0 rounded-md border border-border/80 bg-background/80 p-2.5 text-start shadow-sm">
           <BuilderSetupContent
             onConnected={handleBuilderConnected}
             layout="sidebar"
@@ -659,13 +670,21 @@ function PromptComposerInner({
         className={cn(
           "text-start",
           gateComposer && "cursor-pointer",
+          (gateComposer || onDisabledClick) &&
+            "agent-composer-area--attached-above",
           className,
         )}
         rootClassName={rootClassName}
         style={style}
         rootStyle={rootStyle}
         layoutVariant={layoutVariant}
-        onClick={gateComposer ? bounceMissingKeySetup : undefined}
+        onClick={
+          gateComposer
+            ? bounceMissingKeySetup
+            : onDisabledClick
+              ? () => onDisabledClick()
+              : undefined
+        }
       >
         <PromptAttachmentStrip />
         <TiptapComposer
@@ -687,6 +706,7 @@ function PromptComposerInner({
           plusMenuMode={
             plusMenuMode ?? (attachmentsEnabled ? "upload-only" : "hidden")
           }
+          terminalModeControl={terminalModeControl}
           extensionTools={extensionTools}
           attachButton={attachButton}
           modeControl={modeControl}
@@ -708,6 +728,7 @@ function PromptComposerInner({
           availableModels={composerModelGroups}
           availableAgents={availableAgents}
           selectedAgent={selectedAgent}
+          agentOnly={agentOnly}
           showAutoModelOption={showAutoModelOption}
           modelListLoading={composerModelListLoading}
           onModelChange={handleModelChange}

package/src/composer/TiptapComposer.tsx

@@ -36,7 +36,10 @@ import {
   PopoverTrigger,
 } from "../ui/popover.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
-import { ComposerPlusMenu } from "./ComposerPlusMenu.js";
+import {
+  ComposerPlusMenu,
+  type ComposerTerminalModeControl,
+} from "./ComposerPlusMenu.js";
 import { getComposerDraftKey } from "./draft-key.js";
 import { FileReference } from "./extensions/FileReference.js";
 import { MentionReference } from "./extensions/MentionReference.js";
@@ -668,6 +671,8 @@ export interface ComposerAgentOption {
   id: string;
   /** Human-readable runtime name shown in the picker. */
   label: string;
+  /** Optional icon shown beside the runtime name. */
+  icon?: React.ReactNode;
   /** Optional short detail shown below the runtime name. */
   description?: string;
   /** Whether this runtime can be selected right now. */
@@ -774,6 +779,8 @@ export interface TiptapComposerProps {
   availableAgents?: ComposerAgentOption[];
   /** Selected agent runtime identifier. Defaults to the built-in agent. */
   selectedAgent?: string;
+  /** Show only the selected agent in the model control. */
+  agentOnly?: boolean;
   /** Mark the selected runtime as the hosted tools-only harness mode. */
   hostedHarness?: boolean;
   /** Callback when the user picks an agent runtime. */
@@ -811,7 +818,9 @@ export interface TiptapComposerProps {
    * that opens the file picker directly. `"hidden"` hides attachment controls
    * for text-only prompt surfaces.
    */
-  plusMenuMode?: "full" | "upload-only" | "hidden";
+  plusMenuMode?: "full" | "upload-only" | "terminal" | "hidden";
+  /** Controls the terminal-specific plus menu when `plusMenuMode` is terminal. */
+  terminalModeControl?: ComposerTerminalModeControl;
   /**
    * Include extension creation in the full "+" menu. Defaults to false so
    * apps opt into the extension capability deliberately.
@@ -1297,6 +1306,7 @@ function ModelSelector({
   engines,
   agents,
   selectedAgent,
+  agentOnly = false,
   hostedHarness = false,
   showAutoModelOption = true,
   modelListLoading = false,
@@ -1323,6 +1333,7 @@ function ModelSelector({
     statusLabel?: string;
     isSubscription?: boolean;
   }>;
+  agentOnly?: boolean;
   showAutoModelOption?: boolean;
   modelListLoading?: boolean;
   onChange: (model: string, engine: string) => void;
@@ -1411,9 +1422,10 @@ function ModelSelector({
     }
     onChange(preferredAgentModel.model, preferredAgentModel.engine);
   }, [engines, isClaudeCodeAgent, model, onChange, preferredAgentModel]);
-  const effortOptions =
-    reasoning?.getOptionsForModel?.(model) ??
-    getComposerReasoningEffortOptions(model);
+  const effortOptions = agentOnly
+    ? []
+    : (reasoning?.getOptionsForModel?.(model) ??
+      getComposerReasoningEffortOptions(model));
   const selectedEffort =
     reasoning?.resolve?.(model, effort) ??
     resolveReasoningEffortSelection(model, effort ?? defaultEffort);
@@ -1435,15 +1447,15 @@ function ModelSelector({
   const [detailSection, setDetailSection] = useState<
     "agent" | "model" | "effort" | null
   >(null);
-  const resolvedSection = detailSection ?? "model";
+  const resolvedSection = detailSection ?? (agentOnly ? "agent" : "model");
 
   const setPickerOpen = useCallback(
     (nextOpen: boolean) => {
       if (controlledOpen === undefined) setInternalOpen(nextOpen);
-      if (nextOpen) setDetailSection(null);
+      if (nextOpen) setDetailSection(agentOnly ? "agent" : null);
       onModelSelectorOpenChange?.(nextOpen);
     },
-    [controlledOpen, onModelSelectorOpenChange],
+    [agentOnly, controlledOpen, onModelSelectorOpenChange],
   );
 
   const visibleProviderGroups = modelProviderGroups;
@@ -1518,6 +1530,11 @@ function ModelSelector({
           className="agent-composer-model-button flex min-w-0 max-w-[10.5rem] shrink items-center gap-1 rounded-md px-2 py-1 text-[12px] font-medium text-muted-foreground hover:bg-accent/50 hover:text-foreground"
         >
           <span className="min-w-0 truncate">
+            {selectedAgentOption?.icon ? (
+              <span className="me-1 inline-flex shrink-0 align-[-2px] text-muted-foreground">
+                {selectedAgentOption.icon}
+              </span>
+            ) : null}
             {selectedAgentOption && selectedAgentOption.id !== "default"
               ? selectedAgentLabel
               : compactComposerModelName(model, t)}
@@ -1613,25 +1630,29 @@ function ModelSelector({
                   <IconChevronRight className="h-3 w-3 shrink-0 opacity-60 rtl:-scale-x-100" />
                 </button>
               )}
-              <button
-                type="button"
-                role="tab"
-                aria-selected={resolvedSection === "model"}
-                onClick={() => setDetailSection("model")}
-                onMouseEnter={() => setDetailSection("model")}
-                className={`flex w-full min-w-0 items-center gap-1 rounded-md px-2 py-2 text-start transition-colors ${
-                  resolvedSection === "model"
-                    ? "bg-accent text-foreground"
-                    : "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
-                }`}
-              >
-                <span className="shrink-0 text-[12px] font-medium">Model</span>
-                <span className="ms-auto min-w-0 max-w-[6rem] truncate text-end text-[11px] text-muted-foreground/80">
-                  {selectedModelLabel}
-                </span>
-                <IconChevronRight className="h-3 w-3 shrink-0 opacity-60 rtl:-scale-x-100" />
-              </button>
-              {effortOptions.length > 0 && (
+              {!agentOnly && (
+                <button
+                  type="button"
+                  role="tab"
+                  aria-selected={resolvedSection === "model"}
+                  onClick={() => setDetailSection("model")}
+                  onMouseEnter={() => setDetailSection("model")}
+                  className={`flex w-full min-w-0 items-center gap-1 rounded-md px-2 py-2 text-start transition-colors ${
+                    resolvedSection === "model"
+                      ? "bg-accent text-foreground"
+                      : "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
+                  }`}
+                >
+                  <span className="shrink-0 text-[12px] font-medium">
+                    Model
+                  </span>
+                  <span className="ms-auto min-w-0 max-w-[6rem] truncate text-end text-[11px] text-muted-foreground/80">
+                    {selectedModelLabel}
+                  </span>
+                  <IconChevronRight className="h-3 w-3 shrink-0 opacity-60 rtl:-scale-x-100" />
+                </button>
+              )}
+              {!agentOnly && effortOptions.length > 0 && (
                 <button
                   type="button"
                   role="tab"
@@ -1703,6 +1724,14 @@ function ModelSelector({
                                 : "cursor-default opacity-50"
                             }`}
                           >
+                            {agent.icon ? (
+                              <span
+                                className="flex size-4 shrink-0 items-center justify-center text-muted-foreground"
+                                aria-hidden="true"
+                              >
+                                {agent.icon}
+                              </span>
+                            ) : null}
                             <span
                               className={`min-w-0 truncate text-[12px] ${
                                 isSelected
@@ -2134,6 +2163,7 @@ export function TiptapComposer({
   onEffortChange,
   availableAgents,
   selectedAgent,
+  agentOnly = false,
   hostedHarness,
   onAgentChange,
   onModelSelectorOpenChange,
@@ -2145,6 +2175,7 @@ export function TiptapComposer({
   contextItems = [],
   onRemoveContextItem,
   plusMenuMode = "full",
+  terminalModeControl,
   extensionTools = false,
   interceptBuildRequestsForBuilder = false,
   onAttachmentError,
@@ -3631,6 +3662,7 @@ export function TiptapComposer({
             <ComposerPlusMenu
               onSelectMode={handleSelectMode}
               mode={plusMenuMode}
+              terminalModeControl={terminalModeControl}
               extensionTools={extensionTools}
               onAttachmentError={onAttachmentError}
             />
@@ -3645,6 +3677,7 @@ export function TiptapComposer({
             engines={availableModels}
             agents={availableAgents}
             selectedAgent={selectedAgent}
+            agentOnly={agentOnly}
             hostedHarness={hostedHarness}
             showAutoModelOption={showAutoModelOption}
             modelListLoading={modelListLoading}

package/src/composer/index.ts

@@ -29,6 +29,7 @@ export {
   type PromptComposerFile,
   type PromptComposerSubmitOptions,
 } from "./PromptComposer.js";
+export type { ComposerTerminalModeControl } from "./ComposerPlusMenu.js";
 export {
   RealtimeVoiceModeDock,
   RealtimeVoiceModeEntry,

package/src/editor/extensions.ts

@@ -50,6 +50,56 @@ import type { Doc as YDoc } from "yjs";
 import { createCodeBlockNode } from "./CodeBlockNode.js";
 import { createImageExtension, type ImageUploadFn } from "./ImageExtension.js";
 
+interface YSyncBindingWithInitialRender {
+  beforeTransactionSelection: unknown | null;
+  _forceRerender: () => void;
+}
+
+const CollaborationWithSafeInitialSelection = Collaboration.extend({
+  addProseMirrorPlugins() {
+    const plugins = this.parent?.() ?? [];
+
+    for (const plugin of plugins) {
+      const originalView = plugin.spec.view;
+      if (!originalView) continue;
+
+      plugin.spec.view = (view) => {
+        const pluginState = plugin.getState(view.state) as
+          | { binding?: YSyncBindingWithInitialRender }
+          | undefined;
+        const binding = pluginState?.binding;
+        if (!binding || typeof binding._forceRerender !== "function") {
+          return originalView(view);
+        }
+
+        const originalForceRerender = binding._forceRerender.bind(binding);
+        binding._forceRerender = () => {
+          const previousSelection = binding.beforeTransactionSelection;
+          // y-prosemirror recreates its initial TextSelection at the same
+          // absolute position after replacing the whole document. That
+          // position can land inside a zero-child block. Let the replacement
+          // transaction map its existing selection instead; ProseMirror then
+          // chooses a valid nearby selection without warning.
+          binding.beforeTransactionSelection ??= view.state.selection;
+          try {
+            originalForceRerender();
+          } finally {
+            binding.beforeTransactionSelection = previousSelection;
+          }
+        };
+
+        try {
+          return originalView(view);
+        } finally {
+          binding._forceRerender = originalForceRerender;
+        }
+      };
+    }
+
+    return plugins;
+  },
+});
+
 /**
  * Markdown dialect the editor parses/serializes.
  *
@@ -385,7 +435,9 @@ export function createSharedEditorExtensions({
   // saved representation (onChange serializes it); the Y.Doc is transient live
   // state only. Appended last so it binds over the configured schema above.
   if (ydoc) {
-    exts.push(Collaboration.configure({ document: ydoc }));
+    exts.push(
+      CollaborationWithSafeInitialSelection.configure({ document: ydoc }),
+    );
     // Live multi-user cursors. Only mounted alongside a Y.Doc so the standalone
     // controlled editor (today's plan/content behavior) is untouched.
     if (awareness) {

package/src/editor/useCollabReconcile.concurrent.spec.ts

@@ -48,6 +48,7 @@ afterEach(() => {
 interface HarnessProps {
   value: string;
   contentUpdatedAt: string;
+  editorOwnedFocus?: boolean;
 }
 
 interface CollabSeedHarnessProps {
@@ -65,7 +66,11 @@ interface Captured {
 function makeHarness() {
   const captured: Captured = { editor: null, emitted: [], setContentCalls: 0 };
 
-  function Harness({ value, contentUpdatedAt }: HarnessProps) {
+  function Harness({
+    value,
+    contentUpdatedAt,
+    editorOwnedFocus = false,
+  }: HarnessProps) {
     const guardsRef = React.useRef<ReturnType<
       typeof useCollabReconcile
     > | null>(null);
@@ -88,6 +93,7 @@ function makeHarness() {
       value,
       contentUpdatedAt,
       editable: true,
+      isEditorFocused: () => editorOwnedFocus,
       getMarkdown: getEditorMarkdown,
       setContent: (ed, v, options) => {
         captured.setContentCalls += 1;
@@ -739,4 +745,37 @@ describe("useCollabReconcile — concurrent edit / lost-update guards", () => {
 
     expect(getEditorMarkdown(captured.editor!)).toBe("# Doc updated by agent");
   });
+
+  it("does not reapply a partial save echo while an external editor control owns focus", async () => {
+    const { captured, Harness } = makeHarness();
+
+    render(root, Harness, {
+      value: "# abcdef",
+      contentUpdatedAt: "2024-01-01T00:00:01.000Z",
+      editorOwnedFocus: true,
+    });
+    await flush();
+
+    act(() => captured.editor!.commands.setContent("# abcde"));
+    act(() => captured.editor!.commands.setContent("# ab"));
+    expect(getEditorMarkdown(captured.editor!)).toBe("# ab");
+
+    render(root, Harness, {
+      value: "# abcde",
+      contentUpdatedAt: "2024-01-01T00:00:02.000Z",
+      editorOwnedFocus: true,
+    });
+    await flush();
+
+    expect(getEditorMarkdown(captured.editor!)).toBe("# ab");
+
+    render(root, Harness, {
+      value: "# updated externally",
+      contentUpdatedAt: "2024-01-01T00:00:03.000Z",
+      editorOwnedFocus: false,
+    });
+    await flush();
+
+    expect(getEditorMarkdown(captured.editor!)).toBe("# updated externally");
+  });
 });

package/src/editor/useCollabReconcile.ts

@@ -62,6 +62,13 @@ export interface UseCollabReconcileOptions {
   contentUpdatedAt?: string | null;
   /** Whether the editor accepts edits. Reconcile/seed only run for the live editor. */
   editable: boolean;
+  /**
+   * Reports whether focus is inside any editing surface owned by this editor.
+   * Defaults to TipTap's contenteditable focus. Apps with editable NodeView
+   * controls outside the contenteditable surface can include those controls so
+   * a partial save echo cannot interrupt an active edit.
+   */
+  isEditorFocused?: (editor: Editor) => boolean;
   /**
    * Reads the current markdown from the editor. Injected so a dialect could
    * swap serializers; defaults to the tiptap-markdown storage reader. For an app
@@ -216,6 +223,10 @@ function defaultSetContent(
   editor.commands.setContent(value);
 }
 
+function defaultIsEditorFocused(editor: Editor): boolean {
+  return editor.isFocused;
+}
+
 export function useCollabReconcile({
   editor,
   ydoc = null,
@@ -224,6 +235,7 @@ export function useCollabReconcile({
   value,
   contentUpdatedAt,
   editable,
+  isEditorFocused = defaultIsEditorFocused,
   getMarkdown = getEditorMarkdown,
   setContent = defaultSetContent,
   parseValue,
@@ -452,8 +464,9 @@ export function useCollabReconcile({
       const editorUnchangedSinceApply =
         lastAppliedSerializedRef.current !== null &&
         currentMarkdown === lastAppliedSerializedRef.current;
+      const editorFocused = isEditorFocused(editor);
       const typingRecently =
-        editor.isFocused && Date.now() - lastTypedAtRef.current < 1500;
+        editorFocused && Date.now() - lastTypedAtRef.current < 1500;
 
       // Doc-equivalence skip. Never re-apply content the editor already
       // represents — comparing by DOC EQUIVALENCE, not raw strings/timestamps:
@@ -531,7 +544,7 @@ export function useCollabReconcile({
       // `lastAppliedSerializedRef` so the very first seed (nothing applied yet,
       // also not-newer) still lands.
       const seeded = lastAppliedSerializedRef.current !== null;
-      if (!externalNewer && (editor.isFocused || (!collab && seeded))) return;
+      if (!externalNewer && (editorFocused || (!collab && seeded))) return;
 
       // Race guard: with peers present, let Yjs deliver a peer's edit first.
       // Defer once and re-check — a peer edit makes the equality check above
@@ -616,6 +629,7 @@ export function useCollabReconcile({
     setContent,
     parseValue,
     normalizeValue,
+    isEditorFocused,
   ]);
 
   const shouldIgnoreUpdate = (transaction: Transaction): boolean => {