@mxalbert/context-mode 2.0.0

package/build/adapters/openclaw/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * adapters/openclaw — OpenClaw platform adapter.
+ *
+ * Implements HookAdapter for OpenClaw's TypeScript plugin paradigm.
+ *
+ * OpenClaw hook specifics:
+ *   - I/O: TS plugin functions via api.registerHook() and api.on()
+ *   - Hook events: tool_call:before, tool_call:after, command:new
+ *   - Lifecycle: before_prompt_build (routing instruction injection)
+ *   - Context engine: api.registerContextEngine() with ownsCompaction
+ *   - Arg modification: mutate event.params in tool_call:before
+ *   - Blocking: return { block: true, blockReason } from tool_call:before
+ *   - Session ID: event context (no specific env var)
+ *   - Project dir: process.cwd()
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ *   - Session dir: ~/.openclaw/context-mode/sessions/
+ */
+import { BaseAdapter } from "../base.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration } from "../types.js";
+export declare class OpenClawAdapter extends BaseAdapter implements HookAdapter {
+    constructor();
+    readonly name = "OpenClaw";
+    readonly paradigm: HookParadigm;
+    readonly capabilities: PlatformCapabilities;
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    parsePreCompactInput(raw: unknown): PreCompactEvent;
+    parseSessionStartInput(raw: unknown): SessionStartEvent;
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    formatPostToolUseResponse(response: PostToolUseResponse): unknown;
+    formatPreCompactResponse(response: PreCompactResponse): unknown;
+    formatSessionStartResponse(response: SessionStartResponse): unknown;
+    getSettingsPath(): string;
+    /**
+     * OpenClaw stores everything in the project root — no separate config
+     * dir. Returned as the absolute project directory itself per the
+     * HookAdapter.getConfigDir contract (always-absolute).
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
+    /**
+     * Absolute <projectRoot>/memory directory.
+     *
+     * OpenClaw's `getConfigDir(projectDir)` already returns the project root,
+     * so the memory dir is naturally project-scoped per the OpenClaw
+     * convention. The `projectDir` parameter is honored for explicit
+     * resolution; without it, falls back to the implicit `process.cwd()`
+     * inside `getConfigDir`. Either way, two projects never share a path
+     * — no hash suffix needed (issue #663).
+     */
+    getMemoryDir(projectDir?: string): string;
+    generateHookConfig(_pluginRoot: string): HookRegistration;
+    readSettings(): Record<string, unknown> | null;
+    writeSettings(settings: Record<string, unknown>): void;
+    validateHooks(_pluginRoot: string): DiagnosticResult[];
+    checkPluginRegistration(): DiagnosticResult;
+    getInstalledVersion(): string;
+    configureAllHooks(_pluginRoot: string): string[];
+    backupSettings(): string | null;
+    setHookPermissions(_pluginRoot: string): string[];
+    updatePluginRegistry(_pluginRoot: string, _version: string): void;
+    /**
+     * Resolve the project directory for an OpenClaw hook input.
+     * Priority: input.cwd > OPENCLAW_PROJECT_DIR env > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even under worktrees or when the
+     * platform omits cwd from the wire payload.
+     */
+    private getProjectDir;
+    /**
+     * Extract session ID from OpenClaw hook input.
+     */
+    private extractSessionId;
+}

package/build/adapters/openclaw/index.js

@@ -0,0 +1,439 @@
+/**
+ * adapters/openclaw — OpenClaw platform adapter.
+ *
+ * Implements HookAdapter for OpenClaw's TypeScript plugin paradigm.
+ *
+ * OpenClaw hook specifics:
+ *   - I/O: TS plugin functions via api.registerHook() and api.on()
+ *   - Hook events: tool_call:before, tool_call:after, command:new
+ *   - Lifecycle: before_prompt_build (routing instruction injection)
+ *   - Context engine: api.registerContextEngine() with ownsCompaction
+ *   - Arg modification: mutate event.params in tool_call:before
+ *   - Blocking: return { block: true, blockReason } from tool_call:before
+ *   - Session ID: event context (no specific env var)
+ *   - Project dir: process.cwd()
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ *   - Session dir: ~/.openclaw/context-mode/sessions/
+ */
+import { readFileSync, writeFileSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { BaseAdapter } from "../base.js";
+// ─────────────────────────────────────────────────────────
+// Hook constants (re-exported from hooks.ts)
+// ─────────────────────────────────────────────────────────
+import { HOOK_EVENTS as OPENCLAW_HOOK_EVENTS } from "./hooks.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class OpenClawAdapter extends BaseAdapter {
+    constructor() {
+        super([".openclaw"]);
+    }
+    name = "OpenClaw";
+    paradigm = "ts-plugin";
+    capabilities = {
+        preToolUse: true,
+        postToolUse: true,
+        preCompact: true, // via registerContextEngine with ownsCompaction
+        sessionStart: true, // via command:new hook
+        canModifyArgs: true,
+        canModifyOutput: false,
+        canInjectSessionContext: true, // via before_prompt_build lifecycle hook
+    };
+    // ── Input parsing ──────────────────────────────────────
+    parsePreToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.toolName ?? input.tool_name ?? "",
+            toolInput: input.params ?? input.tool_input ?? {},
+            sessionId: this.extractSessionId(input),
+            projectDir: this.getProjectDir(input),
+            raw,
+        };
+    }
+    parsePostToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.toolName ?? input.tool_name ?? "",
+            toolInput: input.params ?? input.tool_input ?? {},
+            toolOutput: input.output ?? input.tool_output,
+            isError: input.isError ?? input.is_error,
+            sessionId: this.extractSessionId(input),
+            projectDir: this.getProjectDir(input),
+            raw,
+        };
+    }
+    parsePreCompactInput(raw) {
+        const input = raw;
+        return {
+            sessionId: this.extractSessionId(input),
+            projectDir: this.getProjectDir(input),
+            raw,
+        };
+    }
+    parseSessionStartInput(raw) {
+        const input = raw;
+        const rawSource = input.source ?? "startup";
+        let source;
+        switch (rawSource) {
+            case "compact":
+                source = "compact";
+                break;
+            case "resume":
+                source = "resume";
+                break;
+            case "clear":
+                source = "clear";
+                break;
+            default:
+                source = "startup";
+        }
+        return {
+            sessionId: this.extractSessionId(input),
+            source,
+            projectDir: this.getProjectDir(input),
+            raw,
+        };
+    }
+    // ── Response formatting ────────────────────────────────
+    formatPreToolUseResponse(response) {
+        if (response.decision === "deny") {
+            // OpenClaw plugin paradigm: return { block, blockReason } to block
+            return {
+                block: true,
+                blockReason: response.reason ?? "Blocked by context-mode hook",
+            };
+        }
+        if (response.decision === "modify" && response.updatedInput) {
+            // OpenClaw: mutate params in the event object
+            return { params: response.updatedInput };
+        }
+        if (response.decision === "ask") {
+            // OpenClaw: block for safety when user confirmation needed
+            return {
+                block: true,
+                blockReason: response.reason ?? "Action requires user confirmation (security policy)",
+            };
+        }
+        if (response.decision === "context" && response.additionalContext) {
+            // OpenClaw supports context injection via before_prompt_build,
+            // but not inline in tool_call:before. Passthrough.
+            return undefined;
+        }
+        // "allow" — passthrough
+        return undefined;
+    }
+    formatPostToolUseResponse(response) {
+        const result = {};
+        if (response.additionalContext) {
+            result.additionalContext = response.additionalContext;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    formatPreCompactResponse(response) {
+        // Context engine compact() returns { ok, compacted } — context is managed internally
+        return response.context ?? "";
+    }
+    formatSessionStartResponse(response) {
+        return response.context ?? "";
+    }
+    // ── Configuration ──────────────────────────────────────
+    getSettingsPath() {
+        // OpenClaw uses openclaw.json in the project root or ~/.openclaw/openclaw.json
+        return resolve("openclaw.json");
+    }
+    /**
+     * OpenClaw stores everything in the project root — no separate config
+     * dir. Returned as the absolute project directory itself per the
+     * HookAdapter.getConfigDir contract (always-absolute).
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? process.cwd());
+    }
+    getInstructionFiles() {
+        return ["AGENTS.md"];
+    }
+    /**
+     * Absolute <projectRoot>/memory directory.
+     *
+     * OpenClaw's `getConfigDir(projectDir)` already returns the project root,
+     * so the memory dir is naturally project-scoped per the OpenClaw
+     * convention. The `projectDir` parameter is honored for explicit
+     * resolution; without it, falls back to the implicit `process.cwd()`
+     * inside `getConfigDir`. Either way, two projects never share a path
+     * — no hash suffix needed (issue #663).
+     */
+    getMemoryDir(projectDir) {
+        return join(this.getConfigDir(projectDir), "memory");
+    }
+    generateHookConfig(_pluginRoot) {
+        // OpenClaw uses TS plugin paradigm — hooks are registered via
+        // api.registerHook() in the plugin entry point, not via config files.
+        // Return the hook name mapping for documentation purposes.
+        return {
+            [OPENCLAW_HOOK_EVENTS.TOOL_CALL_BEFORE]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+            [OPENCLAW_HOOK_EVENTS.TOOL_CALL_AFTER]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+            [OPENCLAW_HOOK_EVENTS.COMMAND_NEW]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    readSettings() {
+        // Try project-local paths first, then global config
+        const paths = [
+            resolve("openclaw.json"),
+            resolve(".openclaw", "openclaw.json"),
+            join(homedir(), ".openclaw", "openclaw.json"),
+        ];
+        for (const configPath of paths) {
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                return JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    writeSettings(settings) {
+        // Write to openclaw.json in current directory
+        const configPath = resolve("openclaw.json");
+        writeFileSync(configPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    }
+    // ── Diagnostics (doctor) ─────────────────────────────────
+    validateHooks(_pluginRoot) {
+        const results = [];
+        const settings = this.readSettings();
+        if (!settings) {
+            results.push({
+                check: "Plugin configuration",
+                status: "fail",
+                message: "Could not read openclaw.json",
+                fix: "context-mode upgrade",
+            });
+            return results;
+        }
+        // Check for context-mode in plugins.entries
+        const plugins = settings.plugins;
+        const entries = plugins?.entries;
+        if (entries) {
+            const hasPlugin = Object.keys(entries).some((k) => k.includes("context-mode"));
+            results.push({
+                check: "Plugin registration",
+                status: hasPlugin ? "pass" : "fail",
+                message: hasPlugin
+                    ? "context-mode found in plugins.entries"
+                    : "context-mode not found in plugins.entries",
+                fix: hasPlugin
+                    ? undefined
+                    : "context-mode upgrade",
+            });
+            // Check if enabled
+            if (hasPlugin) {
+                const entry = entries["context-mode"];
+                const isEnabled = entry?.enabled !== false;
+                results.push({
+                    check: "Plugin enabled",
+                    status: isEnabled ? "pass" : "warn",
+                    message: isEnabled
+                        ? "context-mode plugin is enabled"
+                        : "context-mode plugin is disabled",
+                });
+            }
+        }
+        else {
+            results.push({
+                check: "Plugin registration",
+                status: "fail",
+                message: "No plugins.entries found in openclaw.json",
+                fix: "context-mode upgrade",
+            });
+        }
+        // Check context engine slot
+        const slots = plugins?.slots;
+        if (slots?.contextEngine === "context-mode") {
+            results.push({
+                check: "Context engine",
+                status: "pass",
+                message: "context-mode registered as context engine (owns compaction)",
+            });
+        }
+        else {
+            results.push({
+                check: "Context engine",
+                status: "warn",
+                message: "context-mode not set as context engine — compaction will use default engine",
+            });
+        }
+        return results;
+    }
+    checkPluginRegistration() {
+        const settings = this.readSettings();
+        if (!settings) {
+            return {
+                check: "Plugin registration",
+                status: "warn",
+                message: "Could not read openclaw.json",
+            };
+        }
+        const plugins = settings.plugins;
+        const entries = plugins?.entries;
+        if (entries) {
+            const hasPlugin = Object.keys(entries).some((k) => k.includes("context-mode"));
+            if (hasPlugin) {
+                return {
+                    check: "Plugin registration",
+                    status: "pass",
+                    message: "context-mode found in plugins.entries",
+                };
+            }
+        }
+        return {
+            check: "Plugin registration",
+            status: "fail",
+            message: "context-mode not found in openclaw.json plugins.entries",
+            fix: "context-mode upgrade",
+        };
+    }
+    getInstalledVersion() {
+        // Check ~/.openclaw/extensions/context-mode/ for the plugin
+        try {
+            const pkgPath = resolve(homedir(), ".openclaw", "extensions", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            /* not found */
+        }
+        // Also check node_modules
+        try {
+            const pkgPath = resolve("node_modules", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            /* not found */
+        }
+        return "not installed";
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    configureAllHooks(_pluginRoot) {
+        const settings = this.readSettings() ?? {};
+        const changes = [];
+        // Ensure plugins.entries exists
+        if (!settings.plugins) {
+            settings.plugins = {};
+        }
+        const plugins = settings.plugins;
+        if (!plugins.entries) {
+            plugins.entries = {};
+        }
+        const entries = plugins.entries;
+        // Add context-mode to plugins.entries
+        if (!entries["context-mode"]) {
+            entries["context-mode"] = { enabled: true };
+            changes.push("Added context-mode to plugins.entries");
+        }
+        else {
+            const entry = entries["context-mode"];
+            if (entry.enabled === false) {
+                entry.enabled = true;
+                changes.push("Enabled context-mode plugin");
+            }
+            else {
+                changes.push("context-mode already configured in plugins.entries");
+            }
+        }
+        // Optionally set context engine slot
+        if (!plugins.slots) {
+            plugins.slots = {};
+        }
+        const slots = plugins.slots;
+        if (!slots.contextEngine) {
+            slots.contextEngine = "context-mode";
+            changes.push("Set context-mode as context engine (owns compaction)");
+        }
+        else if (slots.contextEngine !== "context-mode") {
+            changes.push(`Context engine already set to "${slots.contextEngine}" — not overwriting`);
+        }
+        this.writeSettings(settings);
+        return changes;
+    }
+    backupSettings() {
+        const paths = [
+            resolve("openclaw.json"),
+            resolve(".openclaw", "openclaw.json"),
+            join(homedir(), ".openclaw", "openclaw.json"),
+        ];
+        for (const configPath of paths) {
+            try {
+                accessSync(configPath, constants.R_OK);
+                const backupPath = configPath + ".bak";
+                copyFileSync(configPath, backupPath);
+                return backupPath;
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    setHookPermissions(_pluginRoot) {
+        // OpenClaw uses TS plugin paradigm — no shell scripts to chmod
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // OpenClaw manages plugins through npm/openclaw.json — no separate registry
+    }
+    // ── Internal helpers ───────────────────────────────────
+    /**
+     * Resolve the project directory for an OpenClaw hook input.
+     * Priority: input.cwd > OPENCLAW_PROJECT_DIR env > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even under worktrees or when the
+     * platform omits cwd from the wire payload.
+     */
+    getProjectDir(input) {
+        return input.cwd ?? process.env.OPENCLAW_PROJECT_DIR ?? process.cwd();
+    }
+    /**
+     * Extract session ID from OpenClaw hook input.
+     */
+    extractSessionId(input) {
+        if (input.sessionId)
+            return input.sessionId;
+        return `pid-${process.ppid}`;
+    }
+}

package/build/adapters/openclaw/mcp-tools.d.ts

@@ -0,0 +1,54 @@
+/**
+ * OpenClaw MCP tool registry.
+ *
+ * Catalogs the 11 ctx_* tools that OpenClaw plugin must register via
+ * api.registerTool(...) so the routing block (which nudges agents toward
+ * ctx_execute, ctx_search, etc.) actually has tools to call. Without this,
+ * Phase 7 audit (v1.0.107-adapter-openclaw.json) flagged severity=CRITICAL —
+ * routing-block premise is broken when the named tools don't exist.
+ *
+ * Pattern mirrors the swarmvault MCP plugin
+ * (refs/plugin-examples/openclaw/swarmvault/packages/engine/src/mcp.ts:46-51):
+ *   server.registerTool(name, { description, inputSchema }, handler)
+ *
+ * OpenClaw signature is slightly different — see building-plugins.md:116
+ *   api.registerTool({ name, description, parameters: TypeBox, execute(id, params) })
+ *
+ * Tool handlers are intentionally thin shims that delegate to the bundled CLI
+ * (cli.bundle.mjs) — same fall-through pattern already used by ctx-doctor and
+ * ctx-upgrade slash commands. This keeps the plugin's blast radius minimal:
+ * we don't re-export the entire MCP server stack inside OpenClaw's process.
+ *
+ * The 11 tools mirror src/server.ts registerTool calls (lines 897, 1226, 1371,
+ * 1497, 2034, 2256, 2440, 2501, 2592, 2712, 2808).
+ */
+/** Minimal JSON-schema-like parameter spec accepted by OpenClaw registerTool. */
+export interface OpenClawToolParameters {
+    type: "object";
+    properties: Record<string, {
+        type: string;
+        description?: string;
+    }>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+/** Tool definition shape returned to OpenClaw via api.registerTool. */
+export interface OpenClawToolDef {
+    name: string;
+    description: string;
+    parameters: OpenClawToolParameters;
+    execute: (id: string, params: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+    }>;
+}
+/**
+ * The 11 ctx_* tool definitions registered into OpenClaw via api.registerTool.
+ * Names + descriptions mirror src/server.ts registerTool blocks 1:1 so prompts
+ * referencing them (routing block, AGENTS.md) resolve to real callable tools.
+ */
+export declare const OPENCLAW_TOOL_DEFS: readonly OpenClawToolDef[];
+/** Stable list of tool names — used by tests and manifest validation. */
+export declare const OPENCLAW_TOOL_NAMES: readonly string[];