@jbarket/loomai 0.5.0 → 0.6.0

package/dist/tools/memory-history.js

@@ -0,0 +1,52 @@
+/**
+ * memory_history tool — body-revision listing and inspection for memories.
+ *
+ * update() snapshots the displaced body into memory_revisions before
+ * overwriting it. This tool is the read surface: list a memory's snapshots
+ * (metadata only) or read one snapshot's full content. To put a snapshot
+ * back, use memory_revision_restore.
+ */
+import { createBackend } from '../backends/index.js';
+export async function memoryHistory(contextDir, input) {
+    if (!input.ref) {
+        return 'Error: ref is required.';
+    }
+    const backend = createBackend(contextDir);
+    try {
+        // ── Read mode ──
+        if (input.revision_id !== undefined) {
+            const revision = await backend.getRevision(input.revision_id);
+            if (!revision) {
+                return `Error: revision not found: ${input.revision_id}`;
+            }
+            // Ownership is memory_id, not the ref recorded at snapshot time:
+            // memory_merge re-parents a source's revisions onto the target and
+            // keeps the original ref as provenance (PR120 review). So a revision
+            // belongs to input.ref iff it is in input.ref's listing.
+            const owned = (await backend.listRevisions(input.ref)).some((r) => r.id === revision.id);
+            if (!owned) {
+                return `Error: revision #${input.revision_id} does not belong to \`${input.ref}\` (recorded on \`${revision.ref}\`).`;
+            }
+            const provenance = revision.ref !== input.ref ? ` (recorded on \`${revision.ref}\`, merged in)` : '';
+            return (`# Revision #${revision.id} of \`${input.ref}\`${provenance}\n` +
+                `op: ${revision.op} | replaced: ${revision.replaced_at}\n\n` +
+                `${revision.content}\n\n` +
+                `_Pass to memory_revision_restore to put this body back._`);
+        }
+        // ── List mode ──
+        const revisions = await backend.listRevisions(input.ref);
+        if (revisions.length === 0) {
+            return `\`${input.ref}\` has no revisions — its body has never been replaced.`;
+        }
+        const lines = revisions.map((r) => `- **#${r.id}** | ${r.op} | replaced ${r.replaced_at} | ${r.content_length} chars` +
+            (r.ref !== input.ref ? ` | from \`${r.ref}\` (merged in)` : ''));
+        return (`# Revision history — \`${input.ref}\` — ${revisions.length} snapshot(s)\n\n` +
+            `${lines.join('\n')}\n\n` +
+            `_Pass revision_id to read a snapshot; use memory_revision_restore to put one back._`);
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    // No close(): createBackend hands out the shared, process-cached handle.
+    // Closing it here would kill any in-flight call on the same backend.
+}

package/dist/tools/memory-list.js

@@ -8,7 +8,8 @@
 import { createBackend } from '../backends/index.js';
 export function formatEntry(e) {
     const projectTag = e.project ? ` [${e.project}]` : '';
-    return `- **${e.title}** — ${e.category}${projectTag} (${e.created.slice(0, 10)})\n  ref: \`${e.ref}\``;
+    const confidenceTag = e.confidence !== undefined ? ` · confidence ${e.confidence.toFixed(2)} (${e.evidenceCount} obs)` : '';
+    return `- **${e.title}** — ${e.category}${projectTag} (${e.created.slice(0, 10)})${confidenceTag}\n  ref: \`${e.ref}\``;
 }
 export function formatEntries(entries) {
     if (entries.length === 0)

package/dist/tools/memory-merge.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryMergeInput } from '../backends/types.js';
+export declare function memoryMerge(contextDir: string, input: MemoryMergeInput): Promise<string>;

package/dist/tools/memory-merge.js

@@ -0,0 +1,40 @@
+/**
+ * memory_merge tool — consolidate N memories into one canonical row.
+ *
+ * Acts on a memory_audit duplicate-finding: pick a survivor (target_ref) and
+ * fold the rest (source_refs) into it. Sources are archived with a
+ * tombstone pointing at the target and the supersession edge is recorded in
+ * memory_supersessions (same table supersede() writes to) — merge is just
+ * supersede() for N sources instead of one, plus times_seen consolidation
+ * and (optionally) body concatenation. Distinct from forget/archive, which
+ * only discard one side of a duplicate pair rather than consolidating it.
+ */
+import { createBackend } from '../backends/index.js';
+export async function memoryMerge(contextDir, input) {
+    if (!input.source_refs || input.source_refs.length === 0) {
+        return 'Error: source_refs must not be empty.';
+    }
+    const backend = createBackend(contextDir);
+    try {
+        const result = await backend.mergeMemories(input);
+        const lines = [
+            `Merged ${result.sources_merged} memory(ies) into \`${result.target_ref}\`.`,
+            `times_seen on the survivor: ${result.times_seen}.`,
+            `Losers archived: ${result.losers.map((l) => `\`${l.ref}\``).join(', ')}.`,
+        ];
+        if (!input.append_loser_bodies && result.losers.length > 0) {
+            lines.push('');
+            lines.push('Loser bodies (target content NOT modified — review before discarding):');
+            for (const loser of result.losers) {
+                lines.push(`\n**${loser.ref}** (*${loser.title}*):\n${loser.content}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    // No close(): createBackend hands out the shared, process-cached handle.
+    // Closing it here would kill any in-flight call on the same backend
+    // (PR120 review — same lifecycle bug fixed in memory_history).
+}

package/dist/tools/memory-revision-restore.d.ts

@@ -0,0 +1,5 @@
+export interface MemoryRevisionRestoreToolInput {
+    ref: string;
+    revision_id: number;
+}
+export declare function memoryRevisionRestore(contextDir: string, input: MemoryRevisionRestoreToolInput): Promise<string>;

package/dist/tools/memory-revision-restore.js

@@ -0,0 +1,33 @@
+/**
+ * memory_revision_restore tool — restore a snapshotted body onto a memory.
+ *
+ * Snapshots the current body first, so restore is never destructive.
+ * Use memory_history to list revision IDs before calling this.
+ */
+import { createBackend } from '../backends/index.js';
+export async function memoryRevisionRestore(contextDir, input) {
+    if (!input.ref) {
+        return 'Error: ref is required.';
+    }
+    if (input.revision_id === undefined) {
+        return 'Error: revision_id is required — list revisions with memory_history first.';
+    }
+    const backend = createBackend(contextDir);
+    try {
+        const result = await backend.restoreRevision({
+            ref: input.ref,
+            revision_id: input.revision_id,
+        });
+        if (!result.restored) {
+            return (`Error: could not restore revision #${input.revision_id} onto \`${input.ref}\`. ` +
+                `Check that the ref exists and the revision belongs to it.`);
+        }
+        return (`Restored revision #${result.revision_id} onto \`${result.ref}\`. ` +
+            `The displaced body was snapshotted as revision #${result.snapshot_id}.`);
+    }
+    catch (e) {
+        return `Error: ${e.message}`;
+    }
+    // No close(): createBackend hands out the shared, process-cached handle.
+    // Closing it here would kill any in-flight call on the same backend.
+}

package/dist/tools/person.d.ts

@@ -0,0 +1,32 @@
+import { type PersonWriteInput, type PersonReadResult, type PersonListEntry } from '../backends/people.js';
+export declare function personWrite(contextDir: string, input: PersonWriteInput): Promise<string>;
+export declare function personVerify(contextDir: string, input: {
+    slug: string;
+    fields: string[];
+    verified_at?: string;
+    source?: string;
+}): Promise<string>;
+export declare function personArchive(contextDir: string, input: {
+    slug: string;
+    reason: string;
+}): Promise<string>;
+export declare function personRestore(contextDir: string, input: {
+    slug: string;
+}): Promise<string>;
+export declare function personRevisionRestore(contextDir: string, input: {
+    slug: string;
+    revision_id: number;
+}): Promise<string>;
+/** The `person` read. Throws on an invalid slug or an unreadable row; the MCP wrapper turns that into text. */
+export declare function readPerson(contextDir: string, slug: string, includeArchived?: boolean): PersonReadResult;
+export declare function listPeople(contextDir: string, includeArchived?: boolean): PersonListEntry[];
+export declare function person(contextDir: string, input: {
+    slug: string;
+    include_archived?: boolean;
+}): Promise<string>;
+export declare function personList(contextDir: string, input: {
+    include_archived?: boolean;
+}): Promise<string>;
+export declare function personHistory(contextDir: string, input: {
+    slug: string;
+}): Promise<string>;

package/dist/tools/person.js

@@ -0,0 +1,111 @@
+/**
+ * Person-card tools — person_write / person_verify / person_archive /
+ * person_restore / person / person_list / person_history /
+ * person_revision_restore (docs/specs/person-cards.md).
+ *
+ * Thin wrappers over backends/people.ts: each opens the store on the memory
+ * database, runs one call, closes. Results are JSON text, the shape the spec
+ * names; a rejection is `Error: <message naming the path>`, like every other
+ * loom tool. The CLI (`loom person`) calls the read functions here too.
+ */
+import { resolveIdentityName } from '../config.js';
+import { openPeopleStore, personSlugError, PersonCardError, UnreadableCardError, } from '../backends/people.js';
+const json = (v) => JSON.stringify(v, null, 2);
+/** Slugs validate before anything else, store or no store (criterion 11). */
+function assertSlug(slug) {
+    const err = personSlugError(slug);
+    if (err)
+        throw new PersonCardError(`slug: ${err}`);
+}
+function errorText(e) {
+    if (e instanceof PersonCardError || e instanceof UnreadableCardError)
+        return `Error: ${e.message}`;
+    return `Error: ${e.message ?? String(e)}`;
+}
+function withWritable(contextDir, fn) {
+    try {
+        const store = openPeopleStore(contextDir);
+        try {
+            return json(fn(store));
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (e) {
+        return errorText(e);
+    }
+}
+export async function personWrite(contextDir, input) {
+    return withWritable(contextDir, (s) => s.write(input));
+}
+export async function personVerify(contextDir, input) {
+    return withWritable(contextDir, (s) => s.verify(input));
+}
+export async function personArchive(contextDir, input) {
+    // The actor is the calling agent's name — the value knowledge_write uses for author.
+    return withWritable(contextDir, (s) => s.archive({ ...input, actor: resolveIdentityName(contextDir) }));
+}
+export async function personRestore(contextDir, input) {
+    return withWritable(contextDir, (s) => s.restore(input));
+}
+export async function personRevisionRestore(contextDir, input) {
+    return withWritable(contextDir, (s) => s.revisionRestore(input));
+}
+/** The `person` read. Throws on an invalid slug or an unreadable row; the MCP wrapper turns that into text. */
+export function readPerson(contextDir, slug, includeArchived = false) {
+    assertSlug(slug);
+    const store = openPeopleStore(contextDir, { readonly: true });
+    if (!store)
+        return { found: false };
+    try {
+        return store.read(slug, includeArchived);
+    }
+    finally {
+        store.close();
+    }
+}
+export function listPeople(contextDir, includeArchived = false) {
+    const store = openPeopleStore(contextDir, { readonly: true });
+    if (!store)
+        return [];
+    try {
+        return store.list(includeArchived);
+    }
+    finally {
+        store.close();
+    }
+}
+export async function person(contextDir, input) {
+    try {
+        return json(readPerson(contextDir, input.slug, input.include_archived ?? false));
+    }
+    catch (e) {
+        return errorText(e);
+    }
+}
+export async function personList(contextDir, input) {
+    try {
+        return json(listPeople(contextDir, input.include_archived ?? false));
+    }
+    catch (e) {
+        return errorText(e);
+    }
+}
+export async function personHistory(contextDir, input) {
+    try {
+        assertSlug(input.slug);
+        const store = openPeopleStore(contextDir, { readonly: true });
+        if (!store)
+            return json([]);
+        try {
+            return json(store.history(input.slug));
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (e) {
+        return errorText(e);
+    }
+}

package/dist/tools/prune.js

@@ -9,7 +9,7 @@ export async function prune(contextDir, options) {
     const result = await backend.prune(options);
     const lines = [];
     if (result.expired.length > 0) {
-        const verb = options?.dryRun ? 'Would expire' : 'Expired';
+        const verb = options?.dryRun ? 'Would archive' : 'Archived';
         lines.push(`**${verb} ${result.expired.length} memories (TTL elapsed):**`);
         for (const ref of result.expired) {
             lines.push(`- ${ref}`);

package/dist/tools/recall.js

@@ -8,7 +8,13 @@
 import { createBackend } from '../backends/index.js';
 export function formatMatchResult(m) {
     const projectTag = m.project ? ` [${m.project}]` : '';
-    return `## ${m.title}\n*${m.category}${projectTag} — ${m.created.slice(0, 10)}*\n\n${m.content}`;
+    // Show sourcing when set — 'inferred' is the critical signal (AI-generated,
+    // not ground truth). Provenance follows in parens when present.
+    const sourcingTag = m.sourcing ? ` · ${m.sourcing}` : '';
+    const provenanceTag = m.provenance ? ` (${m.provenance})` : '';
+    // Decayed confidence, feedback memories only — undefined elsewhere (t-338).
+    const confidenceTag = m.confidence !== undefined ? ` · confidence ${m.confidence.toFixed(2)} (${m.evidenceCount} obs)` : '';
+    return `## ${m.title}\n*${m.category}${projectTag} — ${m.created.slice(0, 10)}${sourcingTag}${provenanceTag}${confidenceTag}*\n\n${m.content}`;
 }
 export function formatResults(matches) {
     const results = matches.map(formatMatchResult);

package/dist/tools/remember.js

@@ -7,6 +7,7 @@
  */
 import { createBackend } from '../backends/index.js';
 import { EPISODE_CATEGORY, EPISODE_DEFAULT_TTL } from '../categories.js';
+import { recordSuccess, recordFailure } from '../backends/recorder-health.js';
 /**
  * Lint-on-write (c-loom-strictness §lint): validate the record BEFORE it reaches
  * the backend, so a malformed write is refused with a typed reason and the store
@@ -24,6 +25,9 @@ export function validateMemoryInput(input) {
     if (typeof input.category !== 'string' || input.category.trim() === '') {
         return 'memory category is required and cannot be empty';
     }
+    if (input.scope !== undefined && input.scope !== 'project' && input.scope !== 'global') {
+        return 'scope must be "project" or "global"';
+    }
     return null;
 }
 export async function remember(contextDir, input) {
@@ -36,8 +40,20 @@ export async function remember(contextDir, input) {
     const backend = createBackend(contextDir);
     // An episode is short-term by definition: without an explicit ttl it gets the
     // tier default, so a body can never accidentally leave a permanent episode.
-    if (input.category === EPISODE_CATEGORY && !input.ttl) {
+    const isEpisode = input.category === EPISODE_CATEGORY;
+    if (isEpisode && !input.ttl) {
         input = { ...input, ttl: EPISODE_DEFAULT_TTL };
     }
-    return backend.remember(input);
+    try {
+        const ref = await backend.remember(input);
+        // Record health only for episode writes — that's the path identity.ts monitors.
+        if (isEpisode)
+            recordSuccess(contextDir);
+        return ref;
+    }
+    catch (err) {
+        if (isEpisode)
+            recordFailure(contextDir, err);
+        throw err;
+    }
 }

package/dist/tools/update.js

@@ -12,5 +12,9 @@ export async function update(contextDir, input) {
         const identifier = input.ref ?? `${input.category}/${input.title}`;
         return `Memory not found: "${identifier}". Use recall to find the correct reference.`;
     }
-    return `Memory updated: ${result.ref}`;
+    const snap = result.snapshotId !== undefined ? ` (snapshot #${result.snapshotId})` : '';
+    const conf = result.confidence !== undefined
+        ? ` — confidence now ${result.confidence.toFixed(2)} (${result.evidenceCount} observations)`
+        : '';
+    return `Memory updated: ${result.ref}${snap}${conf}`;
 }

package/dist/transport/cli-endpoint.d.ts

@@ -0,0 +1,13 @@
+import { type CliRequest, type CliResponse } from '../cli/remote.js';
+export type CliOutcome = {
+    ok: true;
+    response: CliResponse;
+} | {
+    ok: false;
+    error: string;
+};
+/** Validate a POST /cli body; returns the request or why it's refused. */
+export declare function parseCliRequest(body: unknown): CliRequest | string;
+/** Run a validated request's argv against `contextDir`. */
+export declare function runCliRequest(contextDir: string, request: CliRequest): Promise<CliResponse>;
+export declare function handleCliBody(contextDir: string, body: unknown): Promise<CliOutcome>;

package/dist/transport/cli-endpoint.js

@@ -0,0 +1,97 @@
+/**
+ * POST /cli — the server half of the CLI's remote mode (src/cli/remote.ts,
+ * t-1472).
+ *
+ * Runs the real CLI in-process (runCliLocal: remote mode isn't on its path)
+ * against THIS server's stack, with captured
+ * streams, and returns what it printed and its exit code. It sits behind the
+ * same bearer gate and payload cap as /mcp, and grants nothing /mcp doesn't:
+ *
+ *   - only REMOTE_VERBS (the store verbs, all of which have MCP tools),
+ *     minus the memory subcommands that have none
+ *   - never --context-dir or --url: the stack is the server's, full stop
+ *   - a fixed env: the server's HOME and stack, plus the caller's
+ *     LOOM_CLIENT / LOOM_MODEL hints and nothing else
+ *   - stdin is never a TTY here, so no verb can reach $EDITOR server-side
+ */
+import { Readable } from 'node:stream';
+import { runCliLocal } from '../cli/index.js';
+import { extractGlobalFlags, firstNonGlobalIndex } from '../cli/args.js';
+import { LOCAL_MEMORY_SUBCOMMANDS, REMOTE_VERBS } from '../cli/remote.js';
+const MAX_ARGV = 256;
+function isStringRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Validate a POST /cli body; returns the request or why it's refused. */
+export function parseCliRequest(body) {
+    if (!isStringRecord(body))
+        return 'bad-input: expected a JSON object';
+    const { argv, stdin, env } = body;
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > MAX_ARGV || !argv.every((a) => typeof a === 'string')) {
+        return `bad-input: argv must be 1..${MAX_ARGV} strings`;
+    }
+    if (stdin !== undefined && typeof stdin !== 'string')
+        return 'bad-input: stdin must be a string';
+    let hints;
+    if (env !== undefined) {
+        if (!isStringRecord(env))
+            return 'bad-input: env must be an object';
+        hints = {};
+        for (const [k, v] of Object.entries(env)) {
+            if (k !== 'LOOM_CLIENT' && k !== 'LOOM_MODEL')
+                return `refused: env may only carry LOOM_CLIENT and LOOM_MODEL, not ${k}`;
+            if (typeof v !== 'string')
+                return `bad-input: env.${k} must be a string`;
+            hints[k] = v;
+        }
+    }
+    const args = argv;
+    if (args.some((a) => a === '--context-dir' || a.startsWith('--context-dir=') || a === '--url' || a.startsWith('--url='))) {
+        return 'refused: --context-dir and --url name a stack; this server only serves its own';
+    }
+    const verbIdx = firstNonGlobalIndex(args);
+    const verb = args[verbIdx];
+    if (verb === undefined || !REMOTE_VERBS.has(verb)) {
+        return `refused: ${verb ?? '(no verb)'} doesn't run remotely; remote verbs are ${[...REMOTE_VERBS].join(', ')}`;
+    }
+    if (verb === 'memory') {
+        // memory.ts dispatches on its first token after the globals are pulled out.
+        const after = [...args.slice(0, verbIdx), ...args.slice(verbIdx + 1)];
+        const sub = extractGlobalFlags(after).rest[0];
+        if (sub !== undefined && LOCAL_MEMORY_SUBCOMMANDS.has(sub)) {
+            return `refused: memory ${sub} has no MCP tool, so it doesn't run remotely`;
+        }
+    }
+    return { argv: args, stdin: stdin, env: hints };
+}
+/** Run a validated request's argv against `contextDir`. */
+export async function runCliRequest(contextDir, request) {
+    let stdout = '';
+    let stderr = '';
+    const env = { LOOM_CONTEXT_DIR: contextDir, ...request.env };
+    if (process.env.HOME)
+        env.HOME = process.env.HOME;
+    const io = {
+        stdout: (s) => { stdout += s; },
+        stderr: (s) => { stderr += s; },
+        stdin: Readable.from([request.stdin ?? '']),
+        stdinIsTTY: false,
+        env,
+    };
+    let exitCode;
+    try {
+        exitCode = await runCliLocal(request.argv, io);
+    }
+    catch (err) {
+        // The local CLI would crash with a stack trace; a remote one gets the message and exit 1.
+        stderr += `${err.message}\n`;
+        exitCode = 1;
+    }
+    return { exitCode, stdout, stderr };
+}
+export async function handleCliBody(contextDir, body) {
+    const request = parseCliRequest(body);
+    if (typeof request === 'string')
+        return { ok: false, error: request };
+    return { ok: true, response: await runCliRequest(contextDir, request) };
+}

package/dist/transport/guards.d.ts

@@ -31,5 +31,19 @@ export declare function assertSafeBind(host: string): void;
  * raw Authorization header value (e.g. "Bearer abc"); the scheme is tolerated.
  */
 export declare function checkBearer(configured: string | undefined, presented: string | undefined): GuardResult;
+/**
+ * Multi-token auth gate (t-677): each configured token maps to one identity,
+ * so a single scoped endpoint (the knowledge-only service) can serve several
+ * identities while still deriving WHICH one made a given call — the bearer
+ * itself is the identity claim, there is no separate login step. Same
+ * refusal shape as checkBearer; `identity` is only set on success.
+ *
+ * Every candidate token is compared with the same timing-safe routine as
+ * checkBearer, so this doesn't reintroduce a timing side-channel by doing a
+ * plain map lookup instead.
+ */
+export declare function checkBearerMulti(configured: Record<string, string> | undefined, presented: string | undefined): GuardResult & {
+    identity?: string;
+};
 /** Oversized guard: refuse a body beyond the cap before the handler runs. */
 export declare function checkPayloadSize(bytes: number, cap?: number): GuardResult;

package/dist/transport/guards.js

@@ -98,6 +98,32 @@ export function checkBearer(configured, presented) {
     }
     return { ok: true };
 }
+/**
+ * Multi-token auth gate (t-677): each configured token maps to one identity,
+ * so a single scoped endpoint (the knowledge-only service) can serve several
+ * identities while still deriving WHICH one made a given call — the bearer
+ * itself is the identity claim, there is no separate login step. Same
+ * refusal shape as checkBearer; `identity` is only set on success.
+ *
+ * Every candidate token is compared with the same timing-safe routine as
+ * checkBearer, so this doesn't reintroduce a timing side-channel by doing a
+ * plain map lookup instead.
+ */
+export function checkBearerMulti(configured, presented) {
+    const entries = configured ? Object.entries(configured) : [];
+    if (entries.length === 0) {
+        return { ok: false, error: 'unauthorized: no identities configured for this endpoint' };
+    }
+    const token = (presented ?? '').replace(/^Bearer\s+/i, '').trim();
+    if (token === '')
+        return { ok: false, error: 'unauthorized: missing bearer token' };
+    for (const [identity, candidate] of entries) {
+        if (timingSafeEqual(token, candidate)) {
+            return { ok: true, identity };
+        }
+    }
+    return { ok: false, error: 'unauthorized: bearer token mismatch' };
+}
 /** Oversized guard: refuse a body beyond the cap before the handler runs. */
 export function checkPayloadSize(bytes, cap = DEFAULT_MAX_BODY_BYTES) {
     if (bytes > cap) {

package/dist/transport/http-server.d.ts

@@ -1,12 +1,39 @@
+import type { McpServer } from '@modelcontextprotocol/server';
 export interface HttpServeOptions {
     contextDir: string;
     host: string;
     port: number;
-    /** When set, every request must present this bearer token. */
+    /** Single-token mode: every request must present this bearer token. */
     token?: string;
+    /**
+     * Multi-token mode (t-677): token → identity. Mutually exclusive with
+     * `token` — when set, `checkBearerMulti` resolves the caller's identity
+     * from whichever configured token it presents instead of a single shared
+     * secret. Required for `createServer` factories that need an identity
+     * (e.g. the knowledge-only service); refuses every call if empty.
+     */
+    tokens?: Record<string, string>;
     maxBytes?: number;
     /** SSE keep-alive ping interval (ms). Default HEARTBEAT_MS; tests use a small value. */
     heartbeatMs?: number;
+    /**
+     * Optional path to the knowledge-gaps directory. Forwarded to the server
+     * factory so zero-result knowledge_recall calls can log misses.
+     */
+    gapsDir?: string;
+    /**
+     * Server factory for this endpoint. Defaults to the full loom server
+     * (createLoomServer, identity 'art') — pass createKnowledgeOnlyServer to
+     * scope the endpoint to knowledge tools only. `identity` is resolved from
+     * `tokens` per connection; always 'art' in single-token/no-auth mode.
+     */
+    createServer?: (ctx: {
+        contextDir: string;
+        gapsDir?: string;
+        identity: string;
+    }) => {
+        server: McpServer;
+    };
 }
 export interface HttpServeHandle {
     /** The actually-bound port (resolves a 0 request to the OS-assigned port). */