context-mode 1.0.21 → 1.0.23

package/build/adapters/openclaw/hooks.js

@@ -0,0 +1,61 @@
+/**
+ * adapters/openclaw/hooks — OpenClaw hook definitions and validators.
+ *
+ * Defines the hook types and validation helpers specific to OpenClaw's
+ * TypeScript plugin paradigm. This module is used by:
+ *   - CLI setup/upgrade commands (to configure plugin in openclaw.json)
+ *   - Doctor command (to validate plugin configuration)
+ *
+ * OpenClaw hook system reference:
+ *   - I/O: TS plugin functions via api.registerHook() and api.on()
+ *   - Hook events: tool_call:before, tool_call:after, command:new, command:reset
+ *   - Lifecycle: session_start, before_compaction, after_compaction, before_prompt_build, before_model_resolve
+ *   - Context engine: api.registerContextEngine() with ownsCompaction
+ *   - Blocking: return { block: true, blockReason } from tool_call:before
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ */
+// ─────────────────────────────────────────────────────────
+// Hook type constants
+// ─────────────────────────────────────────────────────────
+/** OpenClaw hook event names (registered via api.registerHook). */
+export const HOOK_EVENTS = {
+    TOOL_CALL_BEFORE: "tool_call:before",
+    TOOL_CALL_AFTER: "tool_call:after",
+    COMMAND_NEW: "command:new",
+    COMMAND_RESET: "command:reset",
+    COMMAND_STOP: "command:stop",
+};
+/** OpenClaw lifecycle hook names (registered via api.on). */
+export const LIFECYCLE_HOOKS = {
+    SESSION_START: "session_start",
+    BEFORE_COMPACTION: "before_compaction",
+    AFTER_COMPACTION: "after_compaction",
+    BEFORE_PROMPT_BUILD: "before_prompt_build",
+    BEFORE_MODEL_RESOLVE: "before_model_resolve",
+    BEFORE_AGENT_START: "before_agent_start",
+};
+// ─────────────────────────────────────────────────────────
+// Hook validation
+// ─────────────────────────────────────────────────────────
+/**
+ * Required hooks that must be active for context-mode to function.
+ * OpenClaw registers these via api.registerHook() in the plugin entry point.
+ */
+export const REQUIRED_HOOKS = [
+    HOOK_EVENTS.TOOL_CALL_BEFORE,
+    HOOK_EVENTS.TOOL_CALL_AFTER,
+];
+/**
+ * Optional hooks that enhance functionality but aren't critical.
+ * command:new provides session cleanup; context engine handles compaction.
+ */
+export const OPTIONAL_HOOKS = [
+    HOOK_EVENTS.COMMAND_NEW,
+];
+/**
+ * Check if a plugin entry is the context-mode plugin.
+ * OpenClaw plugins are registered by id in plugins.entries.
+ */
+export function isContextModePlugin(pluginId) {
+    return pluginId.includes("context-mode");
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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.env.OPENCLAW_PROJECT_DIR or process.cwd()
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ *   - Session dir: ~/.openclaw/context-mode/sessions/
+ */
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+export declare class OpenClawAdapter implements HookAdapter {
+    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;
+    getSessionDir(): string;
+    getSessionDBPath(projectDir: string): string;
+    getSessionEventsPath(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;
+    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
+    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
+    /**
+     * Extract session ID from OpenClaw hook input.
+     */
+    private extractSessionId;
+}

package/build/adapters/openclaw/index.js

@@ -0,0 +1,459 @@
+/**
+ * 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.env.OPENCLAW_PROJECT_DIR or process.cwd()
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ *   - Session dir: ~/.openclaw/context-mode/sessions/
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+// ─────────────────────────────────────────────────────────
+// Hook constants (re-exported from hooks.ts)
+// ─────────────────────────────────────────────────────────
+import { HOOK_EVENTS as OPENCLAW_HOOK_EVENTS } from "./hooks.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class OpenClawAdapter {
+    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: process.env.OPENCLAW_PROJECT_DIR || process.cwd(),
+            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: process.env.OPENCLAW_PROJECT_DIR || process.cwd(),
+            raw,
+        };
+    }
+    parsePreCompactInput(raw) {
+        const input = raw;
+        return {
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env.OPENCLAW_PROJECT_DIR || process.cwd(),
+            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: process.env.OPENCLAW_PROJECT_DIR || process.cwd(),
+            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");
+    }
+    getSessionDir() {
+        const dir = join(homedir(), ".openclaw", "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    getSessionDBPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}.db`);
+    }
+    getSessionEventsPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}-events.md`);
+    }
+    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
+    }
+    // ── Routing Instructions (soft enforcement) ────────────
+    getRoutingInstructionsConfig() {
+        return {
+            fileName: "AGENTS.md",
+            globalPath: resolve(homedir(), ".openclaw", "AGENTS.md"),
+            projectRelativePath: "AGENTS.md",
+        };
+    }
+    writeRoutingInstructions(projectDir, pluginRoot) {
+        const config = this.getRoutingInstructionsConfig();
+        const targetPath = resolve(projectDir, config.projectRelativePath);
+        const sourcePath = resolve(pluginRoot, "configs", "openclaw", config.fileName);
+        try {
+            let content;
+            try {
+                content = readFileSync(sourcePath, "utf-8");
+            }
+            catch {
+                // Fall back to opencode config if openclaw-specific doesn't exist yet
+                const fallbackPath = resolve(pluginRoot, "configs", "opencode", config.fileName);
+                content = readFileSync(fallbackPath, "utf-8");
+            }
+            try {
+                const existing = readFileSync(targetPath, "utf-8");
+                if (existing.includes("context-mode"))
+                    return null;
+                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
+                return targetPath;
+            }
+            catch {
+                writeFileSync(targetPath, content, "utf-8");
+                return targetPath;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Internal helpers ───────────────────────────────────
+    /**
+     * Extract session ID from OpenClaw hook input.
+     */
+    extractSessionId(input) {
+        if (input.sessionId)
+            return input.sessionId;
+        return `pid-${process.ppid}`;
+    }
+}

package/build/adapters/openclaw/session-db.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OpenClawSessionDB — OpenClaw-specific extension of SessionDB.
+ *
+ * Adds session_key mapping (openclaw_session_map table) and session
+ * rename support needed for OpenClaw's gateway restart re-keying.
+ *
+ * The shared SessionDB remains unaware of session_key; all OpenClaw-specific
+ * session mapping lives here.
+ */
+import { SessionDB } from "../../session/db.js";
+/** Row from the openclaw_session_map table. */
+export interface SessionMapRow {
+    session_key: string;
+    session_id: string;
+    created_at: string;
+}
+export declare class OpenClawSessionDB extends SessionDB {
+    /**
+     * OpenClaw-specific prepared statements, separate from the parent's
+     * private statement cache. Created in prepareStatements() after
+     * super.prepareStatements() finishes.
+     *
+     * `declare` prevents TypeScript from emitting a field initializer
+     * that would wipe the value set during the base constructor's
+     * prepareStatements() call chain.
+     */
+    private ocStmts;
+    protected initSchema(): void;
+    protected prepareStatements(): void;
+    /** Shorthand to retrieve an OpenClaw-specific cached statement. */
+    private oc;
+    /**
+     * Ensure a session metadata entry exists with an associated session_key.
+     * Calls the parent's 2-param ensureSession and also records the mapping
+     * in openclaw_session_map.
+     */
+    ensureSessionWithKey(sessionId: string, projectDir: string, sessionKey: string): void;
+    /**
+     * Get the session_id of the most recently mapped session for a given sessionKey.
+     * Returns null if no sessions exist for that key.
+     */
+    getMostRecentSession(sessionKey: string): string | null;
+    /**
+     * Rename a session ID in-place across all tables (session_meta, session_events,
+     * session_resume, openclaw_session_map), preserving all events, metadata,
+     * and resume snapshots. Used when OpenClaw re-keys session IDs on gateway
+     * restart so accumulated events survive the re-key.
+     */
+    renameSession(oldId: string, newId: string): void;
+    /**
+     * Remove a session_key mapping from openclaw_session_map.
+     * Called on command:stop to clean up agent session tracking.
+     */
+    removeSessionKey(sessionKey: string): void;
+}