@jbarket/loomai 0.5.0 → 0.7.0

package/dist/cli/serve.js

@@ -4,10 +4,19 @@
  * optional bearer token. Host/port/token come from flags or env:
  *   --http  --host <h>  --port <n>   (LOOM_HTTP_HOST, LOOM_HTTP_PORT, LOOM_BEARER_TOKEN)
  * Bind-safety refuses a public/0.0.0.0 host; Tailscale is the access control.
+ *
+ * `--scope knowledge` (t-677) starts the standalone knowledge-only service
+ * instead of the full server — same transport, tailscale-bind-safety, and
+ * bearer-gating pattern, but the MCP tool surface is knowledge_* only and
+ * auth is per-identity (LOOM_KNOWLEDGE_BEARER_TOKENS, "identity:token,...")
+ * so the acting identity is derivable server-side for attribution. It is
+ * NOT started by default and ships disabled — nothing in this repo enables
+ * or deploys it; standing it up is a separate, deliberate operational step.
  */
 import { parseArgs } from 'node:util';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createLoomServer } from '../server.js';
+import { createKnowledgeOnlyServer } from '../transport/knowledge-server.js';
 import { startHttpServer } from '../transport/http-server.js';
 import { resolveContextDir } from '../config.js';
 const USAGE = `Usage: loom serve [options]
@@ -17,12 +26,49 @@ mesh-reachable HTTP daemon instead.
 
 Options:
   --http                 Serve over HTTP instead of stdio
+  --scope <full|knowledge>  Tool surface for --http (default full);
+                         knowledge without --http is rejected
   --host <h>             HTTP bind host (env LOOM_HTTP_HOST, default 127.0.0.1)
-  --port <n>             HTTP port (env LOOM_HTTP_PORT, default 8787)
+  --port <n>             HTTP port (env LOOM_HTTP_PORT, or LOOM_KNOWLEDGE_HTTP_PORT
+                         for --scope knowledge, default 8787 / 8788)
   --help, -h             Show this help
 
-Bearer token comes from LOOM_BEARER_TOKEN. Bind-safety refuses a public host.
+--scope full (default): bearer token from LOOM_BEARER_TOKEN.
+--scope knowledge: per-identity bearer from LOOM_KNOWLEDGE_BEARER_TOKENS,
+  format "identity:token,identity:token" — e.g. "art:abc123,mark:def456".
+  Required and non-empty; the knowledge-only service refuses to boot without
+  at least one identity configured. Registers knowledge_* tools only — no
+  identity/memory/dossier tools on this surface.
+
+Bind-safety refuses a public host in both scopes.
 `;
+/**
+ * Parse "identity:token,identity:token" into a token → identity map ready
+ * for startHttpServer's `tokens` option (checkBearerMulti). Throws with a
+ * message naming the offending pair on malformed input — fail loud at CLI
+ * startup rather than silently dropping an identity.
+ */
+export function parseIdentityTokens(raw) {
+    const tokens = {};
+    const pairs = raw.split(',');
+    for (let i = 0; i < pairs.length; i++) {
+        const trimmed = pairs[i].trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf(':');
+        const identity = idx > 0 ? trimmed.slice(0, idx).trim() : '';
+        const token = idx > 0 ? trimmed.slice(idx + 1).trim() : '';
+        if (!identity || !token) {
+            // Never echo `trimmed` — a malformed pair is exactly the shape a
+            // pasted-without-colon secret takes, and this error can land in
+            // stderr/journal/CI logs. Report position only, never content.
+            throw new Error(`malformed identity:token pair at position ${i + 1} — expected "identity:token", ` +
+                `got ${identity ? 'an identity with no token' : 'no identity'} (value withheld from this error)`);
+        }
+        tokens[identity] = token;
+    }
+    return tokens;
+}
 export async function run(argv, io) {
     let values;
     try {
@@ -30,6 +76,7 @@ export async function run(argv, io) {
             args: argv,
             options: {
                 http: { type: 'boolean', default: false },
+                scope: { type: 'string', default: 'full' },
                 host: { type: 'string' },
                 port: { type: 'string' },
                 help: { type: 'boolean', short: 'h' },
@@ -46,19 +93,61 @@ export async function run(argv, io) {
         io.stdout(USAGE);
         return 0;
     }
+    if (values.scope !== 'full' && values.scope !== 'knowledge') {
+        io.stderr(`Unknown --scope "${values.scope}" — expected "full" or "knowledge".\n${USAGE}`);
+        return 2;
+    }
+    // The knowledge-only surface exists only as an HTTP service. Without
+    // --http the stdio branch below would open the FULL server — every
+    // identity/memory/dossier tool — under a flag that asked for less
+    // (PR #124 review). Refuse before any transport opens.
+    if (values.scope === 'knowledge' && !values.http) {
+        io.stderr(`--scope knowledge requires --http — the knowledge-only surface is HTTP-only; ` +
+            `refusing to start the full stdio server instead.\n${USAGE}`);
+        return 2;
+    }
     const contextDir = resolveContextDir();
+    // Optional: gaps directory for recall-miss logging (LOOM_GAPS_DIR env var).
+    // When set, knowledge_recall misses are appended to ${gapsDir}/recall-miss.jsonl
+    // so the knowledge-mine script can surface them as expansion candidates.
+    const gapsDir = process.env.LOOM_GAPS_DIR || undefined;
+    if (values.http && values.scope === 'knowledge') {
+        const host = values.host ?? process.env.LOOM_HTTP_HOST ?? '127.0.0.1';
+        const port = Number(values.port ?? process.env.LOOM_KNOWLEDGE_HTTP_PORT ?? 8788);
+        const rawTokens = process.env.LOOM_KNOWLEDGE_BEARER_TOKENS ?? '';
+        let tokens;
+        try {
+            tokens = parseIdentityTokens(rawTokens);
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n${USAGE}`);
+            return 2;
+        }
+        if (Object.keys(tokens).length === 0) {
+            io.stderr(`--scope knowledge requires LOOM_KNOWLEDGE_BEARER_TOKENS ` +
+                `("identity:token,identity:token") — refusing to start unauthenticated.\n${USAGE}`);
+            return 2;
+        }
+        const handle = await startHttpServer({
+            contextDir, host, port, tokens, gapsDir, createServer: createKnowledgeOnlyServer,
+        });
+        io.stderr(`loom: knowledge-only HTTP MCP daemon on http://${handle.host}:${handle.port} ` +
+            `(per-identity bearer: ${Object.keys(tokens).join(', ')})\n`);
+        await new Promise(() => { });
+        return 0;
+    }
     if (values.http) {
         const host = values.host ?? process.env.LOOM_HTTP_HOST ?? '127.0.0.1';
         const port = Number(values.port ?? process.env.LOOM_HTTP_PORT ?? 8787);
         const token = process.env.LOOM_BEARER_TOKEN || undefined;
-        const handle = await startHttpServer({ contextDir, host, port, token });
+        const handle = await startHttpServer({ contextDir, host, port, token, gapsDir });
         io.stderr(`loom: HTTP MCP daemon on http://${handle.host}:${handle.port} ` +
             `(${token ? 'bearer-gated' : 'open — network is the boundary'})\n`);
         // Hold open until the process is signalled.
         await new Promise(() => { });
         return 0;
     }
-    const { server } = createLoomServer({ contextDir });
+    const { server } = createLoomServer({ contextDir, gapsDir });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // connect() resolves when the stdio transport STARTS, not when it closes.

package/dist/cli/subcommands.d.ts

@@ -3,5 +3,5 @@
  * (src/cli/index.ts) and the CLI-vs-MCP routing gate (src/index.ts) so
  * the set never drifts between entry points.
  */
-export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate', 'pieces'];
 export type Subcommand = typeof SUBCOMMANDS[number];

package/dist/cli/subcommands.js

@@ -5,7 +5,7 @@
  */
 export const SUBCOMMANDS = [
     'wake', 'recall', 'remember', 'forget', 'update',
-    'memory', 'knowledge', 'update-identity', 'bootstrap', 'serve',
+    'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve',
     'inject', 'harness',
-    'install', 'doctor', 'migrate',
+    'install', 'doctor', 'migrate', 'pieces',
 ];

package/dist/cli/update.js

@@ -11,11 +11,14 @@ const USAGE = `Usage: loom update <ref> [options]
        loom update --category <cat> --title <exact> [options]
 
 Updates content (from stdin or \$EDITOR) and/or metadata on an existing
-memory.
+memory. --confirm/--contradict record an observation against a feedback
+memory's confidence instead — no body required for those.
 
 Options:
   --category <name>      Identify by category (with --title)
   --title <exact>        Identify by title (with --category)
+  --confirm               Feedback memories only: raise confidence (+0.05)
+  --contradict            Feedback memories only: lower confidence (-0.1)
   --json                 Emit UpdateResult
   --context-dir <path>   Agent context dir
   --help, -h             Show this help
@@ -29,6 +32,8 @@ export async function run(argv, io) {
             options: {
                 category: { type: 'string' },
                 title: { type: 'string' },
+                confirm: { type: 'boolean' },
+                contradict: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
             },
             strict: true,
@@ -49,6 +54,15 @@ export async function run(argv, io) {
         io.stderr(`Provide a <ref> or --category+--title.\n${USAGE}`);
         return 2;
     }
+    if (parsed.values.confirm && parsed.values.contradict) {
+        io.stderr(`--confirm and --contradict are mutually exclusive.\n${USAGE}`);
+        return 2;
+    }
+    const observation = parsed.values.confirm
+        ? 'confirm'
+        : parsed.values.contradict
+            ? 'contradict'
+            : undefined;
     const env = resolveEnv(global, io.env);
     try {
         assertStackVersionCompatible(env.contextDir);
@@ -57,23 +71,28 @@ export async function run(argv, io) {
         io.stderr(`${err.message}\n`);
         return 1;
     }
+    // A pure observation needs no new body — --confirm/--contradict alone is a
+    // complete update. Any other call still requires one (existing behavior).
     let body;
-    try {
-        body = await readBody(io, 'update');
-    }
-    catch (err) {
-        io.stderr(`${err.message}\n`);
-        return 1;
-    }
-    if (!body) {
-        io.stderr(`body cannot be empty\n`);
-        return 2;
+    if (!observation) {
+        try {
+            body = await readBody(io, 'update');
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        if (!body) {
+            io.stderr(`body cannot be empty\n`);
+            return 2;
+        }
     }
     const input = {
         ref,
         category: parsed.values.category,
         title: parsed.values.title,
         content: body,
+        observation,
     };
     if (env.json) {
         const backend = createBackend(env.contextDir);

package/dist/clients.js

@@ -14,17 +14,20 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertSafePathSegment } from './path-safety.js';
+import { INSTALL_TARGETS } from './install/harnesses.js';
 // ─── Tool list ────────────────────────────────────────────────────────────────
 // Canonical tool names — used to generate the prefix-specific list per client
 export const TOOLS = [
     'identity', 'dossier', 'remember', 'recall', 'update', 'forget',
     'memory_list', 'memory_prune', 'find_similar', 'memory_audit', 'episodes',
-    'memory_archive', 'memory_restore',
+    'memory_archive', 'memory_restore', 'memory_merge', 'memory_history', 'memory_revision_restore',
     'memory_propose', 'memory_proposals', 'memory_ratify', 'memory_reject',
     'update_identity', 'bootstrap', 'harness_init', 'harness_describe',
     'knowledge_write', 'knowledge_recall', 'knowledge_maintain',
     'knowledge_archive', 'knowledge_restore', 'knowledge_supersede', 'knowledge_move', 'knowledge_merge',
     'knowledge_purge', 'knowledge_verify', 'knowledge_history',
+    'person_write', 'person_verify', 'person_archive', 'person_restore',
+    'person', 'person_list', 'person_history', 'person_revision_restore',
 ];
 function toolList(prefix) {
     return TOOLS.map((t) => `\`${prefix}${t}\``).join(', ');
@@ -34,11 +37,11 @@ const ADAPTERS = {
     'claude-code': `## Runtime: Claude Code
 
 You are running in Claude Code (Anthropic CLI). Loom tools use double-underscore prefix:
-${toolList('mcp__loom__')}`,
+${toolList(INSTALL_TARGETS['claude-code'].toolPrefix)}`,
     'gemini-cli': `## Runtime: Gemini CLI
 
-You are running in Gemini CLI (Google). Loom tools use double-underscore prefix:
-${toolList('mcp__loom__')}`,
+You are running in Gemini CLI (Google). Loom tools use single-underscore prefix:
+${toolList(INSTALL_TARGETS['gemini-cli'].toolPrefix)}`,
 };
 // ─── Loader ──────────────────────────────────────────────────────────────────
 export function getBuiltInAdapter(client) {

package/dist/config.d.ts

@@ -25,6 +25,20 @@ export declare function assertContextBootable(contextDir: string, defaultPath?:
 export declare function resolveRepoRoot(): string;
 export declare function resolveSqliteDbPath(contextDir: string): string;
 export declare function resolveKnowledgeDbPath(contextDir: string): string;
+/**
+ * Resolve the acting identity's name for actor attribution (knowledge
+ * pages.author / page_revisions.actor / verifications.verifier). This is
+ * deliberately NOT a tool argument — an LLM-supplied free-text identity is
+ * spoofable (any caller could claim to be any identity), so it is derived
+ * server-side from the connection instead.
+ *
+ * LOOM_IDENTITY overrides explicitly (useful for the multi-identity
+ * knowledge service, where each bearer token maps to a known identity).
+ * Otherwise derived from the context dir's real path basename — this
+ * resolves symlink aliases (e.g. `~/.config/loom/default` -> the real
+ * `.../loom/art` dir) to the actual identity name rather than the alias.
+ */
+export declare function resolveIdentityName(contextDir: string): string;
 /**
  * Local-only observation logs (e.g. `telemetry/recall.jsonl`). Lives inside
  * the context dir so it travels with the agent and never leaves the machine.

package/dist/config.js

@@ -14,10 +14,10 @@
  *   2. --context-dir CLI argument
  *   3. ~/.config/loom/default (fallback)
  */
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, statSync, realpathSync } from 'node:fs';
 /**
  * The single canonical helper for the default context path. Every call
  * site that needs `~/.config/loom/default` must go through this —
@@ -70,6 +70,29 @@ export function resolveSqliteDbPath(contextDir) {
 export function resolveKnowledgeDbPath(contextDir) {
     return process.env.LOOM_KNOWLEDGE_DB_PATH ?? resolve(contextDir, 'knowledge.db');
 }
+/**
+ * Resolve the acting identity's name for actor attribution (knowledge
+ * pages.author / page_revisions.actor / verifications.verifier). This is
+ * deliberately NOT a tool argument — an LLM-supplied free-text identity is
+ * spoofable (any caller could claim to be any identity), so it is derived
+ * server-side from the connection instead.
+ *
+ * LOOM_IDENTITY overrides explicitly (useful for the multi-identity
+ * knowledge service, where each bearer token maps to a known identity).
+ * Otherwise derived from the context dir's real path basename — this
+ * resolves symlink aliases (e.g. `~/.config/loom/default` -> the real
+ * `.../loom/art` dir) to the actual identity name rather than the alias.
+ */
+export function resolveIdentityName(contextDir) {
+    if (process.env.LOOM_IDENTITY)
+        return process.env.LOOM_IDENTITY;
+    try {
+        return basename(realpathSync(contextDir));
+    }
+    catch {
+        return basename(contextDir);
+    }
+}
 /**
  * Local-only observation logs (e.g. `telemetry/recall.jsonl`). Lives inside
  * the context dir so it travels with the agent and never leaves the machine.

package/dist/index.js

@@ -2,10 +2,16 @@
 /**
  * Loom — CLI + stdio MCP entry point.
  *
- * When argv[2] is a known CLI subcommand or --help/--version, routes to
- * src/cli/index.ts. Otherwise (or if argv is empty / only flags), falls
- * through to the MCP stdio server so existing .mcp.json configs keep
- * working.
+ * When the first non-global token is a known CLI subcommand or
+ * --help/--version, routes to src/cli/index.ts. Otherwise (or if argv is
+ * empty / only flags), falls through to the MCP stdio server so existing
+ * .mcp.json configs keep working.
+ *
+ * "First non-global token", not argv[2]: --context-dir and friends are
+ * documented as global flags, so `loom --context-dir DIR knowledge write`
+ * has to reach the CLI. Routing on argv[2] alone sent it to the stdio
+ * server instead, which read an empty stdin and exited 0 — a write verb
+ * reporting success having never entered the write path (t-665).
  *
  * Configure via environment variables:
  *   LOOM_CONTEXT_DIR         — path to identity/memory directory (required)
@@ -16,26 +22,40 @@
  */
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createLoomServer } from './server.js';
 import { resolveContextDir } from './config.js';
 import { SUBCOMMANDS } from './cli/subcommands.js';
+import { firstNonGlobalIndex } from './cli/args.js';
+import { findPiece } from './cli/pieces.js';
 const CLI_KEYWORDS = new Set(SUBCOMMANDS);
 function isCliInvocation(argv) {
-    const first = argv[2];
+    const args = argv.slice(2);
+    const first = args[firstNonGlobalIndex(args)];
     if (first === undefined)
         return false;
     if (first === '--help' || first === '-h')
         return true;
     if (first === '--version' || first === '-V')
         return true;
-    return CLI_KEYWORDS.has(first);
+    if (CLI_KEYWORDS.has(first))
+        return true;
+    // An installed piece (loom-<first> on PATH) is a CLI call too. Anything else
+    // still falls through to the stdio server, exactly as before.
+    return findPiece(first, process.env) !== undefined;
 }
 export { isCliInvocation };
 async function main() {
     if (isCliInvocation(process.argv)) {
         const { runCli } = await import('./cli/index.js');
-        process.exit(await runCli(process.argv.slice(2)));
+        const code = await runCli(process.argv.slice(2));
+        // Drain stdout before exiting — without this, large outputs (e.g.
+        // `loom memory list --json` on a big store) truncate at 64 KiB when
+        // piped because process.exit() tears down the stream before the OS
+        // buffer drains (t-198). process.stdout.write('', cb) fires after all
+        // prior writes have been handed to the OS.
+        process.stdout.write('', () => process.exit(code));
+        return;
     }
     const contextDir = resolveContextDir();
     const { server } = createLoomServer({ contextDir });

package/dist/injection/harnesses.js

@@ -2,9 +2,15 @@
  * Harness preset table for `loom inject`. Each entry names a target
  * harness, its canonical default path, and the MCP tool prefix to emit
  * in the injected instruction block.
+ *
+ * toolPrefix is NOT redeclared here — it's read from
+ * `src/install/harnesses.ts`'s INSTALL_TARGETS, which is the single
+ * source of truth for the prefix per harness (t-397: the two tables used
+ * to carry independent, disagreeing hardcoded values for codex).
  */
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { INSTALL_TARGETS } from '../install/harnesses.js';
 export const HARNESS_KEYS = [
     'claude-code',
     'codex',
@@ -15,19 +21,19 @@ export const HARNESSES = {
         key: 'claude-code',
         display: 'Claude Code',
         defaultPath: join(homedir(), '.claude', 'CLAUDE.md'),
-        toolPrefix: 'mcp__loom__',
+        toolPrefix: INSTALL_TARGETS['claude-code'].toolPrefix,
     },
     'codex': {
         key: 'codex',
         display: 'Codex',
         defaultPath: join(homedir(), '.codex', 'AGENTS.md'),
-        toolPrefix: 'mcp__loom__',
+        toolPrefix: INSTALL_TARGETS['codex'].toolPrefix,
     },
     'gemini-cli': {
         key: 'gemini-cli',
         display: 'Gemini CLI',
         defaultPath: join(homedir(), '.gemini', 'GEMINI.md'),
-        toolPrefix: 'mcp__loom__',
+        toolPrefix: INSTALL_TARGETS['gemini-cli'].toolPrefix,
     },
 };
 export function isHarnessKey(s) {

package/dist/install/harnesses.js

@@ -27,7 +27,9 @@ export const INSTALL_TARGETS = {
         mcpConfigHint: '~/.codex/config.toml',
         invoke: 'use the loom-setup skill',
         restart: 'restart the Codex session',
-        toolPrefix: 'mcp_loom_',
+        // mcp__loom__, not mcp_loom_: a live Codex session's own tool catalog
+        // names it mcp__loom__identity (t-397, verified 2026-09-05 by mark).
+        toolPrefix: 'mcp__loom__',
     },
     'gemini-cli': {
         key: 'gemini-cli',
@@ -36,6 +38,10 @@ export const INSTALL_TARGETS = {
         mcpConfigHint: '~/.gemini/settings.json',
         invoke: 'use the loom-setup skill',
         restart: 'exit and restart Gemini CLI',
+        // mcp_loom_, single underscores: gemini-cli joins server + '_' + tool
+        // and prepends 'mcp_' (MCP_QUALIFIED_NAME_SEPARATOR / generateValidName in
+        // packages/core/src/tools/mcp-tool.ts @ b25669d), so the model sees
+        // mcp_loom_identity (t-397, caught by mark in review of #122).
         toolPrefix: 'mcp_loom_',
     },
     'opencode': {

package/dist/server.d.ts

@@ -1,6 +1,13 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 export interface LoomServerConfig {
     contextDir: string;
+    /**
+     * Optional path to the knowledge-gaps directory (e.g. `~/Art/.knowledge-gaps`).
+     * When set, zero-result knowledge_recall calls append a miss entry to
+     * `${gapsDir}/recall-miss.jsonl`, feeding the expansion engine's second
+     * signal channel. Set via LOOM_GAPS_DIR env var in production.
+     */
+    gapsDir?: string;
 }
 export interface LoomServerInstance {
     server: McpServer;