@gamaze/hicortex 0.12.0 → 0.13.0

package/dist/index.js

@@ -19,9 +19,12 @@
  * canonical nightly-from-logs, same as CC JSONL and Hermes state.db.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+const paths_js_1 = require("./paths.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
+const context_store_js_1 = require("./context-store.js");
+const lessons_context_js_1 = require("./lessons-context.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -30,7 +33,10 @@ const node_os_1 = require("node:os");
 // ---------------------------------------------------------------------------
 const DEFAULT_SERVER_URL = "http://127.0.0.1:8787";
 const LESSONS_TIMEOUT_MS = 3000;
-const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+const CONTEXT_TIMEOUT_MS = 3000;
+const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** Harness name this plugin injects for — used to self-gate on GET /context `clients`. */
+const THIS_HARNESS = "oc";
 // ---------------------------------------------------------------------------
 // Module state — initialized in registerService.start()
 // ---------------------------------------------------------------------------
@@ -94,6 +100,54 @@ async function serverPost(path, body, timeoutMs) {
     }
 }
 // ---------------------------------------------------------------------------
+// Context layer (L2) — per-agent standing context (0.13)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch GET /context (per-agent when an id is supplied) and build the
+ * `## Context` block via the shared gate (gateAndRenderContext), or null when
+ * nothing should be injected. The old-server guard is required only when an
+ * agent id was actually sent (amendment A2 — a bare fetch skips it). The server
+ * does the merge; the plugin stays dumb (no client-side mode logic).
+ */
+async function fetchOcContextBlock(agentId) {
+    const path = agentId ? `/context?agent=${encodeURIComponent(agentId)}` : "/context";
+    const { data } = await serverGet(path, CONTEXT_TIMEOUT_MS);
+    if (!data)
+        return null;
+    return (0, lessons_context_js_1.gateAndRenderContext)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
+}
+/**
+ * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
+ * output; the caller prepends the `## Context` block and adds separators.
+ */
+async function buildLessonsBlock(project) {
+    const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
+    if (!data || !data.lessons || data.lessons.length === 0)
+        return null;
+    const maxLessons = (0, features_js_1.lessonsLimit)();
+    const state = (0, state_js_1.loadState)(hicortexHome);
+    const moduleIndex = data.moduleIndex ?? state.moduleIndex;
+    const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
+        maxLessons,
+        project,
+        moduleIndex,
+    });
+    if (selected.length === 0)
+        return null;
+    const formatted = selected.map((l) => {
+        const titleMatch = l.content.match(/## Lesson: (.+)/);
+        const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
+        const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
+        const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
+        const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
+        return `- ${title}${meta ? ` (${meta})` : ""}`;
+    });
+    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
+        `These are actionable lessons learned from past sessions:\n\n` +
+        formatted.join("\n"));
+}
+// ---------------------------------------------------------------------------
 // Tool result formatter
 // ---------------------------------------------------------------------------
 function formatToolResults(results) {
@@ -157,40 +211,32 @@ exports.default = {
             },
         });
         // -----------------------------------------------------------------------
-        // Hook: before_agent_start — fetch lessons from server (fail-soft)
+        // Hook: before_agent_start — fetch context + lessons from server (fail-soft)
         // -----------------------------------------------------------------------
         api.on("before_agent_start", async (_event, ctx) => {
+            // Outer guard: the hook must NEVER throw (a rejection could block the
+            // agent). `ctx` itself can be nullish on some gateway variants, and the
+            // synchronous sanitize below runs before any per-fetch .catch — so the
+            // whole body is wrapped, not just the fetches.
             try {
-                // One fetch — build context and check cap from the same response.
-                const { data } = await serverGet("/lessons", LESSONS_TIMEOUT_MS);
-                if (!data || !data.lessons || data.lessons.length === 0)
-                    return {};
-                const maxLessons = (0, features_js_1.lessonsLimit)();
-                const state = (0, state_js_1.loadState)(hicortexHome);
-                const moduleIndex = data.moduleIndex ?? state.moduleIndex;
-                const selected = await (0, extensions_js_1.getLessonSelector)().select(data.lessons, {
-                    maxLessons,
-                    project: ctx.project,
-                    moduleIndex,
-                });
-                if (selected.length === 0)
+                // Per-agent context id: sanitize the OC agent id (a symbols-only id
+                // sanitizes to null → bare /context → global set). Null id never sends
+                // ?agent=, so an old server behaves exactly as before.
+                const agentId = (0, context_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
+                // Fetch both concurrently with INDEPENDENT fail-soft: a /context
+                // failure must never cost the lessons block, and vice versa. The
+                // `## Context` block (standing context, 0.13) is prepended before
+                // `## Hicortex Lessons`, mirroring the CC hook.
+                const [contextBlock, lessonsBlock] = await Promise.all([
+                    fetchOcContextBlock(agentId).catch(() => null),
+                    buildLessonsBlock(ctx?.project).catch(() => null),
+                ]);
+                const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+                if (blocks.length === 0)
                     return {};
-                const formatted = selected.map((l) => {
-                    const titleMatch = l.content.match(/## Lesson: (.+)/);
-                    const typeMatch = l.content.match(/\*\*Type:\*\* (\w+)/);
-                    const severityMatch = l.content.match(/\*\*Severity:\*\* (\w+)/);
-                    const title = titleMatch ? titleMatch[1] : l.content.slice(0, 150);
-                    const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
-                    return `- ${title}${meta ? ` (${meta})` : ""}`;
-                });
-                const context = `\n\n## Hicortex Lessons (auto-injected from long-term memory)\n` +
-                    `These are actionable lessons learned from past sessions:\n\n` +
-                    formatted.join("\n") +
-                    "\n";
-                return { appendSystemContext: context };
+                return { appendSystemContext: `\n\n${blocks.join("\n\n")}\n` };
             }
             catch {
-                // Fail-soft — a broken lessons fetch must not block the agent
                 return {};
             }
         });

package/dist/init.d.ts

@@ -16,6 +16,13 @@
  *   - Install CC custom commands (/learn, /hicortex-activate)
  */
 import type { DomainDef } from "./types.js";
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+export declare function parseMcpListStatus(mcpListOutput: string): "connected" | "registered" | "missing";
 /**
  * Parse a KEY=VALUE env file (e.g. ~/.hermes/.env or ~/.claude/settings.json env block).
  * Handles: comments (#), quoted values, empty lines.
@@ -37,6 +44,29 @@ export declare function persistAuthToken(configPath: string): {
     token: string;
     generated: boolean;
 };
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+export declare function decideAgentName(existing: unknown, flag: string | undefined): {
+    write: boolean;
+    value: string | null;
+    clear?: boolean;
+    error?: string;
+};
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -61,6 +91,15 @@ export declare const GENERIC_DEFAULT_DOMAINS: DomainDef[];
 export declare function scaffoldDefaultDomains(configPath: string): {
     scaffolded: boolean;
 };
+/**
+ * True if a resolved binary path lives in npm's ephemeral npx cache
+ * (`~/.npm/_npx/<hash>/node_modules/.bin/…`). When `hicortex init` is itself
+ * run via `npx -y @gamaze/hicortex init`, npx prepends that cache dir to PATH,
+ * so `which hicortex` resolves there. npm garbage-collects `_npx`, so any
+ * SessionStart hook or nightly timer wired to such a path breaks silently
+ * later — the "looks configured but isn't" trap (#176). Never persist it.
+ */
+export declare function isEphemeralNpxPath(binPath: string): boolean;
 /**
  * Install (or verify) the CC SessionStart hook that runs `hicortex lessons-context`.
  * The hook fetches lessons from the configured server at session start and injects
@@ -74,6 +113,7 @@ export declare function scaffoldDefaultDomains(configPath: string): {
 export declare function installSessionStartHook(settingsPath?: string): void;
 export declare function runInit(options?: {
     serverUrl?: string;
+    agentName?: string;
 }): Promise<void>;
 /**
  * Resolve the nightly hour (0–23, local time) for the generated schedule.

package/dist/init.js

@@ -18,13 +18,17 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_DEFAULT_DOMAINS = void 0;
+exports.parseMcpListStatus = parseMcpListStatus;
 exports.parseEnvFile = parseEnvFile;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
+exports.decideAgentName = decideAgentName;
 exports.scaffoldDefaultDomains = scaffoldDefaultDomains;
+exports.isEphemeralNpxPath = isEphemeralNpxPath;
 exports.installSessionStartHook = installSessionStartHook;
 exports.runInit = runInit;
 exports.resolveNightlyHour = resolveNightlyHour;
+const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -32,7 +36,8 @@ const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
 const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
-const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+const context_store_js_1 = require("./context-store.js");
+const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -155,6 +160,54 @@ function registerCcMcp(serverUrl) {
     }
     // Add MCP tool permissions to settings.json so users don't get prompted
     allowHicortexTools();
+    // Post-install verification (finding #5): a registration that wrote files
+    // but didn't actually take can still look "done". Best-effort confirm and,
+    // either way, tell the user exactly how to check.
+    verifyCcMcp();
+}
+/**
+ * Classify `claude mcp list` output for the hicortex entry. Pure (testable):
+ *   - "missing"    — hicortex not listed → registration didn't take
+ *   - "connected"  — listed AND reachable (✓/✔/Connected shown)
+ *   - "registered" — listed but connection not confirmed (server down / not restarted)
+ */
+function parseMcpListStatus(mcpListOutput) {
+    // `claude mcp list` prints one line per server: "hicortex: <url> (SSE) - <status>".
+    // Anchor on the "hicortex:" line prefix (not a bare word match) so a
+    // differently-named MCP like "hicortex-foo" can't be mistaken for our entry,
+    // and read status from THAT line only.
+    const line = mcpListOutput.split(/\r?\n/).find((l) => /^\s*hicortex:/.test(l));
+    if (!line)
+        return "missing";
+    return /(✓|✔|connected)/i.test(line) ? "connected" : "registered";
+}
+/**
+ * Best-effort post-install check that the hicortex MCP is actually registered
+ * (and, when reachable, connected). NEVER fails init — if the claude CLI is
+ * absent (e.g. registration went via the ~/.claude.json fallback), we can't
+ * query it, so we just tell the user how to confirm. Closes the "looks
+ * configured but isn't, with no verification" gap.
+ */
+function verifyCcMcp() {
+    let out;
+    try {
+        out = (0, node_child_process_1.execSync)("claude mcp list", { encoding: "utf-8", stdio: "pipe" });
+    }
+    catch {
+        console.log("  ℹ After restarting Claude Code, confirm with `claude mcp list` (hicortex should show ✓ Connected).");
+        return;
+    }
+    switch (parseMcpListStatus(out)) {
+        case "connected":
+            console.log("  ✓ Verified: hicortex MCP registered and connected");
+            break;
+        case "registered":
+            console.log("  ✓ Verified: hicortex MCP registered — restart Claude Code, then `claude mcp list` should show it Connected");
+            break;
+        case "missing":
+            console.log("  ⚠ Could NOT confirm the hicortex MCP registration — run `claude mcp list`; if it's absent, re-run init.");
+            break;
+    }
 }
 function allowHicortexTools() {
     let settings = {};
@@ -699,6 +752,68 @@ function persistAuthToken(configPath) {
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
     return { token, generated: true };
 }
+/**
+ * Decide the per-agent context id to persist at init (#179; CC default = global,
+ * owner decision 20.07.2026). `agentName` is an explicit opt-in only — there is
+ * NO hostname default, so an install with no `--agent-name` sends no `?agent=`
+ * and shares the global context (one user = one identity across machines).
+ *
+ * Empty string == unset everywhere: `--agent-name ""` (or whitespace-only) is
+ * the explicit way to opt BACK OUT — it CLEARS any existing `agentName` key and
+ * returns to global, rather than erroring as an invalid id.
+ *  - explicit `--agent-name <non-empty>` → the sanitized flag (error if it
+ *    sanitizes to null, so a bad flag is loud rather than silently ignored);
+ *  - explicit `--agent-name ""` / whitespace-only → `clear` (remove the key);
+ *  - no flag but an existing non-empty `agentName` → keep it untouched
+ *    (non-clobber like persistAuthToken / scaffoldDefaultDomains);
+ *  - no flag, no (non-empty) existing value → do not write (global by default).
+ * Pure + exported for testability; never touches disk.
+ */
+function decideAgentName(existing, flag) {
+    if (flag !== undefined) {
+        // Explicit empty / whitespace-only value → clear back to global (unset).
+        if (flag.trim() === "")
+            return { write: false, value: null, clear: true };
+        const s = (0, context_store_js_1.sanitizeAgentId)(flag);
+        if (s === null) {
+            return {
+                write: false,
+                value: null,
+                error: `Invalid --agent-name '${flag}'. Must contain letters or digits and sanitize to ^[a-z0-9][a-z0-9_-]*$ (max 64 chars). Pass --agent-name "" to clear it (global context).`,
+            };
+        }
+        return { write: true, value: s };
+    }
+    if (typeof existing === "string" && existing.trim().length > 0)
+        return { write: false, value: existing };
+    return { write: false, value: null };
+}
+/** Read config.json, set agentName, write it back. Used by the server path. */
+function writeAgentNameConfig(configPath, value) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch { /* new / unreadable → start fresh */ }
+    config.agentName = value;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
+/** Read config.json, delete any `agentName` key, write it back (server path). */
+function clearAgentNameConfig(configPath) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch {
+        return; /* new / unreadable → nothing to clear */
+    }
+    if (!("agentName" in config))
+        return;
+    delete config.agentName;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+}
 /**
  * Generic default memory domains scaffolded by server-mode init (issue #150).
  * Deliberately broad, high-level spheres — an editable STARTING POINT, not a
@@ -789,16 +904,31 @@ function findNpxPath() {
         return "/usr/local/bin/npx";
     }
 }
+/**
+ * True if a resolved binary path lives in npm's ephemeral npx cache
+ * (`~/.npm/_npx/<hash>/node_modules/.bin/…`). When `hicortex init` is itself
+ * run via `npx -y @gamaze/hicortex init`, npx prepends that cache dir to PATH,
+ * so `which hicortex` resolves there. npm garbage-collects `_npx`, so any
+ * SessionStart hook or nightly timer wired to such a path breaks silently
+ * later — the "looks configured but isn't" trap (#176). Never persist it.
+ */
+function isEphemeralNpxPath(binPath) {
+    return binPath.includes("/_npx/");
+}
 /**
  * Resolve the absolute path of the hicortex binary.
  * For global npm installs (e.g. /usr/bin/hicortex) this is the binary itself.
  * For dev/npx installs, falls back to `npx <packageSpec> <command>` form.
  * Returns an array: [binaryPath] for global, or [npxPath, "-y", packageSpec] for npx.
+ *
+ * A `which hicortex` hit inside the npx cache (#176) is REJECTED — it is
+ * ephemeral, so we emit the durable `npx -y <spec>` form instead. This is the
+ * standard client path (`npx … init`), where the fix matters most.
  */
 function resolveBinaryArgs() {
     try {
         const bin = (0, node_child_process_1.execSync)("which hicortex", { encoding: "utf-8" }).trim();
-        if (bin)
+        if (bin && !isEphemeralNpxPath(bin))
             return [bin];
     }
     catch { /* not in PATH as a global binary */ }
@@ -977,7 +1107,7 @@ async function ask(question) {
 // ---------------------------------------------------------------------------
 async function runInit(options = {}) {
     if (options.serverUrl) {
-        await runClientInit(options.serverUrl);
+        await runClientInit(options.serverUrl, options.agentName);
         return;
     }
     console.log("Hicortex — Setup for Claude Code\n");
@@ -1059,6 +1189,25 @@ async function runInit(options = {}) {
     // Classification activates automatically once an LLM is configured; until
     // then domains sit inert (strict-skip path).
     scaffoldDefaultDomains(configPath);
+    // Per-agent context id (#179): server mode writes it ONLY when the operator
+    // passes --agent-name. Without the flag no agentName is written and the
+    // co-located CC shares the global context (global by default). Explicit flag
+    // overwrites on re-init; `--agent-name ""` clears it back to global.
+    if (options.agentName !== undefined) {
+        const decision = decideAgentName(undefined, options.agentName);
+        if (decision.error) {
+            console.error(`  ✗ ${decision.error}`);
+            process.exit(1);
+        }
+        if (decision.clear) {
+            clearAgentNameConfig(configPath);
+            console.log("  ✓ Agent name cleared — global context");
+        }
+        else if (decision.write && decision.value) {
+            writeAgentNameConfig(configPath, decision.value);
+            console.log(`  ✓ Agent name set to '${decision.value}'`);
+        }
+    }
     // Install the nightly job (capture via localhost /distill + consolidation).
     // Without it a server-mode install never captures or consolidates — the
     // daemon only serves recall + /distill. Skips if a schedule already exists.
@@ -1120,7 +1269,7 @@ async function runInit(options = {}) {
 // ---------------------------------------------------------------------------
 // Client Mode Init
 // ---------------------------------------------------------------------------
-async function runClientInit(serverUrl) {
+async function runClientInit(serverUrl, agentName) {
     console.log("Hicortex — Client Mode Setup\n");
     serverUrl = serverUrl.replace(/\/+$/, "");
     // Step 1: Verify server is reachable
@@ -1199,8 +1348,30 @@ async function runClientInit(serverUrl) {
     config.serverUrl = serverUrl;
     if (authToken)
         config.authToken = authToken;
+    // Per-agent context id (#179): explicit opt-in only. Written ONLY when
+    // --agent-name is passed; otherwise no agentName is set and the client shares
+    // the global context (global by default). Re-init keeps an existing value
+    // unless --agent-name is explicit; `--agent-name ""` clears it back to global.
+    const nameDecision = decideAgentName(config.agentName, agentName);
+    if (nameDecision.error) {
+        console.error(`  ✗ ${nameDecision.error}`);
+        process.exit(1);
+    }
+    if (nameDecision.clear) {
+        delete config.agentName;
+        console.log("  ✓ Agent name cleared — global context");
+    }
+    else if (nameDecision.write && nameDecision.value) {
+        config.agentName = nameDecision.value;
+        if (agentName && nameDecision.value !== agentName) {
+            console.log(`  ℹ Agent name sanitized to '${nameDecision.value}'`);
+        }
+    }
     saveConfig(configPath, config);
     console.log(`  ✓ Client config saved to ${configPath}`);
+    if (typeof config.agentName === "string") {
+        console.log(`  ✓ Agent name: ${config.agentName}`);
+    }
     // Step 4: Register CC MCP pointing to remote server
     if (authToken) {
         // Write directly with auth header

package/dist/lessons-context.d.ts

@@ -21,6 +21,62 @@
  * parse error) results in silent exit-0. A broken hook must never block a
  * CC session, and a broken /context fetch must never blank the whole output.
  */
+/**
+ * The GET /context response shape, shared by the CC hook and the OC plugin so
+ * their gating cannot drift. `agent`/`mode` are echoed by a 0.13 server whenever
+ * `?agent=` was sent (in EVERY mode); a pre-0.13 server omits them.
+ */
+export interface ContextResponse {
+    sections?: Record<string, string>;
+    updated_at?: string;
+    clients?: string[];
+    agent?: string;
+    mode?: string;
+}
+/**
+ * Title-case a section name for its heading: split on `-`/`_`, capitalize each
+ * word ("user" → "User", "my_notes" → "My Notes").
+ * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * identically to the CC hook rather than duplicating the logic.
+ */
+export declare function titleCaseSection(name: string): string;
+/**
+ * Stable section ordering: `user` first, then `rules` (the seeded primary
+ * sections, spec §8), then every other section alphabetically. Server-side
+ * enumeration order (readdirSync) is FS-dependent, so we sort here for a
+ * deterministic injection block. Exported for reuse by the OC plugin.
+ */
+export declare function orderSectionNames(names: string[]): string[];
+/**
+ * Render the `## Context` block from a resolved section map, or null when there
+ * is nothing to inject (no sections, or every section blank after trimming).
+ * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
+ * both harnesses emit an identical block. Sections are ordered (user, rules,
+ * then alphabetical) and rendered under title-cased `###` headings.
+ */
+export declare function renderContextBlock(sections: Record<string, string>): string | null;
+/**
+ * Gate a GET /context response and render the `## Context` block, or null when
+ * nothing should be injected: `harness` not in the server-resolved `clients`,
+ * an empty/blank section set, or — when `requireAgentEcho` — a response that
+ * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
+ * never drift (the Python Hermes plugin `provider.py::_context_block` mirrors
+ * this logic — keep them in sync).
+ *
+ * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
+ *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     into every persona; on a bare fetch (no id) the guard is off (amendment
+ *     A2).
+ *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
+ *     client auto-upgrades via npx BEFORE bedrock does, so during the upgrade
+ *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
+ *     global IS the operator's intended state there, and a guard would instead
+ *     blank ALL context for every CC session in that window.
+ */
+export declare function gateAndRenderContext(data: ContextResponse, harness: string, opts: {
+    requireAgentEcho: boolean;
+}): string | null;
 /**
  * Fetch context + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints