@cadraos/sdk 0.3.14-p102.2 → 0.3.14-p139.2

package/dist/chat/index.cjs

@@ -12,6 +12,28 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 var ReactMarkdown__default = /*#__PURE__*/_interopDefault(ReactMarkdown);
 var remarkGfm__default = /*#__PURE__*/_interopDefault(remarkGfm);
 
+// src/streaming/steered-refs.ts
+function readSteeredRefs(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const record = data;
+  const metadata = record.metadata;
+  const candidates = [
+    record.steeredRefs,
+    metadata && typeof metadata === "object" ? metadata.steeredRefs : void 0
+  ];
+  for (const value of candidates) {
+    if (Array.isArray(value)) {
+      const refs = value.filter((v) => typeof v === "string" && v.length > 0);
+      if (refs.length > 0) return refs;
+    }
+  }
+  return void 0;
+}
+function readSteeredRefsField(data) {
+  const steeredRefs = readSteeredRefs(data);
+  return steeredRefs ? { steeredRefs } : {};
+}
+
 // src/resources/base.ts
 var BaseResourceAPI = class {
   http;
@@ -65,6 +87,19 @@ var BaseResourceAPI = class {
   }
 };
 
+// src/utils/api-paths.ts
+var API_V1 = "/api/v1";
+var EXECUTION_PATH = `${API_V1}/executions`;
+function executionPath(executionId) {
+  return `${EXECUTION_PATH}/${executionId}`;
+}
+function executionSteerPath(executionId) {
+  return `${EXECUTION_PATH}/${executionId}/steer`;
+}
+function executionCancelPath(executionId) {
+  return `${EXECUTION_PATH}/${executionId}/cancel`;
+}
+
 // src/errors/sdk-errors.ts
 var CadraError = class extends Error {
   /** Error code */
@@ -1306,7 +1341,9 @@ var ExecutionStreamControllerImpl = class {
       tokenUsage: data.tokenUsage,
       cost: data.cost,
       queuedAt: "",
-      ...data
+      ...data,
+      // p139: normalise steeredRefs (event top level or record metadata).
+      ...readSteeredRefsField(data)
     };
     this.finalExecution = execution;
     this.emit("complete", { execution });
@@ -1760,16 +1797,6 @@ async function collectImagesFromStream(stream, options = {}) {
   });
 }
 
-// src/utils/api-paths.ts
-var API_V1 = "/api/v1";
-var EXECUTION_PATH = `${API_V1}/executions`;
-function executionPath(executionId) {
-  return `${EXECUTION_PATH}/${executionId}`;
-}
-function executionCancelPath(executionId) {
-  return `${EXECUTION_PATH}/${executionId}/cancel`;
-}
-
 // src/resources/agents.ts
 var AgentsAPI = class extends BaseResourceAPI {
   constructor(http, getStreamConfig) {
@@ -2078,6 +2105,8 @@ var AgentsAPI = class extends BaseResourceAPI {
    * Cancel a running execution
    *
    * @param executionId - Execution UUID
+   * @param options - Optional. `scope: 'run_and_work'` stops the run AND the
+   *   background work it started in this conversation (p139); omitted = the run only.
    * @returns Updated execution with cancelled status
    *
    * @example
@@ -2086,10 +2115,10 @@ var AgentsAPI = class extends BaseResourceAPI {
    * console.log(execution.status); // 'cancelled'
    * ```
    */
-  async cancelExecution(executionId) {
+  async cancelExecution(executionId, options) {
     return this.http.post(
       executionCancelPath(executionId),
-      void 0,
+      options && Object.keys(options).length > 0 ? options : void 0,
       { skipRetry: true }
     );
   }
@@ -2106,6 +2135,20 @@ var AgentsAPI = class extends BaseResourceAPI {
       await new Promise((resolve) => setTimeout(resolve, pollInterval));
     }
   }
+  // ===== p139 steer =====
+  /**
+   * p139 — forward messages typed while an execution runs. The server answers
+   * `ACCEPTED` (the run will read them between steps), `QUEUED_BEHIND` (not
+   * read yet; send them after the run) or `ENDED` (run finished; send them as
+   * a new turn). Answered = listed in the run's `steeredRefs` on completion.
+   */
+  async steerExecution(executionId, messages) {
+    return this.http.post(
+      executionSteerPath(executionId),
+      { messages },
+      { skipRetry: true }
+    );
+  }
 };
 
 // src/resources/skills.ts
@@ -3579,6 +3622,9 @@ function resolveBaseUrl(config) {
   if (config.baseUrl) return config.baseUrl;
   return "https://api.cadraos.com";
 }
+function steerableField(result) {
+  return typeof result.steerable === "boolean" ? { steerable: result.steerable } : {};
+}
 function createDefaultAdapter(config) {
   const client = resolveClient(config);
   const baseUrl = resolveBaseUrl(config);
@@ -3598,7 +3644,8 @@ function createDefaultAdapter(config) {
         });
         return {
           executionId: result2.executionId,
-          sessionId: result2.sessionId ?? input.sessionId
+          sessionId: result2.sessionId ?? input.sessionId,
+          ...steerableField(result2)
         };
       }
       const pathId = input.agentId || input.teamId || "";
@@ -3615,7 +3662,8 @@ function createDefaultAdapter(config) {
       });
       return {
         executionId: result.executionId,
-        sessionId: result.sessionId ?? ""
+        sessionId: result.sessionId ?? "",
+        ...steerableField(result)
       };
     },
     async sendMessage(input) {
@@ -3630,11 +3678,12 @@ function createDefaultAdapter(config) {
       });
       return {
         executionId: result.executionId,
-        sessionId: result.sessionId ?? input.sessionId
+        sessionId: result.sessionId ?? input.sessionId,
+        ...steerableField(result)
       };
     },
     async cancelExecution(uuid) {
-      await client.agents.cancelExecution(uuid);
+      await client.agents.cancelExecution(uuid, { scope: "run_and_work" });
     },
     async getExecution(uuid) {
       const exec = await client.agents.getExecution(uuid);
@@ -3642,9 +3691,15 @@ function createDefaultAdapter(config) {
         uuid: exec.uuid,
         status: exec.status === "queued" ? "pending" : exec.status,
         result: exec.output,
-        error: exec.error
+        error: exec.error,
+        ...readSteeredRefsField(exec)
       };
     },
+    // p139: steer a running execution (REST `POST /api/v1/executions/{id}/steer`).
+    async steerExecution(executionId, message) {
+      const res = await client.agents.steerExecution(executionId, [message]);
+      return res.state;
+    },
     // -------------------------------------------------------------------------
     // Attachment Methods (delegates to CadraClient.attachments)
     // -------------------------------------------------------------------------
@@ -4034,7 +4089,7 @@ function useExecutionStream(options) {
               clearTimeout(activityTimeoutRef.current);
               activityTimeoutRef.current = null;
             }
-            onComplete?.();
+            onComplete?.(data);
             break;
           case "error":
             const errorMsg = data.error || "Unknown error";
@@ -4501,7 +4556,9 @@ function useAgentChat(options) {
     onClarification,
     pollingInterval,
     pollingEnabled,
-    historyStaleMs = DEFAULT_HISTORY_STALE_MS
+    historyStaleMs = DEFAULT_HISTORY_STALE_MS,
+    allowSendWhileRunning = false,
+    onSteer
   } = options;
   const contextConfig = useChatConfigOptional();
   const adapter = propsAdapter ?? contextConfig?.adapter;
@@ -4538,6 +4595,29 @@ function useAgentChat(options) {
   const firedToolResultsRef = react.useRef(/* @__PURE__ */ new Set());
   const streamControllerRef = react.useRef(null);
   const pendingDelegationsRef = react.useRef(/* @__PURE__ */ new Map());
+  const onSteerRef = react.useRef(onSteer);
+  onSteerRef.current = onSteer;
+  const adapterRef = react.useRef(adapter);
+  adapterRef.current = adapter;
+  const hasSteerHandler = !!onSteer || typeof adapter.steerExecution === "function";
+  const [runSteerable, setRunSteerable] = react.useState(void 0);
+  const canSendWhileRunning = allowSendWhileRunning && hasSteerHandler && runSteerable === true;
+  const canSendWhileRunningRef = react.useRef(canSendWhileRunning);
+  canSendWhileRunningRef.current = canSendWhileRunning;
+  const runActiveRef = react.useRef(false);
+  const currentExecutionIdRef = react.useRef(null);
+  const pendingSteersRef = react.useRef([]);
+  const flushPendingRef = react.useRef(() => {
+  });
+  const settlePendingSteers = react.useCallback((steeredRefs) => {
+    const pending = pendingSteersRef.current;
+    if (pending.length === 0) return;
+    pendingSteersRef.current = [];
+    const answered = new Set(steeredRefs ?? []);
+    const remaining = pending.filter((p) => !answered.has(p.ref));
+    if (remaining.length === 0) return;
+    setTimeout(() => flushPendingRef.current(remaining), 0);
+  }, []);
   const onDelegationRef = react.useRef(options.onDelegation);
   react.useEffect(() => {
     onDelegationRef.current = options.onDelegation;
@@ -4964,19 +5044,22 @@ function useAgentChat(options) {
     [onClarification]
   );
   const completedRef = react.useRef(false);
-  const handleComplete = react.useCallback((finalOutput) => {
+  const handleComplete = react.useCallback((finalOutput, steeredRefs) => {
     if (completedRef.current) {
       if (__DEV__) console.log("[useAgentChat] handleComplete: skipping duplicate complete");
       return;
     }
     completedRef.current = true;
     if (__DEV__) console.log("[useAgentChat] handleComplete called");
+    runActiveRef.current = false;
+    currentExecutionIdRef.current = null;
     setIsLoading(false);
     setIsStreamControllerConnected(false);
     finalizeStreamingMessage(finalOutput);
     setCurrentExecutionId(null);
     streamControllerRef.current = null;
-  }, [finalizeStreamingMessage]);
+    settlePendingSteers(steeredRefs);
+  }, [finalizeStreamingMessage, settlePendingSteers]);
   const handleError = react.useCallback(
     (errorMsg) => {
       if (__DEV__) console.log("[useAgentChat] handleError called:", errorMsg);
@@ -4985,6 +5068,8 @@ function useAgentChat(options) {
         message: errorMsg,
         retryable: true
       };
+      runActiveRef.current = false;
+      currentExecutionIdRef.current = null;
       setError(chatError);
       setIsLoading(false);
       setIsStreamControllerConnected(false);
@@ -4992,8 +5077,9 @@ function useAgentChat(options) {
       setCurrentExecutionId(null);
       streamControllerRef.current = null;
       onError?.(chatError);
+      settlePendingSteers(void 0);
     },
-    [finalizeStreamingMessage, onError]
+    [finalizeStreamingMessage, onError, settlePendingSteers]
   );
   const legacyExecutionId = useStreamController ? void 0 : currentExecutionId;
   const { isConnected: legacyIsConnected, isUsingFallback, disconnect } = useExecutionStream({
@@ -5002,7 +5088,7 @@ function useAgentChat(options) {
     enabled: !!legacyExecutionId,
     onLog: handleStreamLog,
     onClarification: handleClarification,
-    onComplete: handleComplete,
+    onComplete: (data) => handleComplete(void 0, readSteeredRefs(data)),
     onError: handleError,
     // P25 — Action 1: render `progress` / `status_update` / `started`
     // labels in the streaming bubble's thinking pill.
@@ -5072,7 +5158,7 @@ function useAgentChat(options) {
         if (execution.status === "completed") {
           if (__DEV__) console.log("[useAgentChat] Polling: execution completed");
           stopPolling();
-          handleComplete(execution.result || void 0);
+          handleComplete(execution.result || void 0, readSteeredRefs(execution));
           return;
         }
         if (execution.status === "failed") {
@@ -5299,7 +5385,7 @@ function useAgentChat(options) {
       });
       controller.on("complete", ({ execution }) => {
         const output = execution?.output || void 0;
-        handleComplete(output);
+        handleComplete(output, readSteeredRefs(execution));
       });
       controller.on("error", (errorEvent) => {
         handleError(errorEvent.error);
@@ -5315,22 +5401,25 @@ function useAgentChat(options) {
     },
     [adapter, handleExecutionLog, updateStreamingMessage, setStreamingMessageStep, updateToolCall, updateMessageImages, addDelegationEvent, handleClarification, handleComplete, handleError]
   );
-  const sendMessage = react.useCallback(
-    async (content, options2) => {
-      if (!content.trim()) return;
-      const attachmentUuids = options2?.attachmentUuids;
+  const startTurn = react.useCallback(
+    async (content, attachmentUuids, addUserBubble) => {
       lastMessageContentRef.current = content;
+      runActiveRef.current = true;
+      currentExecutionIdRef.current = null;
+      setRunSteerable(void 0);
       setIsLoading(true);
       setError(null);
       setClarification(null);
-      const userMessage = {
-        id: generateId(),
-        role: "user",
-        content: content.trim(),
-        timestamp: /* @__PURE__ */ new Date()
-      };
-      setMessages((prev) => [...prev, userMessage]);
-      onMessage?.(userMessage);
+      if (addUserBubble) {
+        const userMessage = {
+          id: generateId(),
+          role: "user",
+          content: content.trim(),
+          timestamp: /* @__PURE__ */ new Date()
+        };
+        setMessages((prev) => [...prev, userMessage]);
+        onMessage?.(userMessage);
+      }
       const preparedExecutionId = generateExecutionId2();
       const assistantMessageId = generateId();
       const assistantMessage = {
@@ -5375,6 +5464,10 @@ function useAgentChat(options) {
           onSessionCreated?.(result.sessionId);
           onSessionStart?.(result.sessionId);
         }
+        if (runActiveRef.current && !completedRef.current) {
+          currentExecutionIdRef.current = result.executionId;
+        }
+        setRunSteerable(result.steerable);
         if (useStreamController) {
           connectStreamController(
             result.executionId,
@@ -5407,6 +5500,64 @@ function useAgentChat(options) {
       handleError
     ]
   );
+  flushPendingRef.current = (pending) => {
+    const attachments = pending.flatMap((p) => p.attachmentUuids ?? []);
+    void startTurn(
+      pending.map((p) => p.text).join("\n\n"),
+      attachments.length > 0 ? attachments : void 0,
+      false
+    );
+  };
+  const steerWhileRunning = react.useCallback(
+    async (text, attachmentUuids) => {
+      const ref = generateExecutionId2();
+      pendingSteersRef.current.push({ ref, text, attachmentUuids });
+      const userMessage = {
+        id: ref,
+        role: "user",
+        content: text,
+        timestamp: /* @__PURE__ */ new Date(),
+        steerState: "pending"
+      };
+      setMessages((prev) => [...prev, userMessage]);
+      onMessage?.(userMessage);
+      const executionId = currentExecutionIdRef.current;
+      if (!executionId) return;
+      let outcome;
+      try {
+        const handler = onSteerRef.current;
+        const steerMessage = { ref, text, ...attachmentUuids?.length ? { attachmentUuids } : {} };
+        outcome = handler ? await handler(executionId, steerMessage) : await adapterRef.current.steerExecution(executionId, steerMessage);
+      } catch {
+        return;
+      }
+      if (outcome === "ACCEPTED") {
+        setMessages(
+          (prev) => prev.map((m) => m.id === ref ? { ...m, steerState: "delivered" } : m)
+        );
+        return;
+      }
+      if (outcome === "ENDED" && !runActiveRef.current) {
+        const idx = pendingSteersRef.current.findIndex((p) => p.ref === ref);
+        if (idx >= 0) {
+          const entry = pendingSteersRef.current.splice(idx, 1)[0];
+          flushPendingRef.current([entry]);
+        }
+      }
+    },
+    [onMessage]
+  );
+  const sendMessage = react.useCallback(
+    async (content, options2) => {
+      if (!content.trim()) return;
+      if (runActiveRef.current && canSendWhileRunningRef.current) {
+        await steerWhileRunning(content.trim(), options2?.attachmentUuids);
+        return;
+      }
+      await startTurn(content, options2?.attachmentUuids, true);
+    },
+    [startTurn, steerWhileRunning]
+  );
   const respondToClarification = react.useCallback(
     async (response) => {
       if (!clarification) return;
@@ -5416,7 +5567,10 @@ function useAgentChat(options) {
     [clarification, sendMessage]
   );
   const cancel = react.useCallback(async () => {
+    pendingSteersRef.current = [];
     if (currentExecutionId) {
+      runActiveRef.current = false;
+      currentExecutionIdRef.current = null;
       try {
         await adapter.cancelExecution(currentExecutionId);
       } catch {
@@ -5442,6 +5596,7 @@ function useAgentChat(options) {
     setError(null);
   }, []);
   const clearMessages = react.useCallback(() => {
+    pendingSteersRef.current = [];
     setMessages([]);
     setCurrentSessionId(null);
     hasLoadedInitialSession.current = false;
@@ -5655,7 +5810,8 @@ function useAgentChat(options) {
     retry,
     clearError,
     clearMessages,
-    loadSession
+    loadSession,
+    canSendWhileRunning
   };
 }
 
@@ -6605,6 +6761,7 @@ function ChatInput({
   placeholder = "Type a message...",
   disabled = false,
   isLoading = false,
+  allowSendWhileRunning = false,
   enableAttachments = false,
   attachments = [],
   onRemoveAttachment,
@@ -6630,6 +6787,7 @@ function ChatInput({
     });
   }, [onInputControlReady, onInputChange]);
   const hasAttachments = enableAttachments && attachments.length > 0;
+  const lockedByRun = isLoading && !allowSendWhileRunning;
   react.useEffect(() => {
     const textarea = textareaRef.current;
     if (textarea) {
@@ -6639,10 +6797,10 @@ function ChatInput({
   }, [content]);
   const handleSubmit = react.useCallback(async () => {
     const trimmedContent = content.trim();
-    if (!trimmedContent && !hasAttachments || disabled || isLoading || isUploadingAttachments) return;
+    if (!trimmedContent && !hasAttachments || disabled || lockedByRun || isUploadingAttachments) return;
     setContent("");
     await onSend(trimmedContent);
-  }, [content, hasAttachments, disabled, isLoading, isUploadingAttachments, onSend]);
+  }, [content, hasAttachments, disabled, lockedByRun, isUploadingAttachments, onSend]);
   const handleKeyDown = react.useCallback(
     (e) => {
       if (e.key === "Enter" && !e.shiftKey) {
@@ -6658,7 +6816,7 @@ function ChatInput({
   const handleAttachClick = react.useCallback(() => {
     dropZoneRef?.current?.openFileDialog();
   }, [dropZoneRef]);
-  const canSend = (content.trim().length > 0 || hasAttachments) && !disabled && !isLoading && !isUploadingAttachments;
+  const canSend = (content.trim().length > 0 || hasAttachments) && !disabled && !lockedByRun && !isUploadingAttachments;
   const showStopButton = isLoading && onStop;
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
@@ -6683,7 +6841,7 @@ function ChatInput({
             {
               type: "button",
               onClick: handleAttachClick,
-              disabled: disabled || isLoading,
+              disabled: disabled || lockedByRun,
               className: cn3(
                 "flex-shrink-0 p-3 rounded-lg transition-colors",
                 "text-gray-500 dark:text-gray-400",
@@ -9076,7 +9234,9 @@ function AgentChat({
   hideTypingIndicator = false,
   onInputChange,
   onInputControlReady,
-  injectedMessages
+  injectedMessages,
+  allowSendWhileRunning = false,
+  onSteer
 }) {
   const {
     messages,
@@ -9090,7 +9250,8 @@ function AgentChat({
     respondToClarification,
     cancel,
     retry,
-    clearError
+    clearError,
+    canSendWhileRunning
   } = useAgentChat({
     agentId,
     teamId,
@@ -9106,7 +9267,9 @@ function AgentChat({
     onClarification,
     onDelegation,
     pollingInterval,
-    pollingEnabled
+    pollingEnabled,
+    allowSendWhileRunning,
+    onSteer
   });
   const effectiveVerbosity = showToolCalls === false ? "hidden" : toolCallVerbosity ?? "compact";
   const dropZoneRef = react.useRef(null);
@@ -9188,6 +9351,7 @@ function AgentChat({
         placeholder,
         disabled: !!clarification || isLoadingHistory,
         isLoading,
+        allowSendWhileRunning: canSendWhileRunning,
         enableAttachments,
         attachments: enableAttachments ? attachments.files : void 0,
         onRemoveAttachment: enableAttachments ? attachments.removeFile : void 0,
@@ -9203,7 +9367,7 @@ function AgentChat({
     {
       ref: dropZoneRef,
       ...attachments.dropZoneProps,
-      disabled: isLoading || !!clarification || isLoadingHistory,
+      disabled: isLoading && !canSendWhileRunning || !!clarification || isLoadingHistory,
       children: chatContent
     }
   ) : chatContent });