@fuxi-ailabs/crowdmemory-codex-plugin 0.0.0-stage → 0.1.1

package/lib/core/replay.js

@@ -0,0 +1,46 @@
+// Crowd Memory adapter core — edit in distributions/memory-adapter-core, then `npm run sync` there (copies into every adapter).
+/**
+ * The shell command of a tool call as a replay can rerun it (v1.1 FR-44): the workspace root written as `.`, and
+ * nothing recorded when the command is too long or still names a secret or a home directory after that (a cut or
+ * redacted command would replay something else).
+ */
+import { isAbsolute } from 'node:path';
+import { redact } from './redact.js';
+/** The command is recorded only up to this many code points (longer: not recorded, never cut). */
+export const COMMAND_MAX = 4096;
+const PATH_CHAR = /[A-Za-z0-9._~+@%-]/u;
+/** `command` with the absolute workspace root written as `.` (a replay restores the workspace somewhere else). */
+export function relativeToWorkspace(command, root) {
+    if (root === undefined || !isAbsolute(root))
+        return command;
+    const base = root.replace(/\/+$/u, '');
+    if (base === '')
+        return command;
+    let out = '';
+    let from = 0;
+    for (let at = command.indexOf(base); at >= 0; at = command.indexOf(base, from)) {
+        const before = at === 0 ? '' : command[at - 1] ?? '';
+        const after = command[at + base.length] ?? '';
+        const startsPath = before === '' || (before !== '/' && !PATH_CHAR.test(before));
+        const endsPath = after === '' || after === '/' || !PATH_CHAR.test(after);
+        if (startsPath && endsPath) {
+            out += `${command.slice(from, at)}.`;
+            from = at + base.length;
+        }
+        else {
+            out += command.slice(from, at + 1);
+            from = at + 1;
+        }
+    }
+    return out + command.slice(from);
+}
+/** The command as recorded, or `undefined` (see the module comment). */
+export function replayCommand(command, workspaceRoot) {
+    if (command.length > COMMAND_MAX * 2)
+        return undefined;
+    const relative = relativeToWorkspace(command, workspaceRoot).trim();
+    if (relative === '' || Array.from(relative).length > COMMAND_MAX)
+        return undefined;
+    const redacted = redact(relative);
+    return redacted.secrets || redacted.home ? undefined : relative;
+}

package/lib/core/signature.js

@@ -0,0 +1,45 @@
+// Crowd Memory adapter core — edit in distributions/memory-adapter-core, then `npm run sync` there (copies into every adapter).
+/**
+ * Error signature `crowdmemory-error-signature/v1` (COLLAB §3.2, spec FR-05), the TypeScript twin of
+ * `crowdmemory_contracts.signature`. The regular-expression sources below are copied
+ * verbatim from the contract and checked against the published vectors file by the tests, so a
+ * contract change that is not mirrored here fails loudly.
+ */
+import { createHash } from 'node:crypto';
+export const ALGORITHM_ID = 'crowdmemory-error-signature/v1';
+// Plain string literals (not String.raw): bundlers may cook \u escapes inside raw templates.
+export const LINE_SPLIT_PATTERN = '\\r\\n|\\r|\\n';
+export const WHITESPACE_CLASS = '[ \\t\\u000b\\u000c\\u00a0\\u3000\\ufeff]';
+const PATH_STOP = ' \\t\\u000b\\u000c\\u00a0\\u3000\\ufeff\'"`:;,()\\[\\]{}<>|'
+    + '\\uff0c\\u3002\\uff1a\\uff1b\\u3001\\uff08\\uff09\\u3010\\u3011\\u300c\\u300d\\u300a\\u300b\\uff01\\uff1f';
+export const PATH_PATTERN = '(?<![A-Za-z0-9_.~/\\-])(?:~/[^' + PATH_STOP + ']*|/[^' + PATH_STOP + ']+)';
+export const HEX_PATTERN = '0[xX][0-9a-fA-F]+';
+export const DIGITS_PATTERN = '[0-9]+';
+export const PATH_TOKEN = '<path>';
+export const NUMBER_TOKEN = '#';
+const LINE_SPLIT = new RegExp(LINE_SPLIT_PATTERN, 'u');
+const STRIP = new RegExp(`^${WHITESPACE_CLASS}+|${WHITESPACE_CLASS}+$`, 'gu');
+const PATH = new RegExp(PATH_PATTERN, 'gu');
+const HEX = new RegExp(HEX_PATTERN, 'gu');
+const DIGITS = new RegExp(DIGITS_PATTERN, 'gu');
+function strip(text) {
+    return text.replace(STRIP, '');
+}
+/** The normalized first non-empty line, or `''` when the text has none. */
+export function normalizeErrorLine(text) {
+    if (text === null || text === undefined || text === '')
+        return '';
+    for (const line of text.split(LINE_SPLIT)) {
+        if (strip(line) === '')
+            continue;
+        return strip(line.replace(PATH, PATH_TOKEN).replace(HEX, NUMBER_TOKEN).replace(DIGITS, NUMBER_TOKEN));
+    }
+    return '';
+}
+/** `sha256:<hex>` of the normalized line, or `undefined` when the text carries no content. */
+export function errorSignature(text) {
+    const normalized = normalizeErrorLine(text);
+    if (normalized === '')
+        return undefined;
+    return `sha256:${createHash('sha256').update(normalized, 'utf8').digest('hex')}`;
+}

package/lib/core/state.js

@@ -0,0 +1,167 @@
+/**
+ * Per-session routing state, shared by the short-lived hook processes and the MCP server of one host session.
+ *
+ * Each session ref has one JSON file in a private directory (owned by this user, mode 0700; files 0600), changed
+ * only under an exclusive lock file. Callers keep Runtime requests outside `update` except for `session.start`, so
+ * parallel hooks of one session do not queue behind each other's network calls.
+ */
+import { constants, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { lstat, mkdir, open, readdir, rename, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
+export const STATE_MAX_BYTES = 1024 * 1024;
+const LOCK_WAIT_MS = 8000;
+const LOCK_STALE_MS = 30000;
+/** Session files untouched for this long are removed when a new session starts. */
+export const STATE_RETENTION_MS = 7 * 24 * 3600 * 1000;
+function keyOf(ref) {
+    return createHash('sha256').update(ref, 'utf8').digest('hex').slice(0, 40);
+}
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+export class StateStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async ensureDir() {
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        const info = await lstat(this.dir);
+        if (!info.isDirectory() || (process.getuid !== undefined && info.uid !== process.getuid()) || (info.mode & 0o077) !== 0) {
+            throw new Error('crowdmemory state directory must be a private directory owned by this user');
+        }
+    }
+    async lock(key) {
+        const path = join(this.dir, `${key}.lock`);
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        for (;;) {
+            try {
+                const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                await handle.write(String(process.pid));
+                await handle.close();
+                return async () => { await unlink(path).catch(() => undefined); };
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            try {
+                // a holder that crashed leaves its lock behind: take it over once it is clearly stale
+                if (Date.now() - (await lstat(path)).mtimeMs > LOCK_STALE_MS)
+                    await unlink(path).catch(() => undefined);
+            }
+            catch {
+                // gone in between: retry at once
+            }
+            if (Date.now() > deadline)
+                throw new Error('crowdmemory state lock timed out');
+            await sleep(15 + Math.floor(Math.random() * 15));
+        }
+    }
+    async load(path) {
+        let handle;
+        try {
+            handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || (process.getuid !== undefined && info.uid !== process.getuid()) || (info.mode & 0o077) !== 0) {
+                throw new Error('crowdmemory state file must be a private regular file owned by this user');
+            }
+            if (info.size > STATE_MAX_BYTES)
+                throw new Error('crowdmemory state file too large');
+            const value = JSON.parse(await handle.readFile({ encoding: 'utf8' }));
+            if (value === null || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('invalid crowdmemory state');
+            return value;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async save(path, record) {
+        const temporary = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(record), 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(temporary, path);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => undefined);
+            throw error;
+        }
+    }
+    /** The record of `ref` (or `undefined`), read without the lock. */
+    async read(ref) {
+        await this.ensureDir();
+        return this.load(join(this.dir, `${keyOf(ref)}.json`));
+    }
+    /**
+     * Run `change` on the record of `ref` under its lock and save the result; `create` gives the record when there is
+     * none yet (without it, `change` gets `undefined` and nothing is saved). A throw saves nothing.
+     */
+    async update(ref, change, create) {
+        await this.ensureDir();
+        const key = keyOf(ref);
+        const path = join(this.dir, `${key}.json`);
+        const release = await this.lock(key);
+        try {
+            const record = (await this.load(path)) ?? create?.();
+            if (record === undefined)
+                return undefined;
+            const result = await change(record);
+            await this.save(path, record);
+            return result;
+        }
+        finally {
+            await release();
+        }
+    }
+    /** Remove session files not touched for `STATE_RETENTION_MS` (best effort). */
+    async prune(now = Date.now()) {
+        let removed = 0;
+        try {
+            await this.ensureDir();
+            for (const name of await readdir(this.dir)) {
+                if (!name.endsWith('.json'))
+                    continue;
+                try {
+                    if (now - (await stat(join(this.dir, name))).mtimeMs > STATE_RETENTION_MS) {
+                        await unlink(join(this.dir, name));
+                        removed += 1;
+                    }
+                }
+                catch {
+                    // raced with another session: skip
+                }
+            }
+        }
+        catch {
+            // pruning never fails a hook
+        }
+        return removed;
+    }
+}
+/** True when this module is the script node was started with (paths compared after resolving symlinks, e.g. /tmp on macOS). */
+export function isEntry(moduleUrl) {
+    const script = process.argv[1];
+    if (script === undefined)
+        return false;
+    try {
+        return realpathSync(script) === realpathSync(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return false;
+    }
+}

package/lib/core/util.js

@@ -0,0 +1,60 @@
+// Crowd Memory adapter core — edit in distributions/memory-adapter-core, then `npm run sync` there (copies into every adapter).
+import { createHash } from 'node:crypto';
+/** Canonical JSON: object keys sorted by code unit, no insignificant whitespace, `undefined` members dropped. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        const text = JSON.stringify(value);
+        return text === undefined ? 'null' : text;
+    }
+    if (Array.isArray(value))
+        return `[${value.map(item => canonicalJson(item === undefined ? null : item)).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+}
+export function sha256Digest(text) {
+    return `sha256:${createHash('sha256').update(text, 'utf8').digest('hex')}`;
+}
+/** Whole-second UTC timestamp (the contract accepts fractions; whole seconds keep fixtures stable). */
+export function isoNow(now = new Date()) {
+    return now.toISOString().replace(/\.\d{3}Z$/u, 'Z');
+}
+/** Last `maxBytes` UTF-8 bytes of `text`, cut on a code-point boundary; drops a partial leading line when cut. */
+export function utf8Tail(text, maxBytes) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (bytes.length <= maxBytes)
+        return text;
+    let start = bytes.length - maxBytes;
+    while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80)
+        start += 1;
+    const tail = bytes.subarray(start).toString('utf8');
+    const newline = tail.indexOf('\n');
+    return newline >= 0 && newline < tail.length - 1 ? tail.slice(newline + 1) : tail;
+}
+/** First `maxBytes` UTF-8 bytes of `text`, cut on a code-point boundary. */
+export function utf8Head(text, maxBytes) {
+    const bytes = Buffer.from(text, 'utf8');
+    if (bytes.length <= maxBytes)
+        return text;
+    let end = maxBytes;
+    while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80)
+        end -= 1;
+    return bytes.subarray(0, end).toString('utf8');
+}
+/** At most `max` code points (JSON Schema `maxLength` counts code points). */
+export function codePoints(text, max) {
+    const points = Array.from(text);
+    return points.length <= max ? text : points.slice(0, max).join('');
+}
+/** Text of content blocks (`{type:'text', text}`), joined by newlines. */
+export function blockText(blocks) {
+    if (typeof blocks === 'string')
+        return blocks;
+    if (!Array.isArray(blocks))
+        return '';
+    return blocks
+        .map(block => block?.type === 'text' ? String(block.text ?? '') : '')
+        .filter(text => text !== '')
+        .join('\n');
+}

package/lib/hook.js

@@ -0,0 +1,26 @@
+import { CodexMemory, configFromEnv } from './memory.js';
+import { isEntry } from './core/state.js';
+export async function main() {
+    try {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of process.stdin) {
+            size += Buffer.byteLength(chunk);
+            if (size > 1024 * 1024)
+                return;
+            chunks.push(Buffer.from(chunk));
+        }
+        const event = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!event || typeof event !== 'object' || Array.isArray(event))
+            return;
+        const result = await new CodexMemory(configFromEnv()).hook(event);
+        if (result)
+            process.stdout.write(JSON.stringify(result) + '\n');
+    }
+    catch {
+        if (process.env['CROWDMEMORY_DEBUG'] === '1')
+            process.stderr.write('crowdmemory: hook unavailable; continuing\n');
+    }
+}
+if (isEntry(import.meta.url))
+    void main();

package/lib/mcp.js

@@ -0,0 +1,94 @@
+/**
+ * MCP server (stdio, newline-delimited JSON-RPC 2.0) that offers memory_search / memory_read / memory_note to
+ * Codex and its subagents. One server runs per Codex session; it learns the calling session from the
+ * argument the plugin's PreToolUse hook adds, so it keeps no session state of its own. No MCP SDK: the plugin has no
+ * runtime dependencies.
+ */
+import { createInterface } from 'node:readline';
+import { ADAPTER_VERSION, configFromEnv, CodexMemory } from './memory.js';
+import { memoryTools } from './tools.js';
+import { isEntry } from './core/state.js';
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const MAX_LINE = 4 * 1024 * 1024;
+export class McpServer {
+    write;
+    tools;
+    constructor(memory, write) {
+        this.write = write;
+        this.tools = new Map(memoryTools(memory).map(tool => [tool.name, tool]));
+    }
+    reply(id, result) {
+        this.write(JSON.stringify({ jsonrpc: '2.0', id, result }));
+    }
+    error(id, code, message) {
+        this.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }));
+    }
+    async handle(line) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            this.error(null, -32700, 'parse error');
+            return;
+        }
+        if (request === null || typeof request !== 'object' || typeof request.method !== 'string') {
+            this.error(request?.id ?? null, -32600, 'invalid request');
+            return;
+        }
+        const notification = !('id' in request);
+        const id = request.id ?? null;
+        const params = (request.params ?? {});
+        switch (request.method) {
+            case 'initialize': {
+                const asked = typeof params['protocolVersion'] === 'string' ? params['protocolVersion'] : '';
+                this.reply(id, {
+                    protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'crowdmemory', version: ADAPTER_VERSION },
+                });
+                return;
+            }
+            case 'ping':
+                this.reply(id, {});
+                return;
+            case 'tools/list':
+                // Codex discovers tools through MCP tools/list.
+                this.reply(id, { tools: [...this.tools.values()].map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+                return;
+            case 'tools/call': {
+                const tool = this.tools.get(String(params['name'] ?? ''));
+                if (tool === undefined) {
+                    this.error(id, -32602, `unknown tool ${String(params['name'] ?? '')}`);
+                    return;
+                }
+                const args = params['arguments'] !== null && typeof params['arguments'] === 'object' && !Array.isArray(params['arguments'])
+                    ? params['arguments'] : {};
+                let text;
+                try {
+                    text = await tool.execute(args, String(id));
+                }
+                catch {
+                    text = '记忆暂不可用 (memory temporarily unavailable: internal_adapter_error). Continue without it.';
+                }
+                this.reply(id, { content: [{ type: 'text', text }], isError: false });
+                return;
+            }
+            default:
+                if (!notification)
+                    this.error(id, -32601, `method not found: ${request.method}`);
+        }
+    }
+}
+export function serve() {
+    const server = new McpServer(new CodexMemory(configFromEnv()), line => { process.stdout.write(`${line}\n`); });
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    lines.on('line', line => {
+        if (line.trim() === '' || line.length > MAX_LINE)
+            return;
+        void server.handle(line);
+    });
+    lines.on('close', () => { process.exitCode = 0; });
+}
+if (isEntry(import.meta.url))
+    serve();