agentfootprint 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -52,10 +52,14 @@
     "build": "tsc && tsc -p tsconfig.esm.json",
     "watch": "tsc -w",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:examples": "tsc -p examples/tsconfig.json && bash scripts/run-all-examples.sh",
     "test:examples:typecheck": "tsc -p examples/tsconfig.json",
+    "examples:readme": "node scripts/generate-examples-readme.mjs",
+    "examples:readme:check": "node scripts/generate-examples-readme.mjs --check",
     "example": "TSX_TSCONFIG_PATH=examples/runtime.tsconfig.json npx --yes tsx",
     "test:watch": "vitest --watch",
+    "docs:api": "typedoc",
     "lint": "eslint 'src/**/*.ts' 'test/**/*.ts' --ext .ts",
     "lint:fix": "eslint 'src/**/*.ts' 'test/**/*.ts' --ext .ts --fix",
     "format": "prettier --config .prettierrc.js --list-different 'src/**/*.ts' 'test/**/*.ts'",
@@ -95,6 +99,16 @@
       "import": "./dist/esm/providers.js",
       "require": "./dist/providers.js"
     },
+    "./llm-providers": {
+      "types": "./dist/types/llm-providers.d.ts",
+      "import": "./dist/esm/llm-providers.js",
+      "require": "./dist/llm-providers.js"
+    },
+    "./memory-providers": {
+      "types": "./dist/types/memory-providers.d.ts",
+      "import": "./dist/esm/memory-providers.js",
+      "require": "./dist/memory-providers.js"
+    },
     "./observe": {
       "types": "./dist/types/observe.d.ts",
       "import": "./dist/esm/observe.js",
@@ -124,29 +138,68 @@
       "types": "./dist/types/adapters/memory/agentcore.d.ts",
       "import": "./dist/esm/adapters/memory/agentcore.js",
       "require": "./dist/adapters/memory/agentcore.js"
+    },
+    "./tool-providers": {
+      "types": "./dist/types/tool-providers/index.d.ts",
+      "import": "./dist/esm/tool-providers/index.js",
+      "require": "./dist/tool-providers/index.js"
+    },
+    "./security": {
+      "types": "./dist/types/security/index.d.ts",
+      "import": "./dist/esm/security/index.js",
+      "require": "./dist/security/index.js"
+    },
+    "./locales": {
+      "types": "./dist/types/locales/index.d.ts",
+      "import": "./dist/esm/locales/index.js",
+      "require": "./dist/locales/index.js"
     }
   },
   "sideEffects": false,
   "peerDependencies": {
-    "footprintjs": ">=4.14.0"
+    "footprintjs": ">=4.14.0",
+    "@anthropic-ai/sdk": "*",
+    "openai": "*",
+    "@aws-sdk/client-bedrock-runtime": "*",
+    "@aws-sdk/client-bedrock-agent-runtime": "*",
+    "@modelcontextprotocol/sdk": "*",
+    "ioredis": "*",
+    "zod": "*"
   },
   "peerDependenciesMeta": {
-    "@anthropic-ai/sdk": { "optional": true },
-    "openai": { "optional": true },
-    "@aws-sdk/client-bedrock-runtime": { "optional": true },
-    "@aws-sdk/client-bedrock-agent-runtime": { "optional": true },
-    "@modelcontextprotocol/sdk": { "optional": true },
-    "ioredis": { "optional": true },
-    "zod": { "optional": true }
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "@aws-sdk/client-bedrock-runtime": {
+      "optional": true
+    },
+    "@aws-sdk/client-bedrock-agent-runtime": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^25.5.2",
     "@typescript-eslint/eslint-plugin": "^5.61.0",
     "@typescript-eslint/parser": "^5.61.0",
+    "@vitest/coverage-v8": "^4.1.5",
     "eslint": "^8.44.0",
     "eslint-config-prettier": "^6.15.0",
     "footprintjs": "^4.14.0",
     "prettier": "^2.8.1",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "~5.4.5",
     "vitest": "^4.1.5",
     "zod": "^3.25.76"

package/README.proposed.md

@@ -1,258 +0,0 @@
-<p align="center">
-  <h1 align="center">agentfootprint</h1>
-  <p align="center">
-    <strong>Build agents whose every decision, tool call, and memory write is a typed event<br>you can replay and audit — same day, or six months later.</strong>
-  </p>
-</p>
-
-<p align="center">
-  <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <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://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>
-
-<br>
-
-<!-- ┌────────────────────────────────────────────────────────────────┐
-     │  📹  30-second demo video goes here.                            │
-     │      Embed: GitHub-hosted MP4 or Loom thumbnail.                │
-     │      Content: paste a trace into the viewer → drag the          │
-     │      time-travel slider → every step is there.                  │
-     │      This is the single most important asset on this page.      │
-     └────────────────────────────────────────────────────────────────┘ -->
-
-> **Try it without installing anything →** [Open the live trace viewer](https://footprintjs.github.io/agent-playground/#/viewer), paste the [sample trace](./examples/sample-trace.json), drag the slider. You'll see what your agent did, not what it logged.
-
----
-
-## In 30 seconds
-
-```bash
-npm install agentfootprint footprintjs
-```
-
-```typescript
-import { Agent, defineTool, mock } from 'agentfootprint';
-
-const weather = defineTool({
-  name: 'weather',
-  description: 'Get current weather for a city.',
-  inputSchema: {
-    type: 'object',
-    properties: { city: { type: 'string' } },
-    required: ['city'],
-  },
-  execute: async ({ city }: { city: string }) => `${city}: 72°F, sunny`,
-});
-
-const agent = Agent.create({
-  provider: mock({ reply: 'Paris is 72°F and sunny.' }),  // ← no API key
-  model: 'mock',
-})
-  .system('You answer weather questions using the weather tool.')
-  .tool(weather)
-  .build();
-
-const result = await agent.run({ message: 'Weather in Paris?' });
-console.log(result);  // → "Paris is 72°F and sunny."
-```
-
-That runs offline, deterministically, in <100ms, with no API key. Swap `mock(...)` for `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)` for production. Nothing else changes.
-
----
-
-## The model in your head
-
-Every LLM call has three slots. **Every "agent feature" — Skill, Steering doc, Instruction, Fact, Memory replay, RAG chunk — is content flowing into one of them, under one of four triggers.**
-
-```
-                       ┌─────────────────────────────────────┐
-                       │                                     │
-                       │    Your LLM call has 3 slots:       │
-                       │                                     │
-                       │    system    messages    tools      │
-                       │       ▲          ▲          ▲       │
-                       └───────┼──────────┼──────────┼───────┘
-                               │          │          │
-                               │   one    │   one    │
-                               │ Injection│ Injection│
-                               │  fires…  │  fires…  │
-                               │          │          │
-                ┌──────────────┴────┐  ┌──┴───┐  ┌──┴────┐
-                │ defineSkill        │  │ ...  │  │ ...   │
-                │ defineSteering     │  │      │  │       │
-                │ defineInstruction  │  │      │  │       │
-                │ defineFact         │  │      │  │       │
-                │ defineMemory(read) │  │      │  │       │
-                │ defineRAG (v2.1)   │  │      │  │       │
-                │   …your next idea  │  │      │  │       │
-                └────────────────────┘  └──────┘  └───────┘
-                          ▲
-                   …under one of:
-                  always · rule · on-tool-return · llm-activated
-```
-
-**There's no fourth slot.** There won't be. Every named pattern in the agent literature — Reflexion, Tree-of-Thoughts, Skills, RAG, Constitutional AI — reduces to *which slot* + *which trigger*. You learn one model; the field's growth lands as new factories on the same primitive.
-
----
-
-## What you can build
-
-Three example shapes, all runnable end-to-end with `npm run example examples/<file>.ts`.
-
-### Customer support agent (with skills, memory, and audit trail)
-
-A support agent that activates a "billing" skill when needed, remembers the customer across sessions, and produces an audit-grade trace.
-
-```typescript
-const agent = Agent.create({ provider: anthropic(...), model: 'claude-sonnet-4-5-20250929' })
-  .system('You are a friendly support assistant.')
-  .skill(billingSkill)        // LLM activates with read_skill('billing')
-  .steering(toneGuidelines)   // always-on
-  .memory(conversationMemory) // remembers across .run() calls
-  .build();
-```
-
-→ [`examples/context-engineering/06-mixed-flavors.ts`](examples/context-engineering/06-mixed-flavors.ts)
-
-### Research pipeline (multi-agent, fan-out + merge)
-
-Three perspectives explore in parallel; an LLM merges their findings.
-
-```typescript
-const research = Parallel.create()
-  .branch(optimist).branch(skeptic).branch(historian)
-  .merge(synthesizer)
-  .build();
-
-await research.run({ message: 'Should we adopt microservices?' });
-```
-
-→ [`examples/patterns/05-tot.ts`](examples/patterns/05-tot.ts) (Tree-of-Thoughts) · [`examples/patterns/01-self-consistency.ts`](examples/patterns/01-self-consistency.ts)
-
-### Streaming chat agent (token-by-token to a browser)
-
-<!-- ┌────────────────────────────────────────────────────────────────┐
-     │  📹  Streaming demo clip here.                                  │
-     │      A short loop: user types → token-by-token streaming →     │
-     │      tool call appears mid-stream → final answer.              │
-     │      Demonstrates `provider.stream()` + SSE bridge.            │
-     └────────────────────────────────────────────────────────────────┘ -->
-
-```typescript
-agent.on('agentfootprint.stream.token', (e) => res.write(e.payload.content));
-agent.on('agentfootprint.stream.tool_start', (e) => res.write(`\n→ calling ${e.payload.toolName}...\n`));
-await agent.run({ message: userInput });
-```
-
-→ [`docs-site/guides/streaming/`](docs-site/src/content/docs/guides/streaming.mdx)
-
----
-
-## The differentiator
-
-Agent frameworks are a crowded shelf. Two things in here are not on the rest of that shelf.
-
-### 1. Causal memory — replay *why*, not just *what*
-
-Other libraries' memory remembers what was said. **agentfootprint's `defineMemory({ type: CAUSAL })` remembers the decision evidence** — every `decide()` and `select()` value the agent's flowchart captured during the run. New questions cosine-match against past queries, inject the prior decision evidence, and the LLM answers from *exact past facts* — not reconstruction.
-
-```typescript
-const causal = defineMemory({
-  id: 'causal',
-  type: MEMORY_TYPES.CAUSAL,
-  strategy: { kind: MEMORY_STRATEGIES.TOP_K, topK: 1, threshold: 0.7, embedder },
-  store,
-  projection: SNAPSHOT_PROJECTIONS.DECISIONS,  // inject "why" only, not "what"
-});
-
-// Monday: agent decides loan #42 should be rejected (creditScore=580, threshold=600)
-// Friday: user asks "Why was my application rejected?"
-// → Causal memory loads the exact decision evidence from Monday.
-// → LLM answers from the SOURCE, not from memory of memory.
-```
-
-→ [`examples/memory/06-causal-snapshot.ts`](examples/memory/06-causal-snapshot.ts) — runs end-to-end with mock embedder, ~50 lines.
-
-The same snapshot data shape becomes RL/SFT/DPO training data in v2.3+. Every successful production run becomes a labeled trajectory.
-
-### 2. Trace export → trace replay
-
-Every run exports as one JSON blob. Paste it into the viewer six months later, on a different machine. Every decision, every tool call, every memory write is on a draggable time-travel slider. **No log parsing. No reconstruction. The trace IS the evidence.**
-
-```typescript
-const trace = exportTrace(agent);                       // serialize
-fs.writeFileSync('incident-2026-04-29.json', trace);    // archive
-
-// Later — different team, different machine
-<TraceViewer trace={JSON.parse(fs.readFileSync('incident-2026-04-29.json'))} />
-```
-
-That round-trip is the difference between "we shipped an agent and hope it's working" and "we can audit any production decision after the fact."
-
----
-
-## Mocks first, prod second
-
-Generative AI development is expensive when every iteration hits a paid API. agentfootprint is designed so you build the entire app — agent, context engineering, memory, RAG — against in-memory mocks, prove the logic end-to-end with **zero API cost**, then swap real infrastructure in one boundary at a time.
-
-| Boundary | Dev (mock) | Prod (swap one line) |
-|---|---|---|
-| LLM provider | `mock({ reply })` | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
-| Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder |
-| Memory store | `InMemoryStore` | Redis · DynamoDB · Postgres · Pinecone |
-| MCP server | `mcpClient({ _client })` | `mcpClient({ transport })` |
-| Tool execution | inline closure | real implementation |
-
-The flowchart, recorders, narrative, and tests don't change between dev and prod. **Ship the patterns first; pay for tokens last.**
-
----
-
-## Pick your starting door
-
-| If you are... | Start here |
-|---|---|
-| 🎓 **New to agents** — never built one before | [5-minute Quick Start](https://footprintjs.github.io/agentfootprint/getting-started/quick-start/) → first agent runs offline |
-| 🛠️ **A LangChain / CrewAI / LangGraph user** | [Migration sketch](https://footprintjs.github.io/agentfootprint/getting-started/vs/) — same patterns, fewer classes |
-| 🏗️ **Architecting an enterprise rollout** | [Production guide](https://footprintjs.github.io/agentfootprint/guides/deployment/) — multi-tenant identity, audit trails, redaction, OTel |
-| 🔬 **Researcher / extending the framework** | [Extension guide](https://footprintjs.github.io/agentfootprint/contributing/extension-guide/) — add a new flavor in 50 lines |
-
-Every code snippet on the docs site is a real, runnable file in [`examples/`](examples/) — every example is also an end-to-end test in CI. There is no docs-only code in this repo.
-
----
-
-## What ships today (v2.0)
-
-- **2 primitives** — `LLMCall`, `Agent` (the ReAct loop)
-- **4 compositions** — `Sequence`, `Parallel`, `Conditional`, `Loop`
-- **6 LLM providers** — Anthropic · OpenAI · Bedrock · Ollama · Browser-Anthropic · Browser-OpenAI · Mock
-- **One Injection primitive** — `defineSkill` / `defineSteering` / `defineInstruction` / `defineFact` (one engine, four typed factories, all reduce to `{ trigger, slot }`)
-- **One Memory factory** — `defineMemory({ type, strategy, store })` — 4 types × 7 strategies including **Causal**
-- **47 typed observability events** across 13 domains — context · stream · agent · cost · skill · permission · eval · memory · …
-- **Pause / resume** — JSON-serializable checkpoints; pause via `askHuman`/`pauseHere`, resume hours later on a different server
-- **Resilience** — `withRetry`, `withFallback`, `resilientProvider`
-- **AI-coding-tool support** — bundled instructions for Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot
-- **33 runnable examples** organized by DNA layer (core · core-flow · patterns · context-engineering · memory · features)
-
-## What's next (clearly marked roadmap)
-
-| Release | Focus |
-|---|---|
-| v2.1 ✓ | RAG flavor (`defineRAG`) — *shipped* |
-| v2.2 | MCP integration (`mcpClient`) ✓ · Redis adapter · CircuitBreaker · 3-tier output fallback |
-| v2.3 | Governance (`Policy`, `BudgetTracker`) · DynamoDB / Postgres / Pinecone adapters |
-| v2.4 | Causal training-data exports — `causalMemory.exportForTraining({ format: 'sft' \| 'dpo' \| 'process' })` |
-| v2.5+ | Deep Agents (planning-before-execution) · A2A protocol · Lens UI deep-link |
-
-Roadmap items are *not* claims about the current API. If a feature isn't in `npm install agentfootprint` today, it's listed here, not in the documentation.
-
----
-
-## Built on
-
-[footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. The decision-evidence capture, narrative recording, and time-travel checkpointing this library uses are footprintjs primitives. You don't need to learn footprintjs to use agentfootprint, but if you want to build your own primitives at this depth, [start there](https://footprintjs.github.io/footPrint/).
-
-## License
-
-[MIT](./LICENSE) © [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)

package/dist/instructions.js

@@ -1,21 +0,0 @@
-"use strict";
-/**
- * agentfootprint/instructions — public re-export for the Instructions subsystem.
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./lib/instructions/index.js"), exports);
-//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,8DAA4C"}

package/dist/lib/instructions/defineInstruction.js

@@ -1,35 +0,0 @@
-"use strict";
-/**
- * defineInstruction — ergonomic builder for `Instruction`.
- *
- * Pattern: Builder pattern (GoF) for the Strategy interface.
- * Role:    Public surface — used by consumers to declare instructions.
- *
- * @example
- *   import { defineInstruction } from 'agentfootprint';
- *   import type { InstructionContext } from 'agentfootprint';
- *
- *   const refundEmpathy = defineInstruction({
- *     id: 'refund-empathy',
- *     description: 'Calm tone for refund denials.',
- *     activeWhen: (ctx) => ctx.lastToolResult?.toolName === 'check_refund'
- *                       && ctx.lastToolResult.result.includes('denied'),
- *     prompt: 'Be empathetic. Do NOT promise refund reversal.',
- *   });
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineInstruction = void 0;
-function defineInstruction(options) {
-    if (!options.id || options.id.trim().length === 0) {
-        throw new Error('defineInstruction: `id` is required and must be non-empty.');
-    }
-    if (options.prompt === undefined
-        && (!options.tools || options.tools.length === 0)) {
-        throw new Error(`defineInstruction(${options.id}): instruction must declare at least one of \`prompt\` or \`tools\`.`);
-    }
-    // Freeze for consumer protection — instructions should be immutable
-    // after construction so the agent can cache evaluations.
-    return Object.freeze({ ...options });
-}
-exports.defineInstruction = defineInstruction;
-//# sourceMappingURL=defineInstruction.js.map

package/dist/lib/instructions/defineInstruction.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"defineInstruction.js","sourceRoot":"","sources":["../../../src/lib/instructions/defineInstruction.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAMH,SAAgB,iBAAiB,CAAC,OAAiC;IACjE,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,IACE,OAAO,CAAC,MAAM,KAAK,SAAS;WACzB,CAAC,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,EACjD,CAAC;QACD,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,CAAC,EAAE,sEAAsE,CACtG,CAAC;IACJ,CAAC;IACD,oEAAoE;IACpE,yDAAyD;IACzD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAgB,CAAC;AACtD,CAAC;AAfD,8CAeC"}

package/dist/lib/instructions/evaluator.js

@@ -1,38 +0,0 @@
-"use strict";
-/**
- * Instruction evaluator — runs the `activeWhen` predicates and
- * returns the active set + any skipped predicates.
- *
- * Pattern: Pure function. Stateless.
- * Role:    Internal helper used by Agent during pre-LLM stage.
- * Emits:   N/A — caller handles emit + observability.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.evaluateInstructions = void 0;
-function evaluateInstructions(instructions, ctx) {
-    const active = [];
-    const skipped = [];
-    for (const inst of instructions) {
-        if (!inst.activeWhen) {
-            // No predicate → always active (unconditional injection).
-            active.push(inst);
-            continue;
-        }
-        let matched = false;
-        try {
-            matched = inst.activeWhen(ctx);
-        }
-        catch (err) {
-            skipped.push({
-                id: inst.id,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            continue;
-        }
-        if (matched)
-            active.push(inst);
-    }
-    return { active, skipped };
-}
-exports.evaluateInstructions = evaluateInstructions;
-//# sourceMappingURL=evaluator.js.map

package/dist/lib/instructions/evaluator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../src/lib/instructions/evaluator.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAQH,SAAgB,oBAAoB,CAClC,YAAoC,EACpC,GAAuB;IAEvB,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,MAAM,OAAO,GAAoC,EAAE,CAAC;IAEpD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,0DAA0D;YAC1D,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC;AA3BD,oDA2BC"}

package/dist/lib/instructions/index.js

@@ -1,48 +0,0 @@
-"use strict";
-/**
- * Instructions — declarative rule-based system-prompt injection.
- *
- * Public API for the v2 Instructions subsystem. See `types.ts` for the
- * full interface + the unified context-engineering model placement.
- *
- * ─── 7-panel design review (2026-04-28) ─────────────────────────────
- *
- *   LLM-AI system design   ✓ Maps cleanly to the unified context-
- *                            engineering model: slot=system-prompt
- *                            (+optional tools), role=system, timing=
- *                            per-iteration, decision=rule.
- *   Performance            ✓ Predicates run once per iteration (not
- *                            per token / per event). O(N) in number
- *                            of instructions; typical N ≤ 20.
- *   Scalability            ✓ Stateless evaluator; many concurrent
- *                            agents share the same instruction list
- *                            via Object.freeze.
- *   Research alignment     ✓ Mirrors v1 AgentInstruction's `activeWhen`
- *                            shape (origin/main `c6e11d0`) but drops
- *                            `onToolResult`, `safety`, decision-scope
- *                            wrapping for v2 simplicity. Equivalent
- *                            tool-result-driven behavior is expressed
- *                            via `activeWhen: (ctx) =>
- *                            ctx.lastToolResult?.toolName === 'X'`.
- *   Flexibility            ✓ Same Instruction can be active across
- *                            multiple iterations; can inject tools
- *                            in addition to prompt; predicates can
- *                            inspect history + last tool result.
- *   Abstraction-modular    ✓ Three small files: types, builder,
- *                            evaluator. Agent integration is one
- *                            call into `evaluateInstructions()`.
- *   Software engineering   ✓ Predicate errors are caught + surfaced
- *                            (no crash). Frozen instructions prevent
- *                            mutation. 7-pattern test coverage.
- *
- * ─── 7-pattern test coverage ────────────────────────────────────────
- *
- *   See `test/lib/instructions/*.test.ts`.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.evaluateInstructions = exports.defineInstruction = void 0;
-var defineInstruction_js_1 = require("./defineInstruction.js");
-Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return defineInstruction_js_1.defineInstruction; } });
-var evaluator_js_1 = require("./evaluator.js");
-Object.defineProperty(exports, "evaluateInstructions", { enumerable: true, get: function () { return evaluator_js_1.evaluateInstructions; } });
-//# sourceMappingURL=index.js.map

package/dist/lib/instructions/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/instructions/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAEH,+DAGgC;AAF9B,yHAAA,iBAAiB,OAAA;AAInB,+CAEwB;AADtB,oHAAA,oBAAoB,OAAA"}

package/dist/lib/instructions/types.js

@@ -1,22 +0,0 @@
-"use strict";
-/**
- * Instructions — types.
- *
- * An Instruction is a declarative rule for conditional system-prompt
- * injection. The agent evaluates each Instruction's `activeWhen`
- * predicate at the start of every iteration; matching instructions'
- * `prompt` text is prepended to the system prompt for that iteration.
- *
- * This is the rule-based flavor of the unified context-engineering
- * model: slot=system-prompt, role=system, timing=per-iteration,
- * decision=rule. (Compare with Skills: timing=on-activation,
- * decision=LLM-guided.)
- *
- * Pattern: Strategy (GoF) — each Instruction is a strategy for
- *          "should I add this prompt to the next iteration?"
- * Role:    Consumer-facing shape. Agent.create(...).instruction(...).
- * Emits:   `agentfootprint.context.injected` with source='instruction'
- *          when an instruction activates.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/lib/instructions/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/instructions/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/memory/conversationHelpers.js

@@ -1,39 +0,0 @@
-"use strict";
-/**
- * Pure functions for conversation message management.
- * No state — just transformations on message arrays.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createToolResults = exports.lastMessageHasToolCalls = exports.lastAssistantMessage = exports.lastMessage = exports.appendMessage = void 0;
-const types_1 = require("../types");
-/** Append a message to the conversation. Returns new array. */
-function appendMessage(messages, message) {
-    return [...messages, message];
-}
-exports.appendMessage = appendMessage;
-/** Get the last message in the conversation. */
-function lastMessage(messages) {
-    return messages[messages.length - 1];
-}
-exports.lastMessage = lastMessage;
-/** Get the last assistant message. */
-function lastAssistantMessage(messages) {
-    for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i].role === 'assistant')
-            return messages[i];
-    }
-    return undefined;
-}
-exports.lastAssistantMessage = lastAssistantMessage;
-/** Check if the last assistant message has tool calls. */
-function lastMessageHasToolCalls(messages) {
-    const last = lastAssistantMessage(messages);
-    return last ? (0, types_1.hasToolCalls)(last) : false;
-}
-exports.lastMessageHasToolCalls = lastMessageHasToolCalls;
-/** Create tool result messages from a map of tool call ID → result. */
-function createToolResults(results) {
-    return results.map((r) => (0, types_1.toolResultMessage)(r.content, r.toolCallId));
-}
-exports.createToolResults = createToolResults;
-//# sourceMappingURL=conversationHelpers.js.map

package/dist/memory/conversationHelpers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"conversationHelpers.js","sourceRoot":"","sources":["../../src/memory/conversationHelpers.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,oCAA2D;AAE3D,+DAA+D;AAC/D,SAAgB,aAAa,CAAC,QAAmB,EAAE,OAAgB;IACjE,OAAO,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,CAAC;AAChC,CAAC;AAFD,sCAEC;AAED,gDAAgD;AAChD,SAAgB,WAAW,CAAC,QAAmB;IAC7C,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAFD,kCAEC;AAED,sCAAsC;AACtC,SAAgB,oBAAoB,CAAC,QAAmB;IACtD,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAqB,CAAC;IAC/E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AALD,oDAKC;AAED,0DAA0D;AAC1D,SAAgB,uBAAuB,CAAC,QAAmB;IACzD,MAAM,IAAI,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAA,oBAAY,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3C,CAAC;AAHD,0DAGC;AAED,uEAAuE;AACvE,SAAgB,iBAAiB,CAC/B,OAAuD;IAEvD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,yBAAiB,EAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;AACxE,CAAC;AAJD,8CAIC"}

package/dist/types/instructions.d.ts

@@ -1,5 +0,0 @@
-/**
- * agentfootprint/instructions — public re-export for the Instructions subsystem.
- */
-export * from './lib/instructions/index.js';
-//# sourceMappingURL=instructions.d.ts.map

package/dist/types/instructions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/instructions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,6BAA6B,CAAC"}

package/dist/types/lib/instructions/defineInstruction.d.ts

@@ -1,22 +0,0 @@
-/**
- * defineInstruction — ergonomic builder for `Instruction`.
- *
- * Pattern: Builder pattern (GoF) for the Strategy interface.
- * Role:    Public surface — used by consumers to declare instructions.
- *
- * @example
- *   import { defineInstruction } from 'agentfootprint';
- *   import type { InstructionContext } from 'agentfootprint';
- *
- *   const refundEmpathy = defineInstruction({
- *     id: 'refund-empathy',
- *     description: 'Calm tone for refund denials.',
- *     activeWhen: (ctx) => ctx.lastToolResult?.toolName === 'check_refund'
- *                       && ctx.lastToolResult.result.includes('denied'),
- *     prompt: 'Be empathetic. Do NOT promise refund reversal.',
- *   });
- */
-import type { Instruction } from './types.js';
-export type DefineInstructionOptions = Instruction;
-export declare function defineInstruction(options: DefineInstructionOptions): Instruction;
-//# sourceMappingURL=defineInstruction.d.ts.map

package/dist/types/lib/instructions/defineInstruction.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"defineInstruction.d.ts","sourceRoot":"","sources":["../../../../src/lib/instructions/defineInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC;AAEnD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAehF"}