@applica-software-guru/persona-chat-sdk 0.1.113 → 0.1.115

package/src/runtime/handlers.ts

@@ -1,6 +1,6 @@
 import { AppendMessage } from '@assistant-ui/react';
 import { StartRunConfig } from '@assistant-ui/react/dist/legacy-runtime/runtime-cores/core/ThreadRuntimeCore';
-import { PersonaProtocol, PersonaMessage, TransformMessages } from '../types';
+import { PersonaProtocol, PersonaMessage, TransformMessages, AgentState } from '../types';
 import type { PersonaLogger } from '../logging';
 import { parseMessages } from '../messages';
 import { fileToBase64 } from './utils';
@@ -11,7 +11,7 @@ import { fileToBase64 } from './utils';
 export function createOnNewHandler(
   protocols: PersonaProtocol[],
   setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  setAgentState: React.Dispatch<React.SetStateAction<AgentState>>,
   transformMessages?: TransformMessages,
   logger?: PersonaLogger,
 ) {
@@ -23,7 +23,19 @@ export function createOnNewHandler(
       throw new Error('Message must contain text or attachments');
     }
 
-    const ready = protocols.some((protocol) => protocol.getName() !== 'transaction' && protocol.status === 'connected');
+    const input = textPart?.type === 'text' ? textPart.text ?? '' : '';
+
+    // Check for steer command: /steer <text>
+    if (input.startsWith('/steer ') && !hasAttachments) {
+      const steerText = input.slice(7).trim();
+      if (steerText) {
+        return steerAgent(protocols, steerText, logger);
+      }
+    }
+
+    const ready = protocols.some(
+      (protocol) => protocol.getName() !== 'transaction' && protocol.status === 'connected',
+    );
 
     if (!ready) {
       setMessages((currentConversation) => {
@@ -40,7 +52,6 @@ export function createOnNewHandler(
       return;
     }
 
-    const input = textPart?.type === 'text' ? textPart.text ?? '' : '';
     const userMessage: PersonaMessage = {
       role: 'user',
       type: 'text',
@@ -53,9 +64,11 @@ export function createOnNewHandler(
       return transformMessages ? transformMessages(newMessages) : newMessages;
     });
 
-    setIsRunning(true);
+    setAgentState('running');
 
-    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+    const protocol = protocols
+      .sort((a, b) => b.getPriority() - a.getPriority())
+      .find((protocol) => protocol.status === 'connected');
 
     const content: Array<PersonaMessage> = [];
 
@@ -133,6 +146,36 @@ export function createOnNewHandler(
   };
 }
 
+/**
+ * Sends a steer command to all connected protocols.
+ */
+async function steerAgent(
+  protocols: PersonaProtocol[],
+  steerText: string,
+  logger?: PersonaLogger,
+) {
+  const connectedProtocols = protocols.filter(
+    (p) => p.getName() !== 'transaction' && p.status === 'connected',
+  );
+
+  if (connectedProtocols.length === 0) {
+    logger?.warn('No connected protocol available for steer');
+    return;
+  }
+
+  logger?.debug('Sending steer command:', steerText);
+
+  // Send steer to all connected protocols
+  await Promise.allSettled(
+    connectedProtocols.map((protocol) =>
+      protocol.sendPacket({
+        type: 'command',
+        payload: { command: 'steer', arguments: { text: steerText } },
+      }),
+    ),
+  );
+}
+
 /**
  * Creates the onEdit handler for editing messages
  */
@@ -140,7 +183,7 @@ export function createOnEditHandler(
   protocols: PersonaProtocol[],
   messages: PersonaMessage[],
   setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  setAgentState: React.Dispatch<React.SetStateAction<AgentState>>,
   transformMessages?: TransformMessages,
   logger?: PersonaLogger,
 ) {
@@ -149,7 +192,9 @@ export function createOnEditHandler(
       throw new Error('Only text messages are supported');
     }
 
-    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+    const protocol = protocols
+      .sort((a, b) => b.getPriority() - a.getPriority())
+      .find((protocol) => protocol.status === 'connected');
 
     if (!protocol) {
       logger?.debug('No protocol available for edit');
@@ -179,7 +224,7 @@ export function createOnEditHandler(
     const newMessages = parseMessages([...messagesToKeep, editedMessage]);
     setMessages(transformMessages ? transformMessages(newMessages) : newMessages);
 
-    setIsRunning(true);
+    setAgentState('running');
 
     const content: Array<PersonaMessage> = [
       {
@@ -202,12 +247,14 @@ export function createOnReloadHandler(
   protocols: PersonaProtocol[],
   messages: PersonaMessage[],
   setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  setAgentState: React.Dispatch<React.SetStateAction<AgentState>>,
   transformMessages?: TransformMessages,
   logger?: PersonaLogger,
 ) {
   return async (parentId: string | null, config: StartRunConfig) => {
-    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+    const protocol = protocols
+      .sort((a, b) => b.getPriority() - a.getPriority())
+      .find((protocol) => protocol.status === 'connected');
 
     if (!protocol) {
       logger?.debug('No protocol available for reload');
@@ -250,7 +297,7 @@ export function createOnReloadHandler(
       return;
     }
 
-    setIsRunning(true);
+    setAgentState('running');
 
     const content: Array<PersonaMessage> = [];
 
@@ -281,39 +328,30 @@ export function createOnReloadHandler(
 }
 
 /**
- * Creates the onCancel handler for cancelling message generation
+ * Creates the onCancel handler for cancelling agent execution.
+ * Sends the dedicated 'cancel' command to all connected protocols.
  */
 export function createOnCancelHandler(
   protocols: PersonaProtocol[],
-  setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
-  transformMessages?: TransformMessages,
+  setAgentState: React.Dispatch<React.SetStateAction<AgentState>>,
+  logger?: PersonaLogger,
 ) {
   return () => {
-    setIsRunning(false);
+    setAgentState('cancelling');
 
-    setMessages((currentMessages) => {
-      const lastMessage = currentMessages[currentMessages.length - 1];
-      if (lastMessage?.role === 'assistant' && !lastMessage.finishReason) {
-        const updatedMessages = [...currentMessages];
-        updatedMessages[updatedMessages.length - 1] = {
-          ...lastMessage,
-          finishReason: 'stop',
-          status: { type: 'incomplete' },
-        };
-        return transformMessages ? transformMessages(updatedMessages) : updatedMessages;
-      }
-      return currentMessages;
-    });
+    logger?.debug('Sending cancel command to all connected protocols');
 
+    // Send the dedicated cancel command to ALL connected protocols
     protocols.forEach((protocol) => {
       if (protocol.status === 'connected') {
         protocol
           .sendPacket({
             type: 'command',
-            payload: { command: 'set_initial_context', arguments: { cancel: true } },
+            payload: { command: 'cancel', arguments: {} },
           })
-          .catch(() => {});
+          .catch((err) => {
+            logger?.error('Failed to send cancel command:', err);
+          });
       }
     });
 

package/src/runtime/listeners.ts

@@ -1,23 +1,147 @@
-import { PersonaPacket, PersonaMessage, PersonaReasoning, PersonaTransaction, PersonaProtocol, TransformMessages } from '../types';
+import {
+  PersonaPacket,
+  PersonaMessage,
+  PersonaReasoning,
+  PersonaTransaction,
+  PersonaProtocol,
+  TransformMessages,
+  AgentState,
+  AgentEndPayload,
+  ToolExecutionStartPayload,
+  ToolExecutionUpdatePayload,
+  ToolExecutionEndPayload,
+  SteerAcceptedPayload,
+  SteerProcessedPayload,
+} from '../types';
 import { parseMessages } from '../messages';
 
 /**
- * Creates packet listener for a protocol
+ * Creates packet listener for a protocol.
+ *
+ * Uses setAgentState instead of setIsRunning for proper lifecycle management.
+ * The send button is only re-enabled after agent_end.
  */
 export function createPacketListener(
   protocol: PersonaProtocol,
   setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
+  setAgentState: React.Dispatch<React.SetStateAction<AgentState>>,
   protocols: PersonaProtocol[],
   transformMessages?: TransformMessages,
+  onSteerAccepted?: (payload: SteerAcceptedPayload) => void,
+  onSteerProcessed?: (payload: SteerProcessedPayload) => void,
 ) {
-  return (message: PersonaPacket) => {
-    if (message.type === 'message') {
-      handleMessagePacket(message.payload as PersonaMessage, protocol, setMessages, setIsRunning, transformMessages);
-    } else if (message.type === 'reasoning') {
-      handleReasoningPacket(message.payload as PersonaReasoning, protocol, setMessages, transformMessages);
-    } else if (message.type === 'transaction') {
-      handleTransactionPacket(message.payload as PersonaTransaction, protocol, protocols);
+  return (packet: PersonaPacket) => {
+    switch (packet.type) {
+      // ─── Lifecycle: Agent ───────────────────────────────────────
+      case 'agent_start':
+        setAgentState('running');
+        break;
+
+      case 'agent_end': {
+        const endPayload = packet.payload as unknown as AgentEndPayload;
+        setAgentState('idle');
+
+        // Aggiungi messaggio di sistema per stop reason speciali
+        if (endPayload.stopReason === 'cancelled') {
+          setMessages((current) => [
+            ...current,
+            {
+              role: 'assistant' as const,
+              type: 'text' as const,
+              text: '⏹ Task cancelled',
+              createdAt: new Date(),
+              finishReason: 'stop',
+              status: { type: 'incomplete' as const },
+            },
+          ]);
+        } else if (endPayload.stopReason === 'error') {
+          setMessages((current) => [
+            ...current,
+            {
+              role: 'assistant' as const,
+              type: 'text' as const,
+              text: `❌ Error: ${endPayload.errorMessage || 'Unknown error'}`,
+              createdAt: new Date(),
+              finishReason: 'stop',
+              status: { type: 'incomplete' as const },
+            },
+          ]);
+        }
+        break;
+      }
+
+      // ─── Lifecycle: Turn ────────────────────────────────────────
+      case 'turn_start':
+        // Opzionale: indicatore di nuovo turno nell'UI
+        break;
+
+      case 'turn_end':
+        // Opzionale: riepilogo turno
+        break;
+
+      // ─── Lifecycle: Tool ────────────────────────────────────────
+      case 'tool_execution_start':
+        handleToolStart(
+          packet.payload as unknown as ToolExecutionStartPayload,
+          protocol,
+          setMessages,
+        );
+        break;
+
+      case 'tool_execution_update':
+        handleToolUpdate(
+          packet.payload as unknown as ToolExecutionUpdatePayload,
+          setMessages,
+        );
+        break;
+
+      case 'tool_execution_end':
+        handleToolEnd(
+          packet.payload as unknown as ToolExecutionEndPayload,
+          protocol,
+          setMessages,
+        );
+        break;
+
+      // ─── Steer ──────────────────────────────────────────────────
+      case 'steer_accepted':
+        onSteerAccepted?.(packet.payload as unknown as SteerAcceptedPayload);
+        break;
+
+      case 'steer_processed':
+        onSteerProcessed?.(packet.payload as unknown as SteerProcessedPayload);
+        break;
+
+      // ─── Messages ───────────────────────────────────────────────
+      case 'message':
+        handleMessagePacket(
+          packet.payload as unknown as PersonaMessage,
+          protocol,
+          setMessages,
+          transformMessages,
+        );
+        break;
+
+      case 'reasoning':
+        handleReasoningPacket(
+          packet.payload as unknown as PersonaReasoning,
+          protocol,
+          setMessages,
+          transformMessages,
+        );
+        break;
+
+      case 'transaction':
+        handleTransactionPacket(
+          packet.payload as unknown as PersonaTransaction,
+          protocol,
+          protocols,
+        );
+        break;
+
+      default:
+        // Ignora packet types sconosciuti (forward compatibility)
+        break;
     }
   };
 }
@@ -26,7 +150,6 @@ function handleMessagePacket(
   personaMessage: PersonaMessage,
   protocol: PersonaProtocol,
   setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
-  setIsRunning: React.Dispatch<React.SetStateAction<boolean>>,
   transformMessages?: TransformMessages,
 ) {
   // Ensure message has proper timestamp
@@ -34,11 +157,6 @@ function handleMessagePacket(
     personaMessage.createdAt = new Date();
   }
 
-  // Handle finish reason and update isRunning state
-  if (personaMessage?.finishReason === 'stop' && !personaMessage?.functionResponse && !personaMessage?.thought) {
-    setIsRunning(false);
-  }
-
   // Convert thought to reasoning type
   if (personaMessage.thought) {
     personaMessage.type = 'reasoning';
@@ -74,6 +192,60 @@ function handleReasoningPacket(
   });
 }
 
-function handleTransactionPacket(transaction: PersonaTransaction, currentProtocol: PersonaProtocol, protocols: PersonaProtocol[]) {
-  protocols.filter((p) => p !== currentProtocol).forEach((p) => p.onTransaction(transaction));
+function handleTransactionPacket(
+  transaction: PersonaTransaction,
+  currentProtocol: PersonaProtocol,
+  protocols: PersonaProtocol[],
+) {
+  protocols
+    .filter((p) => p !== currentProtocol)
+    .forEach((p) => p.onTransaction(transaction));
+}
+
+// ─── Tool Execution Handlers ──────────────────────────────────────────
+
+function handleToolStart(
+  payload: ToolExecutionStartPayload,
+  protocol: PersonaProtocol,
+  _setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+) {
+  // Opzionale: crea un messaggio "tool in esecuzione" visibile nell'UI
+  // Per ora, il tool call viene gestito dal flusso functionCalls esistente.
+  // Qui possiamo emettere un log o un indicatore.
+  if (typeof window !== 'undefined' && (window as any).__PERSONA_DEBUG__) {
+    console.debug(
+      `[${protocol.getName()}] Tool start: ${payload.toolName}`,
+      payload.args,
+    );
+  }
+}
+
+function handleToolUpdate(
+  payload: ToolExecutionUpdatePayload,
+  _setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+) {
+  // Tool streaming update: aggiorna il risultato parziale
+  // Per ora logghiamo; in futuro si può aggiornare un messaggio tool inline
+  if (typeof window !== 'undefined' && (window as any).__PERSONA_DEBUG__) {
+    console.debug(
+      `Tool update: ${payload.toolCallId}`,
+      payload.partialResult,
+    );
+  }
+}
+
+function handleToolEnd(
+  payload: ToolExecutionEndPayload,
+  protocol: PersonaProtocol,
+  _setMessages: React.Dispatch<React.SetStateAction<PersonaMessage[]>>,
+) {
+  // Tool execution completata. Il result arriva anche come functionResponse
+  // nel flusso messaggi. Qui logghiamo per debug.
+  if (typeof window !== 'undefined' && (window as any).__PERSONA_DEBUG__) {
+    console.debug(
+      `[${protocol.getName()}] Tool end: ${payload.toolCallId}`,
+      payload.durationMs ? `(${payload.durationMs}ms)` : '',
+      payload.error ? `ERROR: ${payload.error}` : '',
+    );
+  }
 }

package/src/runtime.tsx

@@ -7,7 +7,7 @@ import {
   SimpleTextAttachmentAdapter,
 } from '@assistant-ui/react';
 import { SimpleFileAttachmentAdapter } from './runtime/file-attachment-adapter';
-import { PersonaConfig, PersonaMessage, PersonaResponse, ProtocolStatus, Session, ThreadData } from './types';
+import { PersonaConfig, PersonaMessage, PersonaResponse, ProtocolStatus, Session, ThreadData, AgentState } from './types';
 import { parseMessages, convertMessage } from './messages';
 import { initializeProtocols } from './runtime/protocols';
 import { createPacketListener } from './runtime/listeners';
@@ -23,6 +23,8 @@ export {
   usePersonaRuntimeWebRTCProtocol,
   usePersonaRuntimeMessages,
   usePersonaRenameThread,
+  useAgentState,
+  useSteerAgent,
 } from './runtime/context';
 
 export type { PersonaMessage, PersonaResponse, ThreadData };
@@ -44,9 +46,12 @@ function PersonaRuntimeProviderInner({
   onThreadUnarchive,
   onThreadDelete,
   enableAttachments = false,
+  enableSteer = false,
+  onSteerAccepted,
+  onSteerProcessed,
   ...config
 }: Readonly<PersonaConfig>) {
-  const [isRunning, setIsRunning] = useState(false);
+  const [agentState, setAgentState] = useState<AgentState>('idle');
   const [messages, setMessages] = useState<PersonaMessage[]>([]);
   const [protocolsStatus, setProtocolsStatus] = useState<Map<string, ProtocolStatus>>(new Map());
   const didMount = useRef(false);
@@ -150,13 +155,23 @@ function PersonaRuntimeProviderInner({
       });
 
       // Packet listener
-      protocol.addPacketListener(createPacketListener(protocol, setMessages, setIsRunning, protocols, transformMessages));
+      protocol.addPacketListener(
+        createPacketListener(
+          protocol,
+          setMessages,
+          setAgentState,
+          protocols,
+          transformMessages,
+          onSteerAccepted,
+          onSteerProcessed,
+        ),
+      );
 
       // Auto-connect if configured
       if (protocol.autostart && protocol.status === 'disconnected') {
         logger?.debug(`Auto-connecting protocol: ${protocol.getName()}`);
         protocol.connect(currentThreadRef.current).catch(() => {});
-        setIsRunning(false);
+        setAgentState('idle');
       }
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -235,30 +250,22 @@ function PersonaRuntimeProviderInner({
   }, [currentThreadId, threads, protocols, sessionStorage, transformMessages, logger]);
 
   // Message handlers
-  const onNew = useCallback(createOnNewHandler(protocols, setMessages, setIsRunning, transformMessages, logger), [
-    protocols,
-    transformMessages,
-    logger,
-  ]);
+  const onNew = useCallback(
+    createOnNewHandler(protocols, setMessages, setAgentState, transformMessages, logger),
+    [protocols, transformMessages, logger],
+  );
 
-  const onEdit = useCallback(createOnEditHandler(protocols, messages, setMessages, setIsRunning, transformMessages, logger), [
-    protocols,
-    messages,
-    transformMessages,
-    logger,
-  ]);
+  const onEdit = useCallback(
+    createOnEditHandler(protocols, messages, setMessages, setAgentState, transformMessages, logger),
+    [protocols, messages, transformMessages, logger],
+  );
 
-  const onReload = useCallback(createOnReloadHandler(protocols, messages, setMessages, setIsRunning, transformMessages, logger), [
-    protocols,
-    messages,
-    transformMessages,
-    logger,
-  ]);
+  const onReload = useCallback(
+    createOnReloadHandler(protocols, messages, setMessages, setAgentState, transformMessages, logger),
+    [protocols, messages, transformMessages, logger],
+  );
 
-  const onCancel = useCallback(createOnCancelHandler(protocols, setMessages, setIsRunning, transformMessages), [
-    protocols,
-    transformMessages,
-  ]);
+  const onCancel = useCallback(createOnCancelHandler(protocols, setAgentState, logger), [protocols, logger]);
 
   const handleSetMessages = useCallback(
     (newMessages: readonly PersonaMessage[]) => {
@@ -302,6 +309,7 @@ function PersonaRuntimeProviderInner({
   ]);
 
   // Create runtime
+  const isRunning = agentState === 'running' || agentState === 'cancelling';
   const runtime = useExternalStoreRuntime({
     isRunning,
     messages,
@@ -334,8 +342,30 @@ function PersonaRuntimeProviderInner({
     [sessionStorage, onThreadRename],
   );
 
+  const steerAgent = useCallback(
+    async (text: string) => {
+      const connectedProtocols = protocols.filter(
+        (p) => p.getName() !== 'transaction' && p.status === 'connected',
+      );
+      if (connectedProtocols.length === 0) {
+        logger?.warn('No connected protocol available for steer');
+        return;
+      }
+      logger?.debug('Sending steer command:', text);
+      await Promise.allSettled(
+        connectedProtocols.map((protocol) =>
+          protocol.sendPacket({
+            type: 'command',
+            payload: { command: 'steer', arguments: { text } },
+          }),
+        ),
+      );
+    },
+    [protocols, logger],
+  );
+
   return (
-    <PersonaRuntimeContext.Provider value={{ protocols, protocolsStatus, getMessages, renameThread }}>
+    <PersonaRuntimeContext.Provider value={{ protocols, protocolsStatus, agentState, getMessages, renameThread, steerAgent }}>
       <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>
     </PersonaRuntimeContext.Provider>
   );

package/src/types.ts

@@ -103,16 +103,25 @@ export type PersonaSource = {
 };
 
 export type PersonaCommand = {
-  command: 'get_mcp_assets' | 'set_initial_context' | 'set_local_tools';
+  command: 'get_mcp_assets' | 'set_initial_context' | 'set_local_tools' | 'cancel' | 'steer' | 'get_agent_state';
   arguments: Record<string, unknown>;
 };
 
 export type PersonaRequest = PersonaMessage | Array<PersonaMessage> | string;
 
-export type PersonaPacketPayload = PersonaRequest | PersonaCommand | PersonaReasoning | PersonaTransaction;
+export type PersonaPacketPayload = PersonaRequest | PersonaCommand | PersonaReasoning | PersonaTransaction
+  | AgentStartPayload | AgentEndPayload
+  | TurnStartPayload | TurnEndPayload
+  | ToolExecutionStartPayload | ToolExecutionUpdatePayload | ToolExecutionEndPayload
+  | SteerAcceptedPayload | SteerProcessedPayload
+  | Record<string, unknown>;
 
 export type PersonaPacket = {
-  type: 'request' | 'message' | 'command' | 'reasoning' | 'mcp_assets' | 'transaction';
+  type: 'request' | 'message' | 'command' | 'reasoning' | 'mcp_assets' | 'transaction'
+    | 'agent_start' | 'agent_end'
+    | 'turn_start' | 'turn_end'
+    | 'tool_execution_start' | 'tool_execution_update' | 'tool_execution_end'
+    | 'steer_accepted' | 'steer_processed';
   payload?: PersonaPacketPayload;
 };
 
@@ -139,6 +148,66 @@ export type PersonaMessage = {
   };
 };
 
+// ─── Nuovi tipi per il lifecycle dell'agente ─────────────────────────
+
+export type AgentState = 'idle' | 'running' | 'cancelling';
+
+export type AgentStartPayload = {
+  sessionId: string;
+  agentId: string;
+  timestamp: string;
+};
+
+export type AgentEndPayload = {
+  sessionId: string;
+  stopReason: 'completed' | 'cancelled' | 'error' | 'max_turns' | 'steered_completion';
+  totalTurns: number;
+  totalCredits?: number;
+  errorMessage?: string;
+};
+
+export type TurnStartPayload = {
+  turnNumber: number;
+  timestamp: string;
+};
+
+export type TurnEndPayload = {
+  turnNumber: number;
+  messageCount: number;
+  toolResults: Array<{ toolCallId: string; toolName: string; result: string }>;
+};
+
+export type ToolExecutionStartPayload = {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+  timestamp: string;
+};
+
+export type ToolExecutionUpdatePayload = {
+  toolCallId: string;
+  partialResult: unknown;
+};
+
+export type ToolExecutionEndPayload = {
+  toolCallId: string;
+  result: unknown;
+  durationMs?: number;
+  error?: string;
+};
+
+export type SteerAcceptedPayload = {
+  steerId: string;
+  text: string;
+  acceptedAt: string;
+  willProcessAfterTurn: number | null;
+};
+
+export type SteerProcessedPayload = {
+  steerId: string;
+  processedAtTurn: number;
+};
+
 export type ModelResponse = {
   messages: PersonaMessage[];
 };
@@ -283,4 +352,20 @@ export type PersonaConfig = PersonaBaseConfig &
      * Enable file attachments (images, PDFs, text files) in the composer
      */
     enableAttachments?: boolean;
+
+    /**
+     * Enable steer commands during agent execution.
+     * When true, the user can send steer instructions while the agent is running.
+     */
+    enableSteer?: boolean;
+
+    /**
+     * Callback when a steer command is accepted by the server.
+     */
+    onSteerAccepted?: (payload: SteerAcceptedPayload) => void;
+
+    /**
+     * Callback when a steer command is processed (injected into the agent context).
+     */
+    onSteerProcessed?: (payload: SteerProcessedPayload) => void;
   };