@agent-native/toolkit 0.21.3 → 0.22.0-nightly-20260926111339

package/src/composer/TiptapComposer.tsx

@@ -15,6 +15,9 @@ import {
   IconPencil,
   IconPlugConnected,
   IconHelpCircle,
+  IconRefresh,
+  IconAlertCircle,
+  IconLoader2,
 } from "@tabler/icons-react";
 import Placeholder from "@tiptap/extension-placeholder";
 import type { EditorView } from "@tiptap/pm/view";
@@ -39,10 +42,20 @@ import {
 } from "../ui/popover.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
 import { formatAttachmentError } from "./attachment-accept.js";
+import {
+  ComposerContextMenu,
+  type ComposerContextMenuItem,
+} from "./ComposerContextMenu.js";
 import {
   ComposerPlusMenu,
   type ComposerTerminalModeControl,
 } from "./ComposerPlusMenu.js";
+import {
+  areComposerContextItemsReady,
+  ComposerContextError,
+  snapshotComposerContextItems,
+  type ComposerContextSnapshot,
+} from "./context-items.js";
 import { getComposerDraftKey } from "./draft-key.js";
 import { FileReference } from "./extensions/FileReference.js";
 import { MentionReference } from "./extensions/MentionReference.js";
@@ -93,6 +106,8 @@ export interface TiptapComposerHandle {
   /** Insert text through the editor's normal input path. */
   insertText(text: string): void;
   setText(text: string): void;
+  /** Submit replacement text with the current attachments and context, without editing the draft on failure. */
+  submitWithText(text: string): Promise<boolean>;
   insertReference(ref: AgentComposerReference): void;
 }
 
@@ -102,6 +117,7 @@ export const DEFAULT_VOICE_DICTATION_ENABLED = false;
 
 export interface TiptapComposerSubmitOptions {
   intent?: ComposerSubmitIntent;
+  contextItems?: ComposerContextSnapshot;
 }
 
 export function canSubmitComposerContent(options: {
@@ -762,6 +778,8 @@ export interface TiptapComposerProps {
   ariaLabel?: string;
   disabled?: boolean;
   /** Prevent submission without making the editable surface lose focus. */
+  submissionDisabled?: boolean;
+  /** Prevent submission while a host request is in flight. */
   submitting?: boolean;
   /** Override the generic document attachment cap for a multipart host. */
   maxDocumentAttachmentBytes?: number;
@@ -889,9 +907,13 @@ export interface TiptapComposerProps {
   /** Stable scope for persisted drafts, usually the active thread or tab id. */
   draftScope?: string;
   /** Keyed context nuggets staged for the next submitted prompt. */
-  contextItems?: AgentChatContextItem[];
+  contextItems?: readonly AgentChatContextItem[];
   /** Remove a staged context nugget by key. */
   onRemoveContextItem?: (key: string) => void;
+  onInspectContextItem?: (key: string) => void;
+  onRetryContextItem?: (key: string) => void;
+  contextMenuItems?: readonly ComposerContextMenuItem[];
+  attachmentsEnabled?: boolean;
   /**
    * Controls the "+" menu next to the composer. `"full"` (default) shows the
    * normal Upload / Skill / Job / Automation / MCP picker, plus Extension when
@@ -2434,6 +2456,7 @@ export function TiptapComposer({
   placeholder,
   ariaLabel,
   disabled = false,
+  submissionDisabled = false,
   submitting = false,
   maxDocumentAttachmentBytes = MAX_DOCUMENT_ATTACHMENT_BYTES,
   documentAttachmentLimitLabel = "PDFs",
@@ -2482,14 +2505,19 @@ export function TiptapComposer({
   onConnectLocalRuntime,
   imageModelMenu,
   draftScope,
-  contextItems = [],
+  contextItems: providedContextItems,
   onRemoveContextItem,
+  onInspectContextItem,
+  onRetryContextItem,
+  contextMenuItems,
+  attachmentsEnabled = true,
   plusMenuMode = "full",
   terminalModeControl,
   extensionTools = false,
   interceptBuildRequestsForBuilder = false,
   onAttachmentError,
 }: TiptapComposerProps) {
+  const contextItems = providedContextItems ?? [];
   const adapters = useComposerRuntimeAdapters();
   const t = adapters.translate!;
   const sendButtonTooltip = t(getComposerSendTooltipKey(willQueue), {
@@ -2512,10 +2540,18 @@ export function TiptapComposer({
   >(null);
   const composerText = useComposer((state) => state.text);
   const composerAttachments = useComposer((state) => state.attachments);
+  const [contextSubmissionError, setContextSubmissionError] = useState<
+    string | null
+  >(null);
+  useEffect(() => setContextSubmissionError(null), [providedContextItems]);
   const canSend = canSubmitComposerContent({
     hasEditorContent: editorHasText || slotReferences.length > 0,
     attachmentCount: composerAttachments.length,
-    disabled: disabled || submitting,
+    disabled:
+      disabled ||
+      submissionDisabled ||
+      submitting ||
+      !areComposerContextItemsReady(contextItems),
   });
   const primaryAction = resolveComposerPrimaryAction({
     canSubmit: canSend,
@@ -2616,6 +2652,12 @@ export function TiptapComposer({
   onTextChangeRef.current = onTextChange;
   const contextItemsRef = useRef(contextItems);
   contextItemsRef.current = contextItems;
+  const contextItemsProvidedRef = useRef(providedContextItems !== undefined);
+  contextItemsProvidedRef.current = providedContextItems !== undefined;
+  const submissionDisabledRef = useRef(
+    disabled || submissionDisabled || submitting,
+  );
+  submissionDisabledRef.current = disabled || submissionDisabled || submitting;
   const onRemoveContextItemRef = useRef(onRemoveContextItem);
   onRemoveContextItemRef.current = onRemoveContextItem;
   const selectedContextItemKeyRef = useRef<string | null>(null);
@@ -2871,7 +2913,9 @@ export function TiptapComposer({
         const cursorAtStart = from === to && from <= 1;
         if (event.key === "Backspace" && onRemoveContextItemRef.current) {
           const chipAction = resolveContextChipBackspaceAction({
-            contextItemKeys: contextItemsRef.current.map((item) => item.key),
+            contextItemKeys: contextItemsRef.current
+              .filter((item) => item.removable !== false)
+              .map((item) => item.key),
             selectedKey: selectedContextItemKeyRef.current,
             cursorAtStart,
           });
@@ -2883,9 +2927,6 @@ export function TiptapComposer({
             } else {
               selectedContextItemKeyRef.current = null;
               setSelectedContextItemKey(null);
-              contextItemsRef.current = contextItemsRef.current.filter(
-                (item) => item.key !== chipAction.key,
-              );
               onRemoveContextItemRef.current?.(chipAction.key);
             }
             return true;
@@ -3162,6 +3203,7 @@ export function TiptapComposer({
       onTextChangeRef.current?.(trimmed);
       flushComposerDraft();
     },
+    submitWithText: (text: string) => submitComposer("immediate", text),
     insertReference,
   }));
 
@@ -3558,10 +3600,34 @@ export function TiptapComposer({
   );
 
   const submitComposer = useCallback(
-    async (intent: ComposerSubmitIntent = "immediate") => {
+    async (
+      intent: ComposerSubmitIntent = "immediate",
+      textOverride?: string,
+    ): Promise<boolean> => {
       const ed = editor;
-      if (!isComposerEditorUsable(ed)) return;
-      if (submitInFlightRef.current) return;
+      if (!isComposerEditorUsable(ed)) return false;
+      if (submitInFlightRef.current) return false;
+      if (
+        submissionDisabledRef.current ||
+        !areComposerContextItemsReady(contextItemsRef.current)
+      )
+        return false;
+      let contextSnapshot: ComposerContextSnapshot | undefined;
+      setContextSubmissionError(null);
+      try {
+        contextSnapshot = snapshotComposerContextItems(
+          contextItemsProvidedRef.current ? contextItemsRef.current : undefined,
+        );
+      } catch (error) {
+        if (!(error instanceof ComposerContextError)) throw error;
+        setContextSubmissionError(
+          t("agentChat.composer.contextLimitExceeded", {
+            defaultValue:
+              "Context is too large. Remove an item or attach a smaller selection.",
+          }),
+        );
+        return false;
+      }
 
       draftEditorRef.current = ed;
       flushComposerDraft();
@@ -3583,10 +3649,11 @@ export function TiptapComposer({
       const isCurrentDraftScope = () =>
         draftKeyRef.current === submittingDraftKey &&
         draftScopeGenerationRef.current === submittingDraftGeneration;
-      const { text, references } = syncComposerState();
+      const { text: draftText, references } = syncComposerState();
+      const text = textOverride ?? draftText;
       const attachments = composerRuntime.getState().attachments;
       if (!text.trim() && references.length === 0 && attachments.length === 0)
-        return;
+        return false;
       const oversizedDocumentError = getOversizedDocumentAttachmentError(
         attachments,
         {
@@ -3597,7 +3664,7 @@ export function TiptapComposer({
       );
       if (oversizedDocumentError) {
         onAttachmentErrorRef.current?.(oversizedDocumentError);
-        return;
+        return false;
       }
       const cancelActiveVoice = () => {
         if (
@@ -3617,7 +3684,7 @@ export function TiptapComposer({
         if (matched) {
           clearEditorAfterSubmit();
           announceSlashCommand(matched);
-          return;
+          return true;
         }
       }
 
@@ -3634,20 +3701,20 @@ export function TiptapComposer({
       ) {
         cancelActiveVoice();
         clearEditorAfterSubmit();
-        return;
+        return true;
       }
 
       if (onBeforeSubmit) {
         submitInFlightRef.current = true;
         try {
           const shouldSubmit = await onBeforeSubmit();
-          if (!shouldSubmit) return;
+          if (!shouldSubmit) return false;
         } finally {
           submitInFlightRef.current = false;
         }
       }
-      if (!isComposerEditorUsable(ed)) return;
-      if (!isCurrentDraftScope()) return;
+      if (!isComposerEditorUsable(ed)) return false;
+      if (!isCurrentDraftScope()) return false;
 
       // Composer mode: send with context via agent chat bridge
       if (composerMode) {
@@ -3668,15 +3735,25 @@ export function TiptapComposer({
                 defaultValue: "Use the attached context.",
               })
             : "");
+        const modeContext = config.getContext(modePrompt);
+        const contextItemsText = contextSnapshot?.length
+          ? formatPromptContextItems(contextSnapshot)
+          : "";
+        const context = contextItemsText
+          ? `${modeContext}\n\n${contextItemsText}`
+          : modeContext;
         if (attachments.length > 0) {
           composerRuntime.setText(
-            `${message}\n\n<context>\n${config.getContext(modePrompt)}\n</context>`,
+            `${message}\n\n<context>\n${context}\n</context>`,
           );
           composerRuntime.send();
         } else {
           adapters.agentChat!.sendToAgentChat!({
             message,
-            context: config.getContext(modePrompt),
+            context,
+            ...(contextSnapshot === undefined
+              ? {}
+              : { contextItems: contextSnapshot }),
             mode:
               execMode === "plan"
                 ? "plan"
@@ -3695,32 +3772,44 @@ export function TiptapComposer({
         cancelScheduledDraftPersist();
         clearComposerDraft(draftKey);
         closePopover();
-        return;
+        return true;
       }
 
       if (onSubmit) {
-        if (submitInFlightRef.current) return;
+        if (submitInFlightRef.current) return false;
         submitInFlightRef.current = true;
         try {
-          await onSubmit(text, references, attachments, { intent });
-        } catch {
-          // Hosts own their submit errors. Keep the draft and attachments
-          // available for recovery when a host rejects the submission.
-          return;
+          await onSubmit(text, references, attachments, {
+            intent,
+            ...(contextSnapshot === undefined
+              ? {}
+              : { contextItems: contextSnapshot }),
+          });
+        } catch (error) {
+          setContextSubmissionError(
+            formatAttachmentError(
+              error,
+              t("agentChat.composer.submitFailed", {
+                defaultValue: "Could not submit. Try again.",
+              }),
+            ),
+          );
+          return false;
         } finally {
           submitInFlightRef.current = false;
         }
-        if (!isCurrentDraftScope()) return;
+        if (!isCurrentDraftScope()) return true;
         // Clear any pending attachments now that the host has them.
         void composerRuntime.clearAttachments().catch(() => {});
         if (!clearOnSubmit) {
           closePopover();
-          return;
+          return true;
         }
         cancelActiveVoice();
         clearEditorAfterSubmit(submittingDraftSnapshot);
-        return;
+        return true;
       } else {
+        if (textOverride !== undefined) composerRuntime.setText(text);
         composerRuntime.send();
       }
       cancelActiveVoice();
@@ -3730,6 +3819,7 @@ export function TiptapComposer({
       cancelScheduledDraftPersist();
       clearComposerDraft(draftKey);
       closePopover();
+      return true;
     },
     [
       closePopover,
@@ -4070,6 +4160,9 @@ export function TiptapComposer({
           {contextItems.map((item) => (
             <span
               key={item.key}
+              data-context-key={item.key}
+              data-context-status={item.status ?? "ready"}
+              title={item.statusMessage}
               data-state={
                 selectedContextItemKey === item.key ? "selected" : undefined
               }
@@ -4079,27 +4172,73 @@ export function TiptapComposer({
                   : "border-border bg-muted/50"
               }`}
             >
-              <IconClipboardList className="h-3 w-3 shrink-0 text-muted-foreground" />
-              <span className="min-w-0 truncate">{item.title}</span>
-              <button
-                type="button"
-                onClick={() => {
-                  selectedContextItemKeyRef.current = null;
-                  setSelectedContextItemKey(null);
-                  onRemoveContextItem?.(item.key);
-                }}
-                aria-label={t("agentChat.composer.removeContext", {
-                  defaultValue: "Remove {{name}} context",
-                  name: item.title,
-                })}
-                className="ms-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground"
-              >
-                <IconX className="h-3 w-3" />
-              </button>
+              {item.status === "pending" ? (
+                <IconLoader2
+                  aria-label={t("agentChat.composer.contextPending", {
+                    defaultValue: "Context pending",
+                  })}
+                  className="size-3 shrink-0 animate-spin motion-reduce:animate-none text-muted-foreground"
+                />
+              ) : item.status === "error" ? (
+                <IconAlertCircle
+                  aria-label={t("agentChat.composer.contextError", {
+                    defaultValue: "Context failed",
+                  })}
+                  className="size-3 shrink-0 text-destructive"
+                />
+              ) : (
+                <IconClipboardList className="h-3 w-3 shrink-0 text-muted-foreground" />
+              )}
+              {onInspectContextItem ? (
+                <button
+                  type="button"
+                  onClick={() => onInspectContextItem(item.key)}
+                  className="min-w-0 truncate hover:underline"
+                >
+                  {item.title}
+                </button>
+              ) : (
+                <span className="min-w-0 truncate">{item.title}</span>
+              )}
+              {item.status === "error" && onRetryContextItem ? (
+                <button
+                  type="button"
+                  onClick={() => onRetryContextItem(item.key)}
+                  aria-label={t("agentChat.composer.retryContext", {
+                    defaultValue: "Retry {{name}} context",
+                    name: item.title,
+                  })}
+                  className="flex size-4 shrink-0 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground"
+                >
+                  <IconRefresh className="size-3" />
+                </button>
+              ) : null}
+              {onRemoveContextItem && item.removable !== false ? (
+                <button
+                  type="button"
+                  onClick={() => {
+                    selectedContextItemKeyRef.current = null;
+                    setSelectedContextItemKey(null);
+                    onRemoveContextItem?.(item.key);
+                  }}
+                  aria-label={t("agentChat.composer.removeContext", {
+                    defaultValue: "Remove {{name}} context",
+                    name: item.title,
+                  })}
+                  className="ms-0.5 flex h-4 w-4 shrink-0 items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground"
+                >
+                  <IconX className="h-3 w-3" />
+                </button>
+              ) : null}
             </span>
           ))}
         </div>
       )}
+      {contextSubmissionError ? (
+        <p role="alert" className="px-2 text-xs text-destructive">
+          {contextSubmissionError}
+        </p>
+      ) : null}
       <div
         data-agent-composer-variant={layoutVariant}
         data-agent-composer-slot="editor-wrap"
@@ -4121,7 +4260,17 @@ export function TiptapComposer({
         className="agent-composer-toolbar flex items-center gap-1 px-2 py-1.5"
       >
         {attachButton ??
-          (plusMenuMode === "hidden" ? null : (
+          (contextMenuItems !== undefined || plusMenuMode === "upload-only" ? (
+            <ComposerContextMenu
+              items={contextMenuItems ?? []}
+              addAttachment={
+                attachmentsEnabled ? addAttachmentForCurrentScope : undefined
+              }
+              attachmentAccept={composerRuntime.getState().attachmentAccept}
+              onAttachmentError={onAttachmentError}
+              disabled={disabled}
+            />
+          ) : plusMenuMode === "hidden" ? null : (
             <ComposerPlusMenu
               addAttachment={addAttachmentForCurrentScope}
               attachmentAccept={composerRuntime.getState().attachmentAccept}
@@ -4181,6 +4330,7 @@ export function TiptapComposer({
                     type="button"
                     onClick={() => void submitComposer("immediate")}
                     disabled={!canSend}
+                    aria-label={sendButtonTooltip}
                     data-agent-composer-slot="send-button"
                     className="agent-composer-send-button shrink-0 flex h-7 w-7 items-center justify-center rounded-md bg-primary text-primary-foreground hover:opacity-90 transition-[opacity,transform] duration-150 active:scale-[0.97] disabled:opacity-30 disabled:cursor-not-allowed"
                   >

package/src/composer/context-items.spec.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  areComposerContextItemsReady,
+  snapshotComposerContextItems,
+  COMPOSER_CONTEXT_MAX_BYTES,
+  COMPOSER_CONTEXT_MAX_ITEMS,
+} from "./context-items.js";
+
+describe("persisted reference status", () => {
+  it("enforces item count and serialized UTF-8 byte limits without dropping fields", () => {
+    const item = { key: "brief", title: "Brief", context: "" };
+    expect(
+      snapshotComposerContextItems(
+        Array.from({ length: COMPOSER_CONTEXT_MAX_ITEMS }, () => item),
+      ),
+    ).toHaveLength(COMPOSER_CONTEXT_MAX_ITEMS);
+    expect(() =>
+      snapshotComposerContextItems(
+        Array.from({ length: COMPOSER_CONTEXT_MAX_ITEMS + 1 }, () => item),
+      ),
+    ).toThrow("item limit");
+    const overhead = new TextEncoder().encode(JSON.stringify([item])).length;
+    const exact = {
+      ...item,
+      context: "x".repeat(COMPOSER_CONTEXT_MAX_BYTES - overhead),
+    };
+    expect(snapshotComposerContextItems([exact])[0].context).toBe(
+      exact.context,
+    );
+    expect(() =>
+      snapshotComposerContextItems([
+        { ...exact, context: exact.context + "x" },
+      ]),
+    ).toThrow("size limit");
+    expect(() =>
+      snapshotComposerContextItems([
+        { ...item, context: "界".repeat(COMPOSER_CONTEXT_MAX_BYTES / 2) },
+      ]),
+    ).toThrow("size limit");
+    expect(() =>
+      snapshotComposerContextItems([
+        { ...item, statusMessage: "x".repeat(COMPOSER_CONTEXT_MAX_BYTES) },
+      ]),
+    ).toThrow("size limit");
+  });
+  it("permits steering with a failed persisted source while preserving its honest status", () => {
+    const item = {
+      key: "system-source:source-one",
+      title: "Source",
+      context: "systemId=qa, sourceId=source-one",
+      status: "error" as const,
+      statusMessage: "Read failed",
+      removable: false,
+      blocksSubmission: false,
+    };
+    expect(areComposerContextItemsReady([item])).toBe(true);
+    expect(snapshotComposerContextItems([item])).toEqual([item]);
+  });
+  it.each(["pending", "error"] as const)(
+    "still blocks a normal %s upload/context",
+    (status) => {
+      const item = { key: "upload", title: "Upload", context: "", status };
+      expect(areComposerContextItemsReady([item])).toBe(false);
+      expect(() => snapshotComposerContextItems([item])).toThrow("not ready");
+    },
+  );
+});

package/src/composer/context-items.ts

@@ -0,0 +1,72 @@
+import type { AgentChatContextItem } from "./runtime-adapters.js";
+
+export type ComposerContextSnapshot = readonly Readonly<AgentChatContextItem>[];
+
+export const COMPOSER_CONTEXT_MAX_ITEMS = 32;
+export const COMPOSER_CONTEXT_MAX_BYTES = 64 * 1024;
+
+export class ComposerContextError extends Error {
+  constructor(
+    public readonly code: "not-ready" | "too-many-items" | "too-large",
+  ) {
+    super(
+      code === "not-ready"
+        ? "Composer context is not ready"
+        : code === "too-many-items"
+          ? "Composer context exceeds the item limit"
+          : "Composer context exceeds the size limit",
+    );
+    this.name = "ComposerContextError";
+  }
+}
+
+export function areComposerContextItemsReady(
+  items: readonly AgentChatContextItem[] | undefined,
+): boolean {
+  return !items?.some(
+    (item) =>
+      item.blocksSubmission !== false && item.status && item.status !== "ready",
+  );
+}
+
+export function snapshotComposerContextItems(
+  items: readonly AgentChatContextItem[],
+): ComposerContextSnapshot;
+export function snapshotComposerContextItems(
+  items: readonly AgentChatContextItem[] | undefined,
+): ComposerContextSnapshot | undefined;
+export function snapshotComposerContextItems(
+  items: readonly AgentChatContextItem[] | undefined,
+): ComposerContextSnapshot | undefined {
+  if (items === undefined) return undefined;
+  if (items.length > COMPOSER_CONTEXT_MAX_ITEMS) {
+    throw new ComposerContextError("too-many-items");
+  }
+  if (!areComposerContextItemsReady(items)) {
+    throw new ComposerContextError("not-ready");
+  }
+  const snapshot = Object.freeze(
+    items.map((item) =>
+      Object.freeze({
+        key: item.key,
+        title: item.title,
+        context: item.context,
+        ...(item.removable === undefined ? {} : { removable: item.removable }),
+        ...(item.blocksSubmission === undefined
+          ? {}
+          : { blocksSubmission: item.blocksSubmission }),
+        ...(item.status === undefined ? {} : { status: item.status }),
+        ...(item.statusMessage === undefined
+          ? {}
+          : { statusMessage: item.statusMessage }),
+      }),
+    ),
+  );
+  if (
+    new TextEncoder().encode(JSON.stringify(snapshot)).length >
+    COMPOSER_CONTEXT_MAX_BYTES
+  ) {
+    throw new ComposerContextError("too-large");
+  }
+  return snapshot;
+}

package/src/composer/index.ts

@@ -1,4 +1,30 @@
 export { FileReference } from "./extensions/FileReference.js";
+export {
+  ComposerContextMenu,
+  ComposerContextSearchInput,
+  type ComposerContextSearchInputProps,
+  type ComposerContextPageControls,
+  getComposerContextMenuEntries,
+  type ComposerContextMenuProps,
+  type ComposerContextMenuItem,
+  type ComposerContextMenuAction,
+  type ComposerContextMenuCategory,
+  type ComposerContextPickerConfig,
+  type ComposerContextPickerItem,
+  type ComposerContextPickerRequest,
+  type ComposerContextPickerResult,
+  type ComposerContextPickerSelection,
+  type ComposerContextPickerFooterAction,
+} from "./ComposerContextMenu.js";
+export {
+  areComposerContextItemsReady,
+  snapshotComposerContextItems,
+  ComposerContextError,
+  COMPOSER_CONTEXT_MAX_ITEMS,
+  COMPOSER_CONTEXT_MAX_BYTES,
+  type ComposerContextSnapshot,
+} from "./context-items.js";
+export type { AgentChatContextItem } from "./runtime-adapters.js";
 export { SkillReference } from "./extensions/SkillReference.js";
 export { MentionReference } from "./extensions/MentionReference.js";
 export {
@@ -19,6 +45,7 @@ export {
   displayableComposerModeMessage,
   getComposerSubmitIntentForEnterKey,
   handleComposerFileDrop,
+  getOversizedDocumentAttachmentError,
   insertComposerHardBreakAndScrollIntoView,
   type ComposerSubmitIntent,
   type TiptapComposerHandle,

package/src/composer/runtime-adapters.tsx

@@ -78,11 +78,16 @@ export interface AgentChatContextItem {
   key: string;
   title: string;
   context: string;
+  status?: "ready" | "pending" | "error";
+  statusMessage?: string;
+  removable?: boolean;
+  blocksSubmission?: boolean;
 }
 
 export interface ComposerAgentChatMessage {
   message: string;
   context?: string;
+  contextItems?: readonly Readonly<AgentChatContextItem>[];
   mode?: "plan" | "act";
   submit?: boolean;
 }
@@ -352,7 +357,7 @@ export const AGENT_CHAT_INSERT_REFERENCE_MESSAGE_TYPE =
   "agent-native:insert-composer-reference";
 
 export function formatPromptContextItems(
-  items: AgentChatContextItem[] | undefined,
+  items: readonly AgentChatContextItem[] | undefined,
 ): string {
   return (
     items