@mxalbert/context-mode 2.0.0

package/build/adapters/omp/plugin.js

@@ -0,0 +1,331 @@
+/**
+ * Oh My Pi (OMP) plugin entry point for context-mode.
+ *
+ * Mirrors the Pi extension shape (`src/adapters/pi/extension.ts`) for
+ * the four OMP hook events that materially protect the context window
+ * and persist session continuity:
+ *
+ *   - session_start         — initialize the session row in our DB
+ *   - tool_call             — hard-block curl/wget/inline-HTTP in bash
+ *   - tool_result           — extract structured events into the session DB
+ *   - session_before_compact — persist a resume snapshot before compaction
+ *
+ * Loaded by OMP via the `omp` (or `pi`) field in package.json — see
+ * upstream loader at refs/platforms/oh-my-pi/packages/coding-agent/src/
+ * extensibility/plugins/loader.ts:75:
+ *   `const manifest: PluginManifest | undefined = pluginPkg.omp || pluginPkg.pi;`
+ * Hook factory contract from refs/.../extensibility/hooks/types.ts:809:
+ *   `export type HookFactory = (pi: HookAPI) => void;`
+ *
+ * OMP differs from Pi in two ways that justify a dedicated plugin file:
+ *   1. Storage roots at ~/.omp/context-mode/ via OMPAdapter, not ~/.pi/
+ *   2. OMP has native MCP support (mcp.json), so no MCP bridge is needed
+ *      — the bridge that Pi's extension ships (mcp-bridge.ts) is dead weight
+ *      under OMP and is intentionally omitted here.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveSessionDbPath, SessionDB } from "../../session/db.js";
+import { extractEvents, buildAgentUsageEvent } from "../../session/extract.js";
+import { buildResumeSnapshot } from "../../session/snapshot.js";
+import { OMPAdapter } from "./index.js";
+import { parseOmpUsage } from "./usage.js";
+// ── Tool-name normalization ─────────────────────────────
+// OMP uses lowercase tool names (refs/.../hooks/types.ts:451 example
+// `toolName: "bash"`). Shared event extractors expect PascalCase
+// (Claude Code convention). Map the common ones.
+const OMP_TOOL_MAP = {
+    bash: "Bash",
+    edit: "Edit",
+    read: "Read",
+    write: "Write",
+    list: "Glob",
+    view: "Read",
+};
+// ── Routing patterns ─────────────────────────────────────
+// Inline HTTP client patterns to hard-block in bash. Identical to the
+// Pi extension list (src/adapters/pi/extension.ts:42). One unrouted
+// curl can dump 56 KB into context.
+const BLOCKED_BASH_PATTERNS = [
+    /\bcurl\s/,
+    /\bwget\s/,
+    /\bfetch\s*\(/,
+    /\brequests\.get\s*\(/,
+    /\brequests\.post\s*\(/,
+    /\bhttp\.get\s*\(/,
+    /\bhttp\.request\s*\(/,
+    /\burllib\.request/,
+    /\bInvoke-WebRequest\b/,
+];
+// ── Module-level singletons ──────────────────────────────
+// Same shape as Pi: one DB per process, session ID rebound on each
+// session_start so multi-session reuse within a long-lived plugin
+// process keeps event attribution correct.
+let _db = null;
+let _dbPath = "";
+let _sessionId = "";
+const _ompAdapter = new OMPAdapter();
+// ── MCP self-registration (issue #677) ───────────────────
+// The `omp plugin install context-mode` path wires THIS extension factory
+// (so routing hooks fire), but never creates the MCP config — so the 11
+// `ctx_*` tools stay unreachable even though curl/wget are blocked. Register
+// the server ourselves on plugin load, ONLY when absent (never clobber a
+// user's existing entry). Takes effect on the next OMP restart, same as the
+// manual mcp.json workaround the issue documents.
+const MCP_SERVER_NAME = "context-mode";
+// plugin.js ships at <pkg>/build/adapters/omp/plugin.js; the MCP server
+// bundle sits at the package root (<pkg>/server.bundle.mjs) — three up.
+const SERVER_BUNDLE_RELATIVE = "../../../server.bundle.mjs";
+function resolveServerBundle() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const bundle = resolve(here, SERVER_BUNDLE_RELATIVE);
+        return existsSync(bundle) ? bundle : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure `~/.omp/agent/mcp.json` registers the context-mode MCP server.
+ *
+ * Uses `node <abs>/server.bundle.mjs` rather than the `context-mode` bin:
+ * under the plugin install the package lives in `~/.omp/plugins/node_modules`
+ * and its bin is NOT on PATH, so the bare command would fail to spawn (the
+ * exact symptom reported on issue #677). Best effort — never throws, never
+ * breaks plugin load.
+ */
+function ensureMcpServerRegistered() {
+    try {
+        const bundle = resolveServerBundle();
+        if (!bundle)
+            return; // bundle missing → nothing safe to register
+        const settings = _ompAdapter.readSettings() ?? {};
+        const mcpServers = settings.mcpServers ?? {};
+        if (MCP_SERVER_NAME in mcpServers)
+            return; // already present — don't clobber
+        mcpServers[MCP_SERVER_NAME] = {
+            type: "stdio",
+            command: "node",
+            args: [bundle],
+        };
+        settings.mcpServers = mcpServers;
+        _ompAdapter.writeSettings(settings);
+    }
+    catch {
+        // best effort — a registration failure must never break plugin load
+    }
+}
+function getSessionDir() {
+    const dir = _ompAdapter.getSessionDir();
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+// Issue #645 — route through the canonical per-project resolver the MCP
+// server uses (src/server.ts ctx_stats / ctx_search timeline). The
+// previous shared `context-mode.db` literal was a different file from
+// the `<canonical-hash>.db` the server reads, so every OMP user's
+// `ctx_stats` reported zero history and `ctx_search(sort: "timeline")`
+// silently dropped the sort. Mirrors the matching Pi fix and the
+// opencode plugin pattern (src/adapters/opencode/plugin.ts:307).
+function getDBPath(projectDir) {
+    return resolveSessionDbPath({ projectDir, sessionsDir: getSessionDir() });
+}
+function getOrCreateDB(projectDir) {
+    // Reopen the singleton if the resolved DB path changes. See the
+    // matching Pi extension comment — defensive re-keying on projectDir
+    // hash keeps tests deterministic and stops a stale singleton from
+    // pointing at an earlier projectDir's `<hash>.db`. (#645)
+    const dbPath = getDBPath(projectDir);
+    if (!_db || _dbPath !== dbPath) {
+        if (_db) {
+            try {
+                _db.close();
+            }
+            catch { /* best effort */ }
+        }
+        _db = new SessionDB({ dbPath });
+        _dbPath = dbPath;
+    }
+    return _db;
+}
+/**
+ * Derive a stable session ID from OMP's session manager when available,
+ * otherwise fall back to a wall-clock token. Mirrors the Pi extension
+ * derivation (src/adapters/pi/extension.ts:142) — the OMP `ctx` object
+ * exposes `sessionManager.getSessionFile()` per refs/.../hooks/types.ts.
+ */
+function deriveSessionId(ctx) {
+    try {
+        const sessionManager = ctx
+            ?.sessionManager;
+        const sessionFile = sessionManager?.getSessionFile?.();
+        if (sessionFile && typeof sessionFile === "string") {
+            return createHash("sha256").update(sessionFile).digest("hex").slice(0, 16);
+        }
+    }
+    catch {
+        // best effort
+    }
+    return `omp-${Date.now()}`;
+}
+// ── Test-only state reset (NOT exported via plugin entry) ───────────
+// The plugin's default export is the OMP factory; this helper is only
+// imported by tests to clear singletons between cases.
+export function _resetOmpPluginStateForTests() {
+    if (_db) {
+        try {
+            _db.close();
+        }
+        catch { /* best effort */ }
+    }
+    _db = null;
+    _dbPath = "";
+    _sessionId = "";
+}
+/**
+ * Return the current session ID picked by the most recent session_start
+ * handler. Test-only — production code reads `_sessionId` directly via
+ * the closure. The shared SQLite DB at `~/.omp/context-mode/` survives
+ * between tests, so `getLatestSessionId()` cannot disambiguate which
+ * row belongs to "this" test when multiple tests insert in the same
+ * second; tests use this getter instead.
+ */
+export function _getOmpPluginSessionIdForTests() {
+    return _sessionId;
+}
+// ── Plugin entry point ───────────────────────────────────
+/**
+ * OMP plugin default export. Called once by the OMP runtime per
+ * upstream `extensibility/plugins/loader.ts` after `omp plugin install
+ * context-mode`. Subsequent `pi.on(...)` registrations route the four
+ * lifecycle events to our SessionDB-backed handlers below.
+ */
+export default function ompPlugin(pi) {
+    // OMP upstream uses PI_-prefixed env vars only (verified against
+    // can1357/oh-my-pi v3.20.1 — see `packages/utils/src/dirs.ts`). The
+    // earlier `OMP_PROJECT_DIR` read was an EM mistake — no upstream code
+    // ever sets it. Drop it; fall through PI_PROJECT_DIR → cwd().
+    const projectDir = process.env.PI_PROJECT_DIR || process.cwd();
+    // Self-register the MCP server so `ctx_*` tools are reachable under the
+    // plugin install path, not just the manual MCP-only path (issue #677).
+    ensureMcpServerRegistered();
+    const db = getOrCreateDB(projectDir);
+    // ── 1. session_start — initialize session row ─────────
+    pi.on("session_start", (_event, ctx) => {
+        try {
+            _sessionId = deriveSessionId(ctx);
+            db.ensureSession(_sessionId, projectDir);
+            db.cleanupOldSessions(7);
+        }
+        catch {
+            // best effort — never break session start
+            if (!_sessionId) {
+                _sessionId = `omp-${Date.now()}`;
+            }
+        }
+        return undefined;
+    });
+    // ── 2. tool_call — pre-tool-call hard-block ───────────
+    // Returning `{block: true, reason}` per
+    // refs/.../hooks/types.ts:566 (ToolCallEventResult) terminates the
+    // tool call with the reason surfaced to the LLM.
+    pi.on("tool_call", (event) => {
+        try {
+            const toolName = String(event?.toolName ?? "").toLowerCase();
+            if (toolName !== "bash")
+                return undefined;
+            const command = String(event?.input?.command ?? "");
+            if (!command)
+                return undefined;
+            const isBlocked = BLOCKED_BASH_PATTERNS.some((p) => p.test(command));
+            if (isBlocked) {
+                return {
+                    block: true,
+                    reason: "Use context-mode MCP tools (ctx_execute, ctx_fetch_and_index) instead of inline HTTP. " +
+                        "curl/wget/fetch dump raw HTTP into the context window.",
+                };
+            }
+        }
+        catch {
+            // routing failure → allow passthrough
+        }
+        return undefined;
+    });
+    // ── 3. tool_result — post-tool-call event capture ─────
+    // OMP `tool_result` payload (refs/.../hooks/types.ts:461 onward) is
+    // `{toolName, toolCallId, input, content[], isError}`. We adapt to
+    // the Claude Code-shaped HookInput consumed by extractEvents.
+    pi.on("tool_result", (event) => {
+        try {
+            if (!_sessionId)
+                return undefined;
+            const rawToolName = String(event?.toolName ?? "");
+            const mappedToolName = OMP_TOOL_MAP[rawToolName.toLowerCase()] ?? rawToolName;
+            const content = Array.isArray(event?.content) ? event.content : [];
+            const textParts = content
+                .filter((c) => c?.type === "text" && typeof c.text === "string")
+                .map((c) => c.text);
+            const resultStr = textParts.join("\n");
+            const hookInput = {
+                tool_name: mappedToolName,
+                tool_input: event?.input ?? {},
+                tool_response: resultStr,
+                tool_output: event?.isError ? { isError: true } : undefined,
+            };
+            const events = extractEvents(hookInput);
+            for (const ev of events) {
+                db.insertEvent(_sessionId, ev, "PostToolUse");
+            }
+        }
+        catch {
+            // best effort
+        }
+        return undefined;
+    });
+    // ── 4. session_before_compact — resume snapshot ───────
+    pi.on("session_before_compact", () => {
+        try {
+            if (!_sessionId)
+                return undefined;
+            const events = db.getEvents(_sessionId);
+            const snapshot = buildResumeSnapshot(events);
+            db.upsertResume(_sessionId, snapshot, events.length);
+            db.incrementCompactCount(_sessionId);
+        }
+        catch {
+            // best effort
+        }
+        return undefined;
+    });
+    // ── 5. turn_end — per-turn token + provider cost capture ──
+    // OMP exposes REAL per-turn tokens AND a provider-computed USD cost on the
+    // completed turn's AssistantMessage (`event.message.usage` / `.model`),
+    // delivered INCREMENTALLY per turn (matrix §2,§5). parseOmpUsage maps that to
+    // the buildAgentUsageEvent counts (Usage.cacheWrite→cache_creation,
+    // cacheRead→cache_read, cost.total→native_cost_usd). buildAgentUsageEvent
+    // prefers the native cost over the local price table and returns null on an
+    // all-zero turn. We persist via db.insertEvent — the SessionDB-backed forward
+    // path used everywhere in this in-process plugin runtime (the .mjs
+    // attributeAndInsertEvents helper is the Claude-hook analogue, not reachable
+    // here). Best-effort: a usage parse must never break the turn.
+    pi.on("turn_end", (event) => {
+        try {
+            if (!_sessionId)
+                return undefined;
+            const counts = parseOmpUsage(event);
+            if (counts === null)
+                return undefined;
+            const usageEvent = buildAgentUsageEvent(counts);
+            if (usageEvent === null)
+                return undefined;
+            db.insertEvent(_sessionId, usageEvent, "PostToolUse");
+        }
+        catch {
+            // best effort — never break the turn on cost capture
+        }
+        return undefined;
+    });
+}

package/build/adapters/omp/usage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * adapters/omp/usage — pure parse of an OMP `turn_end` / `agent_end` payload
+ * into the {@link buildAgentUsageEvent} counts shape.
+ *
+ * Ground truth (docs/prds/2026-06-paid-observability/adapter-matrix/omp.md §2-4):
+ *   - Per-turn usage rides on `AssistantMessage.usage`
+ *     (`refs/platforms/omp/packages/ai/src/types.ts:505-541`).
+ *   - The canonical `Usage` shape lives in pi-catalog
+ *     (`refs/platforms/omp/packages/catalog/src/types.ts:100-145`): fields
+ *     `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, plus a
+ *     fully-resolved `cost: { input, output, cacheRead, cacheWrite, total }`
+ *     (:138-144) — provider-computed, so NO client price table is needed.
+ *   - `model: string` is `provider/model` on the `AssistantMessage` (:510).
+ *   - `turn_end` carries `message: AssistantMessage`
+ *     (`refs/.../extensibility/shared-events.ts:204-208`); `agent_end` carries
+ *     `messages: AssistantMessage[]` (:191-194).
+ *
+ * Field mapping (matrix §3 → buildAgentUsageEvent input):
+ *   Usage.input      → input_tokens
+ *   Usage.output     → output_tokens
+ *   Usage.cacheWrite → cache_creation_tokens   (cache CREATION on the provider)
+ *   Usage.cacheRead  → cache_read_tokens
+ *   message.model    → model_id                (the `provider/model` string)
+ *   Usage.cost.total → native_cost_usd         (provider-computed, preferred)
+ *
+ * Algorithmic + null-safe. NO regex. Returns `null` whenever there is no
+ * usable signal (no message / no usage / every token bucket absent-or-zero),
+ * so a malformed or empty turn emits nothing.
+ */
+/**
+ * The counts object accepted by {@link buildAgentUsageEvent}. Re-declared here
+ * (structurally identical) so this module stays a leaf with no import cycle
+ * into the heavy `session/extract` module — the handler in `plugin.ts` passes
+ * the result straight through to `buildAgentUsageEvent`.
+ */
+export interface OmpUsageCounts {
+    model_id: string;
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_tokens: number;
+    cache_read_tokens: number;
+    native_cost_usd: number | null;
+}
+/**
+ * Parse an OMP `turn_end` / `agent_end` event payload into the
+ * {@link buildAgentUsageEvent} counts shape, or `null` when no usable usage is
+ * present. Pure and side-effect free.
+ */
+export declare function parseOmpUsage(payload: unknown): OmpUsageCounts | null;

package/build/adapters/omp/usage.js

@@ -0,0 +1,110 @@
+/**
+ * adapters/omp/usage — pure parse of an OMP `turn_end` / `agent_end` payload
+ * into the {@link buildAgentUsageEvent} counts shape.
+ *
+ * Ground truth (docs/prds/2026-06-paid-observability/adapter-matrix/omp.md §2-4):
+ *   - Per-turn usage rides on `AssistantMessage.usage`
+ *     (`refs/platforms/omp/packages/ai/src/types.ts:505-541`).
+ *   - The canonical `Usage` shape lives in pi-catalog
+ *     (`refs/platforms/omp/packages/catalog/src/types.ts:100-145`): fields
+ *     `input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, plus a
+ *     fully-resolved `cost: { input, output, cacheRead, cacheWrite, total }`
+ *     (:138-144) — provider-computed, so NO client price table is needed.
+ *   - `model: string` is `provider/model` on the `AssistantMessage` (:510).
+ *   - `turn_end` carries `message: AssistantMessage`
+ *     (`refs/.../extensibility/shared-events.ts:204-208`); `agent_end` carries
+ *     `messages: AssistantMessage[]` (:191-194).
+ *
+ * Field mapping (matrix §3 → buildAgentUsageEvent input):
+ *   Usage.input      → input_tokens
+ *   Usage.output     → output_tokens
+ *   Usage.cacheWrite → cache_creation_tokens   (cache CREATION on the provider)
+ *   Usage.cacheRead  → cache_read_tokens
+ *   message.model    → model_id                (the `provider/model` string)
+ *   Usage.cost.total → native_cost_usd         (provider-computed, preferred)
+ *
+ * Algorithmic + null-safe. NO regex. Returns `null` whenever there is no
+ * usable signal (no message / no usage / every token bucket absent-or-zero),
+ * so a malformed or empty turn emits nothing.
+ */
+/** Coerce an unknown to a finite non-negative integer token count, else 0. */
+function toTokenCount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return 0;
+    }
+    // Token counts are integers upstream; floor defensively against floats.
+    return Math.floor(value);
+}
+/** Coerce an unknown to a finite USD cost, else null (so the catalog can fill in). */
+function toCostUsd(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+/** Narrow an unknown to a plain (non-null, non-array) object. */
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/**
+ * Resolve the per-turn `AssistantMessage` from a `turn_end` (`.message`) or
+ * `agent_end` (`.messages[]`) payload. For `agent_end` we take the LAST
+ * assistant message — that is the turn that just completed and whose usage is
+ * the new delta (OMP usage is INCREMENTAL per turn, matrix §5).
+ */
+function resolveMessage(payload) {
+    const single = asRecord(payload.message);
+    if (single !== null)
+        return single;
+    const list = payload.messages;
+    if (Array.isArray(list)) {
+        for (let i = list.length - 1; i >= 0; i--) {
+            const m = asRecord(list[i]);
+            if (m !== null)
+                return m;
+        }
+    }
+    return null;
+}
+/**
+ * Parse an OMP `turn_end` / `agent_end` event payload into the
+ * {@link buildAgentUsageEvent} counts shape, or `null` when no usable usage is
+ * present. Pure and side-effect free.
+ */
+export function parseOmpUsage(payload) {
+    const root = asRecord(payload);
+    if (root === null)
+        return null;
+    const message = resolveMessage(root);
+    if (message === null)
+        return null;
+    const usage = asRecord(message.usage);
+    if (usage === null)
+        return null;
+    const input_tokens = toTokenCount(usage.input);
+    const output_tokens = toTokenCount(usage.output);
+    const cache_creation_tokens = toTokenCount(usage.cacheWrite);
+    const cache_read_tokens = toTokenCount(usage.cacheRead);
+    // No usable token signal → no event (mirrors buildAgentUsageEvent's own
+    // all-zero guard, but lets the handler short-circuit before building).
+    if (input_tokens <= 0 &&
+        output_tokens <= 0 &&
+        cache_creation_tokens <= 0 &&
+        cache_read_tokens <= 0) {
+        return null;
+    }
+    const model_id = typeof message.model === "string" ? message.model : "";
+    const cost = asRecord(usage.cost);
+    const native_cost_usd = cost !== null ? toCostUsd(cost.total) : null;
+    return {
+        model_id,
+        input_tokens,
+        output_tokens,
+        cache_creation_tokens,
+        cache_read_tokens,
+        native_cost_usd,
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * adapters/openclaw/config — Thin re-exports from OpenClawAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { OpenClawAdapter } from "./index.js";
+export { HOOK_EVENTS, LIFECYCLE_HOOKS, REQUIRED_HOOKS, OPTIONAL_HOOKS } from "./hooks.js";

package/build/adapters/openclaw/config.js

@@ -0,0 +1,8 @@
+/**
+ * adapters/openclaw/config — Thin re-exports from OpenClawAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { OpenClawAdapter } from "./index.js";
+export { HOOK_EVENTS, LIFECYCLE_HOOKS, REQUIRED_HOOKS, OPTIONAL_HOOKS } from "./hooks.js";

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

@@ -0,0 +1,50 @@
+/**
+ * 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/
+ */
+/** OpenClaw hook event names (registered via api.registerHook). */
+export declare const HOOK_EVENTS: {
+    readonly TOOL_CALL_BEFORE: "tool_call:before";
+    readonly TOOL_CALL_AFTER: "tool_call:after";
+    readonly COMMAND_NEW: "command:new";
+    readonly COMMAND_RESET: "command:reset";
+    readonly COMMAND_STOP: "command:stop";
+};
+/** OpenClaw lifecycle hook names (registered via api.on). */
+export declare const LIFECYCLE_HOOKS: {
+    readonly SESSION_START: "session_start";
+    readonly BEFORE_COMPACTION: "before_compaction";
+    readonly AFTER_COMPACTION: "after_compaction";
+    readonly BEFORE_PROMPT_BUILD: "before_prompt_build";
+    readonly BEFORE_MODEL_RESOLVE: "before_model_resolve";
+    readonly BEFORE_AGENT_START: "before_agent_start";
+};
+export type HookEvent = (typeof HOOK_EVENTS)[keyof typeof HOOK_EVENTS];
+export type LifecycleHook = (typeof LIFECYCLE_HOOKS)[keyof typeof LIFECYCLE_HOOKS];
+/**
+ * Required hooks that must be active for context-mode to function.
+ * OpenClaw registers these via api.registerHook() in the plugin entry point.
+ */
+export declare const REQUIRED_HOOKS: HookEvent[];
+/**
+ * Optional hooks that enhance functionality but aren't critical.
+ * command:new provides session cleanup; context engine handles compaction.
+ */
+export declare const OPTIONAL_HOOKS: HookEvent[];
+/**
+ * Check if a plugin entry is the context-mode plugin.
+ * OpenClaw plugins are registered by id in plugins.entries.
+ */
+export declare function isContextModePlugin(pluginId: string): boolean;

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");
+}