@cognipeer/agent-sdk 0.5.3 → 0.6.0

package/dist/index.d.cts

@@ -260,7 +260,7 @@ type RuntimeProfile = BuiltInRuntimeProfile | "custom";
 type SummarizationMode = "incremental" | "full_rewrite";
 type ContextPolicy = "raw" | "summary_only" | "hybrid";
 type ToolResponseRetentionPolicy = "keep_full" | "keep_structured" | "summarize_archive" | "drop";
-type ToolResponseClassification = "critical" | "informative" | "verbose" | "redundant";
+type ToolResponseClassification = "critical" | "informative" | "verbose";
 type PlanningMode = "off" | "todo" | "planner_executor" | "reasoning_then_tools";
 type ReplanPolicy = "never" | "on_failure" | "on_conflict" | "every_n_steps";
 type DelegationMode = "off" | "role_based" | "automatic";
@@ -366,15 +366,30 @@ type SmartAgentMemoryConfig = {
     readPolicy?: MemoryReadPolicy;
 };
 type SmartAgentToolResponseConfig = {
+    /**
+     * Hard cap (in characters) applied at tool execution time to a single response.
+     * Anything larger is truncated immediately with a get_tool_response retrieval hint
+     * so a single oversized payload cannot blow up the next model call. Critical
+     * tools are exempt from this cap.
+     */
     maxToolResponseChars?: number;
+    /** Hard cap (approx. tokens) for the same eager truncation rule. */
     maxToolResponseTokens?: number;
+    /**
+     * Retention policy applied to all non-critical tool responses by the summarizer
+     * when it fires (context limit reached). Has no effect at execution time.
+     * Defaults to "summarize_archive".
+     */
     defaultPolicy?: ToolResponseRetentionPolicy;
-    largeResponsePolicy?: ToolResponseRetentionPolicy;
+    /**
+     * Per-tool override of the summarizer retention policy. Wins over `defaultPolicy`.
+     * Critical tools cannot be reduced regardless of override.
+     */
     toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
+    /** Tool names whose responses are never reduced by the summarizer or hard cap. */
     criticalTools?: string[];
     schemaValidation?: "strict" | "warn";
     retryOnSchemaError?: boolean;
-    fallbackPolicy?: ToolResponseRetentionPolicy;
 };
 type SmartAgentCustomProfileConfig = {
     extends?: BuiltInRuntimeProfile;

package/dist/index.d.ts

@@ -260,7 +260,7 @@ type RuntimeProfile = BuiltInRuntimeProfile | "custom";
 type SummarizationMode = "incremental" | "full_rewrite";
 type ContextPolicy = "raw" | "summary_only" | "hybrid";
 type ToolResponseRetentionPolicy = "keep_full" | "keep_structured" | "summarize_archive" | "drop";
-type ToolResponseClassification = "critical" | "informative" | "verbose" | "redundant";
+type ToolResponseClassification = "critical" | "informative" | "verbose";
 type PlanningMode = "off" | "todo" | "planner_executor" | "reasoning_then_tools";
 type ReplanPolicy = "never" | "on_failure" | "on_conflict" | "every_n_steps";
 type DelegationMode = "off" | "role_based" | "automatic";
@@ -366,15 +366,30 @@ type SmartAgentMemoryConfig = {
     readPolicy?: MemoryReadPolicy;
 };
 type SmartAgentToolResponseConfig = {
+    /**
+     * Hard cap (in characters) applied at tool execution time to a single response.
+     * Anything larger is truncated immediately with a get_tool_response retrieval hint
+     * so a single oversized payload cannot blow up the next model call. Critical
+     * tools are exempt from this cap.
+     */
     maxToolResponseChars?: number;
+    /** Hard cap (approx. tokens) for the same eager truncation rule. */
     maxToolResponseTokens?: number;
+    /**
+     * Retention policy applied to all non-critical tool responses by the summarizer
+     * when it fires (context limit reached). Has no effect at execution time.
+     * Defaults to "summarize_archive".
+     */
     defaultPolicy?: ToolResponseRetentionPolicy;
-    largeResponsePolicy?: ToolResponseRetentionPolicy;
+    /**
+     * Per-tool override of the summarizer retention policy. Wins over `defaultPolicy`.
+     * Critical tools cannot be reduced regardless of override.
+     */
     toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
+    /** Tool names whose responses are never reduced by the summarizer or hard cap. */
     criticalTools?: string[];
     schemaValidation?: "strict" | "warn";
     retryOnSchemaError?: boolean;
-    fallbackPolicy?: ToolResponseRetentionPolicy;
 };
 type SmartAgentCustomProfileConfig = {
     extends?: BuiltInRuntimeProfile;

package/dist/index.mjs

@@ -2126,15 +2126,13 @@ var BASE_DEFAULTS = {
     requireJsonOutputContract: true
   },
   toolResponses: {
-    maxToolResponseChars: 3600,
-    maxToolResponseTokens: 1200,
-    defaultPolicy: "keep_structured",
-    largeResponsePolicy: "summarize_archive",
+    maxToolResponseChars: 12e3,
+    maxToolResponseTokens: 3e3,
+    defaultPolicy: "summarize_archive",
     toolResponseRetentionByTool: {},
     criticalTools: [...DEFAULT_CRITICAL_TOOLS],
     schemaValidation: "strict",
-    retryOnSchemaError: true,
-    fallbackPolicy: "keep_structured"
+    retryOnSchemaError: true
   }
 };
 function buildProfile(overrides) {
@@ -2173,7 +2171,7 @@ var DEFAULT_PROFILE_CONFIGS = {
     },
     memory: { readPolicy: "recent_only" },
     delegation: { mode: "off", maxDelegationDepth: 1, maxChildCalls: 2, maxParallelChild: 1, childContextPolicy: "minimal" },
-    toolResponses: { maxToolResponseChars: 2400, maxToolResponseTokens: 800 }
+    toolResponses: { maxToolResponseChars: 8e3, maxToolResponseTokens: 2e3 }
   }),
   balanced: buildProfile({}),
   deep: buildProfile({
@@ -2190,7 +2188,7 @@ var DEFAULT_PROFILE_CONFIGS = {
     },
     memory: { scope: "workspace" },
     delegation: { maxDelegationDepth: 3, maxChildCalls: 6 },
-    toolResponses: { maxToolResponseChars: 5400, maxToolResponseTokens: 1800 }
+    toolResponses: { maxToolResponseChars: 16e3, maxToolResponseTokens: 4e3 }
   }),
   research: buildProfile({
     limits: { maxToolCalls: 20, maxParallelTools: 4, maxContextTokens: 56e3 },
@@ -2206,7 +2204,7 @@ var DEFAULT_PROFILE_CONFIGS = {
     },
     memory: { scope: "workspace" },
     delegation: { mode: "automatic", maxDelegationDepth: 4, maxChildCalls: 8, maxParallelChild: 3, childContextPolicy: "full" },
-    toolResponses: { maxToolResponseChars: 7200, maxToolResponseTokens: 2200 }
+    toolResponses: { maxToolResponseChars: 24e3, maxToolResponseTokens: 6e3 }
   })
 };
 function mergeLimits(base, override) {
@@ -2413,57 +2411,65 @@ function summarizeObject(value) {
   return safeStringify(value);
 }
 function classifyToolResponse(toolName, output, config) {
-  const serialized = safeStringify(output);
-  const tokenCount = countApproxTokens(serialized);
   const criticalTools = new Set(config.toolResponses.criticalTools);
   if (criticalTools.has(toolName)) return "critical";
+  const serialized = safeStringify(output);
+  const tokenCount = countApproxTokens(serialized);
   if (tokenCount >= config.toolResponses.maxToolResponseTokens || serialized.length >= config.toolResponses.maxToolResponseChars) {
     return "verbose";
   }
-  if (serialized === "ok" || serialized === "true" || serialized === "null") {
-    return "redundant";
-  }
   return "informative";
 }
-function resolveToolResponsePolicy(toolName, output, config) {
+function applyToolResponseHardCap(toolName, output, executionId, config) {
   const serialized = safeStringify(output);
   const tokenCount = countApproxTokens(serialized);
   const classification = classifyToolResponse(toolName, output, config);
-  const byTool = config.toolResponses.toolResponseRetentionByTool[toolName];
-  let retentionPolicy = byTool || config.toolResponses.defaultPolicy;
-  if (classification === "critical") {
-    retentionPolicy = byTool || config.toolResponses.fallbackPolicy;
-  } else if (classification === "verbose") {
-    retentionPolicy = byTool || config.toolResponses.largeResponsePolicy;
-  } else if (classification === "redundant") {
-    retentionPolicy = byTool || "drop";
-  }
-  const summary = summarizeObject(output);
-  if (retentionPolicy === "keep_full") {
-    return { classification, retentionPolicy, content: serialized, rawOutput: output, summary, tokenCount };
-  }
-  if (retentionPolicy === "keep_structured") {
-    return { classification, retentionPolicy, content: summary, rawOutput: output, summary, tokenCount };
-  }
-  if (retentionPolicy === "summarize_archive") {
-    return {
-      classification,
-      retentionPolicy,
-      content: `ARCHIVED_TOOL_RESPONSE: ${summary}`,
-      rawOutput: output,
-      summary,
-      tokenCount
-    };
+  if (classification !== "verbose") {
+    return { classification, content: serialized, rawOutput: output, tokenCount, truncated: false };
   }
+  const cap = config.toolResponses.maxToolResponseChars;
+  const head = serialized.slice(0, cap);
+  const note = `
+... [TRUNCATED ${serialized.length - cap} chars by hard cap. Use get_tool_response with executionId="${executionId}" to fetch the full payload.]`;
   return {
     classification,
-    retentionPolicy,
-    content: `DROPPED_TOOL_RESPONSE: ${summary}`,
+    content: head + note,
     rawOutput: output,
-    summary,
-    tokenCount
+    tokenCount,
+    truncated: true
   };
 }
+function resolveSummarizationRetention(toolName, config) {
+  const criticalTools = new Set(config.toolResponses.criticalTools);
+  if (criticalTools.has(toolName)) return "keep_full";
+  const byTool = config.toolResponses.toolResponseRetentionByTool[toolName];
+  return byTool || config.toolResponses.defaultPolicy;
+}
+function renderRetainedToolMessage(args) {
+  const { policy, rawOutput, toolName, toolCallId, executionId, prebuiltSummary } = args;
+  if (policy === "keep_full") {
+    return typeof rawOutput === "string" ? rawOutput : safeStringify(rawOutput);
+  }
+  const summary = prebuiltSummary || summarizeObject(rawOutput);
+  const refs = [
+    `toolName=${toolName}`,
+    toolCallId ? `toolCallId=${toolCallId}` : null,
+    executionId ? `executionId=${executionId}` : null
+  ].filter(Boolean).join("; ");
+  const refId = executionId || toolCallId || "";
+  if (policy === "keep_structured") {
+    return `STRUCTURED_TOOL_RESPONSE [${refs}]
+Preview: ${summary}
+Use get_tool_response with executionId "${refId}" to fetch the full payload when a specific field is needed.`;
+  }
+  if (policy === "summarize_archive") {
+    return `ARCHIVED_TOOL_RESPONSE [${refs}]
+Summary: ${summary}
+Use get_tool_response with executionId "${refId}" to fetch the full payload.`;
+  }
+  return `DROPPED_TOOL_RESPONSE [${refs}]
+Use get_tool_response with executionId "${refId}" only if you must recover the original payload.`;
+}
 function validateToolArgs(tool, args) {
   const schema = tool.schema;
   if (!schema || typeof schema.parse !== "function") {
@@ -2742,52 +2748,25 @@ function createToolsNode(initialTools, opts) {
           state.ctx.__structuredOutputParsed = output.data;
           state.ctx.__finalizedDueToStructuredOutput = true;
         }
-        const responsePolicy = resolveToolResponsePolicy(toolName, output, resolved);
+        const responsePolicy = applyToolResponseHardCap(toolName, output, executionId, resolved);
         const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-        const storedOutput = responsePolicy.retentionPolicy === "keep_full" ? output : responsePolicy.summary;
         toolHistory.push({
           executionId,
           toolName,
           args,
-          output: storedOutput,
+          output,
           rawOutput: output,
           timestamp,
           tool_call_id: tc.id,
-          summarized: responsePolicy.retentionPolicy !== "keep_full",
+          summarized: false,
           originalTokenCount: responsePolicy.tokenCount,
           classification: responsePolicy.classification,
-          retentionPolicy: responsePolicy.retentionPolicy,
-          summary: responsePolicy.summary,
-          archiveId: responsePolicy.retentionPolicy === "summarize_archive" || responsePolicy.retentionPolicy === "drop" ? executionId : void 0,
+          retentionPolicy: "keep_full",
+          summary: void 0,
+          archiveId: void 0,
           status: "success"
         });
-        if (resolved.context.archiveLargeToolResponses && (responsePolicy.retentionPolicy === "summarize_archive" || responsePolicy.retentionPolicy === "drop")) {
-          toolHistoryArchived.push({
-            executionId,
-            toolName,
-            args,
-            output,
-            rawOutput: output,
-            timestamp,
-            tool_call_id: tc.id,
-            summarized: true,
-            originalTokenCount: responsePolicy.tokenCount,
-            classification: responsePolicy.classification,
-            retentionPolicy: responsePolicy.retentionPolicy,
-            summary: responsePolicy.summary,
-            archiveId: executionId,
-            status: "success"
-          });
-        }
-        let toolMessageContent = responsePolicy.content;
-        if (responsePolicy.retentionPolicy === "summarize_archive") {
-          toolMessageContent = `ARCHIVED_TOOL_RESPONSE [executionId=${executionId}]: ${responsePolicy.summary}
-Use get_tool_response with executionId "${executionId}" to retrieve the full output.`;
-        } else if (responsePolicy.retentionPolicy === "drop") {
-          toolMessageContent = `DROPPED_TOOL_RESPONSE [executionId=${executionId}]: ${responsePolicy.summary}
-Use get_tool_response with executionId "${executionId}" to retrieve the full output.`;
-        }
-        appended.push({ role: "tool", content: toolMessageContent, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
+        appended.push({ role: "tool", content: responsePolicy.content, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
         onEvent?.({ type: "tool_call", phase: "success", name: toolName, id: tc.id, args, result: output, durationMs });
         onProgress?.({ stage: "tools", message: `Tool ${tc.name} completed`, detail: { durationMs } });
         if (needsApproval && approvalEntry) {
@@ -2831,8 +2810,9 @@ Use get_tool_response with executionId "${executionId}" to retrieve the full out
           messageList,
           debug: {
             classification: responsePolicy.classification,
-            retentionPolicy: responsePolicy.retentionPolicy,
-            originalTokenCount: responsePolicy.tokenCount
+            retentionPolicy: "keep_full",
+            originalTokenCount: responsePolicy.tokenCount,
+            truncated: responsePolicy.truncated
           }
         });
         toolCount += 1;
@@ -4193,24 +4173,8 @@ function extractCanonicalFacts(messages) {
   }
   return [...facts.values()];
 }
-function flattenToolMessageContent(message) {
-  if (typeof message.content === "string") {
-    return message.content;
-  }
-  if (Array.isArray(message.content)) {
-    return message.content.map((part) => typeof part === "string" ? part : part?.text ?? part?.content ?? String(part ?? "")).join(" ");
-  }
-  return "";
-}
 function isSummarizedToolPlaceholder(content) {
-  return typeof content === "string" && (content === "SUMMARIZED" || content.startsWith("SUMMARIZED_TOOL_RESPONSE"));
-}
-function summarizeToolMessagePreview(message) {
-  const preview = flattenToolMessageContent(message).trim();
-  if (!preview) {
-    return "No summary available.";
-  }
-  return preview.length > 240 ? `${preview.slice(0, 240)}...` : preview;
+  return typeof content === "string" && (content === "SUMMARIZED" || content.startsWith("SUMMARIZED_TOOL_RESPONSE") || content.startsWith("ARCHIVED_TOOL_RESPONSE") || content.startsWith("STRUCTURED_TOOL_RESPONSE") || content.startsWith("DROPPED_TOOL_RESPONSE"));
 }
 function findToolHistoryEntry(state, toolCallId, toolName) {
   const entries = [
@@ -4236,29 +4200,6 @@ function findToolHistoryEntry(state, toolCallId, toolName) {
   }
   return void 0;
 }
-function buildSummarizedToolMessage(message, state) {
-  const toolName = message.name || "unknown_tool";
-  const toolCallId = message.tool_call_id;
-  const historyEntry = findToolHistoryEntry(state, toolCallId, toolName);
-  const executionId = historyEntry?.executionId;
-  const summary = historyEntry?.summary || summarizeToolMessagePreview(message);
-  const references = [
-    `toolName=${toolName}`,
-    toolCallId ? `toolCallId=${toolCallId}` : null,
-    executionId ? `executionId=${executionId}` : null
-  ].filter(Boolean).join("; ");
-  let retrievalHint = "Use get_tool_response if exact details are still needed.";
-  if (executionId && toolCallId) {
-    retrievalHint = `Use get_tool_response with executionId "${executionId}" or tool call id "${toolCallId}" if exact details are still needed.`;
-  } else if (executionId || toolCallId) {
-    retrievalHint = `Use get_tool_response with executionId "${executionId || toolCallId}" if exact details are still needed.`;
-  }
-  return [
-    `SUMMARIZED_TOOL_RESPONSE [${references}]`,
-    `Summary: ${summary}`,
-    retrievalHint
-  ].join("\n");
-}
 function mergeStableFacts(summary, additionalFacts) {
   if (additionalFacts.length === 0) return summary;
   const merged = new Map(summary.stable_facts.map((fact) => [fact.key, fact]));
@@ -4316,18 +4257,13 @@ function createContextSummarizeNode(opts) {
     const messages = state.messages || [];
     const onEvent = state.ctx?.__onEvent;
     const traceSession = state.ctx?.__traceSession;
-    const toolResponsesConfigEarly = resolved.toolResponses;
     const compressableMessages = messages.filter(
       (m) => {
         if (m.role !== "tool") return false;
         if (isSummarizedToolPlaceholder(m.content)) return false;
         if (isSyntheticSummaryMessage(m)) return false;
-        const histEntry = findToolHistoryEntry(state, m.tool_call_id, m.name);
-        if (histEntry?.retentionPolicy === "keep_full") return false;
-        if (!histEntry?.retentionPolicy) {
-          const byTool = toolResponsesConfigEarly.toolResponseRetentionByTool?.[m.name || ""];
-          if ((byTool || toolResponsesConfigEarly.defaultPolicy) === "keep_full") return false;
-        }
+        const policy = resolveSummarizationRetention(m.name || "", resolved);
+        if (policy === "keep_full") return false;
         return true;
       }
     );
@@ -4507,7 +4443,8 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
         break;
       }
     }
-    const toolResponsesConfig = resolved.toolResponses;
+    const archivedExecutions = [...state.toolHistoryArchived || []];
+    const archivedIds = new Set(archivedExecutions.map((entry) => entry?.executionId).filter(Boolean));
     const newMessages = messages.map((m) => {
       if (m.role === "tool") {
         if (isSyntheticSummaryMessage(m)) {
@@ -4520,23 +4457,38 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
         if (isSummarizedToolPlaceholder(m.content)) return m;
         if (toolCallId && protectedToolCallIds.has(toolCallId)) return m;
         const toolName = m.name || "";
+        const policy = resolveSummarizationRetention(toolName, resolved);
+        if (policy === "keep_full") return m;
         const historyEntry = findToolHistoryEntry(state, toolCallId, toolName);
-        const entryRetention = historyEntry?.retentionPolicy;
-        if (entryRetention === "keep_full") return m;
-        if (!entryRetention) {
-          const byTool = toolResponsesConfig.toolResponseRetentionByTool?.[toolName];
-          const configPolicy = byTool || toolResponsesConfig.defaultPolicy;
-          if (configPolicy === "keep_full") return m;
+        const rawOutput = historyEntry?.rawOutput ?? historyEntry?.output ?? m.content;
+        const executionId = historyEntry?.executionId;
+        const prebuiltSummary = historyEntry?.summary || summarizeObject(rawOutput);
+        if ((policy === "summarize_archive" || policy === "drop") && historyEntry && executionId && !archivedIds.has(executionId)) {
+          archivedExecutions.push({
+            ...historyEntry,
+            summarized: true,
+            retentionPolicy: policy,
+            archiveId: executionId,
+            summary: prebuiltSummary
+          });
+          archivedIds.add(executionId);
         }
         return {
           ...m,
-          content: buildSummarizedToolMessage(m, state)
+          content: renderRetainedToolMessage({
+            policy,
+            rawOutput,
+            toolName,
+            toolCallId,
+            executionId,
+            prebuiltSummary
+          })
         };
       }
       return m;
     }).filter((m) => m !== null);
     const actuallyCompressed = newMessages.filter(
-      (m) => m.role === "tool" && typeof m.content === "string" && m.content.startsWith("SUMMARIZED_TOOL_RESPONSE") && !messages.some((orig) => orig.tool_call_id === m.tool_call_id && isSummarizedToolPlaceholder(orig.content))
+      (m) => m.role === "tool" && isSummarizedToolPlaceholder(m.content) && !messages.some((orig) => orig.tool_call_id === m.tool_call_id && isSummarizedToolPlaceholder(orig.content))
     );
     if (actuallyCompressed.length === 0) {
       return {};
@@ -4615,7 +4567,8 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
     return {
       messages: finalMessages,
       summaries,
-      summaryRecords
+      summaryRecords,
+      toolHistoryArchived: archivedExecutions
     };
   };
 }
@@ -4857,8 +4810,9 @@ function createContextTools(stateRef, opts) {
   }
   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. 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, 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.",
     schema: z.object({ executionId: z.string().describe("Tool execution id or original tool_call_id") }),
+    maxExecutionsPerRun: 8,
     func: async ({ executionId }) => {
       const matchesExecution = (t) => t?.executionId === executionId || t?.tool_call_id === executionId;
       let execution = stateRef.toolHistory?.find((t) => matchesExecution(t));