agentfootprint 3.1.0 → 3.1.2

package/AGENTS.md

@@ -44,7 +44,9 @@ const provider = mock({ reply: 'Refunds take 3 business days.' });
 
 // Inline-mocked tool — no real backend yet.
 const lookup = defineTool({
-  schema: { name: 'lookup', description: '...', inputSchema: {} },
+  name: 'lookup',
+  description: '...',
+  inputSchema: { type: 'object', properties: {} },
   execute: async () => 'mock data',
 });
 
@@ -148,7 +150,8 @@ agent.rag(docs);
 ### Agent (ReAct primitive)
 
 ```typescript
-import { Agent, defineTool, anthropic } from 'agentfootprint';
+import { Agent, defineTool } from 'agentfootprint';
+import { anthropic } from 'agentfootprint/llm-providers';
 
 const agent = Agent.create({
   provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
@@ -172,7 +175,8 @@ Builder methods:
 ### LLMCall (one-shot primitive)
 
 ```typescript
-import { LLMCall, anthropic } from 'agentfootprint';
+import { LLMCall } from 'agentfootprint';
+import { anthropic } from 'agentfootprint/llm-providers';
 
 const call = LLMCall.create({ provider: anthropic(...), model: 'claude-sonnet-4-5-20250929' })
   .system('You are a terse assistant.')
@@ -187,14 +191,12 @@ const answer = await call.run({ message: 'Summarize: ...' });
 import { defineTool } from 'agentfootprint';
 
 const weather = defineTool({
-  schema: {
-    name: 'weather',
-    description: 'Current weather for a city.',
-    inputSchema: {
-      type: 'object',
-      properties: { city: { type: 'string' } },
-      required: ['city'],
-    },
+  name: 'weather',
+  description: 'Current weather for a city.',
+  inputSchema: {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city'],
   },
   execute: async (args) => `${(args as { city: string }).city}: 72°F`,
 });
@@ -330,33 +332,34 @@ There is **no** `MultiAgentSystem` class. Multi-agent = compositions of single A
 ```typescript
 import { Sequence, Parallel, Conditional, Loop } from 'agentfootprint';
 
-// Output flows downstream
+// Output flows downstream — every step needs an id + a runner
 const pipeline = Sequence.create()
-  .step(researcher)        // each step is itself an Agent / LLMCall / runner
-  .step(writer)
-  .step(editor)
+  .step('research', researcher)   // each runner is an Agent / LLMCall / composition
+  .step('write', writer)
+  .step('edit', editor)
   .build();
 
-// Multi-perspective with merge
+// Multi-perspective with LLM merge — branches need ids; rank via mergeWithLLM
 const tot = Parallel.create()
-  .branch(thoughtAgent)
-  .branch(thoughtAgent)
-  .branch(thoughtAgent)
-  .merge(rankerLLM)
+  .branch('a', thoughtAgent)
+  .branch('b', thoughtAgent)
+  .branch('c', thoughtAgent)
+  .mergeWithLLM({ provider, model: 'mock', prompt: 'Pick the best answer.' })
   .build();
+// (or .mergeWithFn((results) => ...) to merge in code)
 
-// Predicate-based routing
+// Predicate-based routing — .when(id, predicate, runner); .otherwise is mandatory
 const triage = Conditional.create()
-  .when((ctx) => ctx.intent === 'billing', billingAgent)
-  .when((ctx) => ctx.intent === 'tech', techAgent)
-  .otherwise(generalAgent)
+  .when('billing', (input) => /refund|invoice/i.test(input.message), billingAgent)
+  .when('tech', (input) => /error|bug/i.test(input.message), techAgent)
+  .otherwise('general', generalAgent)
   .build();
 
-// Iterate with budget
+// Iterate with a REQUIRED budget — .repeat(body) + .times(n) / .forAtMost(ms) / .until(guard)
 const refine = Loop.create()
-  .body(critiqueAgent)
-  .untilGuard((ctx) => ctx.qualityScore > 0.9)
-  .maxIterations(5)
+  .repeat(critiqueAgent)
+  .until(({ iteration, latestOutput }) => latestOutput.includes('DONE'))
+  .times(5)
   .build();
 ```
 
@@ -377,7 +380,9 @@ Browse [`examples/patterns/`](examples/patterns/) — every pattern is a runnabl
 ### Providers
 
 ```typescript
-import { anthropic, openai, bedrock, ollama, mock } from 'agentfootprint';
+import { mock } from 'agentfootprint';
+// Vendor-SDK providers (lazy peer-deps) live on the dedicated subpath:
+import { anthropic, openai, bedrock, ollama } from 'agentfootprint/llm-providers';
 
 // Adapter-swap testing: same agent, different provider, $0 in CI
 const provider = process.env.NODE_ENV === 'production'
@@ -385,7 +390,12 @@ const provider = process.env.NODE_ENV === 'production'
   : mock({ reply: 'test response' });
 ```
 
-Every provider implements the same `LLMProvider` interface. Browser variants exist for client-side use.
+Every provider implements the same `LLMProvider` interface. `mock`,
+`browserAnthropic`, `browserOpenai`, and `createProvider` ship on the main
+barrel; the vendor-SDK-backed providers (`anthropic` · `openai` · `bedrock`
+· `ollama`) live ONLY at `agentfootprint/llm-providers` (legacy alias:
+`agentfootprint/providers`) so bundlers never walk their lazy peer-dep
+requires. Browser variants exist for client-side use.
 
 ### Pause / Resume (Human-in-the-Loop)
 
@@ -393,8 +403,13 @@ Every provider implements the same `LLMProvider` interface. Browser variants exi
 import { askHuman, pauseHere, isPaused } from 'agentfootprint';
 
 const approveTool = defineTool({
-  schema: { name: 'approve', description: 'Ask a human.', inputSchema: { ... } },
-  execute: askHuman({ severity: 'high' }),
+  name: 'approve',
+  description: 'Ask a human.',
+  inputSchema: { type: 'object', properties: { amount: { type: 'number' } } },
+  // askHuman() / pauseHere() throw a PauseRequest — CALL them inside
+  // execute, don't pass them as the execute function.
+  execute: async (args) =>
+    askHuman({ question: `Approve $${(args as { amount: number }).amount}?` }),
 });
 
 const result = await agent.run({ message: 'Refund $500?' });
@@ -408,14 +423,20 @@ if (isPaused(result)) {
 ### Resilience
 
 ```typescript
-import { withRetry, withFallback, resilientProvider } from 'agentfootprint';
+import { withRetry, withFallback, fallbackProvider, withCircuitBreaker } from 'agentfootprint/resilience';
+import { anthropic, openai, ollama } from 'agentfootprint/llm-providers';
 
-const reliable = withRetry(provider, { maxRetries: 3 });
+const reliable = withRetry(provider, { maxAttempts: 3 });
 const resilient = withFallback(primary, fallback);
-const chain = resilientProvider([anthropic({...}), openai({...}), ollama({...})]);
+const chain = fallbackProvider(anthropic({...}), openai({...}), ollama({...}));
+const guarded = withCircuitBreaker(provider);
 ```
 
-### Observability — 47 typed events × 13 domains
+Resilience decorators live on the `agentfootprint/resilience` subpath
+(not the main barrel). Each preserves the `LLMProvider` interface and
+stacks freely.
+
+### Observability — 59 typed events across 16 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>
@@ -440,7 +461,7 @@ Recorders (auto-attached when relevant builder method is called):
 
 - ❌ **Don't ship a `ReflexionAgent` class.** Compose `Sequence(Agent, critique-LLM, Agent)`.
 - ❌ **Don't use `agent.run('string')`** — use `agent.run({ message: '...', identity? })`.
-- ❌ **Don't import from stale subpaths** like `'agentfootprint/instructions'`, `'agentfootprint/observe'`, `'agentfootprint/security'`. Top-level barrel covers it: `from 'agentfootprint'`.
+- ❌ **Don't import from non-existent subpaths** like `'agentfootprint/instructions'` — the injection factories live on the main barrel (or `'agentfootprint/injection-engine'`). NOTE: `'agentfootprint/observe'`, `'agentfootprint/security'`, `'agentfootprint/resilience'`, `'agentfootprint/llm-providers'`, `'agentfootprint/memory'`, `'agentfootprint/tool-providers'`, `'agentfootprint/locales'` ARE real subpaths — some surfaces (vendor providers, resilience decorators) live ONLY there, not on the main barrel.
 - ❌ **Don't use `.memoryPipeline(pipeline)`** — that's the v1 API. Use `.memory(defineMemory({...}))`.
 - ❌ **Don't fall back when TopK threshold returns nothing.** Strict semantics: garbage past context > none is wrong.
 - ❌ **Don't store closures or class instances in scope** — TransactionBuffer can't clone functions. Memory-store entries serialize to JSON.
@@ -471,10 +492,10 @@ Recorders (auto-attached when relevant builder method is called):
 ## Build & Test
 
 ```bash
-npm install agentfootprint footprintjs
-npm test                           # vitest run — 1100+ tests
+npm install agentfootprint footprintjs   # footprintjs ^6 is a peer dependency
+npm test                           # vitest run
 npm run example examples/...       # run a single example end-to-end
-npm run examples:run-all           # run every example (33 of them)
+npm run test:examples              # typecheck + run every example
 ```
 
 ## Package layout
@@ -489,10 +510,10 @@ src/
 ├── memory/       — defineMemory + 4 types × 7 strategies + InMemoryStore + Causal
 ├── adapters/llm/ — Anthropic, OpenAI, Bedrock, Ollama, Browser variants, Mock
 ├── recorders/    — context, stream, agent, cost, skill, permission, eval, memory
-├── resilience/   — withRetry, withFallback, resilientProvider
+├── resilience/   — withRetry, withFallback, fallbackProvider, withCircuitBreaker
 └── stream.ts     — SSE formatter
 
-examples/        — 33 runnable end-to-end tests organized by DNA layer
+examples/        — runnable end-to-end tests organized by DNA layer
   ├── core/                — primitives
   ├── core-flow/           — compositions
   ├── patterns/            — canonical recipes
@@ -503,10 +524,8 @@ examples/        — 33 runnable end-to-end tests organized by DNA layer
 
 ## Roadmap (informs what to defer)
 
-- **v2.0 (current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + 6 providers + 33 examples
-- **v2.1** — RAG flavor (`defineRAG`) · Redis memory adapter · MCP integration · CircuitBreaker · 3-tier output fallback
-- **v2.2** — Governance (Policy + BudgetTracker) · DynamoDB / Postgres / Pinecone adapters
-- **v2.3** — Causal training-data exports (SFT / DPO / process-RL)
-- **v2.4+** — Deep Agents · A2A protocol · Lens UI integration
+- **v3.1 (current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + providers + RAG (`defineRAG`) + MCP (`mcpClient`) + Redis/AgentCore memory adapters + resilience (retry / fallback / circuit breaker) + Permission policy + observability subsystem
+- **Shipped since v2.0** — RAG flavor · Redis memory adapter · MCP integration · CircuitBreaker · governance (PermissionPolicy)
+- **Planned** — Causal training-data exports (SFT / DPO / process-RL) · DynamoDB / Postgres / Pinecone adapters · Deep Agents · A2A protocol · Lens UI integration
 
 When in doubt — read [`examples/`](examples/), every file is a runnable spec.

package/CLAUDE.md

@@ -54,7 +54,7 @@ await agent.run({ message: 'How long does a refund take?' });
 
 | Boundary | Mock for development | Production swap |
 |---|---|---|
-| LLM provider | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
+| LLM provider | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `anthropic()` · `openai()` · `bedrock()` · `ollama()` (from `agentfootprint/llm-providers`) |
 | Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder factory |
 | Memory store | `InMemoryStore` | `RedisStore` (`agentfootprint/memory-redis`) · `AgentCoreStore` (`agentfootprint/memory-agentcore`) · DynamoDB / Postgres / Pinecone (planned) |
 | MCP server | `mockMcpClient({ tools })` — in-memory, no SDK | `mcpClient({ transport })` to a real server |
@@ -148,7 +148,8 @@ agent.rag(docs);
 ### Agent (ReAct primitive)
 
 ```typescript
-import { Agent, defineTool, anthropic } from 'agentfootprint';
+import { Agent, defineTool } from 'agentfootprint';
+import { anthropic } from 'agentfootprint/llm-providers';
 
 const agent = Agent.create({
   provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
@@ -172,7 +173,8 @@ Builder methods:
 ### LLMCall (one-shot primitive)
 
 ```typescript
-import { LLMCall, anthropic } from 'agentfootprint';
+import { LLMCall } from 'agentfootprint';
+import { anthropic } from 'agentfootprint/llm-providers';
 
 const call = LLMCall.create({ provider: anthropic(...), model: 'claude-sonnet-4-5-20250929' })
   .system('You are a terse assistant.')
@@ -330,33 +332,35 @@ There is **no** `MultiAgentSystem` class. Multi-agent = compositions of single A
 ```typescript
 import { Sequence, Parallel, Conditional, Loop } from 'agentfootprint';
 
-// Output flows downstream
+// Output flows downstream — each step takes an id + a runner (Agent / LLMCall / runner)
 const pipeline = Sequence.create()
-  .step(researcher)        // each step is itself an Agent / LLMCall / runner
-  .step(writer)
-  .step(editor)
+  .step('research', researcher)
+  .step('write', writer)
+  .step('edit', editor)
   .build();
 
-// Multi-perspective with merge
+// Multi-perspective with LLM merge — each branch takes an id + a runner
 const tot = Parallel.create()
-  .branch(thoughtAgent)
-  .branch(thoughtAgent)
-  .branch(thoughtAgent)
-  .merge(rankerLLM)
+  .branch('t1', thoughtAgent)
+  .branch('t2', thoughtAgent)
+  .branch('t3', thoughtAgent)
+  .mergeWithLLM({ provider, model: 'claude-sonnet-4-5-20250929', prompt: 'Rank and synthesize.' })
   .build();
 
-// Predicate-based routing
+// Predicate-based routing — .when(id, predicate, runner); exactly one .otherwise(id, runner).
+// predicate receives ConditionalInput { message }.
 const triage = Conditional.create()
-  .when((ctx) => ctx.intent === 'billing', billingAgent)
-  .when((ctx) => ctx.intent === 'tech', techAgent)
-  .otherwise(generalAgent)
+  .when('billing', (input) => /refund|invoice/i.test(input.message), billingAgent)
+  .when('tech', (input) => /error|bug/i.test(input.message), techAgent)
+  .otherwise('general', generalAgent)
   .build();
 
-// Iterate with budget
+// Iterate with budget — .repeat(runner) sets the body, .times(n) caps iterations.
+// until() guard receives { iteration, latestOutput, startMs }.
 const refine = Loop.create()
-  .body(critiqueAgent)
-  .untilGuard((ctx) => ctx.qualityScore > 0.9)
-  .maxIterations(5)
+  .repeat(critiqueAgent)
+  .until((ctx) => /done/i.test(ctx.latestOutput))
+  .times(5)
   .build();
 ```
 
@@ -377,7 +381,8 @@ Browse [`examples/patterns/`](examples/patterns/) — every pattern is a runnabl
 ### Providers
 
 ```typescript
-import { anthropic, openai, bedrock, ollama, mock } from 'agentfootprint';
+import { mock } from 'agentfootprint';                          // zero-peer-dep, on the main barrel
+import { anthropic, openai, bedrock, ollama } from 'agentfootprint/llm-providers';  // vendor-SDK-backed
 
 // Adapter-swap testing: same agent, different provider, $0 in CI
 const provider = process.env.NODE_ENV === 'production'
@@ -385,7 +390,7 @@ const provider = process.env.NODE_ENV === 'production'
   : mock({ reply: 'test response' });
 ```
 
-Every provider implements the same `LLMProvider` interface. Browser variants exist for client-side use.
+Every provider implements the same `LLMProvider` interface. The vendor-SDK providers (`anthropic`, `openai`, `bedrock`, `ollama`, plus their `*Provider` classes) live ONLY at `agentfootprint/llm-providers` (legacy alias `agentfootprint/providers`) — kept off the main barrel so bundlers never walk the lazy peer-dep requires. The main barrel exports the zero-peer-dep providers: `mock`, `browserAnthropic`, `browserOpenai`, and `createProvider`.
 
 ### Pause / Resume (Human-in-the-Loop)
 
@@ -394,7 +399,12 @@ import { askHuman, pauseHere, isPaused } from 'agentfootprint';
 
 const approveTool = defineTool({
   schema: { name: 'approve', description: 'Ask a human.', inputSchema: { ... } },
-  execute: askHuman({ severity: 'high' }),
+  // askHuman()/pauseHere() THROW a PauseRequest — call them INSIDE execute,
+  // do not assign them as the execute function.
+  execute: async (args) => {
+    askHuman({ question: `Approve this action?`, risk: 'high' });
+    return ''; // unreachable — askHuman always throws
+  },
 });
 
 const result = await agent.run({ message: 'Refund $500?' });
@@ -408,14 +418,17 @@ if (isPaused(result)) {
 ### Resilience
 
 ```typescript
-import { withRetry, withFallback, resilientProvider } from 'agentfootprint';
+import { withRetry, withFallback, fallbackProvider } from 'agentfootprint/resilience';
+import { anthropic, openai, ollama } from 'agentfootprint/llm-providers';
 
-const reliable = withRetry(provider, { maxRetries: 3 });
+const reliable = withRetry(provider, { maxAttempts: 3 });
 const resilient = withFallback(primary, fallback);
-const chain = resilientProvider([anthropic({...}), openai({...}), ollama({...})]);
+const chain = fallbackProvider(anthropic({...}), openai({...}), ollama({...}));
 ```
 
-### Observability — 47 typed events × 13 domains
+Also available: `withCircuitBreaker(provider, opts?)`. The resilience decorators live ONLY at `agentfootprint/resilience` (not the main barrel).
+
+### Observability — 59 typed events × 16 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>
@@ -440,7 +453,7 @@ Recorders (auto-attached when relevant builder method is called):
 
 - ❌ **Don't ship a `ReflexionAgent` class.** Compose `Sequence(Agent, critique-LLM, Agent)`.
 - ❌ **Don't use `agent.run('string')`** — use `agent.run({ message: '...', identity? })`.
-- ❌ **Don't import from stale subpaths** like `'agentfootprint/instructions'`, `'agentfootprint/observe'`, `'agentfootprint/security'`. Top-level barrel covers it: `from 'agentfootprint'`.
+- ❌ **Don't import from removed subpaths** like `'agentfootprint/instructions'` — the injection factories are on the main barrel (or `'agentfootprint/injection-engine'`). NOTE: `'agentfootprint/observe'`, `'agentfootprint/security'`, `'agentfootprint/resilience'`, `'agentfootprint/llm-providers'` ARE real, current subpaths — some symbols (e.g. `buildStepGraph`, `extractSequence`, the resilience decorators, the vendor-SDK providers) are intentionally subpath-only, NOT on the main barrel.
 - ❌ **Don't use `.memoryPipeline(pipeline)`** — that's the v1 API. Use `.memory(defineMemory({...}))`.
 - ❌ **Don't fall back when TopK threshold returns nothing.** Strict semantics: garbage past context > none is wrong.
 - ❌ **Don't store closures or class instances in scope** — TransactionBuffer can't clone functions. Memory-store entries serialize to JSON.
@@ -472,9 +485,9 @@ Recorders (auto-attached when relevant builder method is called):
 
 ```bash
 npm install agentfootprint footprintjs
-npm test                           # vitest run — 1100+ tests
+npm test                           # vitest run — 2000+ tests
 npm run example examples/...       # run a single example end-to-end
-npm run examples:run-all           # run every example (33 of them)
+npm run test:examples              # typecheck + run every example end-to-end
 ```
 
 ## Package layout
@@ -489,10 +502,10 @@ src/
 ├── memory/       — defineMemory + 4 types × 7 strategies + InMemoryStore + Causal
 ├── adapters/llm/ — Anthropic, OpenAI, Bedrock, Ollama, Browser variants, Mock
 ├── recorders/    — context, stream, agent, cost, skill, permission, eval, memory
-├── resilience/   — withRetry, withFallback, resilientProvider
+├── resilience/   — withRetry, withFallback, fallbackProvider, withCircuitBreaker
 └── stream.ts     — SSE formatter
 
-examples/        — 33 runnable end-to-end tests organized by DNA layer
+examples/        — 47 runnable end-to-end tests organized by DNA layer
   ├── core/                — primitives
   ├── core-flow/           — compositions
   ├── patterns/            — canonical recipes
@@ -503,10 +516,7 @@ examples/        — 33 runnable end-to-end tests organized by DNA layer
 
 ## Roadmap (informs what to defer)
 
-- **v2.0 (current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + 6 providers + 33 examples
-- **v2.1** — RAG flavor (`defineRAG`) · Redis memory adapter · MCP integration · CircuitBreaker · 3-tier output fallback
-- **v2.2** — Governance (Policy + BudgetTracker) · DynamoDB / Postgres / Pinecone adapters
-- **v2.3** — Causal training-data exports (SFT / DPO / process-RL)
-- **v2.4+** — Deep Agents · A2A protocol · Lens UI integration
+- **Shipped (v3.x current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + providers (vendor-SDK + browser + mock) + RAG (`defineRAG`) + MCP (`mcpClient`) + Redis/AgentCore memory adapters + resilience (`withRetry` / `withFallback` / `fallbackProvider` / `withCircuitBreaker`) + reliability subsystem + governance (`PermissionPolicy`) + observability subpaths (`/observe`, `/thinking`, `/locales`, `/status`)
+- **Planned** — BudgetTracker · DynamoDB / Postgres / Pinecone memory adapters · Causal training-data exports (SFT / DPO / process-RL) · Deep Agents · A2A protocol · Lens UI integration
 
 When in doubt — read [`examples/`](examples/), every file is a runnable spec.

package/README.md

@@ -18,6 +18,8 @@
   <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <!-- coverage-badge --><img src="https://img.shields.io/badge/coverage-87%25-green.svg" alt="coverage: 87%"><!-- /coverage-badge -->
   <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
+  <a href="https://bundlephobia.com/package/agentfootprint"><img src="https://img.shields.io/bundlephobia/minzip/agentfootprint?label=minzipped" alt="minzipped size"></a>
+  <a href="#tree-shakeable--esm-first"><img src="https://img.shields.io/badge/tree--shakeable-%E2%9C%93-success?style=flat" alt="tree-shakeable"></a>
   <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
   <a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
 </p>
@@ -54,15 +56,15 @@ That's the whole model: `Injection = slot × trigger × cache`.
 
 ### The 4 triggers
 
-| Trigger | Flavor | Fires when | Builder example | Default slot |
+| Trigger | Flavor | Fires when | Illustration | Default slot |
 |---|---|---|---|---|
-| `always` | static | Every iteration | `.steering('You are a triage agent…')` | `system` |
-| `rule` | runtime — predicate | Your rule returns true | `.rag({ when: s => /price\|refund/.test(s.userQuery) })` | `messages` |
-| `on-tool-return` | runtime — lifecycle | After a specific tool returns | `.instruction({ after: 'search_db', text: 'Cite source IDs.' })` | `messages` |
-| `llm-activated` | runtime — agent-driven | LLM calls `read_skill('id')` | `.skill({ id: 'refund-policy', activatedBy: 'read_skill' })` | `messages` (body) |
+| `always` | static | Every iteration | `.steering(defineSteering({ id, prompt: 'You are a triage agent…' }))` | `system` |
+| `rule` | runtime — predicate | Your rule returns true | `.instruction(defineInstruction({ id, activeWhen: s => /price\|refund/.test(s.userQuery), prompt }))` | `system` |
+| `on-tool-return` | runtime — lifecycle | After a specific tool returns | `.instruction(defineInstruction({ id, slot: 'messages', activeWhen, prompt: 'Cite source IDs.' }))` | `messages` |
+| `llm-activated` | runtime — agent-driven | LLM calls `read_skill('id')` | `.skill(defineSkill({ id: 'refund-policy', description, body, viaToolName: 'read_skill' }))` | `messages` (body) |
 
 > [!NOTE]
-> Slot is a default, not a coupling — the same `Skill` can live in `tools` (schema only, discovered via `read_skill`), `messages` (body injected on activation), or `system` (baked into the prompt as steering).
+> The "Illustration" column shows the shape of each flavor — the typed builder methods (`.steering` / `.instruction` / `.skill` / `.fact` / `.rag`) take an `Injection` (or `MemoryDefinition` for `.rag`) produced by the matching `defineSteering` / `defineInstruction` / `defineSkill` / `defineFact` / `defineRAG` factory. Slot is a default, not a coupling — the same `Skill` can live in `tools` (schema only, discovered via `read_skill`), `messages` (body injected on activation), or `system` (baked into the prompt as steering).
 
 **3 slots × 4 triggers × N flavors = the entire context-engineering surface.**
 
@@ -204,8 +206,8 @@ const fan = Parallel.create()
 import { Conditional } from 'agentfootprint';
 
 const router = Conditional.create()
-  .when('billing', s => s.intent === 'billing', billingAgent)
-  .when('tech',    s => s.intent === 'tech',    techAgent)
+  .when('billing', s => /bill|invoice|refund/.test(s.message), billingAgent)
+  .when('tech',    s => /error|bug|crash/.test(s.message),     techAgent)
   .otherwise('default', defaultAgent)
   .build();
 ```
@@ -227,7 +229,7 @@ import { Loop } from 'agentfootprint';
 
 const reflexion = Loop.create()
   .repeat(thinkAgent)
-  .until(s => s.satisfied)
+  .until(({ latestOutput }) => latestOutput.includes('DONE'))
   .build();
 ```
 
@@ -270,7 +272,8 @@ Pick the flows that match your problem. Chain them. **That's your Agentic Applic
 ```typescript
 const research = Loop.create()
   .repeat(Sequence.create().step('plan', plan).step('search', searchAll).build())
-  .until(s => s.satisfied).build();
+  .until(({ iteration, latestOutput }) => iteration >= 3 || latestOutput.includes('DONE'))
+  .build();
 ```
 
 Same `.create().method().build()` shape as the four rows above — just composed.
@@ -367,7 +370,7 @@ const result = await agent.run({ message: 'Weather in Paris?' });
 console.log(result);  // → "I checked: it is 72°F and sunny."
 ```
 
-Swap `mock(...)` for `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)` for production. Nothing else changes.
+For production, import a real provider from `agentfootprint/llm-providers` and swap it in — `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)`. Only the import line changes; the agent code stays the same. (The vendor-SDK providers live on the `agentfootprint/llm-providers` subpath so the main `agentfootprint` barrel stays free of optional peer-dep requires; `mock`, `browserAnthropic`, and `browserOpenai` are on the main barrel.)
 
 ---
 
@@ -393,7 +396,7 @@ The flowchart, recorders, and tests don't change between dev and prod.
 - 4 control flows — `Sequence`, `Parallel`, `Conditional`, `Loop`
 - 1 Injection primitive — `defineSkill` / `defineSteering` / `defineInstruction` / `defineFact`
 - 1 reliability gate — `.reliability({ preCheck, postDecide, providers, circuitBreaker, fallback })`
-- 1 tool dispatch primitive — `ToolProvider` (sync OR async) — `staticTools` · `gatedTools` · `skillScopedTools` · custom `discoveryProvider` over hubs / MCP / per-tenant catalogs
+- 1 tool dispatch primitive — `ToolProvider` (sync OR async) — `staticTools` · `gatedTools` · `skillScopedTools` · or a custom `ToolProvider` that discovers over hubs / MCP / per-tenant catalogs
 
 **LLM providers** (7)
 
@@ -441,6 +444,18 @@ Or jump into the [examples gallery](https://github.com/footprintjs/agentfootprin
 
 ---
 
+## Tree-shakeable & ESM-first
+
+Import one thing, ship one thing. agentfootprint is built so your bundle grows only with what you actually use:
+
+- **Dual build, true ESM.** Ships CommonJS (`require`) **and** real ECMAScript Modules (`import`) with TypeScript types. The ESM build is `type:module` with explicit `.js` import extensions, so it loads as true ESM under Node, Vite, Next, Deno, and Bun — no shims.
+- **Per-file modules + honest `sideEffects`.** The dist is emitted file-by-file (never pre-bundled), so bundlers drop every export you don't touch. A small `import { defineTool }` doesn't pull in the Agent runtime, injection engine, memory stores, or LLM providers.
+- **Subpath exports + lazy peer-deps.** Heavyweight integrations live behind their own subpaths and load their SDK **only when you instantiate them** — importing agentfootprint never bundles `@anthropic-ai/sdk`, `ioredis`, the AWS SDKs, or the MCP SDK unless you actually use that adapter.
+
+**Proven, not promised.** A CI smoke test bundles a minimal `import { defineTool }` and asserts the Agent runtime, injection engine, memory stores, and providers are pruned; a second test loads the main barrel and every subpath as true ESM and verifies the lazy-adapter loader works under ESM (`createRequire`, not a bare `require`). See [`test/esm-packaging.test.ts`](test/esm-packaging.test.ts).
+
+---
+
 ## Built on
 
 [footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. agentfootprint's decision-evidence capture, narrative recording, and time-travel checkpointing are footprintjs primitives at the runtime layer.

package/dist/adapters/llm/createProvider.js

@@ -9,11 +9,12 @@
  * Emits:   N/A.
  *
  * @example
+ *   const kind = (process.env.LLM_PROVIDER ?? 'anthropic') as ProviderKind;
  *   const provider = createProvider({
- *     kind: process.env.LLM_PROVIDER ?? 'mock',
+ *     kind,
  *     apiKey: process.env.LLM_API_KEY,
  *     defaultModel: process.env.LLM_MODEL,
- *   });
+ *   } as CreateProviderOptions);
  *
  * For provider-specific options (Bedrock region, Ollama host, Browser
  * apiUrl, etc.) construct the underlying factory directly — this

package/dist/adapters/llm/createProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"createProvider.js","sourceRoot":"","sources":["../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAGH,uDAAmE;AACnE,iEAAkF;AAClF,2DAAiF;AACjF,6DAA4E;AAC5E,+EAGuC;AACvC,yEAA8F;AA2B9F;;GAEG;AACH,SAAgB,cAAc,CAAC,OAA8B;IAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAA,sBAAI,EAAC,OAAO,CAAC,CAAC;QACvB,KAAK,WAAW;YACd,OAAO,IAAA,gCAAS,EAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,IAAA,4BAAO,EAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,mBAAmB;YACtB,OAAO,IAAA,8CAAgB,EAAC,OAAO,CAAC,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,IAAA,wCAAa,EAAC,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC;YACR,sEAAsE;YACtE,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAE,WAAgC,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAxBD,wCAwBC"}
+{"version":3,"file":"createProvider.js","sourceRoot":"","sources":["../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAGH,uDAAmE;AACnE,iEAAkF;AAClF,2DAAiF;AACjF,6DAA4E;AAC5E,+EAGuC;AACvC,yEAA8F;AA2B9F;;GAEG;AACH,SAAgB,cAAc,CAAC,OAA8B;IAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAA,sBAAI,EAAC,OAAO,CAAC,CAAC;QACvB,KAAK,WAAW;YACd,OAAO,IAAA,gCAAS,EAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,IAAA,4BAAO,EAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,mBAAmB;YACtB,OAAO,IAAA,8CAAgB,EAAC,OAAO,CAAC,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,IAAA,wCAAa,EAAC,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC;YACR,sEAAsE;YACtE,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAE,WAAgC,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAxBD,wCAwBC"}

package/dist/adapters/observability/agentcore.js

@@ -42,6 +42,7 @@
  * @example Test injection (skip SDK require entirely)
  * ```ts
  * agentcoreObservability({
+ *   logGroupName: '/agentfootprint/test',
  *   _client: {
  *     putLogEvents: async (input) => { capturedBatches.push(input); },
  *   },

package/dist/adapters/observability/agentcore.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;;;AAIH,mDAGyB;AAWzB;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,IAAmC;IACxE,OAAO,IAAA,6CAA6B,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC;AAFD,wDAEC"}
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;;AAIH,mDAGyB;AAWzB;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,IAAmC;IACxE,OAAO,IAAA,6CAA6B,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC;AAFD,wDAEC"}

package/dist/core/flowchartAsTool.js

@@ -38,13 +38,13 @@
  *
  * @example  Single-stage flowchart as a tool
  *   import { flowChart } from 'footprintjs';
- *   import { flowchartAsTool } from 'agentfootprint';
+ *   import { Agent, flowchartAsTool } from 'agentfootprint';
  *
- *   const refundChart = flowChart<{ orderId: string; reason: string }>(
+ *   const refundChart = flowChart<{ refundId: string }>(
  *     'RefundFlow',
  *     async (scope) => {
- *       const refundId = await refundService.process(scope.$getArgs().orderId);
- *       scope.refundId = refundId;
+ *       const args = scope.$getArgs<{ orderId: string; reason: string }>();
+ *       scope.refundId = await refundService.process(args.orderId);
  *     },
  *     'refund-flow',
  *   ).build();
@@ -65,7 +65,7 @@
  *       JSON.stringify({ refundId: snapshot.values.refundId, status: 'processed' }),
  *   });
  *
- *   agent.tool(refundTool);
+ *   const agent = Agent.create({ provider }).tool(refundTool).build();
  *
  * @example  Multi-stage flowchart with decide() + recorders
  *   const triageChart = flowChart<TriageState>('Triage', validateInput, 'validate')

package/dist/esm/adapters/llm/createProvider.js

@@ -8,11 +8,12 @@
  * Emits:   N/A.
  *
  * @example
+ *   const kind = (process.env.LLM_PROVIDER ?? 'anthropic') as ProviderKind;
  *   const provider = createProvider({
- *     kind: process.env.LLM_PROVIDER ?? 'mock',
+ *     kind,
  *     apiKey: process.env.LLM_API_KEY,
  *     defaultModel: process.env.LLM_MODEL,
- *   });
+ *   } as CreateProviderOptions);
  *
  * For provider-specific options (Bedrock region, Ollama host, Browser
  * apiUrl, etc.) construct the underlying factory directly — this

package/dist/esm/adapters/llm/createProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"createProvider.js","sourceRoot":"","sources":["../../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,IAAI,EAA4B,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAiC,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,EAA8B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,OAAO,EAA+B,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EACL,gBAAgB,GAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAqC,MAAM,4BAA4B,CAAC;AA2B9F;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,KAAK,WAAW;YACd,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,mBAAmB;YACtB,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC;YACR,sEAAsE;YACtE,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAE,WAAgC,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"createProvider.js","sourceRoot":"","sources":["../../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,IAAI,EAA4B,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAiC,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,EAA8B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,OAAO,EAA+B,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EACL,gBAAgB,GAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAqC,MAAM,4BAA4B,CAAC;AA2B9F;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,KAAK,WAAW;YACd,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,mBAAmB;YACtB,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC;YACR,sEAAsE;YACtE,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAE,WAAgC,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/esm/adapters/observability/agentcore.js

@@ -41,6 +41,7 @@
  * @example Test injection (skip SDK require entirely)
  * ```ts
  * agentcoreObservability({
+ *   logGroupName: '/agentfootprint/test',
  *   _client: {
  *     putLogEvents: async (input) => { capturedBatches.push(input); },
  *   },

package/dist/esm/adapters/observability/agentcore.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,EACL,6BAA6B,GAE9B,MAAM,iBAAiB,CAAC;AAWzB;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmC;IACxE,OAAO,6BAA6B,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,EACL,6BAA6B,GAE9B,MAAM,iBAAiB,CAAC;AAWzB;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmC;IACxE,OAAO,6BAA6B,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC"}

package/dist/esm/core/flowchartAsTool.js

@@ -37,13 +37,13 @@
  *
  * @example  Single-stage flowchart as a tool
  *   import { flowChart } from 'footprintjs';
- *   import { flowchartAsTool } from 'agentfootprint';
+ *   import { Agent, flowchartAsTool } from 'agentfootprint';
  *
- *   const refundChart = flowChart<{ orderId: string; reason: string }>(
+ *   const refundChart = flowChart<{ refundId: string }>(
  *     'RefundFlow',
  *     async (scope) => {
- *       const refundId = await refundService.process(scope.$getArgs().orderId);
- *       scope.refundId = refundId;
+ *       const args = scope.$getArgs<{ orderId: string; reason: string }>();
+ *       scope.refundId = await refundService.process(args.orderId);
  *     },
  *     'refund-flow',
  *   ).build();
@@ -64,7 +64,7 @@
  *       JSON.stringify({ refundId: snapshot.values.refundId, status: 'processed' }),
  *   });
  *
- *   agent.tool(refundTool);
+ *   const agent = Agent.create({ provider }).tool(refundTool).build();
  *
  * @example  Multi-stage flowchart with decide() + recorders
  *   const triageChart = flowChart<TriageState>('Triage', validateInput, 'validate')