@cognipeer/agent-sdk 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @cognipeer/agent-sdk
 
-[![npm](https://img.shields.io/npm/v/@cognipeer/agent-sdk?color=success)](https://npmjs.com/package/@cognipeer/agent-sdk) [Docs Website](https://cognipeer.github.io/agent-sdk/)
+[![npm](https://img.shields.io/npm/v/@cognipeer/agent-sdk?color=success)](https://npmjs.com/package/@cognipeer/agent-sdk) [Docs Website](https://cognipeer.github.io/agent-sdk/) 
 
 Lightweight, message-first agent runtime that keeps tool calls transparent, automatically summarizes long histories, and ships with planning, multi-agent handoffs, and structured tracing.
 
@@ -158,12 +158,27 @@ Examples live under `examples/` with per-folder READMEs. Build the package first
 | `mcp-tavily/` | MCP remote tool discovery. |
 | `vision/` | Text + image input using LangChain’s OpenAI bindings. |
 
-Run directly with `tsx`, for example:
+To run examples:
 
-```sh
-# from repo root
-npm run build
-OPENAI_API_KEY=... npx tsx examples/tools/tools.ts
+```bash
+# Install root dependencies
+npm install
+
+# Install example dependencies
+cd examples
+npm install
+
+# Run an example from the examples directory
+npm run example:basic
+npm run example:tools
+npm run example:multi-agent
+```
+
+Or run directly with tsx:
+
+```bash
+# From examples directory
+OPENAI_API_KEY=... npx tsx basic/basic.ts
 ```
 
 ## Architecture snapshot

package/dist/index.cjs

@@ -1105,9 +1105,58 @@ function createAgentCoreNode(opts) {
     const shouldLogPrompt = !!traceSession && traceSession.resolvedConfig.logData;
     const promptPayload = shouldLogPrompt ? sanitizeTracePayload(state.messages) : void 0;
     const promptBytes = promptPayload !== void 0 ? estimatePayloadBytes(promptPayload) : void 0;
+    const extractToolUses = (m) => {
+      const tcs = m?.tool_calls || m?.additional_kwargs?.tool_calls;
+      if (!Array.isArray(tcs)) return [];
+      return tcs.map((tc) => ({ id: tc?.id, name: tc?.function?.name || tc?.name })).filter((x) => typeof x.id === "string" && x.id.length > 0);
+    };
+    const normalizeBedrockToolPairing = (input) => {
+      const msgs = Array.isArray(input) ? [...input] : [];
+      for (let i = 0; i < msgs.length; i++) {
+        const m = msgs[i];
+        if (m?.role !== "assistant") continue;
+        const toolUses = extractToolUses(m);
+        if (toolUses.length === 0) continue;
+        const next = msgs[i + 1];
+        const firstId = toolUses[0]?.id;
+        const nextIsToolForFirst = !!(next && next.role === "tool" && next.tool_call_id === firstId);
+        if (nextIsToolForFirst) continue;
+        const placeholders = toolUses.map((tu) => ({
+          role: "tool",
+          name: tu.name || "unknown_tool",
+          tool_call_id: tu.id,
+          content: "SUMMARIZED/DEFERRED: tool result missing in transcript; inserted placeholder for Bedrock tool_result adjacency."
+        }));
+        msgs.splice(i + 1, 0, ...placeholders);
+        i += placeholders.length;
+      }
+      return msgs;
+    };
+    const debugToolPairing = (messagesToSend) => {
+      try {
+        const msgs = Array.isArray(messagesToSend) ? messagesToSend : [];
+        const toolUseIds = [];
+        const missingResults = [];
+        for (let i = 0; i < msgs.length; i++) {
+          const m = msgs[i];
+          if (m?.role === "assistant") {
+            for (const tu of extractToolUses(m)) {
+              toolUseIds.push(tu.id);
+              const next = msgs[i + 1];
+              if (!(next && next.role === "tool" && (next.tool_call_id === tu.id || next.tool_call_id === m?.tool_call_id))) {
+                missingResults.push({ id: tu.id, atIndex: i, tool: tu.name });
+              }
+            }
+          }
+        }
+      } catch (e) {
+      }
+    };
     let response;
     try {
-      response = await modelWithTools.invoke([...state.messages]);
+      const normalizedMessages = normalizeBedrockToolPairing([...state.messages]);
+      debugToolPairing(normalizedMessages);
+      response = await modelWithTools.invoke(normalizedMessages);
     } catch (err) {
       const durationMs2 = Date.now() - start;
       recordTraceEvent(traceSession, {
@@ -1694,6 +1743,12 @@ function resolveToolApprovalState(state, resolution) {
   };
 }
 
+// src/utils/utilTokens.ts
+function countApproxTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
 // src/agent.ts
 function createAgent(opts) {
   const resolver = createResolverNode();
@@ -1758,8 +1813,8 @@ function createAgent(opts) {
       delete nextCtx.__resumeStage;
       state = { ...state, ctx: Object.keys(nextCtx).length > 0 ? nextCtx : void 0 };
     }
-    const maxToolCalls = opts.limits?.maxToolCalls ?? 10;
-    const iterationLimit = Math.max(maxToolCalls * 3 + 10, 40);
+    const maxToolCalls = opts.limits?.maxToolCalls === void 0 ? 50 : opts.limits?.maxToolCalls;
+    const iterationLimit = maxToolCalls === Infinity ? 100 : Math.max(maxToolCalls * 3 + 10, 40);
     let iterations = 0;
     const onStateChange = config?.onStateChange;
     const checkpointReason = config?.checkpointReason;
@@ -1826,6 +1881,19 @@ function createAgent(opts) {
             }
           }
         }
+        let maxTok = 5e4;
+        if (opts.summarization && typeof opts.summarization === "object" && opts.summarization.maxTokens) {
+          maxTok = opts.summarization.maxTokens;
+        }
+        if (maxTok) {
+          const allText = (state.messages || []).map((m) => typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.map((c) => typeof c === "string" ? c : c?.text ?? c?.content ?? "").join("") : "").join("\n");
+          const tokenCount = countApproxTokens(allText);
+          if (tokenCount > maxTok) {
+            const ctx = { ...state.ctx || {}, __needsSummarization: true };
+            state = { ...state, ctx };
+            break;
+          }
+        }
         state = { ...state, ...await agentCore(state) };
         if (checkpointIfRequested("after_agent")) break;
         const postGuardrails = getGuardrailConfig(state);
@@ -1899,6 +1967,35 @@ function createAgent(opts) {
       if (checkpointIfRequested("after_tools")) break;
       if (state.ctx?.__finalizedDueToStructuredOutput) break;
     }
+    if (opts.outputSchema && !state.ctx?.__finalizedDueToStructuredOutput) {
+      const last = state.messages[state.messages.length - 1];
+      const lastHasToolCalls = Array.isArray(last?.tool_calls) && last.tool_calls.length > 0;
+      if (!lastHasToolCalls) {
+        const forceMsg = {
+          role: "system",
+          content: [
+            "A structured output schema is active.",
+            "You MUST now call tool `response` with the final JSON object that matches the schema.",
+            "Do not write the JSON in the assistant message.",
+            "Call `response` exactly once, then stop."
+          ].join("\n")
+        };
+        const alreadyForced = Boolean(state.ctx?.__structuredOutputForceFinalize);
+        if (!alreadyForced) {
+          const ctx = { ...state.ctx || {}, __structuredOutputForceFinalize: true };
+          state = { ...state, messages: [...state.messages, forceMsg], ctx };
+          try {
+            state = { ...state, ...await agentCore(state) };
+            const lastAfter = state.messages[state.messages.length - 1];
+            const toolCallsAfter = Array.isArray(lastAfter?.tool_calls) ? lastAfter.tool_calls : [];
+            if (toolCallsAfter.length > 0) {
+              state = { ...state, ...await toolsNode(state) };
+            }
+          } catch {
+          }
+        }
+      }
+    }
     if (!pausedStage && typeof onStateChange === "function" && onStateChange(state)) {
       checkpointIfRequested("after_loop");
     }
@@ -2133,234 +2230,96 @@ function createAgentNode(opts) {
   };
 }
 
-// src/utils/utilTokens.ts
-function countApproxTokens(text) {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}
-
 // src/nodes/contextSummarize.ts
 var systemMessage = (content) => ({ role: "system", content });
 var humanMessage = (content) => ({ role: "user", content });
-var toolMessage = (name, content, tool_call_id) => ({ role: "tool", name, content, tool_call_id });
+function getSummarizationConfig(opts) {
+  if (typeof opts.summarization === "object") {
+    return {
+      enabled: opts.summarization.enable !== false,
+      maxTokens: opts.summarization.maxTokens
+    };
+  }
+  return {
+    enabled: opts.summarization !== false,
+    maxTokens: 5e4
+  };
+}
 function createContextSummarizeNode(opts) {
   return async (state) => {
-    const messages = state.messages || [];
-    const summaryTokenLimit = opts.limits?.summaryTokenLimit ?? 1e5;
+    const config = getSummarizationConfig(opts);
+    if (!config.enabled) return {};
     const model = opts.model;
-    const archived = state.toolHistoryArchived ? [...state.toolHistoryArchived] : [];
-    const live = state.toolHistory ? [...state.toolHistory] : [];
-    const byCallId = /* @__PURE__ */ new Map();
-    for (const item of archived) {
-      if (item.tool_call_id) byCallId.set(item.tool_call_id, item);
-    }
-    for (const item of live) {
-      if (item.tool_call_id) byCallId.set(item.tool_call_id, item);
-    }
-    for (const item of live) {
-      if (!item.executionId) item.executionId = nanoid.nanoid();
-    }
-    const getText = (m) => {
-      if (!m) return "";
-      const c = m.content;
-      if (typeof c === "string") return c;
-      if (Array.isArray(c)) return c.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("");
-      return String(c ?? "");
-    };
-    const sysText = "You are a concise summarization assistant for a tool-using agent. Summarize prior tool executions into a compact brief that preserves key facts, decisions, and outputs. Reference executionId values where helpful. Avoid repeating raw data; prefer synthesis.";
-    const sys = systemMessage(sysText);
-    let summaryText = "";
-    try {
-      const limit = Math.max(1e3, Number(summaryTokenLimit) || 1e5);
-      const safetyBuffer = Math.floor(Math.min(4e3, limit * 0.05));
-      const perCallBudget = Math.max(500, limit - safetyBuffer);
-      const safeToolPair = opts?.safeToolPair !== false;
-      const chunks = [];
-      let current = [];
-      let currentTokens = countApproxTokens(sysText);
-      let pendingToolCalls = /* @__PURE__ */ new Set();
-      const extractToolCallIds = (msg) => {
-        const tc = msg?.additional_kwargs?.tool_calls;
-        if (!Array.isArray(tc) || tc.length === 0) return [];
-        return tc.map((c) => c?.id).filter((id) => typeof id === "string");
-      };
-      for (let i = 0; i < messages.length; i++) {
-        const m = messages[i];
-        const text = getText(m);
-        const tks = countApproxTokens(text);
-        const isAIWithToolCalls = safeToolPair && m?.role === "assistant" && extractToolCallIds(m).length > 0;
-        const isToolMsg = safeToolPair && m?.role === "tool";
-        const toolCallId = isToolMsg ? m.tool_call_id : void 0;
-        const wouldExceed = currentTokens + tks > perCallBudget && current.length > 0;
-        if (wouldExceed) {
-          let forceAddToCurrent = false;
-          if (safeToolPair) {
-            if (isToolMsg && toolCallId && pendingToolCalls.has(toolCallId)) {
-              forceAddToCurrent = true;
-            } else if (isAIWithToolCalls) {
-            } else if (pendingToolCalls.size > 0) {
-            }
-          }
-          if (!forceAddToCurrent) {
-            if (current.length > 0) {
-              chunks.push(current);
-            }
-            current = [];
-            currentTokens = countApproxTokens(sysText);
-            pendingToolCalls = /* @__PURE__ */ new Set();
-          }
-        }
-        current.push(m);
-        currentTokens += tks;
-        if (isAIWithToolCalls) {
-          for (const id of extractToolCallIds(m)) pendingToolCalls.add(id);
-        }
-        if (isToolMsg && toolCallId && pendingToolCalls.has(toolCallId)) {
-          pendingToolCalls.delete(toolCallId);
-        }
-        if (currentTokens >= perCallBudget && pendingToolCalls.size === 0) {
-          chunks.push(current);
-          current = [];
-          currentTokens = countApproxTokens(sysText);
-          pendingToolCalls = /* @__PURE__ */ new Set();
-        }
-      }
-      if (current.length > 0) {
-        chunks.push(current);
-      }
-      const partials = [];
-      for (const chunk of chunks) {
-        let resp = null;
-        try {
-          resp = await (model?.invoke ? model.invoke([sys, ...chunk]) : null);
-          const c = resp?.content;
-          const text = typeof c === "string" ? c : Array.isArray(c) ? c.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("") : "";
-          partials.push((text || "").trim());
-        } catch (e) {
-          console.error("Summarization chunk failed:", e);
-          partials.push("[summary unavailable for one chunk]");
-        }
+    const messages = state.messages || [];
+    const conversationText = messages.map((m) => {
+      let content = "";
+      if (typeof m.content === "string") content = m.content;
+      else if (Array.isArray(m.content)) {
+        content = m.content.map((c) => c.text || JSON.stringify(c)).join(" ");
       }
-      const mergeSysText = "You merge partial summaries into a single cohesive, non-redundant summary that preserves key facts and decisions. Be concise.";
-      const mergeSys = systemMessage(mergeSysText);
-      const mergeIteratively = async (texts) => {
-        if (texts.length === 0) return "";
-        if (texts.length === 1) return texts[0];
-        const groups = [];
-        let group = [];
-        let toks = countApproxTokens(mergeSysText);
-        for (const t of texts) {
-          const tt = `- ${t}`;
-          const tk = countApproxTokens(tt);
-          if (toks + tk > perCallBudget && group.length > 0) {
-            groups.push(group);
-            group = [];
-            toks = countApproxTokens(mergeSysText);
-          }
-          group.push(tt);
-          toks += tk;
-        }
-        if (group.length > 0) groups.push(group);
-        const next = [];
-        for (const g of groups) {
-          const mergePrompt = humanMessage(`Merge the following partial summaries into a single concise brief. Avoid duplication, keep key facts and decisions.
+      let prefix = `${m.role.toUpperCase()}`;
+      if (m.name) prefix += ` (${m.name})`;
+      return `${prefix}: ${content}`;
+    }).join("\n\n");
+    const summaryPrompt = [
+      systemMessage("You are a helpful assistant that summarizes conversation history efficiently."),
+      humanMessage(
+        `Please summarize the following conversation history. 
+Focus on:
+- User goals and intent.
+- Key decisions made and actions taken.
+- Important tool outputs and data retrieved.
+- Current state of the task.
 
-${g.join("\n")}
+Conversation:
+${conversationText}
 
-Merged summary:`);
-          try {
-            const r = await (model?.invoke ? model.invoke([mergeSys, mergePrompt]) : null);
-            const cc = r?.content;
-            const txt = typeof cc === "string" ? cc : Array.isArray(cc) ? cc.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("") : "";
-            next.push((txt || "").trim());
-          } catch (e) {
-            console.error("Merge summarization failed:", e);
-            next.push(g.join(" "));
-          }
-        }
-        return mergeIteratively(next);
-      };
-      summaryText = await mergeIteratively(partials);
-      if (!summaryText) summaryText = "Context summarized.";
-    } catch (e) {
-      console.error("Error during context summarization:", e);
-      summaryText = "Context summarized.";
+Summary:`
+      )
+    ];
+    let summaryText = "Summary unavailable.";
+    try {
+      const response = await model.invoke(summaryPrompt);
+      summaryText = typeof response.content === "string" ? response.content : Array.isArray(response.content) ? response.content.map((c) => c.text || "").join("") : JSON.stringify(response.content);
+    } catch (err) {
+      console.error("[ContextSummarize] Failed to generate summary:", err);
+      return {};
     }
-    const rewritten = [];
-    const alreadySummarized = (content) => {
-      const text = typeof content === "string" ? content : Array.isArray(content) ? content.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("") : String(content ?? "");
-      return /\bSUMMARIZED\b/.test(text);
-    };
-    for (const m of messages) {
-      if (m.getType() === "tool") {
-        const toolMessageObj = m;
-        if (alreadySummarized(toolMessageObj.content) || toolMessageObj.name === "context_summarize" || toolMessageObj.name === "manage_todo_list") {
-          rewritten.push(m);
-          continue;
-        }
-        const callId = toolMessageObj.tool_call_id;
-        const safeId = callId || `summarized_${nanoid.nanoid(6)}`;
-        let hist = callId ? byCallId.get(callId) : void 0;
-        if (!hist) {
-          hist = {
-            executionId: nanoid.nanoid(),
-            toolName: toolMessageObj.name || "unknown_tool",
-            args: null,
-            output: typeof toolMessageObj.content === "string" ? toolMessageObj.content : Array.isArray(toolMessageObj.content) ? toolMessageObj.content.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("") : String(toolMessageObj.content ?? ""),
-            rawOutput: void 0,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-            summarized: true,
-            messageId: void 0,
-            tool_call_id: callId,
-            fromCache: false
-          };
-          if (callId) byCallId.set(callId, hist);
-          archived.push({ ...hist });
-        }
-        if (!hist.executionId) hist.executionId = nanoid.nanoid();
-        hist.summarized = true;
-        rewritten.push({
-          role: "tool",
-          content: `SUMMARIZED executionId:'${hist.executionId}'`,
-          tool_call_id: safeId,
-          name: toolMessage.name
-        });
-        continue;
+    const newMessages = messages.map((m) => {
+      if (m.role === "tool") {
+        if (m.content === "SUMMARIZED") return m;
+        return {
+          ...m,
+          content: "SUMMARIZED"
+        };
       }
-      rewritten.push(m);
-    }
-    const summarizeCallId = `summarize_${nanoid.nanoid(6)}`;
-    const summarizeArgs = { reason: "Exceeded token limit: summarize prior tool outputs for context." };
-    const syntheticAssistant = {
+      return m;
+    });
+    const summaryToolCallId = `call_summary_${Date.now()}`;
+    const assistantSummaryCall = {
       role: "assistant",
-      content: "",
-      additional_kwargs: {
-        tool_calls: [
-          { id: summarizeCallId, type: "function", function: { name: "context_summarize", arguments: JSON.stringify(summarizeArgs) } }
-        ]
-      }
+      // "assistant"
+      content: "Context limit reached. Summarizing conversation history to reduce token usage.",
+      tool_calls: [
+        {
+          id: summaryToolCallId,
+          type: "function",
+          function: {
+            name: "summarize_context",
+            arguments: "{}"
+          }
+        }
+      ]
     };
-    const syntheticToolResp = {
+    const toolSummaryResponse = {
       role: "tool",
-      content: `${summaryText}`,
-      tool_call_id: summarizeCallId,
-      name: "context_summarize"
+      tool_call_id: summaryToolCallId,
+      name: "summarize_context",
+      // Matches the tool name in the call
+      content: summaryText
     };
-    for (const item of live) item.summarized = true;
-    const merged = [...archived, ...live];
-    const dedupMap = /* @__PURE__ */ new Map();
-    for (const it of merged) {
-      const key = it.tool_call_id || `${it.toolName}:${it.timestamp}`;
-      dedupMap.set(key, { ...it });
-    }
-    const newArchived = Array.from(dedupMap.values());
-    const onEvent = state.ctx?.__onEvent;
-    onEvent?.({ type: "summarization", summary: summaryText, archivedCount: newArchived.length });
     return {
-      messages: [...rewritten, syntheticAssistant, syntheticToolResp],
-      toolHistoryArchived: newArchived,
-      toolHistory: [],
-      ctx: { ...state.ctx || {}, __contextSummarized: true }
+      messages: [...newMessages, assistantSummaryCall, toolSummaryResponse]
     };
   };
 }
@@ -2454,13 +2413,16 @@ function createContextTools(stateRef, opts) {
 
 // src/graph/decisions.ts
 function needsSummarization(state, opts, summarizationEnabled) {
-  const maxTok = opts.limits?.maxToken;
-  if (!maxTok || !summarizationEnabled) return false;
+  const maxTok = opts.limits?.maxToken ?? opts.limits?.contextTokenLimit;
+  if (!maxTok || !summarizationEnabled) {
+    return false;
+  }
   try {
     const allText = (state.messages || []).map((m) => typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.map((c) => typeof c === "string" ? c : c?.text ?? c?.content ?? "").join("") : "").join("\n");
     const tokenCount = countApproxTokens(allText);
-    return tokenCount > maxTok;
-  } catch {
+    const needsSum = tokenCount > maxTok;
+    return needsSum;
+  } catch (e) {
     return false;
   }
 }
@@ -2485,7 +2447,12 @@ function createSmartAgent(opts) {
   const contextTools = createContextTools(stateRef, { planningEnabled, outputSchema: void 0 });
   const mergedTools = [...opts.tools ?? [], ...contextTools];
   const base = createAgent({ ...opts, tools: mergedTools });
-  const summarizationEnabled = opts.summarization !== false;
+  let summarizationEnabled = false;
+  if (typeof opts.summarization === "object") {
+    summarizationEnabled = opts.summarization.enable !== false;
+  } else {
+    summarizationEnabled = opts.summarization !== false;
+  }
   const summarizer = summarizationEnabled ? createContextSummarizeNode(opts) : void 0;
   const decideBefore = resolverDecisionFactory(opts, summarizationEnabled);
   const decideAfter = toolsDecisionFactory(opts, summarizationEnabled);
@@ -2522,6 +2489,14 @@ function createSmartAgent(opts) {
         const res = await base.invoke(state, config);
         lastResult = res;
         state = res.state || { ...state, messages: res.messages };
+        if (state.ctx?.__needsSummarization && summarizer) {
+          const ctx = { ...state.ctx || {} };
+          delete ctx.__needsSummarization;
+          state = { ...state, ctx };
+          const delta = await summarizer(state);
+          state = { ...state, ...delta };
+          continue;
+        }
         if (state.ctx?.__finalizedDueToStructuredOutput) break;
         if (summarizationEnabled) {
           const after = decideAfter(state);