@agents24/chat-react 0.5.37 → 0.5.38

package/README.md

@@ -1,6 +1,6 @@
 # `@agents24/chat-react`
 
-Last Updated: 2026-10-07
+Last Updated: 2026-10-25
 
 Reusable React chat UI, runtime orchestration, and the canonical source-owned Agents24 chat scaffold.
 
@@ -30,6 +30,36 @@ Agent/model selector in the composer, preserves the active controller,
 transcript, thread, and draft while switching, and adopts the durable thread
 ID from the first accepted runtime event.
 
+## Fill the default composer with a suggestion
+
+Keep the default composer and its attachment handling using a public ref:
+
+```tsx
+import { useRef } from "react";
+import { AgentChatComposer, type AgentChatComposerHandle, type AgentChatComposerSubmit } from "@agents24/chat-react/ui";
+
+function SuggestedComposer({ scopeKey, onSubmit }: {
+  scopeKey: string;
+  onSubmit: (message: AgentChatComposerSubmit) => void | Promise<void>;
+}) {
+  const composerRef = useRef<AgentChatComposerHandle>(null);
+  const prompt = "Find a patient with [prescription details].";
+  return <>
+    <button type="button" onClick={() => composerRef.current?.setText(prompt, {
+      focus: true,
+      selection: { start: prompt.indexOf("["), end: prompt.indexOf("]") + 1 },
+    })}>Find a patient</button>
+    <AgentChatComposer ref={composerRef} scopeKey={scopeKey} onSubmit={onSubmit} />
+  </>;
+}
+```
+
+`setText` preserves attached files and previews, updates validation/expansion, and never submits. Focus is optional and defaults to false; selection uses UTF-16 offsets into the new text and does not imply focus. Both apply after text commits. Disabled composers still accept text but skip focus and selection. Existing `textareaRef` remains available independently.
+
+Every accepted update advances the draft revision, protecting suggestions and newer user edits from failed-send recovery. Use the current ref and change `scopeKey` with conversation/identity boundaries. Saved handles return false after a scope change or unmount; accepted updates return true. Scope changes invalidate operations; hosts continue to own conversation draft restoration through `restoredDraft`.
+
+This API is pending the coordinated package release; it is not available in the already published `0.5.37`.
+
 ## Timeline customization
 
 `@agents24/react` projects backend response blocks into canonical ordered `message.parts`. The default scaffold renders that sequence through `AgentResponseTimeline`, preserving interleaved text, tools, HITL, and resumed text.

package/compatibility.json

@@ -1,5 +1,5 @@
 {
-  "contractHash": "904701fe1c173854cd4154f2156020da471397fbc6bb644cea60f44c71a1a0d2",
+  "contractHash": "6d6ceb78b4285f987a5635b4d4d0b407732bf5e61abd1aca1369a97a7d6336e6",
   "contractVersion": "0.3.0",
   "corpus": "conformance/v1/corpus.json",
   "generatedBy": "@agents24/sdk-contract",
@@ -15,11 +15,11 @@
       "reactDom": ">=19 <20"
     },
     "@agents24/client": {
-      "contract": "904701fe1c173854cd4154f2156020da471397fbc6bb644cea60f44c71a1a0d2",
+      "contract": "6d6ceb78b4285f987a5635b4d4d0b407732bf5e61abd1aca1369a97a7d6336e6",
       "runtime": "run-stream.v3"
     },
     "@agents24/node": {
-      "contract": "904701fe1c173854cd4154f2156020da471397fbc6bb644cea60f44c71a1a0d2",
+      "contract": "6d6ceb78b4285f987a5635b4d4d0b407732bf5e61abd1aca1369a97a7d6336e6",
       "node": "^22.0.0 || ^24.0.0"
     },
     "@agents24/react": {
@@ -27,11 +27,11 @@
       "react": ">=19 <20"
     },
     "@talmudpedia/runtime-sdk": {
-      "contract": "904701fe1c173854cd4154f2156020da471397fbc6bb644cea60f44c71a1a0d2",
+      "contract": "6d6ceb78b4285f987a5635b4d4d0b407732bf5e61abd1aca1369a97a7d6336e6",
       "protocolOwner": "@agents24/client"
     },
     "agents24": {
-      "contract": "904701fe1c173854cd4154f2156020da471397fbc6bb644cea60f44c71a1a0d2",
+      "contract": "6d6ceb78b4285f987a5635b4d4d0b407732bf5e61abd1aca1369a97a7d6336e6",
       "python": ">=3.10"
     }
   },

package/dist/registry/agents24-chat.json

@@ -5,9 +5,9 @@
   "title": "Agents24 Chat",
   "description": "Complete editable Agents24 chat, inheriting your application's theme.",
   "dependencies": [
-    "@agents24/chat-react@0.5.37",
-    "@agents24/client@0.2.19",
-    "@agents24/react@0.2.24",
+    "@agents24/chat-react@0.5.38",
+    "@agents24/client@0.2.20",
+    "@agents24/react@0.2.25",
     "@shadcn/react@^0.2.1",
     "class-variance-authority@^0.7.1",
     "clsx@^2.1.1",
@@ -254,13 +254,13 @@
     }
   ],
   "meta": {
-    "version": "0.5.37",
+    "version": "0.5.38",
     "source": "packages/agents24-chat-react/scaffold",
     "source_sha256": "411a13a78466b84a923ae81a16d1b032deb758e7f44c1df5915cfdff71df6d62",
     "agents24": {
-      "@agents24/client": "0.2.19",
-      "@agents24/react": "0.2.24",
-      "@agents24/chat-react": "0.5.37"
+      "@agents24/client": "0.2.20",
+      "@agents24/react": "0.2.25",
+      "@agents24/chat-react": "0.5.38"
     }
   },
   "docs": "Import the installed styles.css from your application stylesheet. Pass your configured AgentClient to Agents24ChatScaffold. Authentication and URLs remain host-owned. Installed UI is editable; review changes before reinstalling and do not use --overwrite on customized files."

package/dist/ui/agent-chat-composer.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { AgentChatComposerFile } from "./composer-attachments";
+import { type AgentChatComposerTextOptions } from "./use-agent-chat-composer";
 import type { AgentChatInputContract } from "../runtime/input-contract";
 import type { ContextWindow } from "@agents24/client/protocol";
 export type { AgentChatComposerFile } from "./composer-attachments";
@@ -8,7 +9,13 @@ export type AgentChatComposerSubmit = {
     files: AgentChatComposerFile[];
     attachmentIds?: string[];
 };
+export type AgentChatComposerHandle = {
+    /** Replace only text, preserving attachments. Returns false after scope change or unmount. */
+    setText(text: string, options?: AgentChatComposerTextOptions): boolean;
+};
 export type AgentChatComposerProps = {
+    /** Public draft controls for the default composer. */
+    ref?: React.Ref<AgentChatComposerHandle>;
     inputContract?: AgentChatInputContract | null;
     recordingEnabled?: boolean;
     contextWindow?: ContextWindow | null;
@@ -35,4 +42,4 @@ export type AgentChatComposerProps = {
     } | null;
     textareaRef?: React.Ref<HTMLTextAreaElement>;
 };
-export declare function AgentChatComposer({ inputContract, recordingEnabled, contextWindow, accept, allowAttachments, className, disabled, forceExpanded, focusKey, scopeKey, inputToolbarContent, isRunning, isCancelling, onAttachmentCountChange, onStop, onSubmit, placeholder, restoredDraft, textareaRef, }: AgentChatComposerProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentChatComposer({ ref, inputContract, recordingEnabled, contextWindow, accept, allowAttachments, className, disabled, forceExpanded, focusKey, scopeKey, inputToolbarContent, isRunning, isCancelling, onAttachmentCountChange, onStop, onSubmit, placeholder, restoredDraft, textareaRef, }: AgentChatComposerProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/index.cjs

@@ -1099,15 +1099,33 @@ function useAgentChatComposer(options) {
   const generationRef = React4.useRef(0);
   const mountedRef = React4.useRef(true);
   const textRef = React4.useRef(text);
+  const scope = React4.useMemo(() => ({ active: false }), [options.scopeKey]);
+  const [textInteraction, setTextInteraction] = React4.useState(null);
+  const handledTextInteractionRef = React4.useRef(textInteraction);
   React4.useLayoutEffect(() => {
+    scope.active = true;
     mountedRef.current = true;
     submittingRef.current = false;
     setIsSubmitting(false);
     return () => {
+      scope.active = false;
       mountedRef.current = false;
       generationRef.current += 1;
     };
-  }, [options.scopeKey]);
+  }, [scope]);
+  React4.useLayoutEffect(() => {
+    if (handledTextInteractionRef.current === textInteraction) return;
+    handledTextInteractionRef.current = textInteraction;
+    if (!textInteraction || textInteraction.scope !== scope || !scope.active || textInteraction.revision !== revisionRef.current || options.disabled) return;
+    const textarea = textareaRef.current;
+    if (!textarea) return;
+    if (textInteraction.options.focus) textarea.focus({ preventScroll: true });
+    const selection = textInteraction.options.selection;
+    if (selection) {
+      const clamp = (offset) => Math.max(0, Math.min(textRef.current.length, offset));
+      textarea.setSelectionRange(clamp(selection.start), clamp(selection.end), selection.direction);
+    }
+  }, [textInteraction, scope, textareaRef, options.disabled]);
   React4.useEffect(() => () => {
     revokeAgentChatComposerFiles(filesRef.current);
     revokeAgentChatComposerFiles([...inFlightFilesRef.current.values()].flat());
@@ -1132,11 +1150,14 @@ function useAgentChatComposer(options) {
     }
   });
   const attachmentMimeTypes = inputMimeTypes(options.inputContract);
-  const setText = (value) => {
-    revisionRef.current += 1;
+  const setText = React4.useCallback((value, interaction = {}) => {
+    if (!scope.active) return false;
+    const revision = ++revisionRef.current;
     textRef.current = value;
     setTextState(value);
-  };
+    setTextInteraction({ scope, revision, options: interaction });
+    return true;
+  }, [scope]);
   const addFiles = (selected) => {
     const accepted = selected.filter((file) => attachmentMimeTypes.includes(canonicalInputMimeType(file.type, file.name)));
     revisionRef.current += 1;
@@ -1349,6 +1370,7 @@ function formatFileCount(files) {
 var pillButtonClass = "inline-flex size-8 shrink-0 items-center justify-center gap-2 rounded-lg border-0 bg-muted text-sm text-muted-foreground shadow-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-0 disabled:pointer-events-none disabled:opacity-50";
 var submitButtonClass = "inline-flex size-9 shrink-0 items-center justify-center gap-2 rounded-lg border-0 bg-primary text-sm text-primary-foreground shadow-none transition-[background-color,color,opacity,transform] duration-200 hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-0 disabled:pointer-events-none disabled:opacity-50";
 function AgentChatComposer({
+  ref,
   inputContract,
   recordingEnabled,
   contextWindow,
@@ -1384,6 +1406,7 @@ function AgentChatComposer({
     onSubmit: (text2, files2) => onSubmit({ text: text2.trim(), files: files2, attachmentIds: files2.flatMap((file) => file.id ? [file.id] : []) })
   });
   const { text, files, setText, isSubmitting, canSubmit, action, submit } = composer;
+  React6.useImperativeHandle(ref, () => ({ setText }), [setText]);
   const isExpanded = forceExpanded || text.includes("\n") || text.length > 62;
   const setTextareaRef = React6.useCallback(
     (node) => {