@cognipeer/agent-sdk 0.6.2 → 0.6.3

package/dist/index.cjs

@@ -627,6 +627,7 @@ function buildSystemPrompt(extra, planning, name = "Agent", todoListPrompt) {
     "- Keep privacy and safety: do not reveal secrets or sensitive data.",
     "- If inputs are ambiguous or missing, ask one concise clarifying question.",
     "- Reuse prior tool results already present in the conversation when sufficient.",
+    '- Use recovery tools such as "get_tool_response" only when the visible transcript explicitly shows a reduced tool-response marker (for example ARCHIVED_TOOL_RESPONSE, STRUCTURED_TOOL_RESPONSE, SUMMARIZED_TOOL_RESPONSE, DROPPED_TOOL_RESPONSE, or a truncation note with an executionId). Never use a recovery tool to re-fetch a normal tool result already visible in context.',
     planningBlock,
     extraTrimmed ? `Extra instructions: ${extraTrimmed}` : ""
   ].filter(Boolean).join("\n");
@@ -2552,6 +2553,7 @@ function createToolsNode(initialTools, opts) {
         anyTool._stateRef.toolHistory = state.toolHistory;
         anyTool._stateRef.toolHistoryArchived = state.toolHistoryArchived;
         anyTool._stateRef.pendingApprovals = pendingApprovals;
+        anyTool._stateRef.messages = state.messages;
         anyTool._stateRef.ctx = state.ctx || (state.ctx = {});
         anyTool._stateRef.__onEvent = onEvent;
       }
@@ -4020,8 +4022,10 @@ function createAgent(opts) {
       agentRuntime: res.agent || runtime,
       status: "success"
     });
-    const finalAssistantMsg = getLastAssistantMessage(res.messages);
-    const content = extractMessageText2(finalAssistantMsg);
+    const isTransientSummarizationExit = !!res.ctx?.__needsSummarization;
+    const finalAssistantMsg = isTransientSummarizationExit ? void 0 : getLastAssistantMessage(res.messages);
+    const finalIsSyntheticSummary = !isTransientSummarizationExit && finalAssistantMsg && isSyntheticSummaryMessage(finalAssistantMsg);
+    const content = isTransientSummarizationExit || finalIsSyntheticSummary ? "" : extractMessageText2(finalAssistantMsg);
     let parsed = void 0;
     let outputError = void 0;
     if (soManager) {
@@ -4034,17 +4038,19 @@ function createAgent(opts) {
         } else {
           outputError = fallbackResult.error;
         }
-      } else {
+      } else if (!isTransientSummarizationExit) {
         const noResult = soManager.noOutputResult(1);
         if (!noResult.success) {
           outputError = noResult.error;
         }
       }
     }
-    emit({ type: "finalAnswer", content });
-    if (streamEnabled && content) {
-      onStream?.({ text: content, isFinal: true });
-      emit({ type: "stream", text: content, isFinal: true });
+    if (!isTransientSummarizationExit && !finalIsSyntheticSummary) {
+      emit({ type: "finalAnswer", content });
+      if (streamEnabled && content) {
+        onStream?.({ text: content, isFinal: true });
+        emit({ type: "stream", text: content, isFinal: true });
+      }
     }
     return {
       content,
@@ -4842,6 +4848,13 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
     };
   };
 }
+var TOOL_RESPONSE_RECOVERY_MARKERS = [
+  /ARCHIVED_TOOL_RESPONSE\s*\[/,
+  /STRUCTURED_TOOL_RESPONSE\s*\[/,
+  /SUMMARIZED_TOOL_RESPONSE\b/,
+  /DROPPED_TOOL_RESPONSE\s*\[/,
+  /Use get_tool_response with executionId/i
+];
 var todoStatusSchema = zod.z.enum(["not-started", "in-progress", "completed", "blocked"]);
 var todoWriteItemSchema = zod.z.object({
   id: zod.z.number().int().min(1).describe("Sequential id starting from 1"),
@@ -4910,180 +4923,223 @@ function formatTodoListSummary(todoList) {
   }
   return todoList.map((item) => `${item.id}. ${item.title || item.step || item.description || `Step ${item.id}`} [${item.status}]`).join("\n");
 }
-function createContextTools(stateRef, opts) {
-  const tools = [];
-  if (opts?.planningEnabled) {
-    const manageTodo = createTool({
-      name: "manage_todo_list",
-      description: "Manage a structured todo list to track progress and plan tasks throughout your coding session.\n\nOperations:\n- read: return the current plan\n- write: replace the full plan with a complete ordered todoList\n- update: patch existing todo items by id without resending the whole plan\n\nRules:\n- Use write only when creating or fully rewriting the plan\n- After a plan exists, prefer update for status, evidence, or owner changes\n- Update payloads should contain only the changed items\n- When using update, pass expectedVersion to avoid overwriting a newer plan\n- Keep ids unique; write operations must keep ids sequential starting from 1\n- Keep at most ONE item in-progress at a time\n- If update fails due to version mismatch, read the latest plan and retry",
-      schema: zod.z.object({
-        operation: zod.z.enum(["write", "read", "update"]),
-        expectedVersion: zod.z.number().int().min(0).optional(),
-        todoList: zod.z.array(zod.z.union([todoWriteItemSchema, todoUpdateItemSchema])).optional()
-      }),
-      func: async ({ operation, expectedVersion, todoList }) => {
-        const toolStateRef = manageTodo._stateRef;
-        const onEvent = toolStateRef?.__onEvent;
-        const emitPlanEvent = (list) => {
-          const version = stateRef.planVersion || 1;
-          const adherenceScore = stateRef.adherenceScore || 0;
-          const planData = {
-            source: "manage_todo_list",
+function flattenRecoveryContent(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === "string") {
+        return part;
+      }
+      if (part && typeof part === "object") {
+        if (typeof part.text === "string") {
+          return part.text;
+        }
+        if (typeof part.content === "string") {
+          return part.content;
+        }
+      }
+      return "";
+    }).filter(Boolean).join("\n");
+  }
+  return "";
+}
+function hasToolResponseRecoveryReference(messages, executionId) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return false;
+  }
+  return messages.some((message) => {
+    if (message?.role === "system") {
+      return false;
+    }
+    const content = flattenRecoveryContent(message?.content);
+    if (!content) {
+      return false;
+    }
+    const hasRecoveryMarker = TOOL_RESPONSE_RECOVERY_MARKERS.some((pattern) => pattern.test(content));
+    if (!hasRecoveryMarker) {
+      return false;
+    }
+    return executionId ? content.includes(executionId) : true;
+  });
+}
+function createManageTodoTool(stateRef) {
+  const manageTodo = createTool({
+    name: "manage_todo_list",
+    description: "Manage a structured todo list to track progress and plan tasks throughout your coding session.\n\nOperations:\n- read: return the current plan\n- write: replace the full plan with a complete ordered todoList\n- update: patch existing todo items by id without resending the whole plan\n\nRules:\n- Use write only when creating or fully rewriting the plan\n- After a plan exists, prefer update for status, evidence, or owner changes\n- Update payloads should contain only the changed items\n- When using update, pass expectedVersion to avoid overwriting a newer plan\n- Keep ids unique; write operations must keep ids sequential starting from 1\n- Keep at most ONE item in-progress at a time\n- If update fails due to version mismatch, read the latest plan and retry",
+    schema: zod.z.object({
+      operation: zod.z.enum(["write", "read", "update"]),
+      expectedVersion: zod.z.number().int().min(0).optional(),
+      todoList: zod.z.array(zod.z.union([todoWriteItemSchema, todoUpdateItemSchema])).optional()
+    }),
+    func: async ({ operation, expectedVersion, todoList }) => {
+      const toolStateRef = manageTodo._stateRef;
+      const onEvent = toolStateRef?.__onEvent;
+      const emitPlanEvent = (list) => {
+        const version = stateRef.planVersion || 1;
+        const adherenceScore = stateRef.adherenceScore || 0;
+        const planData = {
+          source: "manage_todo_list",
+          operation,
+          version,
+          adherenceScore,
+          count: Array.isArray(list) ? list.length : 0
+        };
+        onEvent?.({ type: "plan", todoList: list, ...planData });
+        const traceSession = toolStateRef?.ctx?.__traceSession;
+        recordTraceEvent(traceSession, {
+          type: "plan",
+          label: `Plan ${operation}`,
+          actor: { scope: "agent", name: "manage_todo_list", role: "planner" },
+          sections: [
+            {
+              kind: "summary",
+              label: "Todo List",
+              content: formatTodoListSummary(list)
+            },
+            {
+              kind: "metadata",
+              label: "Plan Metadata",
+              data: planData
+            }
+          ],
+          debug: planData
+        });
+      };
+      const currentVersion = stateRef.planVersion || 0;
+      if (operation === "read") {
+        const list = stateRef.todoList || [];
+        emitPlanEvent(list);
+        return list;
+      }
+      if (typeof expectedVersion === "number" && expectedVersion !== currentVersion) {
+        return {
+          status: "error",
+          operation,
+          error: "Plan version mismatch. Read the latest plan and retry.",
+          version: currentVersion,
+          adherenceScore: stateRef.adherenceScore || 0
+        };
+      }
+      if (!Array.isArray(todoList)) {
+        return {
+          status: "error",
+          operation,
+          error: "todoList is required for write and update operations.",
+          version: currentVersion,
+          adherenceScore: stateRef.adherenceScore || 0
+        };
+      }
+      if (operation === "write") {
+        const parsed = zod.z.array(todoWriteItemSchema).safeParse(todoList);
+        if (!parsed.success) {
+          return {
+            status: "error",
             operation,
-            version,
-            adherenceScore,
-            count: Array.isArray(list) ? list.length : 0
+            error: parsed.error.issues[0]?.message || "Invalid todoList for write.",
+            version: currentVersion,
+            adherenceScore: stateRef.adherenceScore || 0
           };
-          onEvent?.({ type: "plan", todoList: list, ...planData });
-          const traceSession = toolStateRef?.ctx?.__traceSession;
-          recordTraceEvent(traceSession, {
-            type: "plan",
-            label: `Plan ${operation}`,
-            actor: { scope: "agent", name: "manage_todo_list", role: "planner" },
-            sections: [
-              {
-                kind: "summary",
-                label: "Todo List",
-                content: formatTodoListSummary(list)
-              },
-              {
-                kind: "metadata",
-                label: "Plan Metadata",
-                data: planData
-              }
-            ],
-            debug: planData
-          });
-        };
-        const currentVersion = stateRef.planVersion || 0;
-        if (operation === "read") {
-          const list = stateRef.todoList || [];
-          emitPlanEvent(list);
-          return list;
         }
-        if (typeof expectedVersion === "number" && expectedVersion !== currentVersion) {
+        const normalizedList = parsed.data.map((item) => normalizeTodoItem(item));
+        const validation = validatePlanInvariants(normalizedList, true);
+        if (!validation.ok) {
           return {
             status: "error",
             operation,
-            error: "Plan version mismatch. Read the latest plan and retry.",
+            error: validation.error,
             version: currentVersion,
             adherenceScore: stateRef.adherenceScore || 0
           };
         }
-        if (!Array.isArray(todoList)) {
+        stateRef.todoList = normalizedList;
+      } else if (operation === "update") {
+        const parsed = zod.z.array(todoUpdateItemSchema).safeParse(todoList);
+        if (!parsed.success) {
           return {
             status: "error",
             operation,
-            error: "todoList is required for write and update operations.",
+            error: parsed.error.issues[0]?.message || "Invalid todoList for update.",
             version: currentVersion,
             adherenceScore: stateRef.adherenceScore || 0
           };
         }
-        if (operation === "write") {
-          const parsed = zod.z.array(todoWriteItemSchema).safeParse(todoList);
-          if (!parsed.success) {
-            return {
-              status: "error",
-              operation,
-              error: parsed.error.issues[0]?.message || "Invalid todoList for write.",
-              version: currentVersion,
-              adherenceScore: stateRef.adherenceScore || 0
-            };
-          }
-          const normalizedList = parsed.data.map((item) => normalizeTodoItem(item));
-          const validation = validatePlanInvariants(normalizedList, true);
-          if (!validation.ok) {
-            return {
-              status: "error",
-              operation,
-              error: validation.error,
-              version: currentVersion,
-              adherenceScore: stateRef.adherenceScore || 0
-            };
-          }
-          stateRef.todoList = normalizedList;
-        } else if (operation === "update") {
-          const parsed = zod.z.array(todoUpdateItemSchema).safeParse(todoList);
-          if (!parsed.success) {
-            return {
-              status: "error",
-              operation,
-              error: parsed.error.issues[0]?.message || "Invalid todoList for update.",
-              version: currentVersion,
-              adherenceScore: stateRef.adherenceScore || 0
-            };
-          }
-          const currentList = Array.isArray(stateRef.todoList) ? stateRef.todoList : [];
-          if (currentList.length === 0) {
+        const currentList = Array.isArray(stateRef.todoList) ? stateRef.todoList : [];
+        if (currentList.length === 0) {
+          return {
+            status: "error",
+            operation,
+            error: "No existing plan to update. Use write first.",
+            version: currentVersion,
+            adherenceScore: stateRef.adherenceScore || 0
+          };
+        }
+        const currentMap = new Map(currentList.map((item) => [item.id, item]));
+        const patchMap = /* @__PURE__ */ new Map();
+        for (const item of parsed.data) {
+          if (patchMap.has(item.id)) {
             return {
               status: "error",
               operation,
-              error: "No existing plan to update. Use write first.",
+              error: "Update payload contains duplicate todo ids.",
               version: currentVersion,
               adherenceScore: stateRef.adherenceScore || 0
             };
           }
-          const currentMap = new Map(currentList.map((item) => [item.id, item]));
-          const patchMap = /* @__PURE__ */ new Map();
-          for (const item of parsed.data) {
-            if (patchMap.has(item.id)) {
-              return {
-                status: "error",
-                operation,
-                error: "Update payload contains duplicate todo ids.",
-                version: currentVersion,
-                adherenceScore: stateRef.adherenceScore || 0
-              };
-            }
-            patchMap.set(item.id, item);
-            if (!currentMap.has(item.id)) {
-              return {
-                status: "error",
-                operation,
-                error: `Cannot update missing todo id ${item.id}. Use write to replace the plan.`,
-                version: currentVersion,
-                adherenceScore: stateRef.adherenceScore || 0
-              };
-            }
-          }
-          const mergedList = currentList.map((item) => {
-            const patch = patchMap.get(item.id);
-            return patch ? normalizeTodoItem(patch, item) : item;
-          });
-          const validation = validatePlanInvariants(mergedList, false);
-          if (!validation.ok) {
+          patchMap.set(item.id, item);
+          if (!currentMap.has(item.id)) {
             return {
               status: "error",
               operation,
-              error: validation.error,
+              error: `Cannot update missing todo id ${item.id}. Use write to replace the plan.`,
               version: currentVersion,
               adherenceScore: stateRef.adherenceScore || 0
             };
           }
-          stateRef.todoList = mergedList;
         }
-        stateRef.planVersion = currentVersion + 1;
-        stateRef.adherenceScore = calculateAdherenceScore(stateRef.todoList || []);
-        const payload = {
-          status: "ok",
-          operation,
-          count: Array.isArray(todoList) ? todoList.length : void 0,
-          version: stateRef.planVersion || 1,
-          adherenceScore: stateRef.adherenceScore || 0
-        };
-        emitPlanEvent(stateRef.todoList || []);
-        return payload;
-      }
-    });
-    manageTodo._stateRef = stateRef;
-    tools.push(manageTodo);
-  }
+        const mergedList = currentList.map((item) => {
+          const patch = patchMap.get(item.id);
+          return patch ? normalizeTodoItem(patch, item) : item;
+        });
+        const validation = validatePlanInvariants(mergedList, false);
+        if (!validation.ok) {
+          return {
+            status: "error",
+            operation,
+            error: validation.error,
+            version: currentVersion,
+            adherenceScore: stateRef.adherenceScore || 0
+          };
+        }
+        stateRef.todoList = mergedList;
+      }
+      stateRef.planVersion = currentVersion + 1;
+      stateRef.adherenceScore = calculateAdherenceScore(stateRef.todoList || []);
+      const payload = {
+        status: "ok",
+        operation,
+        count: Array.isArray(todoList) ? todoList.length : void 0,
+        version: stateRef.planVersion || 1,
+        adherenceScore: stateRef.adherenceScore || 0
+      };
+      emitPlanEvent(stateRef.todoList || []);
+      return payload;
+    }
+  });
+  manageTodo._stateRef = stateRef;
+  return manageTodo;
+}
+function createGetToolResponseTool(stateRef) {
   const getTool = createTool({
     name: "get_tool_response",
-    description: "RETRIEVE the full output of a tool execution whose response was archived, dropped, or later compacted in conversation history. Use this only when the preview or summary is missing a specific field, identifier, snippet, or exact payload you still need to finish the task. Do not call it reflexively for every archived response. When a tool response appears as 'ARCHIVED_TOOL_RESPONSE [executionId=xxx]', 'DROPPED_TOOL_RESPONSE [executionId=xxx]', or 'SUMMARIZED_TOOL_RESPONSE [...]', pass the referenced executionId to this tool to get the complete data. You can also pass the original tool_call_id from the tool call.",
+    description: "RETRIEVE the full output of a tool execution whose response was archived, dropped, truncated, or later compacted in conversation history. This tool is only useful when the visible transcript already shows a reduced tool-response marker for the referenced executionId or tool_call_id. Use it only when a marker such as 'ARCHIVED_TOOL_RESPONSE', 'STRUCTURED_TOOL_RESPONSE', 'SUMMARIZED_TOOL_RESPONSE', 'DROPPED_TOOL_RESPONSE', or an explicit truncation note points you to a missing field you still need. Do not call it to re-fetch a normal tool result that is already present in context.",
     schema: zod.z.object({ executionId: zod.z.string().describe("Tool execution id or original tool_call_id") }),
     maxExecutionsPerRun: 8,
     func: async ({ executionId }) => {
+      if (!hasToolResponseRecoveryReference(stateRef.messages, executionId)) {
+        return "Execution not recoverable from the visible transcript. Use this only when the conversation already shows a reduced tool-response marker for that executionId.";
+      }
       const matchesExecution = (t) => t?.executionId === executionId || t?.tool_call_id === executionId;
       let execution = stateRef.toolHistory?.find((t) => matchesExecution(t));
       if (!execution) {
@@ -5096,7 +5152,16 @@ function createContextTools(stateRef, opts) {
     }
   });
   getTool._stateRef = stateRef;
-  tools.push(getTool);
+  return getTool;
+}
+function createContextTools(stateRef, opts) {
+  const tools = [];
+  if (opts?.planningEnabled) {
+    tools.push(createManageTodoTool(stateRef));
+  }
+  if (opts?.includeGetToolResponse ?? true) {
+    tools.push(createGetToolResponseTool(stateRef));
+  }
   return tools;
 }
 
@@ -5264,9 +5329,11 @@ function createSmartAgent(opts) {
     useTodoList: planningEnabled
   };
   const stateRef = { toolHistory: void 0, toolHistoryArchived: void 0, todoList: void 0, planVersion: 0, adherenceScore: 0 };
-  const contextTools = createContextTools(stateRef, { planningEnabled });
-  const mergedTools = [...opts.tools ?? [], ...contextTools];
-  const base = createAgent({ ...runtimeOpts, tools: mergedTools });
+  const contextTools = createContextTools(stateRef, { planningEnabled, includeGetToolResponse: false });
+  const getToolResponseTool = createGetToolResponseTool(stateRef);
+  const toolsWithoutRecovery = [...opts.tools ?? [], ...contextTools];
+  const toolsWithRecovery = [...toolsWithoutRecovery, getToolResponseTool];
+  const base = createAgent({ ...runtimeOpts, tools: toolsWithoutRecovery });
   base.__runtime.runtimeProfile = resolved.runtimeProfile;
   base.__runtime.smart = resolved;
   const summarizationEnabled = resolved.summarization.enable !== false;
@@ -5324,6 +5391,27 @@ function createSmartAgent(opts) {
     );
     return { role: "system", content: sys };
   }
+  function syncRuntimeTools(currentState, currentMessages) {
+    const needsRecoveryTool = hasToolResponseRecoveryReference(currentMessages);
+    const nextTools = needsRecoveryTool ? toolsWithRecovery : toolsWithoutRecovery;
+    const currentRuntime = currentState.agent || base.__runtime;
+    if (currentRuntime.tools === nextTools) {
+      return currentState;
+    }
+    return {
+      ...currentState,
+      agent: {
+        ...currentRuntime,
+        tools: nextTools
+      }
+    };
+  }
+  function producedTerminalAssistantTurn(messages) {
+    const lastAssistant = [...messages].reverse().find((message) => message?.role === "assistant");
+    if (!lastAssistant) return false;
+    const toolCalls = Array.isArray(lastAssistant.tool_calls) ? lastAssistant.tool_calls : [];
+    return toolCalls.length === 0;
+  }
   async function trySummarize(currentState, currentRawMessages) {
     if (!summarizer) return { state: currentState, rawMessages: currentRawMessages, compressed: false };
     const delta = await summarizer(currentState);
@@ -5345,13 +5433,13 @@ function createSmartAgent(opts) {
       stateRef.adherenceScore = input.plan?.adherenceScore || 0;
       const alreadyHasSystem = Array.isArray(input.messages) && input.messages[0]?.role === "system";
       const seedMessages = alreadyHasSystem ? [...input.messages || []] : [systemMessage2(), ...input.messages || []];
-      let state = await syncMemory({ ...input, messages: seedMessages });
+      let state = syncRuntimeTools(await syncMemory({ ...input, messages: seedMessages }), seedMessages);
       let lastResult = null;
       let rawMessages = [...seedMessages];
       const effectiveMaxToolCalls = config?.limits?.maxToolCalls ?? resolved.limits.maxToolCalls ?? 10;
       const iterationLimit = Math.max(effectiveMaxToolCalls * 3 + 5, 30);
       for (let i = 0; i < iterationLimit; i++) {
-        state = { ...state, messages: rawMessages };
+        state = syncRuntimeTools({ ...state, messages: rawMessages }, rawMessages);
         const next = summarizationEnabled ? decideBefore(state) : "agent";
         if (next === "contextSummarize" && summarizer) {
           const result = await trySummarize(state, rawMessages);
@@ -5378,7 +5466,7 @@ function createSmartAgent(opts) {
         if (currentPlan && !state.plan) {
           state = { ...state, plan: currentPlan };
         }
-        state = syncPlanState(await syncMemory(state));
+        state = syncRuntimeTools(syncPlanState(await syncMemory(state)), rawMessages);
         stateRef.toolHistory = state.toolHistory;
         stateRef.toolHistoryArchived = state.toolHistoryArchived;
         if (state.ctx?.__needsSummarization && summarizer) {
@@ -5392,6 +5480,7 @@ function createSmartAgent(opts) {
         }
         if (state.ctx?.__finalizedDueToStructuredOutput) break;
         if (opts.outputSchema && lastResult?.output != null) break;
+        if (producedTerminalAssistantTurn(appendedMessages)) break;
         if (summarizationEnabled) {
           const after = decideAfter(state);
           if (after === "contextSummarize" && summarizer) {
@@ -7691,8 +7780,10 @@ exports.createAgentNode = createAgentNode;
 exports.createCodeGuardrail = createCodeGuardrail;
 exports.createContextSummarizeNode = createContextSummarizeNode;
 exports.createContextTools = createContextTools;
+exports.createGetToolResponseTool = createGetToolResponseTool;
 exports.createGuardrail = createGuardrail;
 exports.createJsonGuardrail = createJsonGuardrail;
+exports.createManageTodoTool = createManageTodoTool;
 exports.createProvider = createProvider;
 exports.createRegexGuardrail = createRegexGuardrail;
 exports.createResolverNode = createResolverNode;
@@ -7714,6 +7805,7 @@ exports.generateTraceId = generateTraceId;
 exports.getModelCapabilities = getModelCapabilities;
 exports.getNestedValue = getNestedValue;
 exports.getResolvedSmartConfig = getResolvedSmartConfig;
+exports.hasToolResponseRecoveryReference = hasToolResponseRecoveryReference;
 exports.httpSink = httpSink;
 exports.isSmartModel = isSmartModel;
 exports.jsonSchemaRule = jsonSchemaRule;