context-mode 1.0.106 → 1.0.107

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-plugin.d.ts

@@ -28,6 +28,7 @@
  *   - 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;
@@ -68,6 +69,14 @@ interface OpenClawPluginApi {
     }) => 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;

package/build/openclaw-plugin.js

@@ -38,6 +38,24 @@ import { extractEvents, extractUserEvents } from "./session/extract.js";
 import { buildResumeSnapshot } from "./session/snapshot.js";
 import { WorkspaceRouter } from "./openclaw/workspace-router.js";
 import { buildNodeCommand } from "./adapters/types.js";
+import { OPENCLAW_TOOL_DEFS } from "./openclaw/mcp-tools.js";
+// ── System-reminder filter (CCv2 — SLICE OClaw-3) ─────────
+// Mirror hooks/userpromptsubmit.mjs:30-33: skip system-generated wrappers
+// so before_model_resolve never inserts spurious user-prompt events.
+const SYSTEM_REMINDER_PREFIXES = [
+    "<system-reminder>",
+    "<task-notification>",
+    "<context_guidance>",
+    "<tool-result>",
+];
+function isSystemReminderMessage(msg) {
+    const trimmed = msg.trimStart();
+    for (const prefix of SYSTEM_REMINDER_PREFIXES) {
+        if (trimmed.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
 /** Plugin config schema for OpenClaw validation. */
 const configSchema = {
     type: "object",
@@ -114,27 +132,46 @@ export default {
         // Start with temp UUID — session_start will assign the real ID + sessionKey
         let sessionId = randomUUID();
         log.info("register() called, sessionId:", sessionId.slice(0, 8));
+        // SLICE OClaw-6 (F6 retraction): `resumeInjected` is correctly scoped
+        // per-register() singleton — Phase 7 confirmed F6 fabrication-as-tech-debt.
+        // Each OpenClaw agent session calls register() once and gets its own
+        // closure; the flag prevents double-injection of the resume snapshot in
+        // back-to-back before_prompt_build calls within the same session. Do not
+        // promote to module scope.
         let resumeInjected = false;
         let sessionKey;
         // Create temp session so after_tool_call events before session_start have a valid row
         db.ensureSession(sessionId, projectDir);
         const workspaceRouter = new WorkspaceRouter();
-        // Load routing instructions synchronously for prompt injection
+        // Async init: load routing module + dynamic routing-block factory.
+        // SLICE OClaw-2: replaced static readFileSync(configs/openclaw/AGENTS.md)
+        // with createRoutingBlock(createToolNamer("openclaw")) so OpenClaw-specific
+        // MCP-prefix substitution stays in lockstep with hooks/routing-block.mjs.
         let routingInstructions = "";
-        try {
-            const instructionsPath = resolve(buildDir, "..", "configs", "openclaw", "AGENTS.md");
-            if (existsSync(instructionsPath)) {
-                routingInstructions = readFileSync(instructionsPath, "utf-8");
-            }
-        }
-        catch {
-            // best effort
-        }
-        // Async init: load routing module. Hooks await this.
         const initPromise = (async () => {
             const routingPath = resolve(buildDir, "..", "hooks", "core", "routing.mjs");
             const routing = await import(pathToFileURL(routingPath).href);
             await routing.initSecurity(buildDir);
+            try {
+                const blockMod = await import(pathToFileURL(resolve(buildDir, "..", "hooks", "routing-block.mjs")).href);
+                const namingMod = await import(pathToFileURL(resolve(buildDir, "..", "hooks", "core", "tool-naming.mjs")).href);
+                const toolNamer = namingMod.createToolNamer("openclaw");
+                routingInstructions = blockMod.createRoutingBlock(toolNamer);
+            }
+            catch (err) {
+                log.warn?.("failed to build dynamic routing block", err);
+                // Fallback: legacy disk-read of AGENTS.md (kept for resilience only —
+                // primary path is the dynamic factory above).
+                try {
+                    const instructionsPath = resolve(buildDir, "..", "configs", "openclaw", "AGENTS.md");
+                    if (existsSync(instructionsPath)) {
+                        routingInstructions = readFileSync(instructionsPath, "utf-8");
+                    }
+                }
+                catch {
+                    // best effort
+                }
+            }
             return { routing };
         })();
         // ── 1. tool_call:before — Routing enforcement ──────────
@@ -359,6 +396,12 @@ export default {
                 log.debug("before_model_resolve", { hasMessage: !!messageText });
                 if (!messageText)
                     return;
+                // SLICE OClaw-3: skip system-generated wrappers so we never
+                // misclassify them as user prompts. Mirrors hooks/userpromptsubmit.mjs:30-33.
+                if (isSystemReminderMessage(messageText)) {
+                    log.debug("before_model_resolve[skip-system-reminder]");
+                    return;
+                }
                 const events = extractUserEvents(messageText);
                 for (const ev of events) {
                     db.insertEvent(sid, ev, "PostToolUse");
@@ -389,12 +432,85 @@ export default {
             }
         }, { priority: 10 });
         // ── 8. before_prompt_build — Routing instruction injection ──
-        if (routingInstructions) {
-            api.on("before_prompt_build", () => {
-                log.debug("before_prompt_build[routing]", { hasInstructions: !!routingInstructions });
-                return { appendSystemContext: routingInstructions };
-            }, { priority: 5 });
+        // SLICE OClaw-2: register unconditionally; routingInstructions is populated
+        // asynchronously by initPromise. The closure resolves the latest value at
+        // call-time, so the first prompt-build firing after dynamic-import resolution
+        // sees the dynamic ROUTING_BLOCK XML (matching hooks/routing-block.mjs).
+        api.on("before_prompt_build", () => {
+            if (!routingInstructions)
+                return undefined;
+            log.debug("before_prompt_build[routing]", { hasInstructions: !!routingInstructions });
+            // v1.0.107 — visible marker so OpenClaw users can verify the routing
+            // block reached the model (Mickey-class verification path; mirrors
+            // OpenCode + Pi adapters).
+            const marker = `<!-- context-mode: routing block injected (sessionID=${String(sessionId).slice(0, 8)}) -->`;
+            return { appendSystemContext: marker + "\n" + routingInstructions };
+        }, { priority: 5 });
+        // ── 8b. registerTool — Expose 11 ctx_* tools (SLICE OClaw-1) ────
+        // Phase 7 audit (v1.0.107-adapter-openclaw.json) flagged severity=CRITICAL:
+        // routing block tells agents to call ctx_execute / ctx_search / etc. but
+        // nothing called api.registerTool, so the tools didn't exist in the
+        // OpenClaw session. This loop fixes that — mirrors swarmvault MCP pattern
+        // (refs/plugin-examples/openclaw/swarmvault/packages/engine/src/mcp.ts:46-51).
+        if (api.registerTool) {
+            for (const def of OPENCLAW_TOOL_DEFS) {
+                try {
+                    api.registerTool(def);
+                }
+                catch (err) {
+                    log.warn?.("registerTool failed", { name: def.name }, err);
+                }
+            }
+            log.debug("registerTool[ctx_*]", { count: OPENCLAW_TOOL_DEFS.length });
         }
+        else {
+            log.warn?.("api.registerTool unavailable — ctx_* tools not exposed in this OpenClaw build");
+        }
+        // ── 8c. session_end — Finalize resume snapshot (SLICE OClaw-4) ───
+        // OpenClaw fires session_end at session lifecycle boundaries (per
+        // refs/platforms/openclaw/docs/plugins/hooks.md:110). We persist a final
+        // resume snapshot so a future session_start with resumedFrom can re-attach.
+        api.on("session_end", async () => {
+            try {
+                const sid = sessionId;
+                const allEvents = db.getEvents(sid);
+                log.debug("session_end", { sessionId: sid.slice(0, 8), events: allEvents.length });
+                if (allEvents.length === 0)
+                    return;
+                const freshStats = db.getSessionStats(sid);
+                const snapshot = buildResumeSnapshot(allEvents, {
+                    compactCount: freshStats?.compact_count ?? 0,
+                });
+                db.upsertResume(sid, snapshot, allEvents.length);
+            }
+            catch {
+                // best effort — never break session shutdown
+            }
+        });
+        // ── 8d. subagent_spawning — Inject routing block (SLICE OClaw-5) ─
+        // OpenClaw's subagent lifecycle (hooks.md:116) gives us a chance to seed
+        // every spawned subagent with the same routing block the parent agent
+        // sees. Without this, subagents have no MCP-routing guidance and degrade
+        // back to flooding the context with raw tool output.
+        api.on("subagent_spawning", (event) => {
+            try {
+                const e = (event ?? {});
+                const basePrompt = e?.input?.prompt ?? "";
+                if (!routingInstructions)
+                    return undefined;
+                const newPrompt = basePrompt
+                    ? `${basePrompt}\n\n${routingInstructions}`
+                    : routingInstructions;
+                log.debug("subagent_spawning[inject-routing]", {
+                    basePromptLen: basePrompt.length,
+                    blockLen: routingInstructions.length,
+                });
+                return { inputOverride: { ...(e.input ?? {}), prompt: newPrompt } };
+            }
+            catch {
+                return undefined;
+            }
+        });
         // ── 9. Context engine — Compaction management ──────────
         api.registerContextEngine("context-mode", () => ({
             info: {

package/build/opencode-plugin.d.ts

@@ -1,10 +1,12 @@
 /**
  * OpenCode / KiloCode TypeScript plugin entry point for context-mode.
  *
- * Provides three hooks:
+ * Provides five hooks (v1.0.107 — Mickey OC-1..OC-4 follow-up):
  *   - tool.execute.before  — Routing enforcement (deny/modify/passthrough)
- *   - tool.execute.after   — Session event capture
- *   - experimental.session.compacting — Compaction snapshot generation
+ *   - tool.execute.after   — Session event capture + first-fire AGENTS.md scan (OC-4)
+ *   - experimental.session.compacting — Compaction snapshot + budget-capped auto-injection (OC-3)
+ *   - experimental.chat.system.transform — ROUTING_BLOCK + resume snapshot injection (OC-1)
+ *   - chat.message         — User-prompt capture w/ CCv2 inline filter (OC-2)
  *
  * KiloCode loads this via: import("context-mode") → expects default export
  * with shape { server: (input) => Promise<Hooks> } (PluginModule).
@@ -14,7 +16,7 @@
  *
  * Constraints:
  *   - No SessionStart hook (OpenCode doesn't support it — #14808, #5409)
- *   - No context injection (canInjectSessionContext: false)
+ *   - context injection now via chat.system.transform surrogate (OC-1)
  *   - No routing file auto-write (avoid dirtying project trees)
  *   - Session cleanup happens at plugin init (no SessionStart)
  */
@@ -77,6 +79,28 @@ interface SystemTransformHookInput {
 interface SystemTransformHookOutput {
     system: string[];
 }
+/**
+ * OpenCode chat.message hook — verified against
+ * refs/platforms/opencode/packages/plugin/src/index.ts:233.
+ *   input:  { sessionID; agent?; model?; messageID?; variant? }
+ *   output: { message: UserMessage; parts: Part[] }
+ * We read text from `parts[*].text` (the orchestrator reference at
+ * refs/plugin-examples/opencode/opencode-orchestrator/src/plugin-handlers/
+ * chat-message-handler.ts:41-65 uses the same pattern).
+ */
+interface ChatMessageHookInput {
+    sessionID: string;
+    agent?: string;
+    messageID?: string;
+}
+interface ChatMessagePart {
+    type: string;
+    text?: string;
+}
+interface ChatMessageHookOutput {
+    message: unknown;
+    parts: ChatMessagePart[];
+}
 /**
  * Plugin factory. Called once when KiloCode/OpenCode loads the plugin.
  * Returns an object mapping hook event names to async handler functions.
@@ -87,6 +111,7 @@ interface SystemTransformHookOutput {
 declare function createContextModePlugin(ctx: PluginContext): Promise<{
     "tool.execute.before": (input: BeforeHookInput, output: BeforeHookOutput) => Promise<void>;
     "tool.execute.after": (input: AfterHookInput, output: AfterHookOutput) => Promise<void>;
+    "chat.message": (input: ChatMessageHookInput, output: ChatMessageHookOutput) => Promise<void>;
     "experimental.session.compacting": (input: CompactingHookInput, output: CompactingHookOutput) => Promise<string>;
     "experimental.chat.system.transform": (input: SystemTransformHookInput, output: SystemTransformHookOutput) => Promise<void>;
 }>;