@retinue/agentkit 0.1.0

package/dist/adapters/memory/hitl.js

@@ -0,0 +1,130 @@
+/**
+ * In-memory HITL adapters — `docs/04` → Questions & Approvals. Durable pending questions/approvals
+ * and standing approval grants for tests/dev. `answerQuestion`/`decideApproval` are idempotent so a
+ * continuation is queued exactly once; grants respect revocation and expiry.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Interaction ${id} not found`, retryable: false });
+export const createMemoryInteractionStore = () => {
+    const questions = new Map(); // tenant -> id -> q
+    const approvals = new Map();
+    const qMap = (t) => {
+        let m = questions.get(t);
+        if (!m)
+            questions.set(t, (m = new Map()));
+        return m;
+    };
+    const aMap = (t) => {
+        let m = approvals.get(t);
+        if (!m)
+            approvals.set(t, (m = new Map()));
+        return m;
+    };
+    return {
+        async createQuestion({ tenantId, question }) {
+            qMap(tenantId).set(question.id, question);
+        },
+        async findPendingQuestion({ tenantId, runId }) {
+            for (const q of qMap(tenantId).values())
+                if (q.runId === runId && q.answeredAt === undefined)
+                    return q;
+            return null;
+        },
+        /**
+         * The newest answered question for the run — #163. Newest, because a run may ask more than once and only
+         * the latest answer is news; the earlier ones are already in the model's history from earlier turns.
+         */
+        async findAnsweredQuestion({ tenantId, runId }) {
+            let latest = null;
+            for (const q of qMap(tenantId).values()) {
+                if (q.runId !== runId || q.answeredAt === undefined)
+                    continue;
+                if (latest?.answeredAt === undefined || q.answeredAt > latest.answeredAt)
+                    latest = q;
+            }
+            return latest;
+        },
+        async answerQuestion({ tenantId, interactionId, answers, at }) {
+            const q = qMap(tenantId).get(interactionId);
+            if (!q)
+                throw notFound(interactionId);
+            if (q.answeredAt !== undefined)
+                return { question: q, alreadyResolved: true };
+            const answered = { ...q, answeredAt: at, answers };
+            qMap(tenantId).set(interactionId, answered);
+            return { question: answered, alreadyResolved: false };
+        },
+        async createApproval({ tenantId, approval }) {
+            aMap(tenantId).set(approval.id, approval);
+        },
+        async findPendingApproval({ tenantId, runId }) {
+            for (const a of aMap(tenantId).values())
+                if (a.runId === runId && a.decidedAt === undefined)
+                    return a;
+            return null;
+        },
+        async decideApproval({ tenantId, interactionId, decision, at }) {
+            const a = aMap(tenantId).get(interactionId);
+            if (!a)
+                throw notFound(interactionId);
+            if (a.decidedAt !== undefined)
+                return { approval: a, alreadyResolved: true };
+            const decided = { ...a, decidedAt: at, decision };
+            aMap(tenantId).set(interactionId, decided);
+            return { approval: decided, alreadyResolved: false };
+        },
+        async findApproval({ tenantId, interactionId }) {
+            return aMap(tenantId).get(interactionId) ?? null;
+        },
+        async findDecidedApproval({ tenantId, runId }) {
+            for (const a of aMap(tenantId).values())
+                if (a.runId === runId && a.decidedAt !== undefined && a.consumedAt === undefined)
+                    return a;
+            return null;
+        },
+        async claimApproval({ tenantId, interactionId, at }) {
+            const a = aMap(tenantId).get(interactionId);
+            if (!a)
+                throw notFound(interactionId);
+            // Undecided is refused, not deferred: an interaction nobody has decided must never become
+            // permission just because something asked for it.
+            if (a.decidedAt === undefined || a.consumedAt !== undefined)
+                return { approval: a, claimed: false };
+            const claimed = { ...a, consumedAt: at };
+            aMap(tenantId).set(interactionId, claimed);
+            return { approval: claimed, claimed: true };
+        },
+    };
+};
+export const createMemoryApprovalGrantStore = () => {
+    const byTenant = new Map();
+    const grants = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    const active = (g, now) => g.revokedAt === undefined && (g.expiresAt === undefined || g.expiresAt > now);
+    return {
+        async grant({ tenantId, grant }) {
+            grants(tenantId).set(grant.id, grant);
+        },
+        async findActive({ tenantId, toolNameOrCategory, now, conversationId }) {
+            for (const g of grants(tenantId).values()) {
+                if (!active(g, now) || g.toolNameOrCategory !== toolNameOrCategory)
+                    continue;
+                // A conversation-scoped grant only applies within its own conversation.
+                if (g.scope === "conversation" && g.conversationId !== conversationId)
+                    continue;
+                return g;
+            }
+            return null;
+        },
+        async revoke({ tenantId, grantId, at }) {
+            const g = grants(tenantId).get(grantId);
+            if (g)
+                grants(tenantId).set(g.id, { ...g, revokedAt: at });
+        },
+    };
+};
+//# sourceMappingURL=hitl.js.map

package/dist/adapters/memory/idempotency.d.ts

@@ -0,0 +1,13 @@
+/**
+ * In-memory idempotency store — `docs/04` → Idempotency. Persists a tool result by key so a resumed
+ * or retried external/destructive call returns the original result instead of repeating the side
+ * effect. Tenant-partitioned. Verified indirectly through the tool registry's replay path.
+ *
+ * The registry's `get`-then-`put` is safe here because the durable runtime serializes work per run
+ * (one worker per run; `runWithRetry` retries sequentially), so no two executions of the same
+ * `(tenant, run, tool-call)` race. A DISTRIBUTED adapter must instead implement an atomic
+ * put-if-absent / reserve so concurrent duplicates cannot both execute before either writes.
+ */
+import type { IdempotencyStore } from "../../idempotency/index.js";
+export declare const createMemoryIdempotencyStore: () => IdempotencyStore;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/adapters/memory/idempotency.js

@@ -0,0 +1,32 @@
+/**
+ * In-memory idempotency store — `docs/04` → Idempotency. Persists a tool result by key so a resumed
+ * or retried external/destructive call returns the original result instead of repeating the side
+ * effect. Tenant-partitioned. Verified indirectly through the tool registry's replay path.
+ *
+ * The registry's `get`-then-`put` is safe here because the durable runtime serializes work per run
+ * (one worker per run; `runWithRetry` retries sequentially), so no two executions of the same
+ * `(tenant, run, tool-call)` race. A DISTRIBUTED adapter must instead implement an atomic
+ * put-if-absent / reserve so concurrent duplicates cannot both execute before either writes.
+ */
+export const createMemoryIdempotencyStore = () => {
+    const byTenant = new Map();
+    const tenant = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    return {
+        async get({ tenantId, key }) {
+            const rows = tenant(tenantId);
+            if (!rows.has(key))
+                return null;
+            // A stored value means the call already ran: firstSeen is false for the replay.
+            return { key, firstSeen: false, result: rows.get(key) };
+        },
+        async put({ tenantId, key, result }) {
+            tenant(tenantId).set(key, result);
+        },
+    };
+};
+//# sourceMappingURL=idempotency.js.map

package/dist/adapters/memory/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * In-memory reference adapters — `docs/02-core-and-persistence.md`.
+ *
+ * The reference implementation used for tests and dev. It implements the storage ports (never
+ * the other way round) and is verified by the shared conformance harness, so a Postgres/Supabase
+ * adapter can be checked against the exact same behavior.
+ */
+import type { ConversationStore } from "../../persistence/index.js";
+export declare const createMemoryConversationStore: (clock?: () => string) => ConversationStore;
+/** Durable-runtime reference adapters (RunStore, CheckpointStore, JobDispatcher, locks). */
+export * from "./runtime.js";
+/** Session/thread reference adapters (SessionStateStore, run coordinator, binding, unit of work). */
+export * from "./sessions.js";
+/** Append-only usage ledger reference adapter. */
+export * from "./usage.js";
+export * from "./usage-limits.js";
+/** Blob store reference adapter (spilled tool output). */
+export * from "./blobs.js";
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./evaluation.js";
+/** Idempotency store reference adapter. */
+export * from "./idempotency.js";
+/** Skill store reference adapter. */
+export * from "./skills.js";
+/** Thread summary reference adapter (compacted history). */
+export * from "./thread-summary.js";
+/** HITL reference adapters (interactions + approval grants). */
+export * from "./hitl.js";
+/** MCP connection reference adapter. */
+export * from "./mcp.js";
+/** Principal (user-level) memory reference adapter. */
+export * from "./principal-memory.js";
+/** Message + agent reference adapters (used by the embedded agent facade). */
+export * from "./message-store.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/memory/index.js

@@ -0,0 +1,107 @@
+/**
+ * In-memory reference adapters — `docs/02-core-and-persistence.md`.
+ *
+ * The reference implementation used for tests and dev. It implements the storage ports (never
+ * the other way round) and is verified by the shared conformance harness, so a Postgres/Supabase
+ * adapter can be checked against the exact same behavior.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `Conversation ${id} not found`, retryable: false });
+const conflict = (message) => new AgentPlatformError({ code: "conflict", message, retryable: false });
+/** Monotonic ISO clock, injectable for deterministic tests. */
+const defaultClock = () => {
+    let n = 0;
+    return () => new Date(Date.UTC(2020, 0, 1, 0, 0, 0, ++n)).toISOString();
+};
+export const createMemoryConversationStore = (clock = defaultClock()) => {
+    // tenantId → (id → row). Partitioning by tenant makes cross-tenant reads structurally impossible.
+    const byTenant = new Map();
+    const tenant = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    const visible = (c) => c.deletedAt === undefined;
+    return {
+        async create({ tenantId, id, title }) {
+            const rows = tenant(tenantId);
+            if (rows.has(id))
+                throw conflict(`Conversation ${id} already exists`);
+            const now = clock();
+            const row = { id, tenantId, title, version: 1, createdAt: now, updatedAt: now };
+            rows.set(id, row);
+            return row;
+        },
+        async findById({ tenantId, id }) {
+            const row = tenant(tenantId).get(id);
+            return row && visible(row) ? row : null;
+        },
+        async list({ tenantId, limit, cursor }) {
+            const all = [...tenant(tenantId).values()]
+                .filter(visible)
+                .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1));
+            const start = cursor ? all.findIndex((c) => c.id === cursor) + 1 : 0;
+            const items = all.slice(start, start + limit);
+            const nextCursor = start + limit < all.length ? items[items.length - 1]?.id : undefined;
+            const page = nextCursor === undefined ? { items } : { items, nextCursor };
+            return page;
+        },
+        async update({ tenantId, id, expectedVersion, patch }) {
+            const rows = tenant(tenantId);
+            const row = rows.get(id);
+            if (!row || !visible(row))
+                throw notFound(id);
+            if (row.version !== expectedVersion)
+                throw conflict(`Conversation ${id} version ${expectedVersion} is stale (current ${row.version})`);
+            const next = {
+                ...row,
+                ...(patch.title === undefined ? {} : { title: patch.title }),
+                ...(patch.archivedAt === undefined
+                    ? {}
+                    : { archivedAt: patch.archivedAt === null ? undefined : patch.archivedAt }),
+                version: row.version + 1,
+                updatedAt: clock(),
+            };
+            rows.set(id, next);
+            return next;
+        },
+        async softDelete({ tenantId, id }) {
+            const rows = tenant(tenantId);
+            const row = rows.get(id);
+            if (!row || !visible(row))
+                throw notFound(id);
+            rows.set(id, { ...row, deletedAt: clock(), version: row.version + 1, updatedAt: clock() });
+        },
+    };
+};
+/** Durable-runtime reference adapters (RunStore, CheckpointStore, JobDispatcher, locks). */
+export * from "./runtime.js";
+/** Session/thread reference adapters (SessionStateStore, run coordinator, binding, unit of work). */
+export * from "./sessions.js";
+/** Append-only usage ledger reference adapter. */
+export * from "./usage.js";
+export * from "./usage-limits.js";
+/** Blob store reference adapter (spilled tool output). */
+export * from "./blobs.js";
+export * from "./files.js";
+export * from "./artifacts.js";
+export * from "./artifact-exports.js";
+export * from "./knowledge.js";
+export * from "./evaluation.js";
+/** Idempotency store reference adapter. */
+export * from "./idempotency.js";
+/** Skill store reference adapter. */
+export * from "./skills.js";
+/** Thread summary reference adapter (compacted history). */
+export * from "./thread-summary.js";
+/** HITL reference adapters (interactions + approval grants). */
+export * from "./hitl.js";
+/** MCP connection reference adapter. */
+export * from "./mcp.js";
+/** Principal (user-level) memory reference adapter. */
+export * from "./principal-memory.js";
+/** Message + agent reference adapters (used by the embedded agent facade). */
+export * from "./message-store.js";
+export * from "./flows.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/memory/knowledge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * In-memory `KnowledgeStore` and `VectorIndex` — the reference implementations (#135).
+ *
+ * The vector search is an exact brute-force scan, which is the right choice for a reference adapter: pgvector's
+ * HNSW index is *approximate*, so a conformance test asserting "the nearest chunk is returned first" would be
+ * asserting something the production adapter is allowed to miss. Making the reference exact means the harness
+ * tests the **contract** — tenant isolation, permission filtering, score ordering, the limit — and recall is
+ * measured separately against a fixed query set, which is what AC-2 actually asks for.
+ *
+ * Two things it takes as seriously as the pgvector adapter:
+ *
+ * - **Permission filtering happens during the scan**, not after. Filtering afterwards would satisfy every
+ *   assertion about the results and still leak through counts in production.
+ * - **`replaceSource` is a replace.** Appending would leave a changed document's old chunks searchable, and a
+ *   stale chunk is a citation pointing at text that is no longer there.
+ */
+import type { KeywordIndex, KnowledgeStore, VectorIndex } from "../../persistence/index.js";
+/**
+ * Cosine similarity, mapped to 0–1.
+ *
+ * Cosine rather than raw dot product, because an embedding's magnitude carries no meaning for most providers
+ * and an unnormalised dot product would rank a long chunk above a relevant one. Mapped from [-1,1] to [0,1] so
+ * a caller's `minScore` means the same thing whatever metric an adapter uses underneath.
+ */
+export declare const cosineScore: (a: readonly number[], b: readonly number[]) => number;
+/** Shared state, so the two ports can be backed by one table the way pgvector backs them. */
+export declare const createMemoryKnowledgeBackend: () => {
+    store: KnowledgeStore;
+    index: VectorIndex;
+    keyword: KeywordIndex;
+};
+/**
+ * Tokens for BM25.
+ *
+ * Lowercased, split on non-alphanumerics, and **`-` is kept inside a token** — `ERR-4021` and `Q3-2026` are
+ * single terms, and splitting them is how an exact-code query stops matching the document containing that
+ * exact code. That is the one case keyword retrieval exists for.
+ */
+export declare const tokenize: (text: string) => readonly string[];
+export declare const createMemoryKnowledgeStore: () => KnowledgeStore;
+export declare const createMemoryVectorIndex: () => VectorIndex;
+export declare const createMemoryKeywordIndex: () => KeywordIndex;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/adapters/memory/knowledge.js

@@ -0,0 +1,248 @@
+/**
+ * In-memory `KnowledgeStore` and `VectorIndex` — the reference implementations (#135).
+ *
+ * The vector search is an exact brute-force scan, which is the right choice for a reference adapter: pgvector's
+ * HNSW index is *approximate*, so a conformance test asserting "the nearest chunk is returned first" would be
+ * asserting something the production adapter is allowed to miss. Making the reference exact means the harness
+ * tests the **contract** — tenant isolation, permission filtering, score ordering, the limit — and recall is
+ * measured separately against a fixed query set, which is what AC-2 actually asks for.
+ *
+ * Two things it takes as seriously as the pgvector adapter:
+ *
+ * - **Permission filtering happens during the scan**, not after. Filtering afterwards would satisfy every
+ *   assertion about the results and still leak through counts in production.
+ * - **`replaceSource` is a replace.** Appending would leave a changed document's old chunks searchable, and a
+ *   stale chunk is a citation pointing at text that is no longer there.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { EMBEDDING_DIMENSIONS, stripStopwords } from "../../persistence/index.js";
+const tenantMap = (outer, tenantId) => {
+    let inner = outer.get(tenantId);
+    if (!inner)
+        outer.set(tenantId, (inner = new Map()));
+    return inner;
+};
+const sourceKey = (sourceType, sourceId) => `${sourceType} ${sourceId}`;
+/**
+ * Cosine similarity, mapped to 0–1.
+ *
+ * Cosine rather than raw dot product, because an embedding's magnitude carries no meaning for most providers
+ * and an unnormalised dot product would rank a long chunk above a relevant one. Mapped from [-1,1] to [0,1] so
+ * a caller's `minScore` means the same thing whatever metric an adapter uses underneath.
+ */
+export const cosineScore = (a, b) => {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return (dot / (Math.sqrt(na) * Math.sqrt(nb)) + 1) / 2;
+};
+/** Shared state, so the two ports can be backed by one table the way pgvector backs them. */
+export const createMemoryKnowledgeBackend = () => {
+    const byTenant = new Map();
+    const store = {
+        async replaceSource({ tenantId, sourceType, sourceId, chunks }) {
+            const rows = tenantMap(byTenant, tenantId);
+            const key = sourceKey(sourceType, sourceId);
+            let removed = 0;
+            for (const [id, chunk] of rows) {
+                if (sourceKey(chunk.sourceType, chunk.sourceId) === key) {
+                    rows.delete(id);
+                    removed += 1;
+                }
+            }
+            for (const chunk of chunks) {
+                // Two checks, and they catch different mistakes: a vector whose length contradicts its own declared
+                // dimensions is a caller bug, and a vector of a width this platform does not store is a *configuration*
+                // one. The reference adapter enforces both so it is exactly as strict as pgvector -- it previously
+                // accepted 768 while pgvector refused it, which is the laxness #129 named.
+                if (chunk.embedding.length !== EMBEDDING_DIMENSIONS)
+                    throw new AgentPlatformError({
+                        code: "invalid_input",
+                        message: `chunk ${chunk.id} has ${chunk.embedding.length} dimensions but this platform stores ${EMBEDDING_DIMENSIONS}`,
+                        retryable: false,
+                    });
+                if (chunk.embedding.length !== chunk.embeddingModel.dimensions)
+                    // Caught here rather than at search time: a vector of the wrong length would silently score against
+                    // whatever prefix happened to overlap, which looks like bad relevance rather than a bug.
+                    throw new AgentPlatformError({
+                        code: "invalid_input",
+                        message: `chunk ${chunk.id} has ${chunk.embedding.length} dimensions but its model declares ${chunk.embeddingModel.dimensions}`,
+                        retryable: false,
+                    });
+                rows.set(chunk.id, { ...chunk, sourceType, sourceId });
+            }
+            return { written: chunks.length, removed };
+        },
+        async listBySource({ tenantId, sourceType, sourceId, limit, cursor }) {
+            const key = sourceKey(sourceType, sourceId);
+            const rows = [...tenantMap(byTenant, tenantId).values()]
+                .filter((c) => sourceKey(c.sourceType, c.sourceId) === key)
+                // By chunk index, because "the chunks of this document" is an ordered thing and reading around a hit
+                // depends on that order being the document's.
+                .sort((a, b) => a.chunkIndex - b.chunkIndex);
+            const after = cursor === undefined ? -1 : Number.parseInt(cursor, 10);
+            const from = Number.isSafeInteger(after) ? after : -1;
+            const items = rows.filter((c) => c.chunkIndex > from).slice(0, limit).map(withoutEmbedding);
+            const last = items[items.length - 1];
+            return last !== undefined && rows.some((c) => c.chunkIndex > last.chunkIndex)
+                ? { items, nextCursor: String(last.chunkIndex) }
+                : { items };
+        },
+        async get({ tenantId, id }) {
+            // Absent from *this tenant's* map, so a foreign id is null without a comparison anyone could get wrong.
+            const found = tenantMap(byTenant, tenantId).get(id);
+            return found === undefined ? null : withoutEmbedding(found);
+        },
+        async deleteSource({ tenantId, sourceType, sourceId }) {
+            const rows = tenantMap(byTenant, tenantId);
+            const key = sourceKey(sourceType, sourceId);
+            let removed = 0;
+            for (const [id, chunk] of rows) {
+                if (sourceKey(chunk.sourceType, chunk.sourceId) === key) {
+                    rows.delete(id);
+                    removed += 1;
+                }
+            }
+            return { removed };
+        },
+        async listStaleSources({ tenantId, current, limit, cursor }) {
+            const grouped = new Map();
+            for (const chunk of tenantMap(byTenant, tenantId).values()) {
+                if (sameModel(chunk.embeddingModel, current))
+                    continue;
+                const key = sourceKey(chunk.sourceType, chunk.sourceId);
+                const entry = grouped.get(key);
+                if (entry === undefined)
+                    grouped.set(key, { sourceType: chunk.sourceType, sourceId: chunk.sourceId, chunkCount: 1 });
+                else
+                    entry.chunkCount += 1;
+            }
+            // Sorted so a resumed re-index sees a stable order; an unstable one would revisit sources it had done
+            // and skip ones it had not.
+            const sorted = [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+            const from = cursor === undefined ? 0 : sorted.findIndex(([k]) => k > cursor);
+            const start = from < 0 ? sorted.length : from;
+            const items = sorted.slice(start, start + limit).map(([, v]) => v);
+            const lastKey = sorted[start + items.length - 1]?.[0];
+            return start + limit < sorted.length && lastKey !== undefined
+                ? { items, nextCursor: lastKey }
+                : { items };
+        },
+    };
+    const index = {
+        async search({ tenantId, embedding, authSubjects, limit, minScore, sourceTypes }) {
+            const allowed = new Set(authSubjects);
+            const types = sourceTypes === undefined ? null : new Set(sourceTypes);
+            const hits = [];
+            for (const chunk of tenantMap(byTenant, tenantId).values()) {
+                // Filtered *during* the scan. Filtering the result set afterwards satisfies every assertion about the
+                // results and still leaks through counts, which is the failure AC-3 names.
+                if (!allowed.has(chunk.authSubject))
+                    continue;
+                if (types !== null && !types.has(chunk.sourceType))
+                    continue;
+                const score = cosineScore(embedding, chunk.embedding);
+                if (minScore !== undefined && score < minScore)
+                    continue;
+                hits.push({ chunk: withoutEmbedding(chunk), score });
+            }
+            // Ties broken by id, so two chunks with identical scores come back in a stable order — otherwise a
+            // recall measurement moves between runs for reasons unrelated to relevance.
+            return hits.sort((a, b) => (b.score !== a.score ? b.score - a.score : a.chunk.id.localeCompare(b.chunk.id))).slice(0, limit);
+        },
+    };
+    /**
+     * BM25 over the same rows.
+     *
+     * A real ranking function rather than a substring match, because the whole point of #136 is that keyword and
+     * semantic retrieval have *different* strengths — and a substring matcher has none. BM25 gives rarer terms
+     * more weight and saturates on repetition, which is what makes `ERR-4021` beat a document that says
+     * "error" forty times.
+     *
+     * `k1 = 1.2, b = 0.75` are the standard parameters and the same operating point Postgres's `ts_rank_cd`
+     * approximates, so the reference adapter and the production one rank alike on the cases that matter.
+     */
+    const keyword = {
+        async search({ tenantId, query, authSubjects, limit, minScore, sourceTypes }) {
+            const allowed = new Set(authSubjects);
+            const types = sourceTypes === undefined ? null : new Set(sourceTypes);
+            // Filtered *before* scoring, so an excluded chunk never enters the corpus statistics either — otherwise
+            // it would shift every other document's IDF and influence ranking without appearing.
+            const corpus = [...tenantMap(byTenant, tenantId).values()].filter((c) => allowed.has(c.authSubject) && (types === null || types.has(c.sourceType)));
+            if (corpus.length === 0)
+                return [];
+            // Stopwords come off the *query*, not the index: the index keeps everything so an exact identifier is
+            // still findable, and the query drops the terms that carry no signal. See `KEYWORD_STOPWORDS`.
+            const terms = tokenize(stripStopwords(query));
+            if (terms.length === 0)
+                return [];
+            const docs = corpus.map((chunk) => ({ chunk, tokens: tokenize(chunk.content) }));
+            const avgLength = docs.reduce((n, d) => n + d.tokens.length, 0) / docs.length;
+            const documentFrequency = new Map();
+            for (const term of new Set(terms)) {
+                documentFrequency.set(term, docs.filter((d) => d.tokens.includes(term)).length);
+            }
+            const K1 = 1.2;
+            const B = 0.75;
+            const raw = docs.map(({ chunk, tokens }) => {
+                let score = 0;
+                for (const term of new Set(terms)) {
+                    const tf = tokens.filter((t) => t === term).length;
+                    if (tf === 0)
+                        continue;
+                    const df = documentFrequency.get(term) ?? 0;
+                    // The +0.5/+0.5 smoothing is Robertson's; without it a term present in every document gets a
+                    // negative weight and a matching document scores *worse* than a non-matching one.
+                    const idf = Math.log(1 + (docs.length - df + 0.5) / (df + 0.5));
+                    const norm = tf * (K1 + 1);
+                    const denom = tf + K1 * (1 - B + (B * tokens.length) / (avgLength || 1));
+                    score += idf * (norm / denom);
+                }
+                return { chunk, score };
+            });
+            const best = Math.max(...raw.map((r) => r.score), 0);
+            // Normalised against the best hit in this result set, so `minScore` means "relative to the best match
+            // here" for both signals. An absolute BM25 threshold would be meaningless: the scale depends on the
+            // corpus.
+            const hits = raw
+                .filter((r) => r.score > 0)
+                .map((r) => ({ chunk: withoutEmbedding(r.chunk), score: best === 0 ? 0 : r.score / best }))
+                .filter((h) => minScore === undefined || h.score >= minScore);
+            return hits
+                // Ties broken by id, so two equally-matching chunks come back in a stable order and a measured figure
+                // does not move between runs.
+                .sort((a, b) => (b.score !== a.score ? b.score - a.score : a.chunk.id.localeCompare(b.chunk.id)))
+                .slice(0, limit);
+        },
+    };
+    return { store, index, keyword };
+};
+/**
+ * Tokens for BM25.
+ *
+ * Lowercased, split on non-alphanumerics, and **`-` is kept inside a token** — `ERR-4021` and `Q3-2026` are
+ * single terms, and splitting them is how an exact-code query stops matching the document containing that
+ * exact code. That is the one case keyword retrieval exists for.
+ */
+export const tokenize = (text) => (text.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)*/g) ?? []).filter((t) => t.length > 1 || /[0-9]/.test(t));
+const sameModel = (a, b) => a.modelId === b.modelId && a.version === b.version && a.dimensions === b.dimensions;
+/** Read paths never return the vector: nothing above this layer needs it, and it is by far the largest field. */
+const withoutEmbedding = (chunk) => {
+    const { embedding, ...rest } = chunk;
+    void embedding;
+    return rest;
+};
+export const createMemoryKnowledgeStore = () => createMemoryKnowledgeBackend().store;
+export const createMemoryVectorIndex = () => createMemoryKnowledgeBackend().index;
+export const createMemoryKeywordIndex = () => createMemoryKnowledgeBackend().keyword;
+//# sourceMappingURL=knowledge.js.map

package/dist/adapters/memory/mcp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * In-memory MCP connection store — `docs/10`. Tenant-partitioned so one tenant can never see
+ * another's connections/tools. Endpoints are egress-validated at registration; a credential is
+ * only ever a `credentialRef`, never an inlined secret (structurally enforced by `McpAuth`).
+ */
+import { type EgressPolicy } from "../../mcp/egress.js";
+import type { McpConnectionStore } from "../../mcp/provider.js";
+export declare const createMemoryMcpConnectionStore: (egress: EgressPolicy) => McpConnectionStore;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/adapters/memory/mcp.js

@@ -0,0 +1,37 @@
+/**
+ * In-memory MCP connection store — `docs/10`. Tenant-partitioned so one tenant can never see
+ * another's connections/tools. Endpoints are egress-validated at registration; a credential is
+ * only ever a `credentialRef`, never an inlined secret (structurally enforced by `McpAuth`).
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+import { validateEndpoint } from "../../mcp/egress.js";
+export const createMemoryMcpConnectionStore = (egress) => {
+    const byTenant = new Map();
+    const tenant = (t) => {
+        let m = byTenant.get(t);
+        if (!m)
+            byTenant.set(t, (m = new Map()));
+        return m;
+    };
+    return {
+        async register({ tenantId, connection }) {
+            // Reject endpoints failing egress at registration (again at handshake by the client).
+            validateEndpoint(egress, connection.transport, connection.endpoint);
+            if (connection.tenantId !== tenantId)
+                throw new AgentPlatformError({ code: "forbidden", message: "connection tenant mismatch", retryable: false });
+            tenant(tenantId).set(connection.id, connection);
+        },
+        async get({ tenantId, id }) {
+            return tenant(tenantId).get(id) ?? null;
+        },
+        async list({ tenantId }) {
+            return [...tenant(tenantId).values()];
+        },
+        async setEnabled({ tenantId, id, enabled }) {
+            const c = tenant(tenantId).get(id);
+            if (c)
+                tenant(tenantId).set(id, { ...c, enabled });
+        },
+    };
+};
+//# sourceMappingURL=mcp.js.map