@cognipeer/agent-sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,41 +1,79 @@
 # @cognipeer/agent-sdk
 
-Composable, message-first agent runtime with token-aware summarization, optional planning, and tool debugging baked in. Ships both ESM and CJS builds with full TypeScript types. LangChain is fully optional via a duck-typed adapter.
-
-## Features
-
-- **Transparent tool turns** – assistant tool calls and tool responses live in `state.messages` so transcripts stay debuggable.
-- **Summarization pipeline** – large tool outputs are archived with reversible execution IDs; summaries keep context under token budgets.
-- **Planning mode** – enable `useTodoList` to expose the `manage_todo_list` tool and strict system prompt rules.
-- **Structured output** – pass a Zod schema to add a hidden `response` finalize tool and receive parsed JSON on `result.output`.
-- **Multi-agent composition** – reuse agents via `asTool` or transfer control mid-run via `asHandoff`.
-- **Usage normalization** – provider usage blobs are normalized and aggregated per model turn.
-- **Rich logging** – enable `debug.enabled` to emit Markdown snapshots under `logs/` or intercept them via `debug.callback`.
+[![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.
+
+- SDK source: `src/`
+- Examples: `examples/`
+- Docs (VitePress): `docs/`
+- Requires Node.js **18.17+**
+
+## Table of contents
+- [Overview](#overview)
+- [What’s inside](#whats-inside)
+- [Install](#install)
+- [Quick start](#quick-start)
+  - [Smart agent (planning + summarization)](#smart-agent-planning--summarization)
+  - [Base agent (minimal loop)](#base-agent-minimal-loop)
+- [Key capabilities](#key-capabilities)
+- [Examples](#examples)
+- [Architecture snapshot](#architecture-snapshot)
+- [API surface](#api-surface)
+- [Tracing & observability](#tracing--observability)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
+
+## Overview
+
+`@cognipeer/agent-sdk` is a zero-graph, TypeScript-first agent loop. Tool calls are persisted as messages, token pressure triggers automatic summarization, and optional planning mode enforces TODO hygiene with the bundled `manage_todo_list` tool. Multi-agent composition, structured output, and batched tracing are built-in.
+
+Highlights:
+- **Message-first design** – assistant tool calls and tool responses stay in the transcript.
+- **Token-aware summarization** – chunked rewriting archives oversized tool outputs while exposing `get_tool_response` for lossless retrieval.
+- **Planning mode** – strict system prompt + TODO tool keeps one task in progress and emits plan events.
+- **Structured output** – provide a Zod schema and the agent injects a finalize tool to capture JSON deterministically.
+- **Multi-agent and handoffs** – wrap agents as tools or transfer control mid-run with `asTool` / `asHandoff`.
+- **Usage + events** – normalize provider usage, surface `tool_call`, `plan`, `summarization`, `metadata`, and `handoff` events.
+- **Structured tracing** – optional per-invoke JSON traces with metadata, payload capture, and pluggable sinks (file, HTTP, Cognipeer, custom).
+
+## What’s inside
+
+| Path | Description |
+|------|-------------|
+| `src/` | Source for the published package (TypeScript, bundled via tsup). |
+| `examples/` | End-to-end scripts demonstrating tools, planning, summarization, multi-agent, MCP, structured output, and vision input. |
+| `docs/` | VitePress documentation site served at [cognipeer.github.io/agent-sdk](https://cognipeer.github.io/agent-sdk/). |
+| `dist/` | Build output (generated). Contains ESM, CommonJS, and TypeScript definitions. |
+| `logs/` | Generated trace sessions when `tracing.enabled: true`. Safe to delete. |
 
 ## Install
 
+Install the SDK and its (optional) LangChain peer dependency:
+
 ```sh
-npm install @cognipeer/agent-sdk zod
-# optional peers for quick starts
-npm install @langchain/core @langchain/openai
+npm install @cognipeer/agent-sdk @langchain/core zod
+# Optional: LangChain OpenAI bindings for quick starts
+npm install @langchain/openai
 ```
 
-`@langchain/core` is marked as an optional peer dependency – install it if you plan to use LangChain tools or models.
+You can also bring your own model adapter as long as it exposes `invoke(messages[])` and (optionally) `bindTools()`.
 
-## Usage
+## Quick start
 
-### ESM quick start
+### Smart agent (planning + summarization)
 
 ```ts
-import { createSmartAgent, createSmartTool, fromLangchainModel } from "@cognipeer/agent-sdk";
+import { createSmartAgent, createTool, fromLangchainModel } from "@cognipeer/agent-sdk";
 import { ChatOpenAI } from "@langchain/openai";
 import { z } from "zod";
 
-const echo = createSmartTool({
+const echo = createTool({
   name: "echo",
-  description: "Echo back the input text",
+  description: "Echo back user text",
   schema: z.object({ text: z.string().min(1) }),
-  func: async ({ text }) => ({ echoed: text }),
+  func: async ({ text }) => ({ echoed: text })
 });
 
 const model = fromLangchainModel(new ChatOpenAI({
@@ -44,136 +82,172 @@ const model = fromLangchainModel(new ChatOpenAI({
 }));
 
 const agent = createSmartAgent({
+  name: "ResearchHelper",
   model,
   tools: [echo],
-  limits: { maxToolCalls: 5, maxToken: 6000 },
   useTodoList: true,
+  limits: { maxToolCalls: 5, maxToken: 8000 },
+  tracing: { enabled: true },
 });
 
 const result = await agent.invoke({
-  messages: [{ role: "user", content: "Plan a greeting and deliver it via the echo tool" }],
+  messages: [{ role: "user", content: "plan a greeting and send it via the echo tool" }],
+  toolHistory: [],
 });
 
 console.log(result.content);
 ```
 
-### Custom adapters
-
-The runtime only requires `invoke(messages[]) => assistantMessage` and (optionally) `bindTools()`. To use a bespoke SDK, wrap it:
-
-```ts
-const model = {
-  async invoke(messages) {
-    const payload = messages.map(m => ({ role: m.role, content: m.content }));
-    const response = await myClient.chat({ messages: payload });
-    return { role: "assistant", content: response.output, tool_calls: response.tool_calls };
-  },
-  bindTools(tools) {
-    this._tools = tools;
-    return this;
-  }
-};
-
-const agent = createAgent({ model, tools: [...], limits: { maxToolCalls: 3 } });
-```
+The smart wrapper injects a system prompt, manages TODO tooling, and runs summarization passes whenever `limits.maxToken` would be exceeded.
 
-### Vision / multimodal input
+### Base agent (minimal loop)
 
-Messages can contain OpenAI-style content parts:
+Prefer a tiny core without system prompt or summarization? Use `createAgent`:
 
 ```ts
-await agent.invoke({
-  messages: [{
-    role: "user",
-    content: [
-      { type: "text", text: "Describe this image" },
-      { type: "image_url", image_url: { url: "https://example.com/cat.jpg", detail: "low" } },
-    ],
-  }],
-});
-```
-
-### CommonJS
-
-```js
-const { createSmartAgent, createTool, fromLangchainModel } = require("@cognipeer/agent-sdk");
-const { ChatOpenAI } = require("@langchain/openai");
-const { z } = require("zod");
+import { createAgent, createTool, fromLangchainModel } from "@cognipeer/agent-sdk";
+import { ChatOpenAI } from "@langchain/openai";
+import { z } from "zod";
 
 const echo = createTool({
   name: "echo",
+  description: "Echo back",
   schema: z.object({ text: z.string().min(1) }),
   func: async ({ text }) => ({ echoed: text }),
 });
 
 const model = fromLangchainModel(new ChatOpenAI({ model: "gpt-4o-mini", apiKey: process.env.OPENAI_API_KEY }));
-const agent = createSmartAgent({ model, tools: [echo] });
 
-agent.invoke({ messages: [{ role: "user", content: "say hi via echo" }] }).then(res => {
-  console.log(res.content);
+const agent = createAgent({
+  model,
+  tools: [echo],
+  limits: { maxToolCalls: 3, maxParallelTools: 2 },
 });
+
+const res = await agent.invoke({ messages: [{ role: "user", content: "say hi via echo" }] });
+console.log(res.content);
 ```
 
-## API overview
+## Key capabilities
+
+- **Summarization pipeline** – automatic chunking keeps tool call history within `contextTokenLimit` / `summaryTokenLimit`, archiving originals so `get_tool_response` can fetch them later.
+- **Planning discipline** – when `useTodoList` is true the system prompt enforces a plan-first workflow 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`.
+- **Usage normalization** – provider `usage` blobs are normalized into `{ prompt_tokens, completion_tokens, total_tokens }` with cached token tracking and totals grouped by model.
+- **Multi-agent orchestration** – reuse agents via `agent.asTool({ toolName })` or perform handoffs that swap runtimes mid-execution.
+- **MCP + LangChain tools** – any object satisfying the minimal tool interface works; LangChain’s `Tool` implementations plug in directly.
+- **Vision input** – message parts accept OpenAI-style `image_url` entries (see `examples/vision`).
+- **Observability hooks** – `config.onEvent` surfaces tool lifecycle, summarization, metadata, and final answer events for streaming UIs or CLIs.
+
+## Examples
+
+Examples live under `examples/` with per-folder READMEs. Build the package first (`npm run build` or `npm run preexample:<name>`).
+
+| Folder | Focus |
+|--------|-------|
+| `basic/` | Minimal tool call run with real model. |
+| `tools/` | Multiple tools, Tavily search integration, `onEvent` usage. |
+| `tool-limit/` | Hitting the global tool-call cap and finalize behavior. |
+| `todo-planning/` | Smart planning workflow with enforced TODO updates. |
+| `summarization/` | Token-threshold summarization walkthrough. |
+| `summarize-context/` | Summaries + `get_tool_response` raw retrieval. |
+| `structured-output/` | Zod schema finalize tool and parsed outputs. |
+| `rewrite-summary/` | Continue conversations after summaries are injected. |
+| `multi-agent/` | Delegating between agents via `asTool`. |
+| `handoff/` | Explicit runtime handoffs. |
+| `mcp-tavily/` | MCP remote tool discovery. |
+| `vision/` | Text + image input using LangChain’s OpenAI bindings. |
+
+Run directly with `tsx`, for example:
+
+```sh
+# from repo root
+npm run build
+OPENAI_API_KEY=... npx tsx examples/tools/tools.ts
+```
 
-Exports from `dist/index.*`:
+## Architecture snapshot
 
-- `createSmartAgent(options)` – smart wrapper with system prompt, planning tools, summarization.
-- `createAgent(options)` – minimal loop without system prompt or summarization.
-- `createSmartTool({ name, description?, schema, func })` – helper for Zod-backed tools.
-- `createTool(...)` – alias kept for migration.
-- `fromLangchainModel(model)` – duck-type adapter for LangChain `ChatModel` / `Runnable` objects.
-- `withTools(model, tools)` – best-effort tool binding helper.
-- `buildSystemPrompt(extra?, planning?, name?)` – construct the internal system prompt.
-- Node factories (`nodes/*`), context helpers, token utilities, and full TypeScript types (`SmartAgentOptions`, `SmartState`, `AgentInvokeResult`, etc.).
+The agent is a deterministic while-loop – no external graph runtime. Each turn flows through:
 
-### SmartAgentOptions highlights
+1. **resolver** – normalize state (messages, counters, limits).
+2. **contextSummarize** (optional) – when token estimates exceed `limits.maxToken`, archive heavy tool outputs.
+3. **agent** – invoke the model (binding tools when supported).
+4. **tools** – execute proposed tool calls with configurable parallelism.
+5. **toolLimitFinalize** – if tool-call cap is hit, inject a system notice so the next assistant turn must answer directly.
 
-- `model`: required chat model adapter (must expose `invoke`).
-- `tools`: array of tool implementations (LangChain `Tool`, MCP adapters, or plain objects implementing `invoke`/`call`).
-- `limits`: `{ maxToolCalls?, maxParallelTools?, maxToken?, contextTokenLimit?, summaryTokenLimit? }`.
-- `useTodoList`: enable planning rules and `manage_todo_list` tool.
-- `summarization`: set to `false` to disable summarization entirely.
-- `outputSchema`: Zod schema for structured output parse + finalize tool.
-- `usageConverter`: hook to normalize provider-specific usage shapes.
-- `debug`: `{ enabled: boolean, path?, callback? }` for Markdown logs.
-- `onEvent`: receive `tool_call`, `plan`, `summarization`, `metadata`, `handoff`, and `finalAnswer` events per invoke.
+The loop stops when the assistant produces a message without tool calls, a structured output finalize signal is observed, or a handoff transfers control. See `docs/architecture/README.md` for diagrams and heuristics.
 
-### Structured output finalize
+## API surface
 
-When `outputSchema` is provided, the framework injects a hidden `response` tool. The model is instructed (via system prompt) to call it exactly once with the final JSON object. Parsed output appears on `result.output` and the loop stops automatically.
+Exported helpers (`agent-sdk/src/index.ts`):
 
-### Summarization internals
+- `createSmartAgent(options)`
+- `createAgent(options)`
+- `createTool({ name, description?, schema, func })`
+- `fromLangchainModel(model)`
+- `withTools(model, tools)`
+- `buildSystemPrompt(extra?, planning?, name?)`
+- Node factories (`nodes/*`), context helpers, token utilities, and full TypeScript types (`SmartAgentOptions`, `SmartState`, `AgentInvokeResult`, etc.).
 
-- Token estimates use a lightweight `countApproxTokens` heuristic (~4 chars per token).
-- When the next model turn would exceed `limits.maxToken`, the contextSummarize node chunk-summarizes tool responses into concise briefs while archiving originals in `state.toolHistoryArchived`.
-- `get_tool_response` lets the model request the raw payload later using `executionId`.
+`SmartAgentOptions` accepts the usual suspects (`model`, `tools`, `limits`, `useTodoList`, `summarization`, `usageConverter`, `tracing`). See `docs/api/` for detailed type references.
 
-## Debugging
+## Tracing & observability
 
-Enable logging with `debug.enabled: true`. By default Markdown files are written to `logs/<ISO_TIMESTAMP>/` containing:
+Enable tracing by passing `tracing: { enabled: true }`. Each invocation writes `trace.session.json` into `logs/<SESSION_ID>/` detailing:
 
-- Model name, invocation limits, and raw usage (if reported).
-- Serialized tool schemas.
-- Message timeline with assistant/tool turns.
+- Model/provider, agent name/version, limits, and timing metadata
+- Structured events for model calls, tool executions, summaries, and errors
+- Optional payload captures (request/response/tool bodies) when `logData` is `true`
+- Aggregated token usage, byte counts, and error summaries for dashboards
 
-Provide `debug.callback` to receive the same payload programmatically (no files written).
+You can disable payload capture with `logData: false` to keep only metrics, or configure sinks such as `httpSink(url, headers?)`, `cognipeerSink(apiKey, url?)`, or `customSink({ onEvent, onSession })` to forward traces after each run. Sensitive headers/callbacks remain in-memory and are never written alongside the trace.
 
-## Build
+## Development
 
-`tsup` bundles to `dist/index.js` (ESM) and `dist/index.cjs` (CJS) with declarations. Run:
+Install dependencies and build the package:
 
 ```sh
+cd agent-sdk
 npm install
 npm run build
 ```
 
-`prepublishOnly` also performs a build to keep the published artifact fresh.
+From the repo root you can run `npm run build` (delegates to the package) or use `npm run example:<name>` scripts defined in `package.json`.
+
+### Publishing
+
+Only publish `agent-sdk/`:
+
+```sh
+cd agent-sdk
+npm version <patch|minor|major>
+npm publish --access public
+```
+
+`prepublishOnly` ensures a fresh build before publishing.
+
+## Troubleshooting
+
+- **Missing tool calls** – ensure your model supports `bindTools`. If not, wrap with `withTools(model, tools)` to provide best-effort behavior.
+- **Summaries too aggressive** – adjust `limits.maxToken`, `contextTokenLimit`, and `summaryTokenLimit`, or disable with `summarization: false`.
+- **Large tool responses** – return structured payloads and rely on `get_tool_response` for raw data instead of dumping megabytes inline.
+- **Usage missing** – some providers do not report usage; customize `usageConverter` to normalize proprietary shapes.
 
-## License
+## Documentation
 
-MIT
+- Live site: https://cognipeer.github.io/agent-sdk/
+- Key guides within this repo:
+  - `docs/getting-started/`
+  - `docs/core-concepts/`
+  - `docs/architecture/`
+  - `docs/api/`
+  - `docs/tools/`
+  - `docs/examples/`
+  - `docs/debugging/`
+  - `docs/limits-tokens/`
+  - `docs/tool-development/`
+  - `docs/faq/`
 
----
+Contributions welcome! Open issues or PRs against `main` with reproduction details when reporting bugs.
 
-LangChain remains an optional peer – install it only if you need its tools or models. The core runtime has no hard dependency on LangChain message classes or graph libraries.