@providerprotocol/agents 0.0.1 → 0.0.3

package/README.md

@@ -1,15 +1,342 @@
-# providerprotocol-agents
+# @providerprotocol/agents
 
-To install dependencies:
+A powerful, flexible agent framework implementing the Unified Agent Protocol (UAP) 1.0. Built on top of [@providerprotocol/ai](https://github.com/providerprotocol/ai) for seamless multi-provider LLM support.
+
+## Features
+
+- **Functional State Management** - Immutable state with explicit data flow
+- **Execution Strategies** - Choose from `loop`, `react`, or `plan` patterns
+- **Middleware Pipeline** - Composable before/after hooks for logging, guardrails, etc.
+- **Multi-Provider Support** - Works with Anthropic, OpenAI, Google, Ollama, and more
+- **Streaming** - Full streaming support with UAP and UPP events
+- **Checkpointing** - Built-in session persistence and recovery
+- **Thread Trees** - Branching conversation support
+- **Type-Safe** - 100% TypeScript with full type inference
+
+## Installation
 
 ```bash
-bun install
+bun install @providerprotocol/agents @providerprotocol/ai
+```
+
+## Quick Start
+
+```typescript
+import { agent, AgentState } from '@providerprotocol/agents';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+
+// Create an agent
+const assistant = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  params: { max_tokens: 4096 },
+  system: 'You are a helpful assistant.',
+});
+
+// Single query (stateless)
+const turn = await assistant.query('What is the capital of France?');
+console.log(turn.response.text);
+
+// Multi-turn conversation (stateful)
+let state = AgentState.initial();
+const r1 = await assistant.ask('My name is Alice.', state);
+state = r1.state;
+
+const r2 = await assistant.ask('What is my name?', state);
+console.log(r2.turn.response.text); // "Alice"
+```
+
+## Adding Tools
+
+```typescript
+import { agent, AgentState } from '@providerprotocol/agents';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+
+const calculator = {
+  name: 'calculate',
+  description: 'Evaluate a math expression',
+  parameters: {
+    type: 'object' as const,
+    properties: {
+      expression: { type: 'string' as const },
+    },
+    required: ['expression'],
+  },
+  run: async (params: { expression: string }) => {
+    // Use a proper math parser in production
+    return String(eval(params.expression));
+  },
+};
+
+const mathBot = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  params: { max_tokens: 1000 },
+  tools: [calculator],
+});
+
+const turn = await mathBot.query('What is 42 * 17?');
+console.log(turn.response.text);
+console.log(turn.toolExecutions); // Shows calculator was used
+```
+
+## Execution Strategies
+
+Choose how your agent thinks and acts:
+
+### Loop (Default)
+
+Simple tool loop - keeps executing until no more tool calls.
+
+```typescript
+import { loop } from '@providerprotocol/agents/execution';
+
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  execution: loop({ maxIterations: 10 }),
+});
+```
+
+### ReAct
+
+Reason-Act-Observe pattern with explicit reasoning phase.
+
+```typescript
+import { react } from '@providerprotocol/agents/execution';
+
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  execution: react({ maxSteps: 20 }),
+});
+```
+
+### Plan
+
+Generate a structured plan, then execute steps with dependencies.
+
+```typescript
+import { plan } from '@providerprotocol/agents/execution';
+
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  execution: plan({ maxPlanSteps: 10, allowReplan: true }),
+});
+```
+
+## Streaming
+
+```typescript
+const stream = myAgent.stream('Explain quantum computing', state);
+
+for await (const event of stream) {
+  if (event.source === 'upp' && event.upp?.type === 'text_delta') {
+    process.stdout.write(event.upp.delta.text ?? '');
+  }
+}
+
+const { turn, state: newState } = await stream.result;
+```
+
+## Middleware
+
+```typescript
+import { logging } from '@providerprotocol/agents/middleware';
+
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  middleware: [
+    logging({ level: 'info', includeTiming: true }),
+  ],
+});
+```
+
+Create custom middleware:
+
+```typescript
+import type { Middleware } from '@providerprotocol/agents/middleware';
+
+const rateLimiter: Middleware = {
+  name: 'rate-limiter',
+  async before(context) {
+    await checkRateLimit(context.agent.id);
+    return context;
+  },
+  async after(context, result) {
+    recordUsage(result.turn.usage);
+    return result;
+  },
+};
 ```
 
-To run:
+## Checkpointing
+
+Persist agent sessions for recovery:
+
+```typescript
+import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';
+
+const store = fileCheckpoints({ dir: '.checkpoints' });
+
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  checkpoints: store,
+  sessionId: 'my-session',
+});
+
+// Execute - state automatically saved after each step
+await myAgent.generate('Hello', AgentState.initial());
+
+// Later: restore and continue
+const saved = await store.load('my-session');
+if (saved) {
+  const state = AgentState.fromJSON(saved);
+  await myAgent.generate('Continue...', state);
+}
+```
+
+## Lifecycle Hooks
+
+```typescript
+const myAgent = agent({
+  model: anthropic('claude-sonnet-4-20250514'),
+  strategy: {
+    stopCondition: (state) => state.step > 50,
+    onStepStart: (step, state) => console.log(`Step ${step}`),
+    onAct: (step, toolCalls) => console.log('Tools:', toolCalls),
+    onComplete: (result) => console.log('Done!'),
+    onError: (error, state) => console.error(error),
+  },
+});
+```
+
+## Provider Support
+
+Works with all providers from `@providerprotocol/ai`:
+
+```typescript
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { openai } from '@providerprotocol/ai/openai';
+import { google } from '@providerprotocol/ai/google';
+import { ollama } from '@providerprotocol/ai/ollama';
+
+// Anthropic
+agent({ model: anthropic('claude-sonnet-4-20250514'), params: { max_tokens: 4096 } });
+
+// OpenAI
+agent({ model: openai('gpt-4o'), params: { max_output_tokens: 4096 } });
+
+// Google
+agent({ model: google('gemini-2.0-flash'), params: { maxOutputTokens: 4096 } });
+
+// Ollama (local)
+agent({ model: ollama('llama3:8b'), params: { num_predict: 4096 } });
+```
+
+## Environment Variables
+
+Create a `.env` file with your API keys:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=AI...
+```
+
+## API Reference
+
+### agent(options)
+
+Creates an agent instance.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `model` | `ModelReference` | Required. Model from UPP provider |
+| `params` | `object` | LLM parameters (provider-specific) |
+| `system` | `string` | System prompt |
+| `tools` | `Tool[]` | Available tools |
+| `execution` | `ExecutionStrategy` | Strategy: `loop()`, `react()`, `plan()` |
+| `middleware` | `Middleware[]` | Middleware pipeline |
+| `strategy` | `AgentStrategy` | Lifecycle hooks |
+| `checkpoints` | `CheckpointStore` | Session persistence |
+| `sessionId` | `string` | Session identifier |
+
+### Agent Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `generate(input, state)` | `Promise<GenerateResult>` | Execute with state |
+| `stream(input, state)` | `AgentStreamResult` | Stream execution |
+| `ask(input, state)` | `Promise<GenerateResult>` | Multi-turn convenience |
+| `query(input)` | `Promise<Turn>` | Stateless single-turn |
+
+### AgentState
+
+Immutable state with chainable operations:
+
+```typescript
+state.withMessage(msg)       // Add message
+state.withMessages(msgs)     // Add messages
+state.withContext(msgs)      // Replace all messages
+state.withStep(n)            // Set step number
+state.withMetadata(k, v)     // Add metadata
+state.withReasoning(text)    // Add reasoning trace
+state.withPlan(steps)        // Set execution plan
+state.toJSON()               // Serialize
+AgentState.fromJSON(json)    // Deserialize
+```
+
+## Examples
+
+See the [`examples/`](./examples) directory for complete examples:
+
+- **coding-agent** - A Claude Code-style coding assistant with file operations, bash, search, and sub-agents
+
+Run the coding agent example:
 
 ```bash
-bun run index.ts
+ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts "List all TypeScript files"
 ```
 
-This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+Interactive mode:
+
+```bash
+ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts -i
+```
+
+TUI mode:
+
+```bash
+ANTHROPIC_API_KEY=sk-... bun examples/coding-agent/index.ts --tui
+```
+
+## Testing
+
+```bash
+bun test              # All tests
+bun test:unit         # Unit tests
+bun test:live         # Live API tests
+bun lint              # Lint
+bun typecheck         # Type check
+```
+
+## Philosophy
+
+**"UAP is a pipe, not a nanny."**
+
+This framework provides orchestration primitives with sensible defaults but no artificial limits. By default:
+
+- Execution continues until naturally complete (no max iterations)
+- State is explicit and immutable
+- All UPP types flow through without abstraction
+- You control safety, budgets, and constraints
+
+## Documentation
+
+- [llms.md](./llms.md) - Comprehensive API documentation for LLMs and developers
+- [CLAUDE.md](./CLAUDE.md) - Project coding guidelines and @providerprotocol/ai usage
+
+## License
+
+MIT
+
+## Related
+
+- [@providerprotocol/ai](https://github.com/providerprotocol/ai) - Unified Provider Protocol for LLM inference

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,43 @@
+import { F as FileCheckpointOptions, C as CheckpointStore } from '../types-BhX9uD_d.js';
+export { b as CheckpointData, a as CheckpointMetadata } from '../types-BhX9uD_d.js';
+import '../types-2Vsthzyu.js';
+import '@providerprotocol/ai';
+
+/**
+ * File-based Checkpoint Store
+ *
+ * Reference implementation of CheckpointStore using the filesystem.
+ *
+ * @see UAP-1.0 Spec Section 12.4.3
+ */
+
+/**
+ * Create a file-based checkpoint store.
+ *
+ * Stores checkpoints as JSON files in a directory structure:
+ * ```
+ * {dir}/
+ *   {sessionId}/
+ *     checkpoint.json   # Latest state
+ *     metadata.json     # Session metadata
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns CheckpointStore implementation
+ *
+ * @example
+ * ```typescript
+ * import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';
+ *
+ * const store = fileCheckpoints({ dir: './my-checkpoints' });
+ *
+ * // Save a checkpoint
+ * await store.save('session-123', state.toJSON());
+ *
+ * // Load a checkpoint
+ * const saved = await store.load('session-123');
+ * ```
+ */
+declare function fileCheckpoints(options?: FileCheckpointOptions): CheckpointStore;
+
+export { CheckpointStore, FileCheckpointOptions, fileCheckpoints };

package/dist/checkpoint/index.js

@@ -0,0 +1,64 @@
+import { generateUUID } from '../chunk-EKRXMSDX.js';
+import { mkdir, readdir, rm, readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+var DEFAULT_DIR = ".checkpoints";
+function fileCheckpoints(options = {}) {
+  const dir = options.dir ?? DEFAULT_DIR;
+  async function ensureSessionDir(sessionId) {
+    const sessionDir = join(dir, sessionId);
+    await mkdir(sessionDir, { recursive: true });
+    return sessionDir;
+  }
+  function getPaths(sessionId) {
+    const sessionDir = join(dir, sessionId);
+    return {
+      checkpointPath: join(sessionDir, "checkpoint.json"),
+      metadataPath: join(sessionDir, "metadata.json")
+    };
+  }
+  return {
+    async save(sessionId, state) {
+      await ensureSessionDir(sessionId);
+      const { checkpointPath, metadataPath } = getPaths(sessionId);
+      const metadata = {
+        sessionId,
+        checkpointId: generateUUID(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        step: state.step,
+        agentId: state.metadata.agentId ?? "unknown"
+      };
+      await writeFile(checkpointPath, JSON.stringify(state, null, 2), "utf-8");
+      await writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    },
+    async load(sessionId) {
+      const { checkpointPath } = getPaths(sessionId);
+      try {
+        const content = await readFile(checkpointPath, "utf-8");
+        return JSON.parse(content);
+      } catch {
+        return null;
+      }
+    },
+    async delete(sessionId) {
+      const sessionDir = join(dir, sessionId);
+      try {
+        await rm(sessionDir, { recursive: true, force: true });
+      } catch {
+      }
+    },
+    async list() {
+      try {
+        await mkdir(dir, { recursive: true });
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+      } catch {
+        return [];
+      }
+    }
+  };
+}
+
+export { fileCheckpoints };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/checkpoint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/checkpoint/file.ts"],"names":[],"mappings":";;;;AAcA,IAAM,WAAA,GAAc,cAAA;AA6Bb,SAAS,eAAA,CAAgB,OAAA,GAAiC,EAAC,EAAoB;AACpF,EAAA,MAAM,GAAA,GAAM,QAAQ,GAAA,IAAO,WAAA;AAK3B,EAAA,eAAe,iBAAiB,SAAA,EAAoC;AAClE,IAAA,MAAM,UAAA,GAAa,IAAA,CAAK,GAAA,EAAK,SAAS,CAAA;AACtC,IAAA,MAAM,KAAA,CAAM,UAAA,EAAY,EAAE,SAAA,EAAW,MAAM,CAAA;AAC3C,IAAA,OAAO,UAAA;AAAA,EACT;AAKA,EAAA,SAAS,SAAS,SAAA,EAAqE;AACrF,IAAA,MAAM,UAAA,GAAa,IAAA,CAAK,GAAA,EAAK,SAAS,CAAA;AACtC,IAAA,OAAO;AAAA,MACL,cAAA,EAAgB,IAAA,CAAK,UAAA,EAAY,iBAAiB,CAAA;AAAA,MAClD,YAAA,EAAc,IAAA,CAAK,UAAA,EAAY,eAAe;AAAA,KAChD;AAAA,EACF;AAEA,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,CAAK,SAAA,EAAmB,KAAA,EAAsC;AAClE,MAAA,MAAM,iBAAiB,SAAS,CAAA;AAChC,MAAA,MAAM,EAAE,cAAA,EAAgB,YAAA,EAAa,GAAI,SAAS,SAAS,CAAA;AAG3D,MAAA,MAAM,QAAA,GAA+B;AAAA,QACnC,SAAA;AAAA,QACA,cAAc,YAAA,EAAa;AAAA,QAC3B,SAAA,EAAA,iBAAW,IAAI,IAAA,EAAK,EAAE,WAAA,EAAY;AAAA,QAClC,MAAM,KAAA,CAAM,IAAA;AAAA,QACZ,OAAA,EAAS,KAAA,CAAM,QAAA,CAAS,OAAA,IAAqB;AAAA,OAC/C;AAGA,MAAA,MAAM,SAAA,CAAU,gBAAgB,IAAA,CAAK,SAAA,CAAU,OAAO,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA;AACvE,MAAA,MAAM,SAAA,CAAU,cAAc,IAAA,CAAK,SAAA,CAAU,UAAU,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA;AAAA,IAC1E,CAAA;AAAA,IAEA,MAAM,KAAK,SAAA,EAAmD;AAC5D,MAAA,MAAM,EAAE,cAAA,EAAe,GAAI,QAAA,CAAS,SAAS,CAAA;AAE7C,MAAA,IAAI;AACF,QAAA,MAAM,OAAA,GAAU,MAAM,QAAA,CAAS,cAAA,EAAgB,OAAO,CAAA;AACtD,QAAA,OAAO,IAAA,CAAK,MAAM,OAAO,CAAA;AAAA,MAC3B,CAAA,CAAA,MAAQ;AAEN,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,IACF,CAAA;AAAA,IAEA,MAAM,OAAO,SAAA,EAAkC;AAC7C,MAAA,MAAM,UAAA,GAAa,IAAA,CAAK,GAAA,EAAK,SAAS,CAAA;AACtC,MAAA,IAAI;AACF,QAAA,MAAM,GAAG,UAAA,EAAY,EAAE,WAAW,IAAA,EAAM,KAAA,EAAO,MAAM,CAAA;AAAA,MACvD,CAAA,CAAA,MAAQ;AAAA,MAER;AAAA,IACF,CAAA;AAAA,IAEA,MAAM,IAAA,GAA0B;AAC9B,MAAA,IAAI;AAEF,QAAA,MAAM,KAAA,CAAM,GAAA,EAAK,EAAE,SAAA,EAAW,MAAM,CAAA;AAEpC,QAAA,MAAM,UAAU,MAAM,OAAA,CAAQ,KAAK,EAAE,aAAA,EAAe,MAAM,CAAA;AAC1D,QAAA,OAAO,OAAA,CACJ,MAAA,CAAO,CAAC,KAAA,KAAU,KAAA,CAAM,WAAA,EAAa,CAAA,CACrC,GAAA,CAAI,CAAC,KAAA,KAAU,KAAA,CAAM,IAAI,CAAA;AAAA,MAC9B,CAAA,CAAA,MAAQ;AACN,QAAA,OAAO,EAAC;AAAA,MACV;AAAA,IACF;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * File-based Checkpoint Store\n *\n * Reference implementation of CheckpointStore using the filesystem.\n *\n * @see UAP-1.0 Spec Section 12.4.3\n */\n\nimport { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport type { AgentStateJSON } from '../state/types.ts';\nimport type { CheckpointStore, FileCheckpointOptions, CheckpointMetadata } from './types.ts';\nimport { generateUUID } from '../utils/uuid.ts';\n\nconst DEFAULT_DIR = '.checkpoints';\n\n/**\n * Create a file-based checkpoint store.\n *\n * Stores checkpoints as JSON files in a directory structure:\n * ```\n * {dir}/\n *   {sessionId}/\n *     checkpoint.json   # Latest state\n *     metadata.json     # Session metadata\n * ```\n *\n * @param options - Configuration options\n * @returns CheckpointStore implementation\n *\n * @example\n * ```typescript\n * import { fileCheckpoints } from '@providerprotocol/agents/checkpoint';\n *\n * const store = fileCheckpoints({ dir: './my-checkpoints' });\n *\n * // Save a checkpoint\n * await store.save('session-123', state.toJSON());\n *\n * // Load a checkpoint\n * const saved = await store.load('session-123');\n * ```\n */\nexport function fileCheckpoints(options: FileCheckpointOptions = {}): CheckpointStore {\n  const dir = options.dir ?? DEFAULT_DIR;\n\n  /**\n   * Ensure session directory exists.\n   */\n  async function ensureSessionDir(sessionId: string): Promise<string> {\n    const sessionDir = join(dir, sessionId);\n    await mkdir(sessionDir, { recursive: true });\n    return sessionDir;\n  }\n\n  /**\n   * Get paths for checkpoint files.\n   */\n  function getPaths(sessionId: string): { checkpointPath: string; metadataPath: string } {\n    const sessionDir = join(dir, sessionId);\n    return {\n      checkpointPath: join(sessionDir, 'checkpoint.json'),\n      metadataPath: join(sessionDir, 'metadata.json'),\n    };\n  }\n\n  return {\n    async save(sessionId: string, state: AgentStateJSON): Promise<void> {\n      await ensureSessionDir(sessionId);\n      const { checkpointPath, metadataPath } = getPaths(sessionId);\n\n      // Build metadata\n      const metadata: CheckpointMetadata = {\n        sessionId,\n        checkpointId: generateUUID(),\n        timestamp: new Date().toISOString(),\n        step: state.step,\n        agentId: state.metadata.agentId as string ?? 'unknown',\n      };\n\n      // Write checkpoint first, then metadata (sequential to avoid race conditions)\n      await writeFile(checkpointPath, JSON.stringify(state, null, 2), 'utf-8');\n      await writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');\n    },\n\n    async load(sessionId: string): Promise<AgentStateJSON | null> {\n      const { checkpointPath } = getPaths(sessionId);\n\n      try {\n        const content = await readFile(checkpointPath, 'utf-8');\n        return JSON.parse(content) as AgentStateJSON;\n      } catch {\n        // File doesn't exist or is invalid\n        return null;\n      }\n    },\n\n    async delete(sessionId: string): Promise<void> {\n      const sessionDir = join(dir, sessionId);\n      try {\n        await rm(sessionDir, { recursive: true, force: true });\n      } catch {\n        // Directory might not exist, ignore\n      }\n    },\n\n    async list(): Promise<string[]> {\n      try {\n        // Ensure base directory exists\n        await mkdir(dir, { recursive: true });\n\n        const entries = await readdir(dir, { withFileTypes: true });\n        return entries\n          .filter((entry) => entry.isDirectory())\n          .map((entry) => entry.name);\n      } catch {\n        return [];\n      }\n    },\n  };\n}\n"]}