context-mode 1.0.154 → 1.0.156

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.154"
+    "version": "1.0.156"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.154",
+      "version": "1.0.156",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.154",
+  "version": "1.0.156",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.154",
+  "version": "1.0.156",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.154",
+  "version": "1.0.156",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.154",
+  "version": "1.0.156",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/build/concurrency/runPool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic in-flight-capped worker pool.
+ *
+ * Used by:
+ *   - runBatchCommands (ctx_batch_execute parallel branch)
+ *   - runBatchFetch    (ctx_fetch_and_index batch path)
+ *
+ * Returns Promise.allSettled-style results so one job's throw cannot
+ * strand siblings. Caller maps fulfilled/rejected per index. Output
+ * order is preserved by input index (not completion order).
+ *
+ * Designed to be the SINGLE concurrency primitive for the project —
+ * all "run N independent operations with at most M in flight" needs
+ * route here. Avoids the worker-pool copy-paste flagged in the
+ * concurrency PRD architectural review (finding G).
+ */
+export interface PoolJob<T> {
+    run(): Promise<T>;
+}
+export interface RunPoolOptions {
+    /** Hard concurrency cap (1-N). Auto-clamped to job count. */
+    concurrency: number;
+    /** Optional: also clamp by `os.cpus().length` (memory-pressure safety). Default false. */
+    capByCpuCount?: boolean;
+    /** Optional: per-settled callback (e.g. for progress reporting / metrics). */
+    onSettled?: (idx: number, result: PromiseSettledResult<unknown>) => void;
+}
+export interface RunPoolResult<T> {
+    /** Per-index settled result, ordered by input index. */
+    settled: PromiseSettledResult<T>[];
+    /** Concurrency actually used after all caps applied. */
+    effectiveConcurrency: number;
+    /** True when effectiveConcurrency < requested concurrency. */
+    capped: boolean;
+}
+export declare function runPool<T>(jobs: PoolJob<T>[], opts: RunPoolOptions): Promise<RunPoolResult<T>>;

package/build/concurrency/runPool.js

@@ -0,0 +1,51 @@
+/**
+ * Generic in-flight-capped worker pool.
+ *
+ * Used by:
+ *   - runBatchCommands (ctx_batch_execute parallel branch)
+ *   - runBatchFetch    (ctx_fetch_and_index batch path)
+ *
+ * Returns Promise.allSettled-style results so one job's throw cannot
+ * strand siblings. Caller maps fulfilled/rejected per index. Output
+ * order is preserved by input index (not completion order).
+ *
+ * Designed to be the SINGLE concurrency primitive for the project —
+ * all "run N independent operations with at most M in flight" needs
+ * route here. Avoids the worker-pool copy-paste flagged in the
+ * concurrency PRD architectural review (finding G).
+ */
+import { cpus } from "node:os";
+export async function runPool(jobs, opts) {
+    const { concurrency, capByCpuCount = false, onSettled } = opts;
+    if (jobs.length === 0) {
+        return { settled: [], effectiveConcurrency: 0, capped: false };
+    }
+    const requested = Math.max(1, concurrency);
+    const cpuCap = capByCpuCount ? Math.max(1, cpus().length) : requested;
+    const effectiveConcurrency = Math.min(requested, cpuCap, jobs.length);
+    const capped = effectiveConcurrency < requested;
+    const settled = new Array(jobs.length);
+    let nextIdx = 0;
+    async function worker() {
+        while (true) {
+            const idx = nextIdx++;
+            if (idx >= jobs.length)
+                return;
+            try {
+                const value = await jobs[idx].run();
+                settled[idx] = { status: "fulfilled", value };
+            }
+            catch (err) {
+                settled[idx] = { status: "rejected", reason: err };
+            }
+            onSettled?.(idx, settled[idx]);
+        }
+    }
+    const workers = [];
+    for (let w = 0; w < effectiveConcurrency; w++)
+        workers.push(worker());
+    // allSettled defends against any promise rejection escaping a worker
+    // (the worker already swallows its own errors, but this is belt-and-braces).
+    await Promise.allSettled(workers);
+    return { settled, effectiveConcurrency, capped };
+}

package/build/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[];

package/build/openclaw/mcp-tools.js

@@ -0,0 +1,198 @@
+/**
+ * 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).
+ */
+/** Wrap any handler so failures become a well-formed text error rather than crashing. */
+function safe(handler) {
+    return async (_id, params) => {
+        try {
+            return await handler(params ?? {});
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `[context-mode] tool error: ${message}`,
+                    },
+                ],
+            };
+        }
+    };
+}
+/** Stub handler — points users at the bundled CLI for full functionality. */
+function cliRedirect(toolName) {
+    return safe(async () => ({
+        content: [
+            {
+                type: "text",
+                text: `[context-mode] ${toolName} is exposed via the bundled context-mode CLI. Run 'context-mode ${toolName}' or invoke the MCP server directly. This OpenClaw stub registers the tool name so the routing block remains valid; full execution requires the standalone MCP transport.`,
+            },
+        ],
+    }));
+}
+/**
+ * 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 const OPENCLAW_TOOL_DEFS = [
+    {
+        name: "ctx_execute",
+        description: "Execute code in a sandboxed subprocess. Only stdout enters context. Prefer over Bash for any command producing >20 lines.",
+        parameters: {
+            type: "object",
+            properties: {
+                language: { type: "string", description: "Runtime language" },
+                code: { type: "string", description: "Source code to execute" },
+                timeout: { type: "number", description: "Max execution time in ms" },
+            },
+            required: ["language", "code"],
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_execute"),
+    },
+    {
+        name: "ctx_execute_file",
+        description: "Execute code with a file path. Only printed summary enters context — raw file stays in sandbox.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path" },
+                language: { type: "string", description: "Runtime language" },
+                code: { type: "string", description: "Source code" },
+            },
+            required: ["path", "language", "code"],
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_execute_file"),
+    },
+    {
+        name: "ctx_index",
+        description: "Store content in the FTS5 knowledge base for later search.",
+        parameters: {
+            type: "object",
+            properties: {
+                content: { type: "string", description: "Text to index" },
+                source: { type: "string", description: "Descriptive source label" },
+            },
+            required: ["content", "source"],
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_index"),
+    },
+    {
+        name: "ctx_search",
+        description: "Query indexed content via FTS5. Pass all questions as an array in ONE call.",
+        parameters: {
+            type: "object",
+            properties: {
+                queries: { type: "array", description: "Search queries" },
+                source: { type: "string", description: "Optional source filter" },
+                sort: { type: "string", description: "relevance | timeline" },
+            },
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_search"),
+    },
+    {
+        name: "ctx_fetch_and_index",
+        description: "Fetch a URL, chunk it, and index — raw HTML never enters context.",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "URL to fetch" },
+                source: { type: "string", description: "Source label for indexed chunks" },
+            },
+            required: ["url"],
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_fetch_and_index"),
+    },
+    {
+        name: "ctx_batch_execute",
+        description: "Run multiple commands and search queries in ONE call. Primary research tool — replaces 30+ individual calls.",
+        parameters: {
+            type: "object",
+            properties: {
+                commands: { type: "array", description: "Array of {label, command} objects" },
+                queries: { type: "array", description: "Search queries to run after indexing" },
+            },
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_batch_execute"),
+    },
+    {
+        name: "ctx_stats",
+        description: "Show context-mode session statistics — token consumption and per-tool breakdown.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_stats"),
+    },
+    {
+        name: "ctx_doctor",
+        description: "Run context-mode diagnostics — runtimes, hooks, FTS5, plugin registration.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_doctor"),
+    },
+    {
+        name: "ctx_upgrade",
+        description: "Upgrade context-mode to the latest version.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_upgrade"),
+    },
+    {
+        name: "ctx_purge",
+        description: "Permanently delete all indexed content and reset session stats. Destructive.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_purge"),
+    },
+    {
+        name: "ctx_insight",
+        description: "Open the context-mode Insight analytics dashboard in the browser.",
+        parameters: {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        execute: cliRedirect("ctx_insight"),
+    },
+];
+/** Stable list of tool names — used by tests and manifest validation. */
+export const OPENCLAW_TOOL_NAMES = OPENCLAW_TOOL_DEFS.map((def) => def.name);

package/build/openclaw/workspace-router.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Extract the agent workspace path from tool call params.
+ * Looks for /openclaw/workspace-<name> patterns in cwd, file_path, and command.
+ * Returns the workspace root (e.g. "/openclaw/workspace-trainer") or null.
+ */
+export declare function extractWorkspace(params: Record<string, unknown>): string | null;
+/**
+ * Maps agent workspaces to sessionIds using sessionKey convention.
+ * sessionKey pattern: "agent:<name>:main" → workspace "/openclaw/workspace-<name>"
+ *
+ * Why this exists alongside per-session closures:
+ * Each register() call creates its own closure with its own sessionId, which
+ * naturally isolates sessions. The WorkspaceRouter acts as a safety net for
+ * after_tool_call events where OpenClaw may deliver the event to the wrong
+ * closure (e.g. tool calls interleaving across agents). It resolves the correct
+ * sessionId from workspace paths in tool params, falling back to the closure
+ * sessionId when no workspace is detected.
+ */
+export declare class WorkspaceRouter {
+    private map;
+    /** Register a session from session_start event. */
+    registerSession(sessionKey: string, sessionId: string): void;
+    /** Remove a session (e.g. on command:stop). */
+    removeSession(sessionKey: string): void;
+    /** Resolve sessionId from tool call params. Returns null if no match. */
+    resolveSessionId(params: Record<string, unknown>): string | null;
+    /** Derive workspace path from sessionKey. */
+    private workspaceFromKey;
+}

package/build/openclaw/workspace-router.js

@@ -0,0 +1,64 @@
+/**
+ * Extract the agent workspace path from tool call params.
+ * Looks for /openclaw/workspace-<name> patterns in cwd, file_path, and command.
+ * Returns the workspace root (e.g. "/openclaw/workspace-trainer") or null.
+ */
+export function extractWorkspace(params) {
+    // Priority: cwd > file_path > command (most specific first)
+    const sources = [
+        params.cwd,
+        params.file_path,
+        params.command,
+    ].filter((v) => typeof v === "string");
+    for (const src of sources) {
+        const match = src.match(/\/openclaw\/workspace-[a-zA-Z0-9_-]+/);
+        if (match)
+            return match[0];
+    }
+    return null;
+}
+/**
+ * Maps agent workspaces to sessionIds using sessionKey convention.
+ * sessionKey pattern: "agent:<name>:main" → workspace "/openclaw/workspace-<name>"
+ *
+ * Why this exists alongside per-session closures:
+ * Each register() call creates its own closure with its own sessionId, which
+ * naturally isolates sessions. The WorkspaceRouter acts as a safety net for
+ * after_tool_call events where OpenClaw may deliver the event to the wrong
+ * closure (e.g. tool calls interleaving across agents). It resolves the correct
+ * sessionId from workspace paths in tool params, falling back to the closure
+ * sessionId when no workspace is detected.
+ */
+export class WorkspaceRouter {
+    // workspace path → sessionId
+    map = new Map();
+    /** Register a session from session_start event. */
+    registerSession(sessionKey, sessionId) {
+        const workspace = this.workspaceFromKey(sessionKey);
+        if (workspace) {
+            this.map.set(workspace, sessionId);
+        }
+    }
+    /** Remove a session (e.g. on command:stop). */
+    removeSession(sessionKey) {
+        const workspace = this.workspaceFromKey(sessionKey);
+        if (workspace) {
+            this.map.delete(workspace);
+        }
+    }
+    /** Resolve sessionId from tool call params. Returns null if no match. */
+    resolveSessionId(params) {
+        const workspace = extractWorkspace(params);
+        if (!workspace)
+            return null;
+        return this.map.get(workspace) ?? null;
+    }
+    /** Derive workspace path from sessionKey. */
+    workspaceFromKey(key) {
+        // Pattern: "agent:<name>:main" or "agent:<name>:<channel>"
+        const match = key.match(/^agent:([^:]+):/);
+        if (!match)
+            return null;
+        return `/openclaw/workspace-${match[1]}`;
+    }
+}

package/build/openclaw-plugin.d.ts

@@ -0,0 +1,130 @@
+/**
+ * OpenClaw TypeScript plugin entry point for context-mode.
+ *
+ * Exports an object with { id, name, configSchema, register(api) } for
+ * declarative metadata and config validation before code execution.
+ *
+ * register(api) registers:
+ *   - before_tool_call hook   — Routing enforcement (deny/modify/passthrough)
+ *   - after_tool_call hook    — Session event capture
+ *   - command:new hook         — Session initialization and cleanup
+ *   - session_start hook             — Re-key DB session to OpenClaw's session ID
+ *   - before_compaction hook         — Flush events to resume snapshot
+ *   - after_compaction hook          — Increment compact count
+ *   - before_prompt_build (p=10)  — Resume snapshot injection into system context
+ *   - before_prompt_build (p=5)   — Routing instruction injection into system context
+ *   - context-mode engine      — Context engine with compaction management
+ *   - /ctx-stats command       — Auto-reply command for session statistics
+ *   - /ctx-doctor command      — Auto-reply command for diagnostics
+ *   - /ctx-upgrade command     — Auto-reply command for upgrade
+ *
+ * Loaded by OpenClaw via: openclaw.extensions entry in package.json
+ *
+ * OpenClaw plugin paradigm:
+ *   - Plugins export { id, name, configSchema, register(api) } for metadata
+ *   - api.registerHook() for event-driven hooks
+ *   - api.on() for typed lifecycle hooks
+ *   - api.registerContextEngine() for compaction ownership
+ *   - api.registerCommand() for auto-reply slash commands
+ *   - Plugins run in-process with the Gateway (trusted code)
+ */
+import type { OpenClawToolDef } from "./openclaw/mcp-tools.js";
+/** Context for auto-reply command handlers. */
+interface CommandContext {
+    senderId?: string;
+    channel?: string;
+    isAuthorizedSender?: boolean;
+    args?: string;
+    commandBody?: string;
+    config?: Record<string, unknown>;
+}
+/** OpenClaw plugin API provided to the register function. */
+interface OpenClawPluginApi {
+    registerHook(event: string, handler: (...args: unknown[]) => unknown, meta: {
+        name: string;
+        description: string;
+    }): void;
+    /**
+     * Register a typed lifecycle hook.
+     * Supported names: "session_start", "before_compaction", "after_compaction",
+     * "before_prompt_build"
+     */
+    on(event: string, handler: (...args: unknown[]) => unknown, opts?: {
+        priority?: number;
+    }): void;
+    registerContextEngine(id: string, factory: () => ContextEngineInstance): void;
+    registerCommand?(cmd: {
+        name: string;
+        description: string;
+        acceptsArgs?: boolean;
+        requireAuth?: boolean;
+        handler: (ctx: CommandContext) => {
+            text: string;
+        } | Promise<{
+            text: string;
+        }>;
+    }): void;
+    registerCli?(factory: (ctx: {
+        program: unknown;
+    }) => void, meta: {
+        commands: string[];
+    }): void;
+    /**
+     * Register an agent tool (OpenClaw native registerTool) — see
+     * refs/platforms/openclaw/docs/plugins/building-plugins.md:116. Optional in
+     * the type so we degrade silently on legacy hosts that pre-date this API.
+     */
+    registerTool?(tool: OpenClawToolDef, opts?: {
+        optional?: boolean;
+    }): void;
+    logger?: {
+        info: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+        debug?: (...args: unknown[]) => void;
+        warn?: (...args: unknown[]) => void;
+    };
+}
+/** Context engine instance returned by the factory. */
+interface ContextEngineInstance {
+    info: {
+        id: string;
+        name: string;
+        ownsCompaction: boolean;
+    };
+    ingest(data: unknown): Promise<{
+        ingested: boolean;
+    }>;
+    assemble(ctx: {
+        messages: unknown[];
+    }): Promise<{
+        messages: unknown[];
+        estimatedTokens: number;
+    }>;
+    compact(): Promise<{
+        ok: boolean;
+        compacted: boolean;
+    }>;
+}
+/**
+ * OpenClaw plugin definition. The object form provides declarative metadata
+ * (id, name, configSchema) that OpenClaw can read without executing code.
+ * register() is called once per agent session with a fresh api object.
+ * Each call creates isolated closures (db, sessionId, hooks) — no shared state.
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            enabled: {
+                type: "boolean";
+                default: boolean;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+    register(api: OpenClawPluginApi): void;
+};
+export default _default;