agentfootprint 1.0.0

package/ai-instructions/copilot-instructions.md

@@ -0,0 +1,109 @@
+# agentfootprint — Copilot Instructions
+
+The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.
+
+## What It Does
+
+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.
+
+## Core Principle
+
+**Every concept is a flowchart. Collect during traversal, never post-process.**
+
+## 5 Concepts (Builder → Runner)
+
+```typescript
+// 1. LLMCall — single LLM call, no tools, no loop
+LLMCall.create({ provider }).system('...').recorder(rec).build()
+// Flowchart: SeedScope → CallLLM → ParseResponse → Finalize
+
+// 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
+
+// 3. RAG — retrieve-augment-generate
+RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
+// Flowchart: SeedScope → Retrieve → AugmentPrompt → CallLLM → ParseResponse → Finalize
+
+// 4. FlowChart — sequential multi-agent pipeline
+FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+
+// 5. Swarm — LLM-routed multi-agent handoff
+Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
+```
+
+## Tools
+
+```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}`,
+});
+```
+
+## Recorders
+
+```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()
+```
+
+## Providers
+
+```typescript
+import { mock, mockRetriever, createProvider, anthropic, openai } from 'agentfootprint';
+
+// Testing
+const provider = mock([{ content: 'Hello' }]);
+const retriever = mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }]);
+
+// Production
+const claude = createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }));
+```
+
+## Prompt Providers
+
+```typescript
+import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
+```
+
+## Tool Providers & Protocol Adapters
+
+```typescript
+import { agentAsTool, compositeTools, mcpToolProvider, a2aRunner } from 'agentfootprint';
+```
+
+## Compositions (Resilience)
+
+```typescript
+import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+```
+
+## Runner API (all concepts)
+
+```typescript
+runner.run(message, { signal?, timeoutMs? })
+runner.getNarrative()           // causal trace
+runner.getSnapshot()            // memory state
+runner.getSpec()                // flowchart spec
+runner.toFlowChart()            // for subflow composition
+```
+
+## Rules
+
+- Never use `CostRecorderV2` — use `CostRecorder`
+- 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

package/ai-instructions/cursor/agentfootprint.md

@@ -0,0 +1,101 @@
+# agentfootprint — Cursor Rules
+
+The explainable agent framework. Every agent is a footprintjs flowchart with auto-generated causal traces.
+
+## Core Principle
+
+**Every concept is a flowchart. Collect during traversal, never post-process.**
+
+## 5 Concepts
+
+```typescript
+// 1. LLMCall — single LLM 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()
+
+// 3. RAG — retrieve-augment-generate
+RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
+
+// 4. FlowChart — sequential multi-agent pipeline
+FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+
+// 5. Swarm — LLM-routed multi-agent handoff
+Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
+```
+
+## Tools
+
+```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}`,
+});
+```
+
+## Recorders (AgentRecorder interface)
+
+```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 builder
+```
+
+## Providers & Testing
+
+```typescript
+import { mock, mockRetriever, createProvider, anthropic } from 'agentfootprint';
+
+// Testing — no API keys needed
+const provider = mock([{ content: 'Hello' }]);
+const retriever = mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }]);
+
+// Production
+const claude = createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }));
+```
+
+## Prompt Providers
+
+```typescript
+import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
+```
+
+## Tool Providers
+
+```typescript
+import { agentAsTool, compositeTools, mcpToolProvider } from 'agentfootprint';
+```
+
+## Compositions (Resilience)
+
+```typescript
+import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+```
+
+## Runner API (all concepts)
+
+```typescript
+runner.run(message, { signal?, timeoutMs? })
+runner.getNarrative()           // causal trace
+runner.getSnapshot()            // full memory state
+runner.getSpec()                // flowchart spec for visualization
+runner.toFlowChart()            // expose for subflow composition
+```
+
+## Rules
+
+- Never use `CostRecorderV2` — use `CostRecorder`
+- Never post-process — use recorders
+- Always use `mock([...])` in tests — no API keys
+- Use concept builders, not raw stages
+- Use `FlowChart`/`Swarm` for multi-agent, not flat stages
+- Attach recorders via `.recorder(rec)` on builders

package/ai-instructions/kiro/agentfootprint.md

@@ -0,0 +1,101 @@
+# agentfootprint — Kiro Rules
+
+The explainable agent framework. Every agent is a footprintjs flowchart with auto-generated causal traces.
+
+## Core Principle
+
+**Every concept is a flowchart. Collect during traversal, never post-process.**
+
+## 5 Concepts
+
+```typescript
+// 1. LLMCall — single LLM 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()
+
+// 3. RAG — retrieve-augment-generate
+RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
+
+// 4. FlowChart — sequential multi-agent pipeline
+FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+
+// 5. Swarm — LLM-routed multi-agent handoff
+Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
+```
+
+## Tools
+
+```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}`,
+});
+```
+
+## Recorders (AgentRecorder interface)
+
+```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 builder
+```
+
+## Providers & Testing
+
+```typescript
+import { mock, mockRetriever, createProvider, anthropic } from 'agentfootprint';
+
+// Testing — no API keys needed
+const provider = mock([{ content: 'Hello' }]);
+const retriever = mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }]);
+
+// Production
+const claude = createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }));
+```
+
+## Prompt Providers
+
+```typescript
+import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
+```
+
+## Tool Providers
+
+```typescript
+import { agentAsTool, compositeTools, mcpToolProvider } from 'agentfootprint';
+```
+
+## Compositions (Resilience)
+
+```typescript
+import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+```
+
+## Runner API (all concepts)
+
+```typescript
+runner.run(message, { signal?, timeoutMs? })
+runner.getNarrative()           // causal trace
+runner.getSnapshot()            // full memory state
+runner.getSpec()                // flowchart spec for visualization
+runner.toFlowChart()            // expose for subflow composition
+```
+
+## Rules
+
+- Never use `CostRecorderV2` — use `CostRecorder`
+- Never post-process — use recorders
+- Always use `mock([...])` in tests — no API keys
+- Use concept builders, not raw stages
+- Use `FlowChart`/`Swarm` for multi-agent, not flat stages
+- Attach recorders via `.recorder(rec)` on builders

package/ai-instructions/setup.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# agentfootprint — AI coding tool setup
+# Installs instruction files for your preferred AI coding assistant.
+#
+# Usage:
+#   npx agentfootprint-setup          (after npm install agentfootprint)
+#   bash node_modules/agentfootprint/ai-instructions/setup.sh
+
+set -euo pipefail
+
+PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(pwd)"
+
+echo ""
+echo "  agentfootprint — AI Coding Tool Setup"
+echo "  ──────────────────────────────────────"
+echo ""
+echo "  This will copy instruction files so your AI coding"
+echo "  assistant understands the agentfootprint API."
+echo ""
+
+install_claude_code() {
+  mkdir -p "$PROJECT_DIR/.claude/skills/agentfootprint"
+  cp "$PKG_DIR/claude-code/SKILL.md" "$PROJECT_DIR/.claude/skills/agentfootprint/SKILL.md"
+  # Also copy CLAUDE.md to project root if not present
+  if [ ! -f "$PROJECT_DIR/CLAUDE.md" ]; then
+    cp "$PKG_DIR/../CLAUDE.md" "$PROJECT_DIR/CLAUDE.md" 2>/dev/null || true
+  fi
+  echo "  [ok] Claude Code — .claude/skills/agentfootprint/SKILL.md"
+}
+
+install_codex() {
+  if [ ! -f "$PROJECT_DIR/AGENTS.md" ]; then
+    cp "$PKG_DIR/../AGENTS.md" "$PROJECT_DIR/AGENTS.md" 2>/dev/null || true
+    echo "  [ok] OpenAI Codex — AGENTS.md"
+  else
+    echo "  [skip] AGENTS.md already exists"
+  fi
+}
+
+install_copilot() {
+  mkdir -p "$PROJECT_DIR/.github"
+  if [ ! -f "$PROJECT_DIR/.github/copilot-instructions.md" ]; then
+    cp "$PKG_DIR/copilot-instructions.md" "$PROJECT_DIR/.github/copilot-instructions.md"
+    echo "  [ok] GitHub Copilot — .github/copilot-instructions.md"
+  else
+    echo "  [skip] .github/copilot-instructions.md already exists"
+  fi
+}
+
+install_cursor() {
+  mkdir -p "$PROJECT_DIR/.cursor/rules"
+  cp "$PKG_DIR/cursor/agentfootprint.md" "$PROJECT_DIR/.cursor/rules/agentfootprint.md"
+  echo "  [ok] Cursor — .cursor/rules/agentfootprint.md"
+}
+
+install_windsurf() {
+  if [ ! -f "$PROJECT_DIR/.windsurfrules" ]; then
+    cp "$PKG_DIR/windsurfrules" "$PROJECT_DIR/.windsurfrules"
+    echo "  [ok] Windsurf — .windsurfrules"
+  else
+    # Append agentfootprint rules to existing file
+    echo "" >> "$PROJECT_DIR/.windsurfrules"
+    cat "$PKG_DIR/windsurfrules" >> "$PROJECT_DIR/.windsurfrules"
+    echo "  [ok] Windsurf — appended to .windsurfrules"
+  fi
+}
+
+install_cline() {
+  if [ ! -f "$PROJECT_DIR/.clinerules" ]; then
+    cp "$PKG_DIR/clinerules" "$PROJECT_DIR/.clinerules"
+    echo "  [ok] Cline — .clinerules"
+  else
+    echo "" >> "$PROJECT_DIR/.clinerules"
+    cat "$PKG_DIR/clinerules" >> "$PROJECT_DIR/.clinerules"
+    echo "  [ok] Cline — appended to .clinerules"
+  fi
+}
+
+install_kiro() {
+  mkdir -p "$PROJECT_DIR/.kiro/rules"
+  cp "$PKG_DIR/kiro/agentfootprint.md" "$PROJECT_DIR/.kiro/rules/agentfootprint.md"
+  echo "  [ok] Kiro — .kiro/rules/agentfootprint.md"
+}
+
+install_all() {
+  install_claude_code
+  install_codex
+  install_copilot
+  install_cursor
+  install_windsurf
+  install_cline
+  install_kiro
+}
+
+# Interactive menu
+echo "  Which tool(s) do you use?"
+echo ""
+echo "    1) Claude Code"
+echo "    2) OpenAI Codex"
+echo "    3) GitHub Copilot"
+echo "    4) Cursor"
+echo "    5) Windsurf"
+echo "    6) Cline"
+echo "    7) Kiro"
+echo "    a) All of the above"
+echo "    q) Quit"
+echo ""
+read -rp "  Choose (e.g. 1,4 or a): " choice
+
+echo ""
+
+if [[ "$choice" == "q" ]]; then
+  echo "  Cancelled."
+  exit 0
+fi
+
+if [[ "$choice" == "a" || "$choice" == "A" ]]; then
+  install_all
+else
+  IFS=',' read -ra selections <<< "$choice"
+  for sel in "${selections[@]}"; do
+    sel="$(echo "$sel" | tr -d ' ')"
+    case "$sel" in
+      1) install_claude_code ;;
+      2) install_codex ;;
+      3) install_copilot ;;
+      4) install_cursor ;;
+      5) install_windsurf ;;
+      6) install_cline ;;
+      7) install_kiro ;;
+      *) echo "  [?] Unknown option: $sel" ;;
+    esac
+  done
+fi
+
+echo ""
+echo "  Done! Your AI assistant now knows the agentfootprint API."
+echo "  Add the generated files to .gitignore if you don't want them in version control."
+echo ""

package/ai-instructions/windsurfrules

@@ -0,0 +1,85 @@
+# agentfootprint — Windsurf Rules
+
+The explainable agent framework. Every agent is a footprintjs flowchart with auto-generated causal traces.
+
+## Core Principle
+
+**Every concept is a flowchart. Collect during traversal, never post-process.**
+
+## 5 Concepts
+
+```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()
+
+// 3. RAG — retrieve-augment-generate
+RAG.create({ provider, retriever }).system('...').topK(5).recorder(rec).build()
+
+// 4. FlowChart — sequential multi-agent
+FlowChart.create().agent('id', 'name', runner).recorder(rec).build()
+
+// 5. Swarm — LLM-routed multi-agent
+Swarm.create({ provider }).specialist('id', 'desc', runner).recorder(rec).build()
+```
+
+## Tools
+
+```typescript
+import { defineTool } from 'agentfootprint';
+defineTool({ id, description, inputSchema, handler })
+```
+
+## Recorders
+
+```typescript
+import { TokenRecorder, CostRecorder, TurnRecorder, ToolUsageRecorder,
+         QualityRecorder, GuardrailRecorder, CompositeRecorder } from 'agentfootprint';
+// Attach via .recorder(rec) on any builder
+```
+
+## Providers
+
+```typescript
+import { mock, mockRetriever, createProvider, anthropic, openai } from 'agentfootprint';
+
+// Testing
+mock([{ content: 'Hi' }])
+mockRetriever([{ chunks: [{ content: '...', score: 0.9, metadata: {} }] }])
+
+// Production
+createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514', apiKey: '...' }))
+```
+
+## Prompt & Tool Providers
+
+```typescript
+import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
+import { agentAsTool, compositeTools, mcpToolProvider, a2aRunner } from 'agentfootprint';
+```
+
+## Compositions
+
+```typescript
+import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+```
+
+## Runner API (all concepts)
+
+```typescript
+runner.run(message, { signal?, timeoutMs? })
+runner.getNarrative()        // causal trace
+runner.getSnapshot()         // memory state
+runner.getSpec()             // flowchart spec
+runner.toFlowChart()         // for subflow composition
+```
+
+## Rules
+
+- Use `CostRecorder` (not `CostRecorderV2`)
+- Never post-process — use recorders
+- Use `mock([...])` in tests
+- Use concept builders, not raw stages
+- Use `FlowChart`/`Swarm` for multi-agent

package/dist/adapters/a2a/a2aRunner.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * a2aRunner — wraps an A2A (Agent-to-Agent) endpoint as a RunnerLike.
+ *
+ * A2A protocol enables agents to communicate across services.
+ * This adapter bridges the A2A interface to agentfootprint's RunnerLike,
+ * enabling composition in FlowChart, Swarm, or agentAsTool.
+ *
+ * The adapter accepts an A2AClient interface (transport-agnostic).
+ * Users provide their own A2A client implementation.
+ *
+ * Usage:
+ *   const remoteAgent = a2aRunner({
+ *     client: myA2AClient,
+ *     agentId: 'research-agent',
+ *   });
+ *   const pipeline = FlowChart.create()
+ *     .agent('remote-research', 'Research', remoteAgent)
+ *     .build();
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.a2aRunner = void 0;
+function a2aRunner(options) {
+    const { client, agentId } = options;
+    return {
+        run: async (message, runOptions) => {
+            const response = await client.sendMessage(agentId, message, {
+                signal: runOptions?.signal,
+                timeoutMs: runOptions?.timeoutMs,
+            });
+            return { content: response.content };
+        },
+    };
+}
+exports.a2aRunner = a2aRunner;
+//# sourceMappingURL=a2aRunner.js.map

package/dist/adapters/a2a/a2aRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2aRunner.js","sourceRoot":"","sources":["../../../src/adapters/a2a/a2aRunner.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AA8BH,SAAgB,SAAS,CAAC,OAAyB;IACjD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEpC,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE;gBAC1D,MAAM,EAAE,UAAU,EAAE,MAAM;gBAC1B,SAAS,EAAE,UAAU,EAAE,SAAS;aACjC,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC;AAZD,8BAYC"}