@cognipeer/agent-sdk 0.5.2 → 0.5.4

package/README.md

@@ -136,7 +136,16 @@ const agent = createSmartAgent({
   memory: { provider: "inMemory", scope: "session", writePolicy: "auto_important" },
   summarization: { summaryTriggerTokens: 8000, summaryMode: "incremental" },
   context: { policy: "hybrid", lastTurnsToKeep: 8 },
-  toolResponses: { maxToolResponseChars: 4000, maxToolResponseTokens: 1200 },
+  toolResponses: {
+    smallResponseChars: 1200,
+    smallResponsePolicy: "keep_full",
+    defaultPolicy: "keep_structured",
+    largeResponsePolicy: "summarize_archive",
+    fallbackPolicy: "keep_full",
+    keepRecentFullCount: 2,
+    maxToolResponseChars: 4000,
+    maxToolResponseTokens: 1200,
+  },
   limits: { maxToolCalls: 5, maxContextTokens: 12000 },
   tracing: { enabled: true },
 });
@@ -149,6 +158,16 @@ const result = await agent.invoke({
 console.log(result.content);
 ```
 
+Tool-response retention is size-aware and composable:
+
+- `smallResponseChars` + `smallResponsePolicy` define how very small payloads are kept.
+- `defaultPolicy` handles normal informative outputs.
+- `largeResponsePolicy` handles verbose outputs that cross the max char/token thresholds.
+- `fallbackPolicy` applies to critical tools and now defaults to `keep_full` so safety-critical payloads are not collapsed accidentally.
+- `keepRecentFullCount` pins the last N successful tool responses at full content during context assembly and excludes them from summarization passes.
+
+Resolution order is: per-tool override, then critical fallback, then large/small classification, then the default policy. Redundant payloads like `ok`, `true`, and `null` are dropped automatically.
+
 The smart wrapper now supports runtime presets (`fast`, `balanced`, `deep`, `research`), custom profiles layered on top of a base preset, structured summarization, hybrid context compaction, configurable tool-response retention, in-memory fact storage, delegation limits, and an eval harness via `runSmartAgentEvalHarness(...)`.
 
 You can also define a custom profile by extending a built-in preset and overriding only the knobs you need:
@@ -201,6 +220,7 @@ console.log(res.content);
 - **Native provider layer** – call OpenAI, Anthropic, Azure, Bedrock, Vertex, and any OpenAI-compatible API directly. No LangChain required. Unified `ChatCompletionRequest` / `ChatCompletionResponse` schema with per-provider wire format conversion.
 - **Full token tracking** – every response surfaces `inputTokens`, `outputTokens`, `cachedInputTokens`, `cachedWriteTokens`, and `reasoningTokens` for all six providers.
 - **Summarization pipeline** – automatic chunking keeps tool call history within `contextTokenLimit` / `summaryTokenLimit`, archiving originals so `get_tool_response` can fetch them later.
+- **Retention controls** – tool outputs can be kept full, reduced to structured previews, archived, or dropped based on size tiers, critical-tool fallback, per-tool overrides, and recent-response pinning.
 - **Planning discipline** – when planning is enabled the system prompt distinguishes full plan writes from incremental plan updates and emits `plan` events as todos change.
 - **Structured output** – supply `outputSchema` and the framework adds a hidden `response` finalize tool; parsed JSON is returned as `result.output`.
 - **Multi-agent orchestration** – reuse agents via `agent.asTool({ toolName })` or perform handoffs that swap runtimes mid-execution.

package/dist/index.cjs

@@ -2138,13 +2138,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) {
@@ -2427,11 +2430,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";
 }
@@ -2441,12 +2448,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") {
@@ -2792,10 +2801,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 });
@@ -3981,6 +3990,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");
@@ -4081,7 +4124,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];
@@ -4101,7 +4144,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
@@ -4257,11 +4300,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}]`,
@@ -4327,11 +4370,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) {
@@ -4518,6 +4563,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)) {
@@ -4529,6 +4575,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;
@@ -4867,8 +4914,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: zod.z.object({ executionId: zod.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));
@@ -7124,23 +7172,79 @@ function convertContent(content) {
 function isZodSchema(obj) {
   return obj != null && typeof obj === "object" && typeof obj.safeParse === "function" && "_def" in obj;
 }
+function hasStrictUnsafeShape(node, inProperty = false) {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) {
+    return node.some((item) => hasStrictUnsafeShape(item, inProperty));
+  }
+  if (typeof node.$ref === "string") {
+    return true;
+  }
+  const hasType = typeof node.type === "string" || Array.isArray(node.type) && node.type.length > 0;
+  const hasProperties = !!node.properties && typeof node.properties === "object" && !Array.isArray(node.properties);
+  const hasItems = node.items !== void 0;
+  const hasComposite = ["anyOf", "oneOf", "allOf"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
+  if (inProperty && !hasType && !hasProperties && !hasItems) {
+    return true;
+  }
+  if (inProperty && hasComposite && !hasType) {
+    return true;
+  }
+  if (hasProperties) {
+    for (const value of Object.values(node.properties)) {
+      if (hasStrictUnsafeShape(value, true)) {
+        return true;
+      }
+    }
+  }
+  if (node.items && hasStrictUnsafeShape(node.items, false)) {
+    return true;
+  }
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    if (Array.isArray(node[key]) && hasStrictUnsafeShape(node[key], false)) {
+      return true;
+    }
+  }
+  for (const key of ["definitions", "$defs"]) {
+    const defs = node[key];
+    if (defs && typeof defs === "object") {
+      for (const value of Object.values(defs)) {
+        if (hasStrictUnsafeShape(value, false)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function canUseStrictToolSchema(schema) {
+  if (!schema || typeof schema !== "object") {
+    return true;
+  }
+  if (isZodSchema(schema)) {
+    return true;
+  }
+  return !hasStrictUnsafeShape(schema);
+}
 function convertToJsonSchema(schema, strict = false) {
   if (!schema || typeof schema !== "object") {
     return { type: "object", properties: {}, required: [], additionalProperties: false };
   }
   if (isZodSchema(schema)) {
-    const converted = zodToJsonSchema.zodToJsonSchema(schema, {
+    const converted2 = zodToJsonSchema.zodToJsonSchema(schema, {
       $refStrategy: "none",
       ...strict ? { openaiStrictMode: true } : {}
     });
-    delete converted["$schema"];
-    if (!converted.type) converted.type = "object";
-    return converted;
+    delete converted2["$schema"];
+    if (!converted2.type) converted2.type = "object";
+    return converted2;
   }
-  if (!schema.type && schema.properties) {
-    return { type: "object", ...schema };
+  const converted = { ...schema };
+  delete converted["$schema"];
+  if (!converted.type && converted.properties) {
+    return { type: "object", ...converted };
   }
-  return schema;
+  return converted;
 }
 function normalizeStrictSchema(schema) {
   if (!schema || typeof schema !== "object") return schema;
@@ -7189,20 +7293,25 @@ function toToolDefinition(tool, strict) {
   let name;
   let description;
   let parameters;
+  let rawSchema;
+  let useStrict = strict ?? false;
   if (tool.type === "function" && tool.function) {
     name = tool.function.name;
     description = tool.function.description ?? "";
-    parameters = tool.function.parameters ?? { type: "object", properties: {}, additionalProperties: false };
+    rawSchema = tool.function.parameters ?? { type: "object", properties: {}, additionalProperties: false };
   } else {
     name = tool.name ?? "unknown";
     description = tool.description ?? "";
-    const rawSchema = tool.schema ?? tool.parameters;
-    parameters = convertToJsonSchema(rawSchema, strict);
+    rawSchema = tool.schema ?? tool.parameters;
+  }
+  if (useStrict && !canUseStrictToolSchema(rawSchema)) {
+    useStrict = false;
   }
-  if (strict) {
+  parameters = convertToJsonSchema(rawSchema, useStrict);
+  if (useStrict) {
     parameters = normalizeStrictSchema(parameters);
   }
-  return { name, description, parameters, ...strict ? { strict: true } : {} };
+  return { name, description, parameters, ...useStrict ? { strict: true } : {} };
 }
 function toBaseChatMessage(response) {
   const msg = {