agentfootprint 2.2.0 → 2.4.0

package/dist/types/lib/injection-engine/factories/defineSkill.d.ts

@@ -28,6 +28,55 @@
  */
 import type { Injection } from '../types.js';
 import type { Tool } from '../../../core/tools.js';
+/**
+ * Where the Skill's body lands when activated.
+ *
+ * - `'system-prompt'` — body appended to the system slot on the
+ *   iteration after activation. Best on Claude ≥ 3.5 (training-time
+ *   adherence to system-prompt instructions is strong).
+ * - `'tool-only'` — body delivered ONLY via the `read_skill` tool's
+ *   result. Recency-first by protocol; doesn't rely on the model's
+ *   training to honor system-prompt anchoring. Default for every
+ *   non-Claude provider.
+ * - `'both'` — body lands in both the system slot AND the tool result.
+ *   Belt-and-suspenders for high-stakes Skills on long-context runs.
+ * - `'auto'` — the library picks per provider via `resolveSurfaceMode`.
+ *   `'both'` on Claude ≥ 3.5; `'tool-only'` everywhere else.
+ *
+ * **Today's behavior:** all four modes route through the recency-first
+ * path the essay describes as cross-provider-correct (the activation +
+ * next-iteration injection pattern). Full per-mode routing diversity
+ * (suppress system-prompt for `'tool-only'`, e.g.) is a v2.5 polish.
+ * Consumers express intent today; runtime behavior tightens later
+ * without API change.
+ */
+export type SurfaceMode = 'auto' | 'system-prompt' | 'tool-only' | 'both';
+/**
+ * When (if ever) to re-deliver a Skill's body in long-running runs.
+ *
+ * Even on providers with strong system-prompt adherence, attention to
+ * the system slot decays past long contexts. `refreshPolicy` re-injects
+ * the body via tool result past a token threshold so the LLM sees it
+ * fresh again.
+ *
+ * **v2.4 status:** the field is reserved + typed; the runtime hook
+ * lands in v2.5 as part of the long-context attention work. Specifying
+ * `refreshPolicy` today is non-breaking — the engine ignores it until
+ * the hook is implemented.
+ */
+export interface RefreshPolicy {
+    /**
+     * Re-inject the Skill body once the run has consumed this many input
+     * tokens since the Skill was last surfaced. Recommended: 50_000 for
+     * 200k-context models; 20_000 for 32k-context models.
+     */
+    readonly afterTokens: number;
+    /**
+     * How to re-inject. `'tool-result'` synthesizes a fresh tool result
+     * carrying the body text (recency-first). Other modes reserved.
+     */
+    readonly via: 'tool-result';
+}
 export interface DefineSkillOptions {
     readonly id: string;
     /** Visible to the LLM via the activation tool's description. */
@@ -42,6 +91,29 @@ export interface DefineSkillOptions {
      * the LLM picks WHICH skill via the tool's argument.
      */
     readonly viaToolName?: string;
+    /**
+     * Where the body lands when activated. See `SurfaceMode`. Default
+     * `'auto'` — the library resolves per provider via `resolveSurfaceMode`.
+     */
+    readonly surfaceMode?: SurfaceMode;
+    /**
+     * Re-deliver the body past a token threshold to defend against
+     * long-context attention decay. Default: undefined (no refresh).
+     */
+    readonly refreshPolicy?: RefreshPolicy;
 }
+/**
+ * Resolve `surfaceMode: 'auto'` to a concrete mode based on provider
+ * + model. The defaults match the per-provider attention profile
+ * documented in the Skills, explained essay:
+ *
+ *   - Claude >= 3.5  → 'both'      (cheap to cache, high adherence)
+ *   - Claude pre-3.5 → 'tool-only' (recency-first more reliable)
+ *   - OpenAI / Bedrock / Ollama / Mock / unknown → 'tool-only'
+ *
+ * Pure function — no side effects. Consumers can call directly to
+ * inspect what `'auto'` will resolve to in their stack.
+ */
+export declare function resolveSurfaceMode(provider: string, model?: string): SurfaceMode;
 export declare function defineSkill(opts: DefineSkillOptions): Injection;
 //# sourceMappingURL=defineSkill.d.ts.map

package/dist/types/lib/injection-engine/factories/defineSkill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CAyB/D"}
+{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAahF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CAiC/D"}

package/dist/types/lib/injection-engine/index.d.ts

@@ -4,66 +4,13 @@
  * The unifying primitive of agentfootprint context engineering.
  * One `Injection` type. One `InjectionEngine` subflow. N typed sugar
  * factories. See `README.md` in this folder for the full concept.
- *
- * ─── 7-panel design review (2026-04-28) ─────────────────────────────
- *
- *   LLM-AI system design   ✓ ONE primitive replaces N feature-specific
- *                            subsystems. Skill, Steering, Instruction,
- *                            Context (and RAG, Memory, Guardrail)
- *                            are typed sugar producing the same shape.
- *                            Engine is shared; observability is shared;
- *                            Lens chips are shared.
- *
- *   Performance            ✓ Trigger evaluation O(N) per iteration.
- *                            Subflow ceremony ~50µs per iteration.
- *                            Negligible. Active set materialized once,
- *                            consumed by 3 slot subflows.
- *
- *   Scalability            ✓ Adding a flavor = adding a sugar factory
- *                            file. Zero engine change. Library scales
- *                            to 50+ flavors without bloating the
- *                            engine. The "narrow waist" pattern.
- *
- *   Research alignment     ✓ Maps to "Augmented LM" framing
- *                            (Mialon et al. 2023): every external
- *                            input is an augmentation; agentfootprint
- *                            calls them Injections. Factory names
- *                            preserve research vocabulary (Skill, RAG,
- *                            Memory, Steering) at the API surface.
- *
- *   Flexibility            ✓ Discriminated `trigger` union handles
- *                            always / rule / on-tool-return /
- *                            llm-activated. New trigger kinds extend
- *                            cleanly. Multi-slot per Injection covers
- *                            Skills (system-prompt + tools).
- *
- *   Abstraction-modular    ✓ Engine = subflow (drill-able). Factories
- *                            = small files (one per flavor). Slot
- *                            subflows are unchanged consumers.
- *                            Textbook narrow-waist architecture.
- *
- *   Software engineering   ✓ Predicate exceptions caught + reported
- *                            via `skipped[]`, never propagate. Frozen
- *                            Injections. Validation in factories.
- *                            7-pattern test coverage. Subpath export
- *                            for tree-shake.
- *
- * Plus footprintjs integration check ✓ — uses existing slot subflow
- * convention (writes activeInjections to scope; slots filter by
- * targeted slot) + ContextRecorder picks up source field zero-change.
- *
- * Plus TypeScript engineer check ✓ — discriminated union, no `any`,
- * frozen returns, exhaustiveness check on trigger kind.
- *
- * ─── 7-pattern test coverage ────────────────────────────────────────
- *
- *   See `test/lib/injection-engine/*.test.ts`.
  */
 export type { Injection, InjectionTrigger, InjectionContent, InjectionContext, InjectionEvaluation, } from './types.js';
 export { evaluateInjections } from './evaluator.js';
 export { buildInjectionEngineSubflow, type InjectionEngineConfig, } from './buildInjectionEngineSubflow.js';
 export { defineInstruction, type DefineInstructionOptions } from './factories/defineInstruction.js';
-export { defineSkill, type DefineSkillOptions } from './factories/defineSkill.js';
+export { defineSkill, resolveSurfaceMode, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, } from './factories/defineSkill.js';
+export { SkillRegistry } from './SkillRegistry.js';
 export { defineSteering, type DefineSteeringOptions } from './factories/defineSteering.js';
 export { defineFact, type DefineFactOptions } from './factories/defineFact.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/lib/injection-engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAElF,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/types/lib/injection-engine/types.d.ts

@@ -131,6 +131,16 @@ export interface Injection {
     readonly trigger: InjectionTrigger;
     /** WHAT to contribute (one or more slots). */
     readonly inject: InjectionContent;
+    /**
+     * Optional flavor-specific metadata. Engine ignores keys it doesn't
+     * recognize; flavor factories use this for opt-in fields without
+     * widening the Injection contract.
+     *
+     * Known keys:
+     *   - `surfaceMode` (Skill) — `'auto' | 'system-prompt' | 'tool-only' | 'both'`
+     *   - `refreshPolicy` (Skill) — `{ afterTokens, via }`
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 /**
  * Returned by `evaluateInjections()`. Slot subflows consume `active`;

package/dist/types/lib/injection-engine/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/types.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/mcp/index.d.ts

@@ -5,5 +5,6 @@
  * use case, not yet shipped).
  */
 export { mcpClient } from './mcpClient.js';
+export { mockMcpClient, type MockMcpClientOptions, type MockMcpTool } from './mockMcpClient.js';
 export type { McpClient, McpClientOptions, McpHttpTransport, McpStdioTransport, McpTransport, McpSdkClient, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/lib/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAChG,YAAY,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/types/lib/mcp/mcpClient.d.ts

@@ -29,23 +29,6 @@
  *          `McpClientOptions` so observability surfaces can group
  *          tool calls by server.
  *
- * 7-panel review (2026-04-29):
- * - LLM Systems    ✅  inputSchema preserved verbatim — the LLM sees
- *                      the same tool schema MCP advertised
- * - Architect      ✅  pure adapter; no engine code. New tool sources
- *                      slot in via the same `Tool` interface
- * - API Designer   ✅  three methods (.tools / .refresh / .close)
- *                      mirror the MCP SDK lifecycle
- * - Performance    ✅  tool list cached after first fetch; .refresh
- *                      is opt-in. callTool round-trip is one network
- *                      hop per tool call (same as direct LLM-tool flow)
- * - Privacy        ✅  no implicit logging; consumer controls auth
- *                      via transport headers
- * - SoftEng        ✅  lazy-required SDK + friendly install error;
- *                      mock injection point for tests
- * - TS Engineer    ✅  structural McpSdkClient shim — works against
- *                      any future SDK version with the same shape
- *
  * Lazy-require pattern: the `@modelcontextprotocol/sdk` peer-dep
  * loads only when a consumer actually constructs a client. Tests
  * inject `_client` and skip the import path entirely.

package/dist/types/lib/mcp/mcpClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAA8B,MAAM,YAAY,CAAC;AAO1F;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4B1E"}
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAA8B,MAAM,YAAY,CAAC;AAU1F;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAyC1E"}

package/dist/types/lib/mcp/mockMcpClient.d.ts

@@ -0,0 +1,66 @@
+/**
+ * mockMcpClient — in-memory MCP client for development and tests.
+ *
+ *   const slack = mockMcpClient({
+ *     tools: [
+ *       {
+ *         name: 'send_message',
+ *         description: 'Post a message to a channel',
+ *         inputSchema: { type: 'object' },
+ *         handler: async ({ text }) => `Posted: ${text}`,
+ *       },
+ *     ],
+ *   });
+ *
+ *   const agent = Agent.create({ provider: mock({ reply: 'ok' }) })
+ *     .tools(await slack.tools())
+ *     .build();
+ *
+ * Pattern: Adapter (GoF) — produces an `McpClient` with the same shape
+ *          as `mcpClient(opts)` but driven by an in-memory tool table
+ *          instead of the MCP SDK + transport. Drop-in for development:
+ *          start with `mockMcpClient`, swap to `mcpClient` once the
+ *          real server is ready.
+ *
+ * Why public: `mcpClient`'s `_client` injection is `@internal` because
+ * the SDK shape isn't a stable public surface. `mockMcpClient` exposes
+ * a curated tool-handler shape that's tied to OUR Tool contract instead
+ * — stable, documented, and the right level of abstraction for
+ * mock-first development.
+ */
+import type { McpClient } from './types.js';
+/** A scripted tool exposed by the mock MCP server. */
+export interface MockMcpTool {
+    /** Tool name as the LLM sees it. */
+    readonly name: string;
+    /** Description surfaced to the LLM via the tool schema. */
+    readonly description?: string;
+    /**
+     * JSON-schema-like input schema. Passed through to the agent's tool
+     * registry verbatim — same as a real MCP server's `listTools()`.
+     */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /**
+     * Async handler that runs when the agent calls this tool. Receives
+     * the args the LLM produced; returns the string result the agent
+     * sees as the tool-result message.
+     *
+     * Defaults to `async () => '[mock result]'` when omitted — useful
+     * when the consumer cares about wiring not behavior.
+     */
+    readonly handler?: (args: Record<string, unknown>) => Promise<string>;
+}
+export interface MockMcpClientOptions {
+    /** Logical server name. Surfaces in observability + error messages. */
+    readonly name?: string;
+    /** Tools exposed by the mock server. */
+    readonly tools: readonly MockMcpTool[];
+}
+/**
+ * Build an in-memory `McpClient`. Useful when you want to develop
+ * against MCP semantics without spawning subprocesses, hitting the
+ * network, or installing `@modelcontextprotocol/sdk`. Same `McpClient`
+ * shape as `mcpClient(opts)` — code that consumes one accepts the other.
+ */
+export declare function mockMcpClient(options: MockMcpClientOptions): McpClient;
+//# sourceMappingURL=mockMcpClient.d.ts.map

package/dist/types/lib/mcp/mockMcpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockMcpClient.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/mockMcpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAoCtE"}

package/dist/types/lib/mcp/types.d.ts

@@ -120,6 +120,8 @@ export interface McpSdkClient {
     callTool(args: {
         readonly name: string;
         readonly arguments?: Readonly<Record<string, unknown>>;
+        /** Forwarded from `McpClientOptions.signal` so consumers can cancel hung tool calls. */
+        readonly signal?: AbortSignal;
     }): Promise<{
         readonly content: ReadonlyArray<{
             readonly type: string;

package/dist/types/lib/mcp/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/lib/mcp/types.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/rag/defineRAG.d.ts

@@ -29,24 +29,6 @@
  *          `agentfootprint.context.injected` when retrieved chunks
  *          land in the messages slot.
  *
- * 7-panel review (2026-04-29):
- * - LLM Systems    ✅  injects as 'user' role by default — RAG chunks
- *                      land where the LLM treats them as authoritative
- *                      retrieved context, not behavior rules
- * - Architect      ✅  composition over defineMemory; zero new engine
- *                      code; multi-RAG layering works via per-id keys
- * - API Designer   ✅  one factory, mirrors defineMemory shape; consumer
- *                      ergonomics: `agent.rag(defineRAG({...}))`
- * - Performance    ✅  embedding cost is one call per turn (TURN_START
- *                      timing, default); strict threshold prevents
- *                      injecting low-confidence noise
- * - Privacy        ✅  multi-tenant via MemoryIdentity tuple; doc
- *                      content never crosses tenant boundaries
- * - ML / IR        ✅  embedder version pinned via `embedderId`; cosine
- *                      score semantics inherited from MemoryStore
- * - SoftEng        ✅  thin file (this one); existing memory tests
- *                      cover the underlying pipeline
- *
  * @see ./indexDocuments.ts  for the seeding helper
  * @see ../../memory/define.ts  for the underlying factory
  *
@@ -119,13 +101,28 @@ export interface DefineRAGOptions {
      * Minimum cosine similarity to inject. **Strict** — when no chunk
      * meets the threshold, NO injection happens (no fallback that would
      * pollute the prompt with weak matches). Default 0.7.
+     *
+     * Tuning note: 0.7 is a high bar for some embedders. Sentence-BERT
+     * relatives (`all-MiniLM-L6-v2`, etc.) often score 0.4–0.6 even on
+     * relevant chunks. If you see frequent zero-result silent skips,
+     * lower to ~0.5 and observe the `agentfootprint.context.injected`
+     * stream. OpenAI `text-embedding-3-*` and Cohere embed-v3 typically
+     * sit comfortably with 0.7.
      */
     readonly threshold?: number;
     /**
      * Role to use when injecting retrieved chunks into the messages
-     * slot. Default `'user'` — RAG chunks are most often treated as
-     * "context the user provided" by LLMs. Use `'system'` for
-     * authoritative reference docs that should outweigh user instruction.
+     * slot. Default `'user'`.
+     *
+     * Why `'user'`: in tool-using ReAct loops, retrieved chunks
+     * conceptually "augment what the user asked." Anthropic's tool-use
+     * cookbook and OpenAI's RAG cookbook both show retrieved context
+     * inside user-turn messages.
+     *
+     * Use `'system'` for authoritative reference docs that should
+     * outweigh user instruction (policy / compliance / brand-voice
+     * corpora). Use `'assistant'` only if you've persisted prior agent
+     * turns as context — rare.
      */
     readonly asRole?: ContextRole;
 }

package/dist/types/lib/rag/defineRAG.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineRAG.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CA8BlE"}
+{"version":3,"file":"defineRAG.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/defineRAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CA8BlE"}

package/dist/types/lib/rag/indexDocuments.d.ts

@@ -41,7 +41,20 @@ export interface IndexDocumentsOptions {
     /**
      * Identity scope to write under. Default: a single shared
      * `{ conversationId: '_global' }` namespace, suitable for app-wide
-     * corpora. Override for per-tenant document partitions.
+     * corpora.
+     *
+     * **Multi-tenant footgun:** the read side (`agent.run({ identity })`)
+     * queries within whichever identity is passed at request time.
+     * If you index here under `_global` but query under
+     * `{ tenant: 'acme' }`, you'll get ZERO results — silently. Either:
+     *   1. Index every document under each tenant's identity (duplicated
+     *      storage, but isolated), or
+     *   2. Index under `_global` AND query under `_global` (shared
+     *      corpus across tenants — fine for product docs, NOT for
+     *      tenant-private data), or
+     *   3. Use a vector store adapter that supports multi-namespace
+     *      reads at query time (Pinecone, Qdrant — outside this helper's
+     *      scope).
      */
     readonly identity?: MemoryIdentity;
     /**
@@ -67,11 +80,27 @@ export interface IndexDocumentsOptions {
      * this through to abort batch indexing on shutdown / timeout.
      */
     readonly signal?: AbortSignal;
+    /**
+     * Max number of concurrent embed calls when the embedder doesn't
+     * implement `embedBatch`. Default `8`. Without this cap, a 10K-doc
+     * corpus would fire 10K parallel embed calls and trigger rate limits.
+     * Ignored when `embedBatch` is available (the embedder controls
+     * its own batching).
+     */
+    readonly maxConcurrency?: number;
 }
 /**
  * Embed + persist documents. Returns the count actually indexed
  * (skips duplicates if the store rejects them). Throws on embedder
  * failure or store error — fail loud at startup is desirable.
+ *
+ * **Re-indexing semantics:** entries are written with `version: 1` and
+ * `putMany` (most adapters: last-write-wins). Re-running this helper
+ * after the store has been mutated by other writers may stomp their
+ * versions. For idempotent corpus refresh, either delete-then-index
+ * or use a custom upsert via `store.putIfVersion()` per document. A
+ * first-class `mode: 'upsert' | 'replace'` API is planned for a
+ * future release.
  */
 export declare function indexDocuments(store: MemoryStore, embedder: Embedder, documents: readonly RagDocument[], options?: IndexDocumentsOptions): Promise<number>;
 //# sourceMappingURL=indexDocuments.d.ts.map

package/dist/types/lib/rag/indexDocuments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexDocuments.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAID;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAwCjB"}
+{"version":3,"file":"indexDocuments.d.ts","sourceRoot":"","sources":["../../../../src/lib/rag/indexDocuments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA6CjB"}

package/dist/types/memory/causal/loadSnapshot.d.ts

@@ -12,7 +12,7 @@
  * Strict-threshold semantics:
  *   When `minScore` is set and no past snapshot meets it, returns an
  *   empty `formatted`. NO fallback — garbage past context is worse than
- *   no context. Aligns with the LLM-systems panel verdict in the design.
+ *   no context.
  *
  * Empty-query handling:
  *   No user message → no embedding → no search → empty result.

package/dist/types/memory/define.d.ts

@@ -23,22 +23,8 @@
  *          `agentfootprint.context.injected` with `source: 'memory'`
  *          when their formatter writes to the messages slot.
  *
- * 8-panel review (2026-04-28):
- * - LLM Systems   ✅  asRole knob honored when present, defaults to 'system'
- * - Architect     ✅  per-id scope keys (`memoryInjectionKey(id)`)
- * - API Designer  ✅  one factory; CAUSAL stays here, no separate snapshotMemory
- * - Performance   ✅  default `MEMORY_TIMING.TURN_START`; pipelines compiled once
- * - Privacy       ✅  redact field passes through
- * - ML / IR       ✅  threshold maps to semantic.minScore strictly; no fallback
- * - SoftEng       ✅  unsupported combos throw with clear remediation hint
- * - TS Engineer   ✅  discriminated union narrowing preserved across switches
- *
- * Book reference: AI Agents — The Definitive Guide, Ch 10 (Memory,
- *   Autonomy, Long-Horizon Use — chapter still unavailable in pre-pub).
- *
  * @see ./define.types.ts        for the const-objects + types
  * @see ./pipeline/*.ts          for the existing pipeline factories this dispatches to
- * @see MEMORY.md                load-bearing design memory
  */
 import { type DefineMemoryOptions } from './define.types.js';
 import type { MemoryDefinition, ReadonlyMemoryFlowChart } from './define.types.js';

package/dist/types/memory/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAaH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAqB3E;AA6RD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAaH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAqB3E;AA6RD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}

package/dist/types/memory/define.types.d.ts

@@ -32,16 +32,6 @@
  *          `agentfootprint.context.injected` event with `source: 'memory'`
  *          when its read subflow places content into the messages slot.
  *
- * 8-panel review (2026-04-28):
- * - LLM Systems   ✅  asRole knob added so memories can land as user/system/assistant
- * - Architect     ✅  per-id scope keys (`memoryInjection_${id}`) — multi-memory layering safe
- * - API Designer  ✅  ONE factory for all four types incl. Causal (no separate `snapshotMemory`)
- * - Performance   ✅  default `MEMORY_TIMING.TURN_START` (was per-iteration — perf trap)
- * - Privacy       ✅  `redact?` API hook reserved
- * - ML / IR       ✅  causal snapshots tagged with original query for retrieval embedding
- * - SoftEng       ✅  discriminated union with `kind` discriminator → full TS narrowing
- * - TS Engineer   ✅  generic over `MemoryEntry<T>` payload preserves type-safety
- *
  * @see ./define.ts          for the `defineMemory()` factory itself
  * @see ../../docs-site      for guides + the 7 strategy examples
  * @see MEMORY.md            for the load-bearing design memory
@@ -193,8 +183,8 @@ export type Strategy = WindowStrategy | BudgetStrategy | SummarizeStrategy | Top
 /**
  * Reserved API surface for content redaction before memory writes.
  * Impl is deferred; the field exists now so adding redaction later
- * is non-breaking. Privacy panel review: snapshot/episodic writes may
- * carry PII — this is the integration point.
+ * is non-breaking. Snapshot/episodic writes may carry PII — this is
+ * the integration point.
  */
 export interface MemoryRedactionPolicy {
     /** Patterns to mask in stored content. */

package/dist/types/memory/define.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"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"}

package/dist/types/resilience/index.d.ts

@@ -14,50 +14,6 @@
  *
  * Reads as: try anthropic; on failure fall back to openai; the whole
  * chain is wrapped in retry with 5 attempts.
- *
- * ─── 7-panel design review (2026-04-28) ────────────────────────────
- *
- *   LLM-AI system design   ✓ Decorator pattern around the existing
- *                            `LLMProvider` port — no new contract.
- *                            Stacks naturally; observation hooks
- *                            (`onRetry`, `onFallback`) keep the
- *                            recorder ecosystem informed.
- *   Performance            ✓ Zero overhead on success path (one
- *                            `try/await` per call). Backoff delays
- *                            use AbortSignal-aware sleep — no busy
- *                            wait, no leaked timers.
- *   Scalability            ✓ Per-call state only. Composition is
- *                            constant-time per attempt; chain depth
- *                            doesn't grow runtime cost.
- *   Research alignment     ✓ Right-fold of `withFallback` matches
- *                            the standard chain-of-responsibility
- *                            shape. No exotic resumption — once a
- *                            stream yields, it commits.
- *   Flexibility            ✓ Predicates (`shouldRetry`,
- *                            `shouldFallback`) and hooks
- *                            (`onRetry`, `onFallback`) make every
- *                            policy decision overridable. Default
- *                            policies match common real-world signals
- *                            (4xx skip, 429 retry, AbortError pass).
- *   Abstraction-modular    ✓ Three primitives, one purpose each.
- *                            `fallbackProvider` is sugar over chained
- *                            `withFallback`. No surprises.
- *   Software engineering   ✓ Pure decorators — no shared state.
- *                            Every option has a documented default.
- *                            Tests cover unit + scenario + integration
- *                            + property + security + performance + ROI.
- *
- * ─── 7-pattern test coverage ───────────────────────────────────────
- *
- *   Unit         test/resilience/unit/withRetry.test.ts
- *                test/resilience/unit/withFallback.test.ts
- *                test/resilience/unit/fallbackProvider.test.ts
- *   Scenario     resilience-patterns.test.ts → "production recipes"
- *   Integration  resilience-patterns.test.ts → "Agent + resilient provider"
- *   Property     resilience-patterns.test.ts → "invariants"
- *   Security     resilience-patterns.test.ts → "hostile inputs"
- *   Performance  resilience-patterns.test.ts → "performance"
- *   ROI          resilience-patterns.test.ts → "realistic SLO budgets"
  */
 export { withRetry, type WithRetryOptions } from './withRetry.js';
 export { withFallback, type WithFallbackOptions } from './withFallback.js';

package/dist/types/resilience/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}