agentfootprint 1.22.0 → 2.0.1

package/ai-instructions/clinerules

@@ -1,84 +1,159 @@
 # agentfootprint — Cline Rules
 
-The explainable agent framework. Every agent is a footprintjs flowchart with auto-generated causal traces.
+Building Generative AI applications is mostly **context engineering** — deciding what content lands in which slot of the LLM call, when, and why. agentfootprint exposes this discipline through 2 primitives + 3 compositions + 1 unifying injection primitive + 1 memory factory.
 
-## Core Principle
-
-**Every concept is a flowchart. Collect during traversal, never post-process.**
-
-## 5 Concepts
+## Core API (use these, not v1 names)
 
 ```typescript
-// 1. LLMCall — single call, no tools, no loop
-LLMCall.create({ provider }).system('...').recorder(rec).build()
-
-// 2. Agent — ReAct agent with tools + loop
-Agent.create({ provider, name? }).system('...').tool(t).maxIterations(n).recorder(rec).build()
+import {
+  Agent, LLMCall, defineTool,
+  Sequence, Parallel, Conditional, Loop,
+  defineSkill, defineSteering, defineInstruction, defineFact,
+  defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, SNAPSHOT_PROJECTIONS,
+  InMemoryStore, mockEmbedder,
+  anthropic, openai, bedrock, ollama, mock,
+  askHuman, pauseHere, isPaused,
+  withRetry, withFallback, resilientProvider,
+} from 'agentfootprint';
+```
 
-// 3. RAG — retrieve-augment-generate
-RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
+**Top-level barrel only.** Don't import from stale subpaths like
+`agentfootprint/instructions`, `agentfootprint/observe`,
+`agentfootprint/security`, `agentfootprint/explain`.
 
-// 4. FlowChart — sequential multi-agent
-FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+## The 6-layer mental model
 
-// 5. Swarm — LLM-routed multi-agent
-Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
+```
+2 primitives        : LLMCall · Agent (= ReAct)
+3 compositions+Loop : Sequence · Parallel · Conditional · Loop
+N patterns          : ReAct · Reflexion · ToT · MapReduce · Debate · Swarm
+                      (RECIPES, not classes)
+Context engineering : defineSkill · defineSteering · defineInstruction · defineFact
+Memory              : defineMemory({type, strategy, store}) — 4 types × 7 strategies
+Production features : pause/resume · cost · permissions · observability · events
 ```
 
-## Tools
+## Three slots of the LLM API call
 
-```typescript
-import { defineTool } from 'agentfootprint';
-defineTool({ id, description, inputSchema, handler })
-```
+Every "agent feature" is content flowing into one of:
 
-## Recorders
+- `system` prompt — Steering / Instruction / Skill body / Fact / formatted memory
+- `messages` array — history / RAG / memory replay / injected instructions
+- `tools` array — Tool schemas (registered + Skill-attached)
 
-```typescript
-import { TokenRecorder, CostRecorder, TurnRecorder, ToolUsageRecorder,
-         QualityRecorder, GuardrailRecorder, CompositeRecorder } from 'agentfootprint';
-// Attach via .recorder(rec) on any builder
-```
+## Canonical examples
 
-## Providers
+### Hello agent
 
 ```typescript
-import { mock, mockRetriever, createProvider, anthropic, openai } from 'agentfootprint';
+const agent = Agent.create({
+  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+  model: 'claude-sonnet-4-5-20250929',
+})
+  .system('You are a helpful assistant.')
+  .tool(weatherTool)
+  .build();
+
+const result = await agent.run({ message: 'Weather in SF?' });
+```
 
-// Testing
-mock([{ content: 'Hi' }])
-mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }])
+### Tools
 
-// Production
-createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }))
+```typescript
+const weather = defineTool({
+  schema: {
+    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`,
+});
 ```
 
-## Prompt & Tool Providers
+### Context engineering
 
 ```typescript
-import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
-import { agentAsTool, compositeTools, mcpToolProvider, a2aRunner } from 'agentfootprint';
+const tone = defineSteering({ id: 'tone', prompt: 'Be friendly.' });
+const urgent = defineInstruction({
+  id: 'urgent',
+  activeWhen: (ctx) => /urgent/i.test(ctx.userMessage),
+  prompt: 'Prioritize the fastest path.',
+});
+const billing = defineSkill({
+  id: 'billing',
+  description: 'Use for refunds.',
+  body: 'Confirm identity first.',
+  tools: [refundTool],
+});
+const userProfile = defineFact({ id: 'user', data: 'Alice, Pro plan.' });
+
+agent.steering(tone).instruction(urgent).skill(billing).fact(userProfile);
 ```
 
-## Compositions
+### Memory
 
 ```typescript
-import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+const memory = defineMemory({
+  id: 'short-term',
+  type: MEMORY_TYPES.EPISODIC,
+  strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+  store: new InMemoryStore(),
+});
+
+agent.memory(memory);
+
+await agent.run({
+  message: '...',
+  identity: { tenant: 'acme', principal: 'alice', conversationId: 'thread-42' },
+});
 ```
 
-## Runner API (all concepts)
+Types: `EPISODIC` · `SEMANTIC` · `NARRATIVE` · `CAUSAL` (snapshot replay ⭐).
+Strategies: `WINDOW` · `BUDGET` · `SUMMARIZE` · `TOP_K` · `EXTRACT` · `DECAY` · `HYBRID`.
+
+### Multi-agent via control flow (no `MultiAgentSystem` class)
 
 ```typescript
-runner.run(message, { signal?, timeoutMs? })
-runner.getNarrative()        // causal trace
-runner.getSnapshot()         // memory state
-runner.getSpec()             // flowchart spec
-runner.toFlowChart()         // for subflow composition
+const pipeline = Sequence.create()
+  .step(researcher).step(writer).step(editor)
+  .build();
+
+const tot = Parallel.create()
+  .branch(thoughtAgent).branch(thoughtAgent).branch(thoughtAgent)
+  .merge(rankerLLM)
+  .build();
 ```
 
-## Rules
-
-- Never post-process — use recorders
-- Use `mock([...])` in tests
-- Use concept builders, not raw stages
-- Use `FlowChart`/`Swarm` for multi-agent
+## Anti-patterns — Don't
+
+- ❌ `agent.run('string')` → use `agent.run({ message: '...', identity? })`
+- ❌ Stale subpaths: `agentfootprint/instructions`, `agentfootprint/observe`, `agentfootprint/security`
+- ❌ `.memoryPipeline(pipeline)` (v1) → use `.memory(defineMemory({...}))`
+- ❌ Shipping a `ReflexionAgent` class → compose `Sequence(Agent, critique-LLM, Agent)`
+- ❌ Closures or class instances in scope (can't be cloned)
+- ❌ Falling back when TopK threshold returns nothing (strict semantics)
+
+## Decision tree
+
+| Goal | Use |
+|---|---|
+| One-shot LLM call | `LLMCall` |
+| Loop with tools | `Agent` |
+| Two LLM calls in series | `Sequence` |
+| Multiple critics → merge | `Parallel` |
+| Route by intent | `Conditional` |
+| Iterate until quality bar | `Loop` |
+| Output format / persona / safety | `defineSteering` |
+| Rule-gated context | `defineInstruction` |
+| LLM-activated body + tools | `defineSkill` |
+| User profile / env data | `defineFact` |
+| Last N turns | `defineMemory({ type: EPISODIC, strategy: WINDOW })` |
+| Vector retrieval | `defineMemory({ type: SEMANTIC, strategy: TOP_K })` |
+| Cross-run "why?" replay | `defineMemory({ type: CAUSAL, strategy: TOP_K })` |
+| Long convo overflow | `defineMemory({ type: EPISODIC, strategy: SUMMARIZE })` |
+
+When in doubt — read [`examples/`](examples/) (33 runnable specs).

package/ai-instructions/copilot-instructions.md

@@ -1,108 +1,159 @@
-# agentfootprint — Copilot Instructions
+# agentfootprint — GitHub Copilot Instructions
 
-The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.
+Building Generative AI applications is mostly **context engineering** — deciding what content lands in which slot of the LLM call, when, and why. agentfootprint exposes this discipline through 2 primitives + 3 compositions + 1 unifying injection primitive + 1 memory factory.
 
-## What It Does
+## Core API (use these, not v1 names)
 
-Every agent is a footprintjs flowchart. Every LLM call, tool use, and decision auto-generates a causal trace. LLMs read the trace for grounded explanations.
+```typescript
+import {
+  Agent, LLMCall, defineTool,
+  Sequence, Parallel, Conditional, Loop,
+  defineSkill, defineSteering, defineInstruction, defineFact,
+  defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, SNAPSHOT_PROJECTIONS,
+  InMemoryStore, mockEmbedder,
+  anthropic, openai, bedrock, ollama, mock,
+  askHuman, pauseHere, isPaused,
+  withRetry, withFallback, resilientProvider,
+} from 'agentfootprint';
+```
 
-## Core Principle
+**Top-level barrel only.** Don't import from stale subpaths like
+`agentfootprint/instructions`, `agentfootprint/observe`,
+`agentfootprint/security`, `agentfootprint/explain`.
 
-**Every concept is a flowchart. Collect during traversal, never post-process.**
+## The 6-layer mental model
 
-## 5 Concepts (Builder → Runner)
+```
+2 primitives        : LLMCall · Agent (= ReAct)
+3 compositions+Loop : Sequence · Parallel · Conditional · Loop
+N patterns          : ReAct · Reflexion · ToT · MapReduce · Debate · Swarm
+                      (RECIPES, not classes)
+Context engineering : defineSkill · defineSteering · defineInstruction · defineFact
+Memory              : defineMemory({type, strategy, store}) — 4 types × 7 strategies
+Production features : pause/resume · cost · permissions · observability · events
+```
 
-```typescript
-// 1. LLMCall — single LLM call, no tools, no loop
-LLMCall.create({ provider }).system('...').recorder(rec).build()
-// Flowchart: SeedScope → CallLLM → ParseResponse → Finalize
+## Three slots of the LLM API call
 
-// 2. Agent — ReAct agent with tools + loop
-Agent.create({ provider, name? }).system('...').tool(t).maxIterations(n).recorder(rec).build()
-// Flowchart: SeedScope → PromptAssembly → CallLLM → ParseResponse → HandleResponse → loopTo
+Every "agent feature" is content flowing into one of:
 
-// 3. RAG — retrieve-augment-generate
-RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
-// Flowchart: SeedScope → Retrieve → AugmentPrompt → CallLLM → ParseResponse → Finalize
+- `system` prompt — Steering / Instruction / Skill body / Fact / formatted memory
+- `messages` array — history / RAG / memory replay / injected instructions
+- `tools` array — Tool schemas (registered + Skill-attached)
 
-// 4. FlowChart — sequential multi-agent pipeline
-FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+## Canonical examples
 
-// 5. Swarm — LLM-routed multi-agent handoff
-Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
-```
-
-## Tools
+### Hello agent
 
 ```typescript
-import { defineTool } from 'agentfootprint';
-const tool = defineTool({
-  id: 'search',
-  description: 'Search the web',
-  inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
-  handler: async (args) => `Results for: ${args.query}`,
-});
+const agent = Agent.create({
+  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+  model: 'claude-sonnet-4-5-20250929',
+})
+  .system('You are a helpful assistant.')
+  .tool(weatherTool)
+  .build();
+
+const result = await agent.run({ message: 'Weather in SF?' });
 ```
 
-## Recorders
+### Tools
 
 ```typescript
-import { TokenRecorder, CostRecorder, TurnRecorder, ToolUsageRecorder,
-         QualityRecorder, GuardrailRecorder, CompositeRecorder } from 'agentfootprint';
-
-const tokens = new TokenRecorder();
-const cost = new CostRecorder();
-const composite = new CompositeRecorder([tokens, cost]);
-
-// Attach via .recorder(rec) on any concept builder
-// Read after execution: tokens.getStats(), cost.getTotalCost()
+const weather = defineTool({
+  schema: {
+    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`,
+});
 ```
 
-## Providers
+### Context engineering
 
 ```typescript
-import { mock, mockRetriever, createProvider, anthropic, openai } from 'agentfootprint';
-
-// Testing
-const provider = mock([{ content: 'Hello' }]);
-const retriever = mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }]);
+const tone = defineSteering({ id: 'tone', prompt: 'Be friendly.' });
+const urgent = defineInstruction({
+  id: 'urgent',
+  activeWhen: (ctx) => /urgent/i.test(ctx.userMessage),
+  prompt: 'Prioritize the fastest path.',
+});
+const billing = defineSkill({
+  id: 'billing',
+  description: 'Use for refunds.',
+  body: 'Confirm identity first.',
+  tools: [refundTool],
+});
+const userProfile = defineFact({ id: 'user', data: 'Alice, Pro plan.' });
 
-// Production
-const claude = createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }));
+agent.steering(tone).instruction(urgent).skill(billing).fact(userProfile);
 ```
 
-## Prompt Providers
+### Memory
 
 ```typescript
-import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
-```
+const memory = defineMemory({
+  id: 'short-term',
+  type: MEMORY_TYPES.EPISODIC,
+  strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+  store: new InMemoryStore(),
+});
 
-## Tool Providers & Protocol Adapters
+agent.memory(memory);
 
-```typescript
-import { agentAsTool, compositeTools, mcpToolProvider, a2aRunner } from 'agentfootprint';
+await agent.run({
+  message: '...',
+  identity: { tenant: 'acme', principal: 'alice', conversationId: 'thread-42' },
+});
 ```
 
-## Compositions (Resilience)
+Types: `EPISODIC` · `SEMANTIC` · `NARRATIVE` · `CAUSAL` (snapshot replay ⭐).
+Strategies: `WINDOW` · `BUDGET` · `SUMMARIZE` · `TOP_K` · `EXTRACT` · `DECAY` · `HYBRID`.
 
-```typescript
-import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
-```
-
-## Runner API (all concepts)
+### Multi-agent via control flow (no `MultiAgentSystem` class)
 
 ```typescript
-runner.run(message, { signal?, timeoutMs? })
-runner.getNarrative()           // causal trace
-runner.getSnapshot()            // memory state
-runner.getSpec()                // flowchart spec
-runner.toFlowChart()            // for subflow composition
+const pipeline = Sequence.create()
+  .step(researcher).step(writer).step(editor)
+  .build();
+
+const tot = Parallel.create()
+  .branch(thoughtAgent).branch(thoughtAgent).branch(thoughtAgent)
+  .merge(rankerLLM)
+  .build();
 ```
 
-## Rules
-
-- Never post-process — use recorders to collect data during traversal
-- Always use `mock([...])` in tests — no API keys in test suites
-- Use concept builders (`Agent.create()`, etc.) not raw stages
-- Use `FlowChart`/`Swarm` for multi-agent, not flat stages
-- Attach recorders via `.recorder(rec)` on builders
+## Anti-patterns — Don't
+
+- ❌ `agent.run('string')` → use `agent.run({ message: '...', identity? })`
+- ❌ Stale subpaths: `agentfootprint/instructions`, `agentfootprint/observe`, `agentfootprint/security`
+- ❌ `.memoryPipeline(pipeline)` (v1) → use `.memory(defineMemory({...}))`
+- ❌ Shipping a `ReflexionAgent` class → compose `Sequence(Agent, critique-LLM, Agent)`
+- ❌ Closures or class instances in scope (can't be cloned)
+- ❌ Falling back when TopK threshold returns nothing (strict semantics)
+
+## Decision tree
+
+| Goal | Use |
+|---|---|
+| One-shot LLM call | `LLMCall` |
+| Loop with tools | `Agent` |
+| Two LLM calls in series | `Sequence` |
+| Multiple critics → merge | `Parallel` |
+| Route by intent | `Conditional` |
+| Iterate until quality bar | `Loop` |
+| Output format / persona / safety | `defineSteering` |
+| Rule-gated context | `defineInstruction` |
+| LLM-activated body + tools | `defineSkill` |
+| User profile / env data | `defineFact` |
+| Last N turns | `defineMemory({ type: EPISODIC, strategy: WINDOW })` |
+| Vector retrieval | `defineMemory({ type: SEMANTIC, strategy: TOP_K })` |
+| Cross-run "why?" replay | `defineMemory({ type: CAUSAL, strategy: TOP_K })` |
+| Long convo overflow | `defineMemory({ type: EPISODIC, strategy: SUMMARIZE })` |
+
+When in doubt — read [`examples/`](examples/) (33 runnable specs).