agentfootprint 1.0.0

package/dist/esm/providers/tools/PermissionPolicy.js

@@ -0,0 +1,100 @@
+/**
+ * PermissionPolicy — centralized, shareable permission policy for tool gating.
+ *
+ * Addresses the "per-agent, not centralized" con of gatedTools().
+ * Create one policy, share it across multiple agents/swarms.
+ *
+ * Features:
+ *   - grant/revoke at runtime (mid-conversation permission changes)
+ *   - wildcard support ('*' grants all)
+ *   - role-based presets (pass a Set of tool IDs per role)
+ *   - onChange callback for audit/logging
+ *
+ * Usage:
+ *   // Centralized policy — shared across agents
+ *   const policy = new PermissionPolicy(['search', 'calc']);
+ *
+ *   const agent1 = Agent.create({ provider })
+ *     .toolProvider(gatedTools(tools, policy.checker()))
+ *     .build();
+ *
+ *   const agent2 = Agent.create({ provider })
+ *     .toolProvider(gatedTools(otherTools, policy.checker()))
+ *     .build();
+ *
+ *   // Runtime changes — both agents see it immediately
+ *   policy.grant('admin-tool');
+ *   policy.revoke('search');
+ *
+ *   // Role-based
+ *   const policy = PermissionPolicy.fromRoles({
+ *     user: ['search', 'calc'],
+ *     admin: ['search', 'calc', 'delete-user', 'run-code'],
+ *   }, 'user');  // current role
+ *   policy.setRole('admin');  // upgrade mid-conversation
+ */
+export class PermissionPolicy {
+    allowed;
+    onChange;
+    // Role-based state
+    roles;
+    currentRole;
+    constructor(initialAllowed = [], options) {
+        this.allowed = new Set(initialAllowed);
+        this.onChange = options?.onChange;
+    }
+    /**
+     * Create a policy from role definitions.
+     * The active role determines which tools are allowed.
+     */
+    static fromRoles(roles, activeRole, options) {
+        const tools = roles[activeRole] ?? [];
+        const policy = new PermissionPolicy(tools, options);
+        policy.roles = roles;
+        policy.currentRole = activeRole;
+        return policy;
+    }
+    /** Grant access to a tool. Takes effect on next resolve() call. */
+    grant(toolId) {
+        this.allowed.add(toolId);
+        this.onChange?.({ type: 'grant', toolId, allowed: this.getAllowed() });
+        return this;
+    }
+    /** Revoke access to a tool. */
+    revoke(toolId) {
+        this.allowed.delete(toolId);
+        this.onChange?.({ type: 'revoke', toolId, allowed: this.getAllowed() });
+        return this;
+    }
+    /** Switch to a different role (role-based policies only). */
+    setRole(role) {
+        if (!this.roles)
+            throw new Error('[PermissionPolicy] setRole requires fromRoles()');
+        if (!this.roles[role])
+            throw new Error(`[PermissionPolicy] Unknown role: "${role}"`);
+        this.currentRole = role;
+        this.allowed = new Set(this.roles[role]);
+        this.onChange?.({ type: 'role-change', role, allowed: this.getAllowed() });
+        return this;
+    }
+    /** Current role (if using role-based policy). */
+    getRole() {
+        return this.currentRole;
+    }
+    /** Check if a tool is allowed. */
+    isAllowed(toolId) {
+        return this.allowed.has('*') || this.allowed.has(toolId);
+    }
+    /** Get all currently allowed tool IDs. */
+    getAllowed() {
+        return [...this.allowed];
+    }
+    /**
+     * Returns a PermissionChecker compatible with gatedTools().
+     * This is the bridge — create one policy, pass checker() to multiple gatedTools.
+     */
+    checker() {
+        return (toolId) => this.isAllowed(toolId);
+    }
+}
+//# sourceMappingURL=PermissionPolicy.js.map

package/dist/esm/providers/tools/PermissionPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionPolicy.js","sourceRoot":"","sources":["../../../../src/providers/tools/PermissionPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAgBH,MAAM,OAAO,gBAAgB;IACnB,OAAO,CAAc;IACZ,QAAQ,CAA0C;IAEnE,mBAAmB;IACX,KAAK,CAAqC;IAC1C,WAAW,CAAU;IAE7B,YAAY,iBAAmC,EAAE,EAAE,OAAiC;QAClF,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAAS,CACd,KAAwC,EACxC,UAAkB,EAClB,OAAiC;QAEjC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,MAAM,CAAC,WAAW,GAAG,UAAU,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAc;QAClB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+BAA+B;IAC/B,MAAM,CAAC,MAAc;QACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6DAA6D;IAC7D,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,GAAG,CAAC,CAAC;QACrF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iDAAiD;IACjD,OAAO;QACL,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,kCAAkC;IAClC,SAAS,CAAC,MAAc;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED,0CAA0C;IAC1C,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,OAAO,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/esm/providers/tools/agentAsTool.js

@@ -0,0 +1,47 @@
+/**
+ * agentAsTool — wraps a RunnerLike as a ToolDefinition.
+ *
+ * Turns any agent (or runner) into a callable tool. The LLM can invoke it
+ * like any other tool, passing a message. The runner executes and returns
+ * the result as tool output.
+ *
+ * This is the primitive for delegation patterns: an orchestrator agent
+ * can call specialist agents as tools (Swarm handoff, hierarchy, etc.).
+ *
+ * Usage:
+ *   const researchTool = agentAsTool({
+ *     id: 'research',
+ *     description: 'Research a topic in depth.',
+ *     runner: researchAgent,
+ *   });
+ *   const orchestrator = Agent.create({ provider })
+ *     .tool(researchTool)
+ *     .build();
+ */
+const DEFAULT_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        message: { type: 'string', description: 'The message to send to the agent.' },
+    },
+    required: ['message'],
+};
+export function agentAsTool(config) {
+    const { id, description, runner, inputSchema = DEFAULT_INPUT_SCHEMA, inputMapper = (input) => input.message ?? '', signal, timeoutMs, } = config;
+    return {
+        id,
+        description,
+        inputSchema,
+        handler: async (input) => {
+            try {
+                const message = inputMapper(input);
+                const result = await runner.run(message, { signal, timeoutMs });
+                return { content: result.content };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: `Agent error: ${msg}`, error: true };
+            }
+        },
+    };
+}
+//# sourceMappingURL=agentAsTool.js.map

package/dist/esm/providers/tools/agentAsTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentAsTool.js","sourceRoot":"","sources":["../../../../src/providers/tools/agentAsTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsBH,MAAM,oBAAoB,GAA4B;IACpD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE;KAC9E;IACD,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,MAAyB;IACnD,MAAM,EACJ,EAAE,EACF,WAAW,EACX,MAAM,EACN,WAAW,GAAG,oBAAoB,EAClC,WAAW,GAAG,CAAC,KAAK,EAAE,EAAE,CAAE,KAAK,CAAC,OAAkB,IAAI,EAAE,EACxD,MAAM,EACN,SAAS,GACV,GAAG,MAAM,CAAC;IAEX,OAAO;QACL,EAAE;QACF,WAAW;QACX,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAA8B,EAAuB,EAAE;YACrE,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;gBACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;gBAChE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACzD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/providers/tools/compositeTools.js

@@ -0,0 +1,49 @@
+/**
+ * compositeTools — ToolProvider that merges multiple ToolProviders.
+ *
+ * Resolves all providers and merges their tool lists. If multiple providers
+ * return a tool with the same name, later providers win (last-write-wins).
+ *
+ * Execute delegates to the provider that owns the tool (by resolve order,
+ * last provider that resolved a tool of that name handles execution).
+ *
+ * Usage:
+ *   const tools = compositeTools([
+ *     staticTools([searchTool]),
+ *     dynamicTools((ctx) => ctx.turnNumber > 3 ? [submitTool] : []),
+ *   ]);
+ */
+export function compositeTools(providers) {
+    return {
+        resolve: async (context) => {
+            const allDecisions = await Promise.all(providers.map((p) => p.resolve(context)));
+            // Merge with last-write-wins by tool name
+            const toolMap = new Map();
+            for (const decision of allDecisions) {
+                for (const tool of decision.value) {
+                    toolMap.set(tool.name, tool);
+                }
+            }
+            const merged = Array.from(toolMap.values());
+            const labels = allDecisions.map((d) => d.chosen).filter((c) => c !== 'static');
+            return {
+                value: merged,
+                chosen: labels.length > 0 ? `composite: ${labels.join(' + ')}` : 'composite',
+                rationale: `${merged.length} tools from ${providers.length} providers`,
+            };
+        },
+        execute: async (call, signal) => {
+            // Walk providers in reverse — last provider that can execute wins
+            for (let i = providers.length - 1; i >= 0; i--) {
+                const provider = providers[i];
+                if (provider.execute) {
+                    // Try this provider — it may not know the tool, but that's ok
+                    // since we already validated via resolve
+                    return provider.execute(call, signal);
+                }
+            }
+            return { content: `No executor found for tool: ${call.name}`, error: true };
+        },
+    };
+}
+//# sourceMappingURL=compositeTools.js.map

package/dist/esm/providers/tools/compositeTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositeTools.js","sourceRoot":"","sources":["../../../../src/providers/tools/compositeTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,UAAU,cAAc,CAAC,SAAkC;IAC/D,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,OAAoB,EAAE,EAAE;YACtC,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAEjF,0CAA0C;YAC1C,MAAM,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;YACtD,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;gBACpC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;oBAClC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YAED,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;YAC/E,OAAO;gBACL,KAAK,EAAE,MAAM;gBACb,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW;gBAC5E,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,eAAe,SAAS,CAAC,MAAM,YAAY;aACvE,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAc,EAAE,MAAoB,EAAgC,EAAE;YACpF,kEAAkE;YAClE,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;gBAC9B,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACrB,8DAA8D;oBAC9D,yCAAyC;oBACzC,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,+BAA+B,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC9E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/providers/tools/dynamicTools.js

@@ -0,0 +1,41 @@
+/**
+ * dynamicTools — resolver-only ToolProvider that resolves tools based on context.
+ *
+ * The resolver function receives the current ToolContext and returns
+ * the tools available for this turn. Useful when:
+ * - Different tools are available based on conversation state
+ * - Tools are loaded from an external source (MCP, DB, API)
+ * - Tool availability depends on user permissions
+ *
+ * This provider does NOT include `execute` — the core loop calls
+ * `ToolDefinition.handler` directly from the resolved set. This avoids
+ * stale cache issues and temporal coupling between resolve/execute.
+ *
+ * For providers where execution is remote (MCP, A2A), implement
+ * `ToolProvider` directly with both `resolve` and `execute`.
+ *
+ * Usage:
+ *   agentLoop().toolProvider(dynamicTools((ctx) => {
+ *     if (ctx.message.includes('code')) return [runCodeTool];
+ *     return [searchTool];
+ *   }))
+ */
+export function dynamicTools(resolver) {
+    return {
+        resolve: async (context) => {
+            const tools = await resolver(context);
+            return {
+                value: tools.map((t) => ({
+                    name: t.id,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                })),
+                chosen: 'dynamic',
+                rationale: `${tools.length} tool${tools.length !== 1 ? 's' : ''} resolved`,
+            };
+        },
+        // No execute — core loop uses ToolDefinition.handler from resolved set.
+        // This avoids cache staleness. For remote execution, implement ToolProvider directly.
+    };
+}
+//# sourceMappingURL=dynamicTools.js.map

package/dist/esm/providers/tools/dynamicTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamicTools.js","sourceRoot":"","sources":["../../../../src/providers/tools/dynamicTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAOH,MAAM,UAAU,YAAY,CAAC,QAAsB;IACjD,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,OAAoB,EAAE,EAAE;YACtC,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACtC,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACvB,IAAI,EAAE,CAAC,CAAC,EAAE;oBACV,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;iBAC3B,CAAC,CAAC;gBACH,MAAM,EAAE,SAAS;gBACjB,SAAS,EAAE,GAAG,KAAK,CAAC,MAAM,QAAQ,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,WAAW;aAC3E,CAAC;QACJ,CAAC;QACD,wEAAwE;QACxE,sFAAsF;KACvF,CAAC;AACJ,CAAC"}

package/dist/esm/providers/tools/gatedTools.js

@@ -0,0 +1,90 @@
+/**
+ * gatedTools — Permission-based tool filtering with defense in depth.
+ *
+ * Wraps any ToolProvider to filter tools based on a permission check.
+ * Two layers of enforcement:
+ *   1. resolve() — blocked tools are hidden from LLM (it never sees them)
+ *   2. execute() — if LLM somehow calls a blocked tool, returns error
+ *
+ * The permission check runs every loop iteration (per-turn), so permissions
+ * can change mid-conversation (e.g., user grants access after auth step).
+ *
+ * Narrative integration: blocked execution returns an error result that
+ * flows through the normal tool result path → recorders see it via
+ * onToolCall, LLM sees it in conversation history and can respond.
+ *
+ * Optional onBlocked callback for observability (logging, metrics).
+ *
+ * Usage:
+ *   // Static permission set
+ *   const tools = gatedTools(
+ *     staticTools([searchTool, adminTool, codeTool]),
+ *     (toolId) => userPermissions.has(toolId),
+ *   );
+ *
+ *   // Context-aware (per-turn)
+ *   const tools = gatedTools(
+ *     staticTools(allTools),
+ *     (toolId, ctx) => {
+ *       if (ctx.turnNumber > 5) return false; // rate limit
+ *       return allowedTools.has(toolId);
+ *     },
+ *   );
+ *
+ *   // With observability
+ *   const tools = gatedTools(
+ *     staticTools(allTools),
+ *     (toolId) => permissions.has(toolId),
+ *     { onBlocked: (toolId, phase) => console.log(`Blocked ${toolId} at ${phase}`) },
+ *   );
+ */
+export function gatedTools(inner, isAllowed, options) {
+    // Track the last ToolContext for use in execute() which doesn't receive it
+    let lastContext;
+    return {
+        resolve: async (context) => {
+            lastContext = context;
+            const innerDecision = await inner.resolve(context);
+            // Filter: only return tools the user has permission for
+            const allowed = [];
+            const blocked = [];
+            for (const tool of innerDecision.value) {
+                const permitted = await isAllowed(tool.name, context);
+                if (permitted) {
+                    allowed.push(tool);
+                }
+                else {
+                    blocked.push(tool.name);
+                    options?.onBlocked?.(tool.name, 'resolve', context);
+                }
+            }
+            return {
+                value: allowed,
+                chosen: blocked.length > 0 ? 'gated' : innerDecision.chosen,
+                rationale: blocked.length > 0
+                    ? `${allowed.length} allowed, ${blocked.length} blocked: ${blocked.join(', ')}`
+                    : innerDecision.rationale,
+            };
+        },
+        execute: inner.execute
+            ? async (call, signal) => {
+                // Defense in depth: check permission even at execute time
+                // (in case LLM hallucinates a tool name that was filtered from resolve)
+                const ctx = lastContext ?? { message: '', turnNumber: 0, loopIteration: 0, messages: [] };
+                const permitted = await isAllowed(call.name, ctx);
+                if (!permitted) {
+                    options?.onBlocked?.(call.name, 'execute', ctx);
+                    // This error flows into conversation history — LLM sees it
+                    // and recorders capture it via onToolCall
+                    return {
+                        content: `Permission denied: tool "${call.name}" is not available. ` +
+                            `Available tools are listed in the system prompt.`,
+                        error: true,
+                    };
+                }
+                return inner.execute(call, signal);
+            }
+            : undefined,
+    };
+}
+//# sourceMappingURL=gatedTools.js.map

package/dist/esm/providers/tools/gatedTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatedTools.js","sourceRoot":"","sources":["../../../../src/providers/tools/gatedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAiBH,MAAM,UAAU,UAAU,CACxB,KAAmB,EACnB,SAA4B,EAC5B,OAA2B;IAE3B,2EAA2E;IAC3E,IAAI,WAAoC,CAAC;IAEzC,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,OAAoB,EAAE,EAAE;YACtC,WAAW,GAAG,OAAO,CAAC;YACtB,MAAM,aAAa,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAEnD,wDAAwD;YACxD,MAAM,OAAO,GAAyB,EAAE,CAAC;YACzC,MAAM,OAAO,GAAa,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC;gBACvC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBACtD,IAAI,SAAS,EAAE,CAAC;oBACd,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACxB,OAAO,EAAE,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YACD,OAAO;gBACL,KAAK,EAAE,OAAO;gBACd,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM;gBAC3D,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;oBAC3B,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,aAAa,OAAO,CAAC,MAAM,aAAa,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC/E,CAAC,CAAC,aAAa,CAAC,SAAS;aAC5B,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,KAAK,CAAC,OAAO;YACpB,CAAC,CAAC,KAAK,EAAE,IAAc,EAAE,MAAoB,EAAgC,EAAE;gBAC3E,0DAA0D;gBAC1D,wEAAwE;gBACxE,MAAM,GAAG,GAAG,WAAW,IAAK,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAkB,CAAC;gBAC3G,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBAElD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,OAAO,EAAE,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;oBAChD,2DAA2D;oBAC3D,0CAA0C;oBAC1C,OAAO;wBACL,OAAO,EAAE,4BAA4B,IAAI,CAAC,IAAI,sBAAsB;4BAClE,kDAAkD;wBACpD,KAAK,EAAE,IAAI;qBACZ,CAAC;gBACJ,CAAC;gBAED,OAAO,KAAK,CAAC,OAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACtC,CAAC;YACH,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC"}

package/dist/esm/providers/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * providers/tools/ — Built-in ToolProvider implementations.
+ */
+export { staticTools } from './staticTools';
+export { dynamicTools } from './dynamicTools';
+export { noTools } from './noTools';
+export { agentAsTool } from './agentAsTool';
+export { compositeTools } from './compositeTools';
+export { gatedTools } from './gatedTools';
+export { PermissionPolicy } from './PermissionPolicy';
+//# sourceMappingURL=index.js.map

package/dist/esm/providers/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/providers/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/esm/providers/tools/noTools.js

@@ -0,0 +1,9 @@
+/**
+ * noTools — ToolProvider that provides no tools.
+ */
+export function noTools() {
+    return {
+        resolve: () => ({ value: [], chosen: 'none' }),
+    };
+}
+//# sourceMappingURL=noTools.js.map

package/dist/esm/providers/tools/noTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noTools.js","sourceRoot":"","sources":["../../../../src/providers/tools/noTools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,UAAU,OAAO;IACrB,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC"}

package/dist/esm/providers/tools/staticTools.js

@@ -0,0 +1,25 @@
+/**
+ * staticTools — ToolProvider with a fixed list of tools.
+ */
+export function staticTools(tools) {
+    const toolMap = new Map(tools.map((t) => [t.id, t]));
+    return {
+        resolve: () => ({
+            value: tools.map((t) => ({
+                name: t.id,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+            chosen: 'static',
+            rationale: `${tools.length} tool${tools.length !== 1 ? 's' : ''}`,
+        }),
+        execute: async (call) => {
+            const tool = toolMap.get(call.name);
+            if (!tool) {
+                return { content: `Unknown tool: ${call.name}`, error: true };
+            }
+            return tool.handler(call.arguments);
+        },
+    };
+}
+//# sourceMappingURL=staticTools.js.map

package/dist/esm/providers/tools/staticTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticTools.js","sourceRoot":"","sources":["../../../../src/providers/tools/staticTools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErD,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACvB,IAAI,EAAE,CAAC,CAAC,EAAE;gBACV,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;aAC3B,CAAC,CAAC;YACH,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,GAAG,KAAK,CAAC,MAAM,QAAQ,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;SAClE,CAAC;QAEF,OAAO,EAAE,KAAK,EAAE,IAAc,EAAgC,EAAE;YAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,OAAO,EAAE,iBAAiB,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAChE,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/providers.barrel.js

@@ -0,0 +1,32 @@
+/**
+ * agentfootprint/providers — Connect to LLM providers.
+ *
+ * Import from here to connect your agent to Anthropic, OpenAI, Bedrock, Ollama, or mock.
+ *
+ * @example
+ * ```typescript
+ * import { mock, anthropic, createProvider } from 'agentfootprint/providers';
+ *
+ * // Testing — deterministic, $0
+ * const provider = mock([{ content: 'Hello!' }]);
+ *
+ * // Production — swap one line
+ * const provider = createProvider(anthropic('claude-sonnet-4-20250514'));
+ * ```
+ */
+// Provider factories
+export { anthropic, openai, ollama, bedrock } from './models';
+export { DEFAULT_PRICING, lookupPricing } from './models';
+// Adapters
+export { MockAdapter, mock, MockRetriever, mockRetriever, createProvider } from './adapters';
+export { AnthropicAdapter, OpenAIAdapter, BedrockAdapter } from './adapters';
+export { BrowserAnthropicAdapter, BrowserOpenAIAdapter } from './adapters';
+// Protocol adapters
+export { mcpToolProvider, a2aRunner } from './adapters';
+// Tool provider strategies
+export { agentAsTool, compositeTools, gatedTools } from './providers';
+// Prompt strategies
+export { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from './providers';
+// Memory strategies
+export { InMemoryStore } from './adapters/memory/inMemory';
+//# sourceMappingURL=providers.barrel.js.map

package/dist/esm/providers.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.barrel.js","sourceRoot":"","sources":["../../src/providers.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,qBAAqB;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1D,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAW3E,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOxD,2BAA2B;AAC3B,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGtE,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9F,oBAAoB;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/esm/recorders/index.js

@@ -0,0 +1,5 @@
+/**
+ * recorders/ — AgentRecorder implementations.
+ */
+export { TokenRecorder, CostRecorder, TurnRecorder, ToolUsageRecorder, QualityRecorder, GuardrailRecorder, CompositeRecorder, PermissionRecorder, agentObservability, } from './v2';
+//# sourceMappingURL=index.js.map

package/dist/esm/recorders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/recorders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,MAAM,CAAC"}

package/dist/esm/recorders/v2/CompositeRecorder.js

@@ -0,0 +1,65 @@
+/**
+ * CompositeRecorder — fans out events to multiple AgentRecorders.
+ *
+ * Convenience wrapper that dispatches each event to all child recorders.
+ * Error in one recorder does not affect others (error isolation).
+ *
+ * Usage:
+ *   const composite = new CompositeRecorder([
+ *     new TokenRecorder(),
+ *     new QualityRecorder(judge),
+ *     new GuardrailRecorder(check),
+ *   ]);
+ *   agent.recorder(composite);
+ */
+export class CompositeRecorder {
+    id;
+    recorders;
+    constructor(recorders, id = 'composite-recorder') {
+        this.recorders = recorders;
+        this.id = id;
+    }
+    onTurnStart(event) {
+        this.dispatch('onTurnStart', event);
+    }
+    onLLMCall(event) {
+        this.dispatch('onLLMCall', event);
+    }
+    onToolCall(event) {
+        this.dispatch('onToolCall', event);
+    }
+    onTurnComplete(event) {
+        this.dispatch('onTurnComplete', event);
+    }
+    onError(event) {
+        this.dispatch('onError', event);
+    }
+    clear() {
+        for (const recorder of this.recorders) {
+            try {
+                recorder.clear?.();
+            }
+            catch {
+                /* error isolation */
+            }
+        }
+    }
+    /** Access child recorders for inspection. */
+    getRecorders() {
+        return this.recorders;
+    }
+    dispatch(hook, event) {
+        for (const recorder of this.recorders) {
+            try {
+                const fn = recorder[hook];
+                if (typeof fn === 'function') {
+                    fn.call(recorder, event);
+                }
+            }
+            catch {
+                // Error isolation — one recorder failure must not affect others
+            }
+        }
+    }
+}
+//# sourceMappingURL=CompositeRecorder.js.map

package/dist/esm/recorders/v2/CompositeRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/v2/CompositeRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,MAAM,OAAO,iBAAiB;IACnB,EAAE,CAAS;IACH,SAAS,CAA2B;IAErD,YAAY,SAAmC,EAAE,EAAE,GAAG,oBAAoB;QACxE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,WAAW,CAAC,KAAqB;QAC/B,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,UAAU,CAAC,KAAoB;QAC7B,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,cAAc,CAAC,KAAwB;QACrC,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,KAAsB;QAC5B,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,KAAK;QACH,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,qBAAqB;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAEO,QAAQ,CAAC,IAAyB,EAAE,KAAc;QACxD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC1B,IAAI,OAAO,EAAE,KAAK,UAAU,EAAE,CAAC;oBAC5B,EAA2B,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;YAClE,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/esm/recorders/v2/CostRecorder.js

@@ -0,0 +1,47 @@
+/**
+ * CostRecorder (v2) — calculates USD cost from AgentRecorder LLM call events.
+ *
+ * Unlike the v1 CostRecorder (which observes scope writes), this one
+ * receives structured LLMCallEvent objects from the core loop.
+ *
+ * Usage:
+ *   const cost = new CostRecorder({ pricingTable: { 'claude-sonnet': { input: 3, output: 15 } } });
+ *   agent.recorder(cost);
+ *   await agent.run(...);
+ *   console.log(`$${cost.getTotalCost().toFixed(4)}`);
+ */
+export class CostRecorder {
+    id;
+    entries = [];
+    pricingTable;
+    constructor(options = {}) {
+        this.id = options.id ?? 'cost-recorder';
+        this.pricingTable = options.pricingTable ?? {};
+    }
+    onLLMCall(event) {
+        const model = event.model ?? 'unknown';
+        const inputTokens = event.usage?.inputTokens ?? 0;
+        const outputTokens = event.usage?.outputTokens ?? 0;
+        const pricing = this.pricingTable[model];
+        const inputCost = pricing ? (inputTokens / 1_000_000) * pricing.input : 0;
+        const outputCost = pricing ? (outputTokens / 1_000_000) * pricing.output : 0;
+        this.entries.push({
+            model,
+            inputTokens,
+            outputTokens,
+            inputCost,
+            outputCost,
+            totalCost: inputCost + outputCost,
+        });
+    }
+    getTotalCost() {
+        return this.entries.reduce((s, e) => s + e.totalCost, 0);
+    }
+    getEntries() {
+        return [...this.entries];
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+//# sourceMappingURL=CostRecorder.js.map

package/dist/esm/recorders/v2/CostRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CostRecorder.js","sourceRoot":"","sources":["../../../../src/recorders/v2/CostRecorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA0BH,MAAM,OAAO,YAAY;IACd,EAAE,CAAS;IACZ,OAAO,GAAgB,EAAE,CAAC;IAC1B,YAAY,CAA+B;IAEnD,YAAY,UAA+B,EAAE;QAC3C,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAmB;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC;QAClD,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,EAAE,YAAY,IAAI,CAAC,CAAC;QAEpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE7E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,KAAK;YACL,WAAW;YACX,YAAY;YACZ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,SAAS,GAAG,UAAU;SAClC,CAAC,CAAC;IACL,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF"}