@cognipeer/agent-sdk 0.5.3 → 0.5.4

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" | "small" | "informative" | "verbose" | "redundant";
 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,32 @@ type SmartAgentMemoryConfig = {
     readPolicy?: MemoryReadPolicy;
 };
 type SmartAgentToolResponseConfig = {
+    /** Upper threshold for marking a response as "verbose" (large). */
     maxToolResponseChars?: number;
+    /** Upper threshold (in approx. tokens) for marking a response as "verbose". */
     maxToolResponseTokens?: number;
+    /** Lower threshold for marking a response as "small". 0 disables the small tier. */
+    smallResponseChars?: number;
+    /** Policy applied to responses classified as "small". Defaults to keep_full. */
+    smallResponsePolicy?: ToolResponseRetentionPolicy;
+    /** Policy applied to mid-sized "informative" responses. */
     defaultPolicy?: ToolResponseRetentionPolicy;
+    /** Policy applied when a response exceeds the verbose thresholds. */
     largeResponsePolicy?: ToolResponseRetentionPolicy;
+    /** Per-tool override map. Wins over size-based classification. */
     toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
+    /** Tool names always treated as critical (resolved via fallbackPolicy). */
     criticalTools?: string[];
     schemaValidation?: "strict" | "warn";
     retryOnSchemaError?: boolean;
+    /** Policy applied to critical tools. Should default to keep_full so critical payloads are never reduced. */
     fallbackPolicy?: ToolResponseRetentionPolicy;
+    /**
+     * Number of most-recent successful tool responses to render at full content
+     * regardless of their classification. Older responses still follow their
+     * resolved policy. 0 disables the recency override. Defaults to 2.
+     */
+    keepRecentFullCount?: number;
 };
 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" | "small" | "informative" | "verbose" | "redundant";
 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,32 @@ type SmartAgentMemoryConfig = {
     readPolicy?: MemoryReadPolicy;
 };
 type SmartAgentToolResponseConfig = {
+    /** Upper threshold for marking a response as "verbose" (large). */
     maxToolResponseChars?: number;
+    /** Upper threshold (in approx. tokens) for marking a response as "verbose". */
     maxToolResponseTokens?: number;
+    /** Lower threshold for marking a response as "small". 0 disables the small tier. */
+    smallResponseChars?: number;
+    /** Policy applied to responses classified as "small". Defaults to keep_full. */
+    smallResponsePolicy?: ToolResponseRetentionPolicy;
+    /** Policy applied to mid-sized "informative" responses. */
     defaultPolicy?: ToolResponseRetentionPolicy;
+    /** Policy applied when a response exceeds the verbose thresholds. */
     largeResponsePolicy?: ToolResponseRetentionPolicy;
+    /** Per-tool override map. Wins over size-based classification. */
     toolResponseRetentionByTool?: Record<string, ToolResponseRetentionPolicy>;
+    /** Tool names always treated as critical (resolved via fallbackPolicy). */
     criticalTools?: string[];
     schemaValidation?: "strict" | "warn";
     retryOnSchemaError?: boolean;
+    /** Policy applied to critical tools. Should default to keep_full so critical payloads are never reduced. */
     fallbackPolicy?: ToolResponseRetentionPolicy;
+    /**
+     * Number of most-recent successful tool responses to render at full content
+     * regardless of their classification. Older responses still follow their
+     * resolved policy. 0 disables the recency override. Defaults to 2.
+     */
+    keepRecentFullCount?: number;
 };
 type SmartAgentCustomProfileConfig = {
     extends?: BuiltInRuntimeProfile;

package/dist/index.mjs

@@ -2128,13 +2128,16 @@ var BASE_DEFAULTS = {
   toolResponses: {
     maxToolResponseChars: 3600,
     maxToolResponseTokens: 1200,
+    smallResponseChars: 0,
+    smallResponsePolicy: "keep_full",
     defaultPolicy: "keep_structured",
     largeResponsePolicy: "summarize_archive",
     toolResponseRetentionByTool: {},
     criticalTools: [...DEFAULT_CRITICAL_TOOLS],
     schemaValidation: "strict",
     retryOnSchemaError: true,
-    fallbackPolicy: "keep_structured"
+    fallbackPolicy: "keep_full",
+    keepRecentFullCount: 0
   }
 };
 function buildProfile(overrides) {
@@ -2417,11 +2420,15 @@ function classifyToolResponse(toolName, output, config) {
   const tokenCount = countApproxTokens(serialized);
   const criticalTools = new Set(config.toolResponses.criticalTools);
   if (criticalTools.has(toolName)) return "critical";
+  if (serialized === "ok" || serialized === "true" || serialized === "null") {
+    return "redundant";
+  }
   if (tokenCount >= config.toolResponses.maxToolResponseTokens || serialized.length >= config.toolResponses.maxToolResponseChars) {
     return "verbose";
   }
-  if (serialized === "ok" || serialized === "true" || serialized === "null") {
-    return "redundant";
+  const smallChars = config.toolResponses.smallResponseChars;
+  if (smallChars > 0 && serialized.length <= smallChars) {
+    return "small";
   }
   return "informative";
 }
@@ -2431,12 +2438,14 @@ function resolveToolResponsePolicy(toolName, output, config) {
   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;
+  if (byTool) ; else if (classification === "critical") {
+    retentionPolicy = config.toolResponses.fallbackPolicy;
   } else if (classification === "verbose") {
-    retentionPolicy = byTool || config.toolResponses.largeResponsePolicy;
+    retentionPolicy = config.toolResponses.largeResponsePolicy;
+  } else if (classification === "small") {
+    retentionPolicy = config.toolResponses.smallResponsePolicy;
   } else if (classification === "redundant") {
-    retentionPolicy = byTool || "drop";
+    retentionPolicy = "drop";
   }
   const summary = summarizeObject(output);
   if (retentionPolicy === "keep_full") {
@@ -2782,10 +2791,10 @@ function createToolsNode(initialTools, opts) {
         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.`;
+Only use get_tool_response with executionId "${executionId}" if this summary is missing a specific field, id, snippet, or exact payload you still need.`;
         } 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.`;
+Only use get_tool_response with executionId "${executionId}" if this summary is missing a specific field, id, snippet, or exact payload you still need.`;
         }
         appended.push({ role: "tool", content: toolMessageContent, 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 });
@@ -3971,6 +3980,40 @@ function createAgentNode(opts) {
 }
 
 // src/smart/contextPolicy.ts
+function collectRecentFullToolCallIds(state, keepRecentFullCount) {
+  if (!keepRecentFullCount || keepRecentFullCount <= 0) return /* @__PURE__ */ new Set();
+  const history = state.toolHistory || [];
+  const ids = [];
+  for (let index = history.length - 1; index >= 0 && ids.length < keepRecentFullCount; index -= 1) {
+    const entry = history[index];
+    if (!entry || !entry.tool_call_id) continue;
+    if (entry.status && entry.status !== "success") continue;
+    ids.push(entry.tool_call_id);
+  }
+  return new Set(ids);
+}
+function applyRecentFullOverride(messages, state, config) {
+  const keepN = config.toolResponses.keepRecentFullCount;
+  if (!keepN || keepN <= 0) return messages;
+  const recentIds = collectRecentFullToolCallIds(state, keepN);
+  if (recentIds.size === 0) return messages;
+  const history = state.toolHistory || [];
+  const byCallId = /* @__PURE__ */ new Map();
+  for (const entry of history) {
+    if (entry?.tool_call_id) byCallId.set(entry.tool_call_id, entry);
+  }
+  return messages.map((message) => {
+    if (message.role !== "tool" || !message.tool_call_id) return message;
+    if (!recentIds.has(message.tool_call_id)) return message;
+    const entry = byCallId.get(message.tool_call_id);
+    if (!entry) return message;
+    const raw = entry.rawOutput ?? entry.output;
+    if (raw === void 0) return message;
+    const fullContent = typeof raw === "string" ? raw : safeStringify(raw);
+    if (!fullContent || fullContent === message.content) return message;
+    return { ...message, content: fullContent };
+  });
+}
 function collectRecentTurns(messages, lastTurnsToKeep) {
   if (lastTurnsToKeep <= 0) return [];
   const systemPrefix = messages.filter((message, index) => index === 0 && message.role === "system");
@@ -4071,7 +4114,7 @@ function clampToBudget(messages, maxContextTokens) {
 function buildModelMessages(state, config) {
   const rawMessages = state.messages || [];
   if (config.context.policy === "raw") {
-    return clampToBudget(rawMessages, config.limits.maxContextTokens);
+    return clampToBudget(applyRecentFullOverride(rawMessages, state, config), config.limits.maxContextTokens);
   }
   const recentMessages = collectRecentTurns(rawMessages, config.context.lastTurnsToKeep);
   const latestSummary = state.summaryRecords?.[state.summaryRecords.length - 1];
@@ -4091,7 +4134,7 @@ function buildModelMessages(state, config) {
     ...syntheticContextMessages,
     ...config.context.policy === "summary_only" ? body.filter((message) => message.role === "user" || message.role === "assistant").slice(-2) : body
   ];
-  return clampToBudget(assembled, config.limits.maxContextTokens);
+  return clampToBudget(applyRecentFullOverride(assembled, state, config), config.limits.maxContextTokens);
 }
 
 // src/nodes/contextSummarize.ts
@@ -4247,11 +4290,11 @@ function buildSummarizedToolMessage(message, state) {
     toolCallId ? `toolCallId=${toolCallId}` : null,
     executionId ? `executionId=${executionId}` : null
   ].filter(Boolean).join("; ");
-  let retrievalHint = "Use get_tool_response if exact details are still needed.";
+  let retrievalHint = "Only use get_tool_response if this summary is missing a specific field, id, snippet, or exact payload you still need.";
   if (executionId && toolCallId) {
-    retrievalHint = `Use get_tool_response with executionId "${executionId}" or tool call id "${toolCallId}" if exact details are still needed.`;
+    retrievalHint = `Only use get_tool_response with executionId "${executionId}" or tool call id "${toolCallId}" if this summary is missing a specific field, id, snippet, or exact payload you still need.`;
   } else if (executionId || toolCallId) {
-    retrievalHint = `Use get_tool_response with executionId "${executionId || toolCallId}" if exact details are still needed.`;
+    retrievalHint = `Only use get_tool_response with executionId "${executionId || toolCallId}" if this summary is missing a specific field, id, snippet, or exact payload you still need.`;
   }
   return [
     `SUMMARIZED_TOOL_RESPONSE [${references}]`,
@@ -4317,11 +4360,13 @@ function createContextSummarizeNode(opts) {
     const onEvent = state.ctx?.__onEvent;
     const traceSession = state.ctx?.__traceSession;
     const toolResponsesConfigEarly = resolved.toolResponses;
+    const recentFullToolCallIdsEarly = collectRecentFullToolCallIds(state, toolResponsesConfigEarly.keepRecentFullCount);
     const compressableMessages = messages.filter(
       (m) => {
         if (m.role !== "tool") return false;
         if (isSummarizedToolPlaceholder(m.content)) return false;
         if (isSyntheticSummaryMessage(m)) return false;
+        if (m.tool_call_id && recentFullToolCallIdsEarly.has(m.tool_call_id)) return false;
         const histEntry = findToolHistoryEntry(state, m.tool_call_id, m.name);
         if (histEntry?.retentionPolicy === "keep_full") return false;
         if (!histEntry?.retentionPolicy) {
@@ -4508,6 +4553,7 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
       }
     }
     const toolResponsesConfig = resolved.toolResponses;
+    const recentFullToolCallIds = collectRecentFullToolCallIds(state, toolResponsesConfig.keepRecentFullCount);
     const newMessages = messages.map((m) => {
       if (m.role === "tool") {
         if (isSyntheticSummaryMessage(m)) {
@@ -4519,6 +4565,7 @@ ${canonicalFacts.length > 0 ? canonicalFacts.map((fact) => `- ${fact.key}: ${fac
         }
         if (isSummarizedToolPlaceholder(m.content)) return m;
         if (toolCallId && protectedToolCallIds.has(toolCallId)) return m;
+        if (toolCallId && recentFullToolCallIds.has(toolCallId)) return m;
         const toolName = m.name || "";
         const historyEntry = findToolHistoryEntry(state, toolCallId, toolName);
         const entryRetention = historyEntry?.retentionPolicy;
@@ -4857,8 +4904,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));