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

package/lib/memory.js

@@ -0,0 +1,240 @@
+/** Codex event translation; storage, ranking, trust and wire format stay in the adapter core / Runtime. */
+import { basename, join, relative, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+import { RuntimeClient } from './core/client.js';
+import { StateStore } from './core/state.js';
+import { codePoints, utf8Tail, utf8Head } from './core/util.js';
+import { redactQueryText } from './core/redact.js';
+import { errorSignature } from './core/signature.js';
+import { maskedExit } from './core/mask.js';
+import { replayCommand } from './core/replay.js';
+import { fenceRecall, injectOf } from './core/recall.js';
+import { searchBody, searchReport, readReport } from './core/memory-tools.js';
+export const ADAPTER_VERSION = createRequire(import.meta.url)('../package.json').version;
+export const SESSION_ARG = 'crowdmemory_session';
+export const OWN_TOOL = /^mcp__crowdmemory__memory_(?:search|read|note)$/u;
+const text = (v) => typeof v === 'string' ? v : '';
+const off = (v) => /^(?:0|false|off|no)$/iu.test(text(v));
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {};
+export function configFromEnv(env = process.env) {
+    const home = env['HOME'] || homedir();
+    return {
+        endpointFile: env['CROWDMEMORY_ENDPOINT_FILE'] || join(home, '.crowdmemory/state/endpoint.json'),
+        // PLUGIN_DATA is hook-only. Both the hook and MCP process must resolve the same fallback directory.
+        stateDir: env['CROWDMEMORY_CODEX_STATE'] || join(env['CODEX_HOME'] || join(home, '.codex'), 'crowdmemory/sessions'),
+        ...(env['CROWDMEMORY_PROJECT'] ? { project: env['CROWDMEMORY_PROJECT'] } : {}),
+        profile: env['CROWDMEMORY_PROFILE'] || 'session-default',
+        inject: !off(env['CROWDMEMORY_INJECT']), notes: !off(env['CROWDMEMORY_NOTES']),
+    };
+}
+export function contextOf(event) {
+    const session = text(event['session_id']);
+    if (!session || session.length > 256)
+        return undefined;
+    const agent = text(event['agent_id']);
+    if (agent.length > 128 || (agent && `${session}/${agent}`.length > 256))
+        return undefined;
+    return { ref: agent ? `${session}/${agent}` : session, parentRef: agent ? session : null,
+        ...(text(event['cwd']) ? { cwd: text(event['cwd']) } : {}) };
+}
+/** A running unified-exec result is not a completed command or a successful test. */
+export function shellResult(response) {
+    const obj = object(response);
+    const output = typeof response === 'string' ? response : text(obj['stdout']) + '\n' + text(obj['stderr']);
+    const exit = obj['exit_code'];
+    if (typeof exit === 'number' && Number.isInteger(exit))
+        return { output, exit };
+    // CLI 0.164.0 supplies only stdout here, even for a nonzero exit. Its content is not exit metadata.
+    return undefined;
+}
+export class CodexMemory {
+    config;
+    client;
+    store;
+    constructor(config) {
+        this.config = config;
+        this.client = new RuntimeClient({ endpointFile: config.endpointFile, adapterId: 'codex', timeoutMs: { 'session.end': 1200 } });
+        this.store = new StateStore(config.stateDir);
+    }
+    fresh(ctx) { return () => ({ ref: ctx.ref, parentRef: ctx.parentRef, ...(ctx.cwd ? { cwd: ctx.cwd } : {}), seq: 0, step: 0 }); }
+    async start(ctx) {
+        return this.store.update(ctx.ref, async (r) => {
+            if (r.ended)
+                return undefined;
+            if (r.handle)
+                return r.handle;
+            if ((r.retryAt ?? 0) > Date.now())
+                return undefined;
+            const reply = await this.client.send({ kind: 'session.start', sessionRef: ctx.ref, parentRef: ctx.parentRef,
+                nativeKey: `start:${++r.seq}`, payload: {
+                    project: codePoints(this.config.project || basename(ctx.cwd || '') || 'workspace', 256),
+                    profile_ref: this.config.profile, adapter_version: ADAPTER_VERSION,
+                    capabilities: ['session_binding', ...(this.config.inject ? ['step_injection'] : []), 'tool_capture', 'subagent_capture',
+                        'query_tools', ...(this.config.notes ? ['note_tool'] : [])],
+                } });
+            if (reply.ok && typeof reply.result['session_handle'] === 'string') {
+                r.handle = reply.result['session_handle'];
+                const disabled = reply.result['disabled_kinds'];
+                r.disabled = Array.isArray(disabled) ? disabled.filter((v) => typeof v === 'string') : [];
+                return r.handle;
+            }
+            r.retryAt = Date.now() + 5000;
+            return undefined;
+        }, this.fresh(ctx));
+    }
+    async forward(ctx, kind, body, key) {
+        if (!ctx)
+            return { ok: false, code: 'session_unbound', message: 'Codex PreToolUse binding required' };
+        const handle = await this.start(ctx);
+        if (!handle)
+            return { ok: false, code: 'runtime_unavailable', message: 'memory session unavailable' };
+        const seq = await this.store.update(ctx.ref, r => !r.ended && !r.disabled?.includes(kind) ? ++r.seq : undefined);
+        if (!seq)
+            return { ok: false, code: 'session_unavailable', message: 'session ended or event disabled' };
+        const reply = await this.client.send({ kind, sessionRef: ctx.ref, parentRef: ctx.parentRef,
+            payload: { session_handle: handle, ...body }, nativeKey: `${key}:${seq}` });
+        if (reply.ok && kind === 'query' && body['op'] === 'read')
+            await this.store.update(ctx.ref, r => { r.memoryShown = true; });
+        return reply;
+    }
+    async lastFailureFacts(ctx) {
+        const r = ctx ? await this.store.read(ctx.ref) : undefined;
+        return r?.lastFailure ? { ...r.lastFailure } : undefined;
+    }
+    async recall(ctx, query) {
+        const step = await this.store.update(ctx.ref, r => { r.firstStepDone = true; return r.step; }, this.fresh(ctx));
+        const reply = await this.forward(ctx, 'step.before', { step: step ?? 0,
+            ...(query ? { query_text: redactQueryText(query) } : {}) }, `step:${step}`);
+        if (!reply.ok || !this.config.inject)
+            return undefined;
+        const inject = injectOf(reply.result);
+        if (!inject)
+            return undefined;
+        const context = fenceRecall(utf8Head(inject.text, 14000), 'crowdmemory-codex-plugin');
+        await this.store.update(ctx.ref, r => { r.memoryShown = true; r.lastInject = context; });
+        return context;
+    }
+    /** A stdout-only hook has no trustworthy outcome. Search/read on its text without inventing tool.result.ok. */
+    async recallOutput(ctx, stdout) {
+        if (!this.config.inject || !stdout.trim())
+            return undefined;
+        const query = redactQueryText(utf8Tail(stdout, 4000));
+        const reply = await this.forward(ctx, 'query', searchBody(query, 2, await this.lastFailureFacts(ctx)), 'output.search');
+        if (!reply.ok)
+            return undefined;
+        const hits = Array.isArray(reply.result['hits']) ? reply.result['hits'] : [];
+        if (!hits.length)
+            return undefined;
+        const parts = [searchReport(reply)];
+        for (const hit of hits.slice(0, 2)) {
+            const ref = text(object(hit)['record_ref']);
+            if (!ref)
+                continue;
+            const record = await this.forward(ctx, 'query', { op: 'read', ref }, `output.read:${ref}`);
+            if (record.ok)
+                parts.push(readReport(record, ref));
+        }
+        const context = fenceRecall(utf8Head(parts.join('\n\n'), 14000), 'crowdmemory-codex-plugin');
+        await this.store.update(ctx.ref, r => { r.memoryShown = true; r.lastInject = context; });
+        return context;
+    }
+    async end(ctx) {
+        const data = await this.store.update(ctx.ref, r => {
+            if (r.ended)
+                return undefined;
+            r.ended = true;
+            return r.handle ? { handle: r.handle, seq: ++r.seq } : undefined;
+        });
+        if (data)
+            await this.client.send({ kind: 'session.end', sessionRef: ctx.ref, parentRef: ctx.parentRef,
+                nativeKey: `end:${data.seq}`, payload: { session_handle: data.handle, reason: 'other' } });
+    }
+    async hook(event) {
+        const ctx = contextOf(event);
+        if (!ctx)
+            return undefined;
+        const name = text(event['hook_event_name']);
+        const output = (context) => context ? { hookSpecificOutput: { hookEventName: name, additionalContext: context } } : undefined;
+        if (name === 'PreToolUse' && OWN_TOOL.test(text(event['tool_name']))) {
+            // Codex requires allow together with updatedInput. Only our own memory tools are matched.
+            return { hookSpecificOutput: { hookEventName: name, permissionDecision: 'allow', updatedInput: {
+                        ...object(event['tool_input']), [SESSION_ARG]: { session_ref: ctx.ref, parent_ref: ctx.parentRef, cwd: ctx.cwd },
+                    } } };
+        }
+        if (name === 'SessionStart') {
+            const record = await this.store.read(ctx.ref);
+            if (text(event['source']) === 'compact')
+                return output(record?.lastInject);
+            if (record?.ended)
+                await this.store.update(ctx.ref, r => { delete r.ended; delete r.handle; delete r.retryAt; delete r.firstStepDone; delete r.lastFailure; delete r.lastInject; delete r.memoryShown; });
+            await this.start(ctx);
+            await this.store.prune();
+        }
+        else if (name === 'UserPromptSubmit') {
+            if (!(await this.store.read(ctx.ref))?.firstStepDone)
+                return output(await this.recall(ctx, text(event['prompt'])));
+        }
+        else if (name === 'SubagentStart') {
+            await this.start(ctx);
+            if (ctx.parentRef) {
+                await this.store.update(ctx.parentRef, r => { r.children = [...new Set([...(r.children ?? []), ctx.ref])].slice(-64); });
+            }
+            // Codex does not provide a stable subagent prompt field; do not assign a parent's queued prompt by FIFO.
+            return output(await this.recall(ctx));
+        }
+        else if (name === 'SubagentStop') {
+            if (ctx.parentRef) {
+                await this.forward({ ...ctx, ref: ctx.parentRef, parentRef: null }, 'subagent.end', { child_ref: ctx.ref, stop_reason: 'other' }, `child:${ctx.ref}`);
+            }
+            await this.end(ctx);
+        }
+        else if (name === 'SessionEnd') {
+            const record = await this.store.read(ctx.ref);
+            await Promise.all((record?.children ?? []).map(ref => this.end({ ref, parentRef: ctx.ref })));
+            await this.end(ctx);
+        }
+        else if (name === 'PostToolUse') {
+            const tool = text(event['tool_name']);
+            if (OWN_TOOL.test(tool))
+                return undefined;
+            const args = object(event['tool_input']);
+            const result = tool === 'Bash' ? shellResult(event['tool_response']) : undefined;
+            if (tool === 'Bash' && !result && typeof event['tool_response'] === 'string') {
+                await this.start(ctx);
+                await this.store.update(ctx.ref, r => { r.step++; });
+                return output(await this.recallOutput(ctx, event['tool_response']));
+            }
+            if (result) {
+                const command = text(args['command']);
+                const masked = maskedExit(command, result.output, '');
+                const exit = masked?.exitCode ?? result.exit;
+                const r = await this.store.read(ctx.ref);
+                const replay = replayCommand(command, ctx.cwd);
+                if (exit !== 0 || r?.memoryShown) {
+                    const tail = utf8Tail(masked?.stdout || result.output, 4096);
+                    const facts = { tool_name: 'bash', error_tail: tail, error_signature: errorSignature(tail) ?? null };
+                    await this.forward(ctx, 'tool.result', { tool_name: 'bash', ok: exit === 0, exit_code: exit,
+                        call_ref: text(event['tool_use_id']), ...(replay ? { command: replay } : {}),
+                        ...(exit !== 0 ? { error_tail: facts.error_tail, error_signature: facts.error_signature } : {}) }, `tool:${text(event['tool_use_id'])}`);
+                    await this.store.update(ctx.ref, current => { current.step++; if (exit !== 0)
+                        current.lastFailure = facts; });
+                    if (exit !== 0)
+                        return output(await this.recall(ctx));
+                }
+            }
+            else if (tool === 'apply_patch') {
+                const response = text(event['tool_response']);
+                if (!response.startsWith('Success.'))
+                    return undefined;
+                for (const match of response.matchAll(/^[AMD] (.+)$/gmu)) {
+                    const path = match[1];
+                    const rel = ctx.cwd && isAbsolute(path) ? relative(ctx.cwd, path) : path;
+                    await this.forward(ctx, 'tool.result', { tool_name: 'apply_patch', ok: true, path: codePoints(rel, 1024),
+                        call_ref: text(event['tool_use_id']) }, `patch:${text(event['tool_use_id'])}:${path}`);
+                }
+            }
+        }
+        return undefined;
+    }
+}

package/lib/tools.js

@@ -0,0 +1,114 @@
+/**
+ * memory_search / memory_read / memory_note for Codex, served over MCP. The tool texts, payloads and reports
+ * come from the adapter core (`core/memory-tools.ts`, the same as the DSH adapter's); this file only writes them as
+ * MCP JSON Schemas and adds the calling session, which the plugin's PreToolUse hook puts into the arguments.
+ */
+import { SESSION_ARG } from './memory.js';
+import { FIX_KINDS, NOTE_RELATIONS, NOTE_SCOPES, NOTE_TYPES, TOOL_TEXT, noteBody, noteReport, readRef, readReport, searchBody, searchReport, } from './core/memory-tools.js';
+import { codePoints } from './core/util.js';
+export { NOTE_RELATIONS, NOTE_SCOPES, NOTE_TYPES, fixOf } from './core/memory-tools.js';
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** The calling session as the PreToolUse hook put it into the arguments. */
+export function sessionOf(args) {
+    const value = args[SESSION_ARG];
+    if (!isRecord(value) || typeof value['session_ref'] !== 'string' || value['session_ref'] === '')
+        return undefined;
+    const parent = typeof value['parent_ref'] === 'string' && value['parent_ref'] !== '' ? value['parent_ref'] : null;
+    const cwd = typeof value['cwd'] === 'string' && value['cwd'] !== '' ? value['cwd'] : undefined;
+    return { ref: codePoints(value['session_ref'], 256), parentRef: parent === null ? null : codePoints(parent, 256), ...(cwd === undefined ? {} : { cwd }) };
+}
+const SESSION_SCHEMA = { type: 'object', description: 'Filled in by the Crowd Memory plugin. Leave it out.' };
+/** MCP validates nothing for us: the note's required fields are checked here (DSH's tool layer does it there). */
+function noteArgs(args) {
+    const content = isRecord(args['content']) ? args['content'] : {};
+    const fields = ['what', 'why', 'where', 'learned'];
+    if (typeof args['title'] !== 'string' || !NOTE_TYPES.includes(args['type']) || !NOTE_SCOPES.includes(args['scope'])
+        || fields.some(key => typeof content[key] !== 'string'))
+        return undefined;
+    return {
+        title: args['title'], type: args['type'], scope: args['scope'],
+        content: Object.fromEntries(fields.map(key => [key, content[key]])),
+        topic_key: typeof args['topic_key'] === 'string' ? args['topic_key'] : undefined,
+        evidence_refs: Array.isArray(args['evidence_refs']) ? args['evidence_refs'].filter((ref) => typeof ref === 'string') : undefined,
+        relates_to: Array.isArray(args['relates_to']) ? args['relates_to'] : undefined,
+        fix: args['fix'],
+    };
+}
+export function memoryTools(memory) {
+    const tools = [{
+            name: 'memory_search',
+            description: TOOL_TEXT.memory_search.description,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: TOOL_TEXT.memory_search.query },
+                    limit: { type: 'integer', description: TOOL_TEXT.memory_search.limit },
+                    [SESSION_ARG]: SESSION_SCHEMA,
+                },
+                required: ['query'],
+            },
+            async execute(args, callKey) {
+                const session = sessionOf(args);
+                const reply = await memory.forward(session, 'query', searchBody(args['query'], args['limit'], await memory.lastFailureFacts(session)), `memory_search:${callKey}`);
+                return searchReport(reply);
+            },
+        }, {
+            name: 'memory_read',
+            description: TOOL_TEXT.memory_read.description,
+            inputSchema: {
+                type: 'object',
+                properties: { ref: { type: 'string', description: TOOL_TEXT.memory_read.ref }, [SESSION_ARG]: SESSION_SCHEMA },
+                required: ['ref'],
+            },
+            async execute(args, callKey) {
+                const ref = readRef(args['ref']);
+                return readReport(await memory.forward(sessionOf(args), 'query', { op: 'read', ref }, `memory_read:${callKey}`), ref);
+            },
+        }];
+    if (memory.config.notes) {
+        tools.push({
+            name: 'memory_note',
+            description: TOOL_TEXT.memory_note.description,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string', description: TOOL_TEXT.memory_note.title },
+                    type: { type: 'string', enum: [...NOTE_TYPES] },
+                    scope: { type: 'string', enum: [...NOTE_SCOPES], description: TOOL_TEXT.memory_note.scope },
+                    topic_key: { type: 'string', description: TOOL_TEXT.memory_note.topic_key },
+                    content: {
+                        type: 'object', additionalProperties: false,
+                        properties: { what: { type: 'string' }, why: { type: 'string' }, where: { type: 'string' }, learned: { type: 'string' } },
+                        required: ['what', 'why', 'where', 'learned'],
+                    },
+                    evidence_refs: { type: 'array', items: { type: 'string' } },
+                    relates_to: {
+                        type: 'array',
+                        items: {
+                            type: 'object', additionalProperties: false,
+                            properties: { record_ref: { type: 'string' }, relation: { type: 'string', enum: [...NOTE_RELATIONS] } },
+                            required: ['record_ref', 'relation'],
+                        },
+                    },
+                    fix: {
+                        type: 'object', additionalProperties: false, description: TOOL_TEXT.memory_note.fix,
+                        properties: {
+                            kind: { type: 'string', enum: [...FIX_KINDS] },
+                            command: { type: 'string' }, diff: { type: 'string' }, path: { type: 'string' }, content: { type: 'string' },
+                        },
+                        required: ['kind'],
+                    },
+                    [SESSION_ARG]: SESSION_SCHEMA,
+                },
+                required: ['title', 'type', 'scope', 'content'],
+            },
+            async execute(args, callKey) {
+                const note = noteArgs(args);
+                if (note === undefined)
+                    return 'memory request refused (schema_invalid): memory_note needs title, type, scope and content.what/why/where/learned';
+                return noteReport(await memory.forward(sessionOf(args), 'note', noteBody(note), `memory_note:${callKey}`));
+            },
+        });
+    }
+    return tools;
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@fuxi-ailabs/crowdmemory-codex-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Codex hooks and MCP adapter for the local Crowd Memory Runtime",
+  "license": "Apache-2.0",
+  "author": "cacheline <cacheline999@gmail.com>",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "files": [
+    ".codex-plugin/plugin.json",
+    ".agents/plugins/marketplace.json",
+    "hooks/hooks.json",
+    ".mcp.json",
+    "lib/**/*.js",
+    "contract/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.0",
+    "ajv": "8.17.1",
+    "typescript": "6.0.3",
+    "tsx": "4.22.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@12.8.1+sha512.f64ba907507f5ceafe06c8d38e6052d0179444580ec1279ddd5bfc11cb48aa8a2644b66598e07e761da84872a9fc57d5f902b87fa49d024198d558612aabbe45"
+}