agentfootprint 2.2.0 → 2.3.0

package/dist/adapters/memory/agentcore.js

@@ -0,0 +1,305 @@
+"use strict";
+/**
+ * AgentCoreStore — AWS Bedrock AgentCore Memory adapter (peer-dep
+ * `@aws-sdk/client-bedrock-agent-runtime`).
+ *
+ * Subpath import: `agentfootprint/memory-agentcore`.
+ *
+ *   import { AgentCoreStore } from 'agentfootprint/memory-agentcore';
+ *   const store = new AgentCoreStore({
+ *     memoryId: 'arn:aws:bedrock:us-east-1:...:memory/my-mem',
+ *     region: 'us-east-1',
+ *   });
+ *
+ * Pattern: Adapter (GoF) — translates the `MemoryStore` interface onto
+ *          AgentCore Memory's session/event model:
+ *            MemoryIdentity     ↔  AgentCore session (sessionId derived
+ *                                  from the identity tuple)
+ *            MemoryEntry        ↔  AgentCore event payload (JSON
+ *                                  envelope keyed by entry id)
+ *            putIfVersion       ↔  unsupported by AgentCore natively;
+ *                                  emulated via list+CAS at adapter level
+ *            seen / signatures  ↔  in-process LRU shadow (AgentCore has
+ *                                  no built-in dedup primitive)
+ *            feedback           ↔  in-process accumulator (AgentCore
+ *                                  doesn't expose a feedback metric API)
+ *            search             ↔  NOT exposed in v2.3 — AgentCore's
+ *                                  retrieve API is opaque (server-side
+ *                                  retrieval pipeline). Will land as
+ *                                  `agentcoreRetrieve()` in a later release.
+ *
+ * Role:    Outer ring. Lazy-requires the AWS SDK; no runtime cost when
+ *          another adapter is in use.
+ * Emits:   N/A (storage adapters don't emit; recorders observe the
+ *          memory pipeline that calls them).
+ *
+ * **Caveats** — call out before adopting:
+ *   1. AgentCore is session/event-based with built-in summarization.
+ *      Mixing `defineMemory({ strategy: SUMMARIZE })` on top will
+ *      double-compress. Pick one summarizer.
+ *   2. Optimistic-concurrency `putIfVersion` is emulated; under high
+ *      concurrent write rates the CAS window is wider than RedisStore.
+ *      Single-writer scenarios (one server process per session) are
+ *      fine.
+ *   3. seen/feedback are in-process — they don't survive process restart.
+ *      For durable recognition, implement at a higher layer or use Redis.
+ *   4. AWS rate limits apply. Production deployments should wrap with
+ *      `withRetry` and budget calls per session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentCoreStore = void 0;
+const index_js_1 = require("../../memory/identity/index.js");
+/**
+ * AgentCore Memory-backed `MemoryStore`. Implements every method
+ * except `search()`. Vector retrieval via AgentCore's native API
+ * lands as a separate read-side helper in a later release.
+ *
+ * @throws when `@aws-sdk/client-bedrock-agent-runtime` is not
+ *         installed and no `_client` is supplied.
+ */
+class AgentCoreStore {
+    client;
+    memoryId;
+    pageSize;
+    closed = false;
+    // In-process shadow state for things AgentCore doesn't surface
+    // natively — see file-level docstring for caveats.
+    signatures = new Map();
+    feedbackBag = new Map();
+    constructor(options) {
+        if (!options.memoryId) {
+            throw new Error('AgentCoreStore requires `memoryId`.');
+        }
+        this.memoryId = options.memoryId;
+        this.pageSize = options.pageSize ?? 50;
+        if (options._client) {
+            this.client = options._client;
+        }
+        else if (options.client) {
+            this.client = options.client;
+        }
+        else {
+            this.client = createAgentCoreClient(options.region);
+        }
+    }
+    // Identity → AgentCore session id. Stable, deterministic, isolating.
+    sessionId(identity) {
+        return `afp:${(0, index_js_1.identityNamespace)(identity)}`;
+    }
+    // Shadow-state keys (in-process Maps)
+    shadowKey(identity) {
+        return (0, index_js_1.identityNamespace)(identity);
+    }
+    feedbackKey(identity, id) {
+        return `${(0, index_js_1.identityNamespace)(identity)}::${id}`;
+    }
+    // ── MemoryStore implementation ──────────────────────────────────
+    async get(identity, id) {
+        this.ensureOpen('get');
+        const r = await this.client.getEvent({
+            memoryId: this.memoryId,
+            sessionId: this.sessionId(identity),
+            eventId: id,
+        });
+        if (!r || !r.payload)
+            return null;
+        const entry = parseEntry(r.payload);
+        if (!entry)
+            return null;
+        if (entry.ttl !== undefined && entry.ttl <= Date.now())
+            return null;
+        return entry;
+    }
+    async put(identity, entry) {
+        this.ensureOpen('put');
+        if (entry.ttl !== undefined && entry.ttl <= Date.now())
+            return;
+        await this.client.putEvent({
+            memoryId: this.memoryId,
+            sessionId: this.sessionId(identity),
+            eventId: entry.id,
+            payload: JSON.stringify(entry),
+        });
+    }
+    async putMany(identity, entries) {
+        this.ensureOpen('putMany');
+        if (entries.length === 0)
+            return;
+        // AgentCore has no batch-write API; sequentialize and let AWS SDK
+        // retry policy handle backoff. Production callers should set a
+        // sane `maxConcurrency` upstream rather than parallelizing here
+        // (per-session events are conceptually ordered).
+        for (const entry of entries) {
+            await this.put(identity, entry);
+        }
+    }
+    /**
+     * Emulated optimistic concurrency. AgentCore's PutEvent overwrites
+     * unconditionally. We read-then-write inside a JS critical section
+     * — adequate for single-writer-per-session deployments. For multi-
+     * writer correctness on AgentCore, layer your own coordination.
+     */
+    async putIfVersion(identity, entry, expectedVersion) {
+        this.ensureOpen('putIfVersion');
+        const current = await this.get(identity, entry.id);
+        if (current === null) {
+            if (expectedVersion !== 0)
+                return { applied: false };
+        }
+        else if (current.version !== expectedVersion) {
+            return { applied: false, currentVersion: current.version };
+        }
+        await this.put(identity, entry);
+        return { applied: true };
+    }
+    async list(identity, options = {}) {
+        this.ensureOpen('list');
+        const page = await this.client.listEvents({
+            memoryId: this.memoryId,
+            sessionId: this.sessionId(identity),
+            ...(options.cursor !== undefined && { nextToken: options.cursor }),
+            maxResults: options.limit ?? this.pageSize,
+        });
+        const out = [];
+        for (const ev of page.events) {
+            const entry = parseEntry(ev.payload);
+            if (!entry)
+                continue;
+            if (entry.ttl !== undefined && entry.ttl <= Date.now())
+                continue;
+            if (options.tiers && (!entry.tier || !options.tiers.includes(entry.tier)))
+                continue;
+            out.push(entry);
+        }
+        return page.nextToken ? { entries: out, cursor: page.nextToken } : { entries: out };
+    }
+    async delete(identity, id) {
+        this.ensureOpen('delete');
+        await this.client.deleteEvent({
+            memoryId: this.memoryId,
+            sessionId: this.sessionId(identity),
+            eventId: id,
+        });
+        this.feedbackBag.delete(this.feedbackKey(identity, id));
+    }
+    async seen(identity, signature) {
+        this.ensureOpen('seen');
+        return this.signatures.get(this.shadowKey(identity))?.has(signature) ?? false;
+    }
+    async recordSignature(identity, signature) {
+        this.ensureOpen('recordSignature');
+        const key = this.shadowKey(identity);
+        const set = this.signatures.get(key) ?? new Set();
+        set.add(signature);
+        this.signatures.set(key, set);
+    }
+    async feedback(identity, id, usefulness) {
+        this.ensureOpen('feedback');
+        if (!Number.isFinite(usefulness))
+            return;
+        const clamped = Math.max(-1, Math.min(1, usefulness));
+        const key = this.feedbackKey(identity, id);
+        const cur = this.feedbackBag.get(key) ?? { sum: 0, count: 0 };
+        this.feedbackBag.set(key, { sum: cur.sum + clamped, count: cur.count + 1 });
+    }
+    async getFeedback(identity, id) {
+        this.ensureOpen('getFeedback');
+        const cur = this.feedbackBag.get(this.feedbackKey(identity, id));
+        if (!cur || cur.count === 0)
+            return null;
+        return { average: cur.sum / cur.count, count: cur.count };
+    }
+    async forget(identity) {
+        this.ensureOpen('forget');
+        await this.client.deleteSession({
+            memoryId: this.memoryId,
+            sessionId: this.sessionId(identity),
+        });
+        // Drop shadow state too — the GDPR contract is "everything for
+        // this identity, gone."
+        const shadowKey = this.shadowKey(identity);
+        this.signatures.delete(shadowKey);
+        for (const key of [...this.feedbackBag.keys()]) {
+            if (key.startsWith(`${shadowKey}::`))
+                this.feedbackBag.delete(key);
+        }
+    }
+    /**
+     * Mark the store closed. Subsequent calls throw cleanly. Idempotent.
+     * AgentCore is stateless from the client perspective so there's no
+     * connection to tear down — the close gate is purely defensive.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+    }
+    ensureOpen(op) {
+        if (this.closed) {
+            throw new Error(`AgentCoreStore.${op}() called after close().`);
+        }
+    }
+}
+exports.AgentCoreStore = AgentCoreStore;
+// Helpers
+function parseEntry(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a thin shim over the AWS SDK that conforms to AgentCoreLikeClient.
+ *
+ * Note on SDK API stability: AgentCore Memory's command names may
+ * evolve. The shim depends only on the request/response shapes our
+ * adapter needs; if AWS renames commands, only this function needs
+ * an update.
+ */
+function createAgentCoreClient(region) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        mod = require('@aws-sdk/client-bedrock-agent-runtime');
+    }
+    catch {
+        throw new Error('AgentCoreStore requires the `@aws-sdk/client-bedrock-agent-runtime` peer dependency.\n' +
+            '  Install:  npm install @aws-sdk/client-bedrock-agent-runtime\n' +
+            '  Or pass `_client` for test injection.');
+    }
+    if (!mod.BedrockAgentRuntimeClient) {
+        throw new Error('AgentCoreStore: `@aws-sdk/client-bedrock-agent-runtime` is installed but ' +
+            '`BedrockAgentRuntimeClient` was not found. Update the SDK to a version that ' +
+            'exports the AgentCore Memory commands.');
+    }
+    const sdkClient = new mod.BedrockAgentRuntimeClient({ ...(region && { region }) });
+    const dispatch = async (CommandCtor, input) => {
+        if (!CommandCtor) {
+            throw new Error('AgentCoreStore: this version of `@aws-sdk/client-bedrock-agent-runtime` ' +
+                'does not expose the required Memory command. Upgrade the SDK.');
+        }
+        const cmd = new CommandCtor(input);
+        return await sdkClient.send(cmd);
+    };
+    return {
+        async putEvent(input) {
+            await dispatch(mod.PutMemoryEventCommand, input);
+        },
+        async getEvent(input) {
+            const r = (await dispatch(mod.GetMemoryEventCommand, input));
+            return r ?? null;
+        },
+        async listEvents(input) {
+            return (await dispatch(mod.ListMemoryEventsCommand, input));
+        },
+        async deleteEvent(input) {
+            await dispatch(mod.DeleteMemoryEventCommand, input);
+        },
+        async deleteSession(input) {
+            await dispatch(mod.DeleteMemorySessionCommand, input);
+        },
+    };
+}
+//# sourceMappingURL=agentcore.js.map

package/dist/adapters/memory/agentcore.js.map

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

package/dist/adapters/memory/redis.js

@@ -0,0 +1,287 @@
+"use strict";
+/**
+ * RedisStore — Redis-backed `MemoryStore` adapter (peer-dep `ioredis`).
+ *
+ * Subpath import: `agentfootprint/memory-redis`.
+ *
+ *   import { RedisStore } from 'agentfootprint/memory-redis';
+ *   const store = new RedisStore({ url: 'redis://localhost:6379' });
+ *
+ * Pattern: Adapter (GoF) — translates the `MemoryStore` interface onto
+ *          Redis primitives (key/value for entries, set for signatures,
+ *          hash for feedback aggregates).
+ * Role:    Outer ring. Lazy-requires `ioredis`; no runtime cost when
+ *          another adapter is in use.
+ * Emits:   N/A (storage adapters don't emit; recorders observe the
+ *          memory pipeline that calls them).
+ *
+ * Vector search (`search()`) is NOT implemented in this adapter — RedisSearch
+ * is a separate Redis module with its own API surface. A `RedisSearchStore`
+ * may ship in a future release. RAG users with v2.3 should use
+ * `InMemoryStore` until the search-capable adapter lands.
+ *
+ * Concurrency model:
+ *   - `put` / `putMany` use simple SET / pipelined SET (last-write-wins).
+ *   - `putIfVersion` uses a small Lua script for atomic version compare-and-swap.
+ *   - Multi-writer correctness ⇒ prefer `putIfVersion` in stage code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStore = void 0;
+const index_js_1 = require("../../memory/identity/index.js");
+/**
+ * Redis-backed `MemoryStore`. Implements every method except `search()`.
+ *
+ * @throws when `ioredis` is not installed and no `_client` is supplied.
+ */
+class RedisStore {
+    client;
+    prefix;
+    scanCount;
+    ownsClient;
+    closed = false;
+    constructor(options = {}) {
+        this.prefix = options.prefix ?? 'agentfootprint';
+        this.scanCount = options.scanCount ?? 100;
+        if (options._client) {
+            this.client = options._client;
+            this.ownsClient = false;
+        }
+        else if (options.client) {
+            this.client = options.client;
+            this.ownsClient = false;
+        }
+        else if (options.url) {
+            this.client = createIoredis(options.url);
+            this.ownsClient = true;
+        }
+        else {
+            throw new Error('RedisStore requires `url` or `client` (or `_client` for tests).');
+        }
+    }
+    // Key helpers
+    nsKey(identity, suffix) {
+        return `${this.prefix}:${(0, index_js_1.identityNamespace)(identity)}:${suffix}`;
+    }
+    entryKey(identity, id) {
+        return this.nsKey(identity, `e:${id}`);
+    }
+    indexKey(identity) {
+        return this.nsKey(identity, 'idx');
+    }
+    sigKey(identity) {
+        return this.nsKey(identity, 'sig');
+    }
+    feedbackKey(identity, id) {
+        return this.nsKey(identity, `fb:${id}`);
+    }
+    // MemoryStore implementation
+    async get(identity, id) {
+        this.ensureOpen('get');
+        const raw = await this.client.get(this.entryKey(identity, id));
+        if (raw === null)
+            return null;
+        const entry = parseEntry(raw);
+        if (!entry)
+            return null;
+        if (entry.ttl !== undefined && entry.ttl <= Date.now())
+            return null;
+        return entry;
+    }
+    async put(identity, entry) {
+        this.ensureOpen('put');
+        const payload = JSON.stringify(entry);
+        const eKey = this.entryKey(identity, entry.id);
+        if (entry.ttl !== undefined) {
+            const pxMs = Math.max(0, entry.ttl - Date.now());
+            if (pxMs <= 0)
+                return;
+            await this.client.set(eKey, payload, 'PX', pxMs);
+        }
+        else {
+            await this.client.set(eKey, payload);
+        }
+        await this.client.sadd(this.indexKey(identity), entry.id);
+    }
+    async putMany(identity, entries) {
+        this.ensureOpen('putMany');
+        if (entries.length === 0)
+            return;
+        const pipeline = this.client.pipeline();
+        const ids = [];
+        const now = Date.now();
+        for (const entry of entries) {
+            const payload = JSON.stringify(entry);
+            const eKey = this.entryKey(identity, entry.id);
+            if (entry.ttl !== undefined) {
+                const pxMs = Math.max(0, entry.ttl - now);
+                if (pxMs <= 0)
+                    continue;
+                pipeline.set(eKey, payload, 'PX', pxMs);
+            }
+            else {
+                pipeline.set(eKey, payload);
+            }
+            ids.push(entry.id);
+        }
+        if (ids.length > 0)
+            pipeline.sadd(this.indexKey(identity), ...ids);
+        await pipeline.exec();
+    }
+    /**
+     * Optimistic concurrency via a small Lua script — atomic
+     * compare-and-swap on the JSON-encoded `version` field.
+     */
+    async putIfVersion(identity, entry, expectedVersion) {
+        this.ensureOpen('putIfVersion');
+        const eKey = this.entryKey(identity, entry.id);
+        const idxKey = this.indexKey(identity);
+        const payload = JSON.stringify(entry);
+        const px = entry.ttl !== undefined ? Math.max(0, entry.ttl - Date.now()).toString() : '';
+        const result = (await this.client.eval(PUT_IF_VERSION_LUA, 2, eKey, idxKey, String(expectedVersion), payload, entry.id, px));
+        const applied = result[0] === 1;
+        if (applied)
+            return { applied: true };
+        return result[1] !== undefined
+            ? { applied: false, currentVersion: result[1] }
+            : { applied: false };
+    }
+    async list(identity, options = {}) {
+        this.ensureOpen('list');
+        const idxKey = this.indexKey(identity);
+        const ids = await this.client.smembers(idxKey);
+        if (ids.length === 0)
+            return { entries: [] };
+        const entries = [];
+        for (const id of ids) {
+            const raw = await this.client.get(this.entryKey(identity, id));
+            if (raw === null)
+                continue;
+            const entry = parseEntry(raw);
+            if (!entry)
+                continue;
+            if (entry.ttl !== undefined && entry.ttl <= Date.now())
+                continue;
+            if (options.tiers && (!entry.tier || !options.tiers.includes(entry.tier)))
+                continue;
+            entries.push(entry);
+        }
+        const start = options.cursor ? parseInt(options.cursor, 10) : 0;
+        const limit = options.limit ?? entries.length;
+        const page = entries.slice(start, start + limit);
+        const next = start + limit;
+        return next < entries.length ? { entries: page, cursor: String(next) } : { entries: page };
+    }
+    async delete(identity, id) {
+        this.ensureOpen('delete');
+        await this.client.del(this.entryKey(identity, id), this.feedbackKey(identity, id));
+        await this.client.srem(this.indexKey(identity), id);
+    }
+    async seen(identity, signature) {
+        this.ensureOpen('seen');
+        const result = await this.client.sismember(this.sigKey(identity), signature);
+        return result === 1;
+    }
+    async recordSignature(identity, signature) {
+        this.ensureOpen('recordSignature');
+        await this.client.sadd(this.sigKey(identity), signature);
+    }
+    async feedback(identity, id, usefulness) {
+        this.ensureOpen('feedback');
+        if (!Number.isFinite(usefulness))
+            return;
+        const clamped = Math.max(-1, Math.min(1, usefulness));
+        const fbKey = this.feedbackKey(identity, id);
+        await this.client.eval(FEEDBACK_LUA, 1, fbKey, String(clamped));
+    }
+    async getFeedback(identity, id) {
+        this.ensureOpen('getFeedback');
+        const fb = await this.client.hgetall(this.feedbackKey(identity, id));
+        if (!fb || !fb.count || parseInt(fb.count, 10) === 0)
+            return null;
+        const count = parseInt(fb.count, 10);
+        const sum = parseFloat(fb.sum ?? '0');
+        return { average: sum / count, count };
+    }
+    /**
+     * GDPR — drop every key under this identity's namespace.
+     */
+    async forget(identity) {
+        this.ensureOpen('forget');
+        const pattern = `${this.prefix}:${(0, index_js_1.identityNamespace)(identity)}:*`;
+        let cursor = '0';
+        do {
+            const [next, keys] = await this.client.scan(cursor, 'MATCH', pattern, 'COUNT', this.scanCount);
+            cursor = next;
+            if (keys.length > 0)
+                await this.client.del(...keys);
+        } while (cursor !== '0');
+    }
+    /**
+     * Close the underlying Redis connection — only when this adapter
+     * owns it. Borrowed clients (passed via `client` option) are left to
+     * the caller. Idempotent.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.ownsClient)
+            await this.client.quit();
+    }
+    ensureOpen(op) {
+        if (this.closed) {
+            throw new Error(`RedisStore.${op}() called after close().`);
+        }
+    }
+}
+exports.RedisStore = RedisStore;
+// Helpers
+function parseEntry(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+const PUT_IF_VERSION_LUA = `
+local current = redis.call('GET', KEYS[1])
+local expected = tonumber(ARGV[1])
+if current == false then
+  if expected ~= 0 then
+    return {0}
+  end
+else
+  local cur_version = tonumber(string.match(current, '"version":(%d+)'))
+  if cur_version ~= expected then
+    return {0, cur_version}
+  end
+end
+if ARGV[4] ~= '' then
+  redis.call('SET', KEYS[1], ARGV[2], 'PX', tonumber(ARGV[4]))
+else
+  redis.call('SET', KEYS[1], ARGV[2])
+end
+redis.call('SADD', KEYS[2], ARGV[3])
+return {1}
+`;
+const FEEDBACK_LUA = `
+redis.call('HINCRBYFLOAT', KEYS[1], 'sum', ARGV[1])
+redis.call('HINCRBY', KEYS[1], 'count', 1)
+return 1
+`;
+function createIoredis(url) {
+    let mod;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        mod = require('ioredis');
+    }
+    catch {
+        throw new Error('RedisStore requires the `ioredis` peer dependency.\n' +
+            '  Install:  npm install ioredis\n' +
+            '  Or pass `_client` for test injection.');
+    }
+    const Ctor = mod.default ?? mod;
+    return new Ctor(url);
+}
+//# sourceMappingURL=redis.js.map

package/dist/adapters/memory/redis.js.map

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

package/dist/esm/adapters/llm/AnthropicProvider.js

@@ -7,33 +7,6 @@
  *          recorders, or compositions.
  * Emits:   N/A — providers don't emit; recorders observe via Agent.
  *
- * ─── 7-panel design review (2026-04-28) ─────────────────────────────
- *
- *   LLM-AI system design   ✓ Native tool_use blocks. Round-trips
- *                            assistant tool_calls via the new
- *                            `LLMMessage.toolCalls` field — preserves
- *                            multi-iteration ReAct correctness.
- *   Performance            ✓ Single SDK call per `complete()`. Stream
- *                            uses SDK's native iterator; no buffering.
- *   Scalability            ✓ Stateless adapter. Concurrent runs share
- *                            one provider instance freely.
- *   Research alignment     ✓ Mirrors v1 AnthropicAdapter's tested
- *                            message-conversion logic (origin/main
- *                            `c6e11d0`); tool-result merge follows the
- *                            documented Anthropic API expectation.
- *   Flexibility            ✓ `_client` injection point for tests.
- *                            `apiKey` falls back to env. `maxTokens`
- *                            override per-construction or per-request.
- *   Abstraction-modular    ✓ Two converters (toAnthropicMessages,
- *                            fromAnthropicResponse) isolate the
- *                            shape-shifting; `complete()` and
- *                            `stream()` reuse them.
- *   Software engineering   ✓ Duck-typed SDK shape (no hard import).
- *                            Errors wrapped with provider tag for
- *                            uniform downstream handling. Tests cover
- *                            unit + scenario + integration + property
- *                            + security + performance + ROI.
- *
  * ─── Limitations ────────────────────────────────────────────────────
  *
  * • Multi-modal content (images, video) NOT supported  — the framework's
@@ -42,10 +15,6 @@
  *   in lockstep.
  * • `responseFormat` (JSON-Schema-coerced output) NOT exposed
  *   — consumers can pass schema instructions via `systemPrompt`.
- *
- * ─── 7-pattern test coverage ────────────────────────────────────────
- *
- *   See `test/adapters/llm/AnthropicProvider/*.test.ts`.
  */
 /**
  * Build an `LLMProvider` backed by Anthropic's Messages API.