agentfootprint 2.4.0 → 2.5.1

package/dist/types/tool-providers/skillScopedTools.d.ts

@@ -0,0 +1,46 @@
+/**
+ * skillScopedTools — ToolProvider that exposes a tool subset only when
+ * a specific Skill is active in the current iteration's context.
+ *
+ * The Block A5 piece. Pairs with `defineSkill({ autoActivate: 'currentSkill' })`
+ * to give the LLM a sharper choice space: when `billing` activates, the
+ * tool list flips from "all 25 agent tools" to "the 7 billing tools" +
+ * any baseline (always-on) tools the consumer composes alongside.
+ *
+ * Pattern: gated ToolProvider keyed by `ctx.activeSkillId`. Pure compute;
+ *          no Agent-runtime dependency. Composes freely with `staticTools`
+ *          for the always-on baseline.
+ *
+ * @example  One skill's tools, scoped by activation
+ *   const billingTools = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   billingTools.list({ iteration: 1, activeSkillId: 'billing', identity: ... });
+ *   // → [refundTool, chargeTool]
+ *   billingTools.list({ iteration: 1, activeSkillId: 'refund', identity: ... });
+ *   // → [] (different skill active)
+ *   billingTools.list({ iteration: 1, identity: ... });
+ *   // → [] (no skill active)
+ *
+ * @example  Compose with baseline + multiple skills
+ *   const baseline   = staticTools([lookupOrderTool, listSkills, readSkill]);
+ *   const billingTbx = skillScopedTools('billing', [refundTool, chargeTool]);
+ *   const refundTbx  = skillScopedTools('refund',  [reverseTool]);
+ *
+ *   // Wrap each scope-provider in a gatedTools for downstream composition,
+ *   // OR build a small wrapper that concatenates list(ctx) outputs:
+ *   const provider: ToolProvider = {
+ *     id: 'composite',
+ *     list: (ctx) => [
+ *       ...baseline.list(ctx),
+ *       ...billingTbx.list(ctx),
+ *       ...refundTbx.list(ctx),
+ *     ],
+ *   };
+ *
+ * Note: the runtime that POPULATES `ctx.activeSkillId` from
+ * `scope.activatedInjectionIds` lands in Block C / v2.5+. Today,
+ * consumers can drive it manually for tests + design-time inspection.
+ */
+import type { Tool } from '../core/tools.js';
+import type { ToolProvider } from './types.js';
+export declare function skillScopedTools(skillId: string, tools: readonly Tool[]): ToolProvider;
+//# sourceMappingURL=skillScopedTools.d.ts.map

package/dist/types/tool-providers/skillScopedTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillScopedTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAGpE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAgBtF"}

package/dist/types/tool-providers/staticTools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * staticTools — the simplest ToolProvider. Wraps a fixed Tool[] list.
+ *
+ * 90% case. What `agent.tools(arr)` does today, made composable.
+ * Equivalent to passing `arr` directly EXCEPT that `staticTools(arr)`
+ * is now a `ToolProvider` you can wrap with `gatedTools(...)` for
+ * permission filtering or per-skill gating.
+ *
+ * Pattern: identity ToolProvider — no filtering, just exposes the
+ *          underlying list verbatim.
+ *
+ * @example
+ *   const provider = staticTools([weatherTool, lookupTool]);
+ *   // Materialize the visible list and register via .tools(...).
+ *   // Direct .toolProvider(...) wiring on the builder lands in Block A5 / v2.5+.
+ *   const visible = provider.list({ iteration: 0, identity: { conversationId: '_' } });
+ *   const agent = Agent.create({ provider: llm, model }).tools(visible).build();
+ */
+import type { Tool } from '../core/tools.js';
+import type { ToolProvider } from './types.js';
+export declare function staticTools(tools: readonly Tool[]): ToolProvider;
+//# sourceMappingURL=staticTools.d.ts.map

package/dist/types/tool-providers/staticTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/staticTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAGpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAWhE"}

package/dist/types/tool-providers/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ToolProvider — abstraction over tool dispatch.
+ *
+ * v2.4 shipped tools as a flat array on the agent (registered via
+ * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
+ * production agents need:
+ *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
+ *   2. Per-skill tool gating (only show the active skill's tools to
+ *      the LLM each turn)
+ *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
+ *      decorator over the base tool list)
+ *
+ * `ToolProvider` is the answer: a chainable abstraction over "what
+ * tools does the LLM see right now?". The agent asks the provider
+ * each iteration; the provider returns the visible tool set computed
+ * from whatever predicates / role gates / skill filters the consumer
+ * composed.
+ *
+ * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
+ *          "compute the visible tool list given current context".
+ *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
+ *          provider with an additional filter, mirroring how `withRetry`
+ *          / `withFallback` decorate `LLMProvider`.
+ * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
+ *          each iteration to compute the visible tool set.
+ * Emits:   N/A (pure compute; permission denials emit elsewhere via the
+ *          permission subsystem).
+ *
+ * @example  Static tool list (90% case — what `.tools(arr)` does today)
+ *   const provider = staticTools([weather, lookupOrder]);
+ *
+ * @example  Read-only enforcement (role-based gate)
+ *   const readOnlyProvider = gatedTools(
+ *     staticTools([weather, lookupOrder, processRefund]),
+ *     (toolName) => policy.isAllowed(toolName),
+ *   );
+ *
+ * @example  Skill-gated dispatch (only active skill's tools visible)
+ *   const skillGated = gatedTools(
+ *     staticTools(allTools),
+ *     (toolName, ctx) => ctx.activeSkillId
+ *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
+ *       : alwaysVisible.includes(toolName),
+ *   );
+ *
+ * @example  Stack: read-only over skill-gated
+ *   const provider = gatedTools(
+ *     gatedTools(staticTools(allTools), readOnlyPredicate),
+ *     skillGatePredicate,
+ *   );
+ */
+import type { Tool } from '../core/tools.js';
+/**
+ * Read-only context the provider receives each iteration. Pure data
+ * — providers MUST NOT mutate. Used by gating predicates to inspect
+ * the current activation state.
+ */
+export interface ToolDispatchContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /**
+     * The id of the currently-activated Skill, if any.
+     * Set by `read_skill(id)` activation; cleared between turns.
+     * Used by `autoActivate`-driven per-skill tool gating.
+     */
+    readonly activeSkillId?: string;
+    /**
+     * Caller identity tuple — passed through from `agent.run({ identity })`.
+     * Permission predicates can role-check based on `identity.principal`
+     * or `identity.tenant`.
+     */
+    readonly identity?: {
+        readonly tenant?: string;
+        readonly principal?: string;
+        readonly conversationId: string;
+    };
+}
+/**
+ * The provider interface. A `ToolProvider` answers ONE question per
+ * iteration: "what tools should the LLM see right now?"
+ *
+ * Implementations are PURE — given the same context, return the same
+ * tool list. No async (the answer is needed synchronously each
+ * iteration; if you need async filtering, precompute upstream).
+ */
+export interface ToolProvider {
+    /**
+     * Return the tool list visible to the LLM for the current iteration.
+     * The returned array MUST be a NEW reference each call (the agent
+     * compares for change detection). Order is preserved — the LLM may
+     * use position as a hint when tool descriptions are ambiguous.
+     */
+    list(ctx: ToolDispatchContext): readonly Tool[];
+    /**
+     * Optional: stable id for observability / debugging. Defaults to
+     * `'static'` for `staticTools`, `'gated'` for `gatedTools`. Custom
+     * implementations should set their own id.
+     */
+    readonly id?: string;
+}
+/** Predicate for `gatedTools` — runs per tool, per iteration. */
+export type ToolGatePredicate = (toolName: string, ctx: ToolDispatchContext) => boolean;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/tool-providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,IAAI,EAAE,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -55,6 +55,8 @@
     "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",
@@ -97,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",
@@ -126,11 +138,33 @@
       "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": {