@gamaze/hicortex 0.17.6 → 0.18.1

package/dist/learnings-identity.d.ts

@@ -0,0 +1,149 @@
+/**
+ * learnings-identity — query-time identity + lessons injection for the CC
+ * SessionStart hook. (Canonical command name `learnings-identity` since #264;
+ * the legacy `lessons-context` subcommand is kept as a backcompat alias via
+ * resolveCommandAlias so existing installed hooks keep working. Fetches the
+ * identity layer + the lessons block.)
+ *
+ * Replaces file-based injection (injectLessons / injectLessonsFromServer).
+ * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
+ * endpoints concurrently and prints a compact Markdown block to stdout so CC
+ * picks it up as session context:
+ *
+ *   GET /identity → the standing identity layer (user info + rules; 0.12,
+ *                   renamed from /context in 0.18 #264). Injected as a
+ *                   `## Identity` block ONLY when this harness ("cc") is in
+ *                   the server-resolved `clients` list (self-gate).
+ *   GET /lessons  → episodic memory lessons + memory index, rendered as the
+ *                   existing `## Hicortex Memory` block.
+ *
+ * The two fetches run in Promise.all, each with its OWN 3 s timeout and
+ * INDEPENDENT fail-soft: an /identity failure must never cost the lessons
+ * block, and vice versa. Sequential fetches would double worst-case
+ * SessionStart latency (~6 s) — see spec §7.
+ *
+ * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
+ * parse error) results in silent exit-0. A broken hook must never block a
+ * CC session, and a broken /identity fetch must never blank the whole output.
+ */
+import { type AgentMode } from "./identity-store.js";
+/**
+ * The GET /identity 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 IdentityResponse {
+    sections?: Record<string, string>;
+    updated_at?: string;
+    clients?: string[];
+    agent?: string;
+    mode?: string;
+}
+export interface ResolvedConfig {
+    serverUrl: string;
+    authToken: string | undefined;
+    home: string;
+    /** Per-agent identity id sent as ?agent= (0.13); null → global (no param). */
+    agentName: string | null;
+    /** Max lessons to inject (config.lessonsLimit, default 10). */
+    lessonsLimit?: number;
+}
+/**
+ * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
+ * null when there is no usable config (server not set up yet — fail soft).
+ * Exported for reuse by the recall-hook CLI (#192) so the two CC hooks can
+ * never resolve the server differently.
+ */
+export declare function resolveConfig(): ResolvedConfig | null;
+/**
+ * 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 `## Identity` 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 `## Identity` 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 renderIdentityBlock(sections: Record<string, string>): string | null;
+/**
+ * Gate a GET /identity response and render the `## Identity` 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 identity
+ *     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 the server 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 identity for every CC session in that window.
+ */
+/**
+ * Result of `buildIdentityToolResult` — the MCP tool handler maps this to its
+ * `{content:[{type:"text",text}],isError?}` shape. Pure value: no MCP SDK
+ * types leak here so the function is unit-testable with no harness.
+ */
+export interface IdentityToolResult {
+    text: string;
+    isError?: boolean;
+}
+/**
+ * Build the `hicortex_identity` MCP tool result from the SAME pure pipeline the
+ * REST `GET /identity` route and the SessionStart hook use (#264 CRITICAL fix:
+ * previously the tool was a closure inside `createMcpServer()` that tests
+ * re-implemented locally, so the production path was never exercised).
+ *
+ * Pipeline (kept identical to REST + hook by CONSTRUCTION, not by mirroring):
+ *  1. `handleIdentityGet` — the real GET /identity handler, with the optional
+ *     `agent` param forwarded so per-agent installs resolve the right scope
+ *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
+ *     with an override saw the wrong identity).
+ *  2. `injectMemorySection` — the synthetic product-owned `memory` section
+ *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
+ *     not, contradicting its "same data" docs).
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *     markdown the hook injects.
+ *
+ * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
+ * identity dir, which is the same I/O the REST route does). Takes the resolved
+ * `identityClients` / `identityAgents` the daemon already holds at boot.
+ */
+export declare function buildIdentityToolResult(identityDir: string, identityClients: string[], identityAgents: Record<string, AgentMode>, opts: {
+    name?: string;
+    agent?: string;
+    memoryInstructionsEnabled: boolean;
+}): IdentityToolResult;
+export declare function gateAndRenderIdentity(data: IdentityResponse, harness: string, opts: {
+    requireAgentEcho: boolean;
+}): string | null;
+/**
+ * Fetch identity + lessons concurrently and return the combined Markdown block,
+ * or null when neither yields anything (nothing to inject; caller prints
+ * nothing and exits 0). The `## Identity` block is prepended before the existing
+ * `## Hicortex Memory` block.
+ */
+export declare function fetchLessonsIdentity(): Promise<string | null>;
+/** Backcompat alias (#264). */
+export declare const fetchLessonsContext: typeof fetchLessonsIdentity;
+/** Backcompat aliases (#264) for the renamed symbols. */
+export declare const renderContextBlock: typeof renderIdentityBlock;
+export declare const gateAndRenderContext: typeof gateAndRenderIdentity;
+export type ContextResponse = IdentityResponse;

package/dist/{lessons-context.js → learnings-identity.js}

@@ -1,43 +1,51 @@
 "use strict";
 /**
- * lessons-context — query-time context injection for the CC SessionStart hook.
+ * learnings-identity — query-time identity + lessons injection for the CC
+ * SessionStart hook. (Canonical command name `learnings-identity` since #264;
+ * the legacy `lessons-context` subcommand is kept as a backcompat alias via
+ * resolveCommandAlias so existing installed hooks keep working. Fetches the
+ * identity layer + the lessons block.)
  *
  * Replaces file-based injection (injectLessons / injectLessonsFromServer).
  * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
  * endpoints concurrently and prints a compact Markdown block to stdout so CC
  * picks it up as session context:
  *
- *   GET /context  → the standing context layer (user info + rules; 0.12).
- *                   Injected as a `## Context` block ONLY when this harness
- *                   ("cc") is in the server-resolved `clients` list (self-gate).
+ *   GET /identity → the standing identity layer (user info + rules; 0.12,
+ *                   renamed from /context in 0.18 #264). Injected as a
+ *                   `## Identity` block ONLY when this harness ("cc") is in
+ *                   the server-resolved `clients` list (self-gate).
  *   GET /lessons  → episodic memory lessons + memory index, rendered as the
  *                   existing `## Hicortex Memory` block.
  *
  * The two fetches run in Promise.all, each with its OWN 3 s timeout and
- * INDEPENDENT fail-soft: a /context failure must never cost the lessons block,
- * and vice versa. Sequential fetches would double worst-case SessionStart
- * latency (~6 s) — see spec §7.
+ * INDEPENDENT fail-soft: an /identity failure must never cost the lessons
+ * block, and vice versa. Sequential fetches would double worst-case
+ * SessionStart latency (~6 s) — see spec §7.
  *
  * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
  * 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.
+ * CC session, and a broken /identity fetch must never blank the whole output.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateAndRenderContext = exports.renderContextBlock = exports.fetchLessonsContext = void 0;
 exports.resolveConfig = resolveConfig;
 exports.titleCaseSection = titleCaseSection;
 exports.orderSectionNames = orderSectionNames;
-exports.renderContextBlock = renderContextBlock;
-exports.gateAndRenderContext = gateAndRenderContext;
-exports.fetchLessonsContext = fetchLessonsContext;
+exports.renderIdentityBlock = renderIdentityBlock;
+exports.buildIdentityToolResult = buildIdentityToolResult;
+exports.gateAndRenderIdentity = gateAndRenderIdentity;
+exports.fetchLessonsIdentity = fetchLessonsIdentity;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
+const memory_instructions_js_1 = require("./memory-instructions.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
 const paths_js_1 = require("./paths.js");
 const DEFAULT_PORT = 8787;
-/** Harness name this hook injects for — used to self-gate on GET /context `clients`. */
+/** Harness name this hook injects for — used to self-gate on GET /identity `clients`. */
 const THIS_HARNESS = "cc";
 /**
  * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
@@ -58,12 +66,12 @@ function resolveConfig() {
     const serverUrl = config.mode === "client" && typeof config.serverUrl === "string"
         ? config.serverUrl.replace(/\/+$/, "")
         : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
-    // Per-agent context id (0.13) via the shared resolver, so the id sent here
+    // Per-agent identity id (0.13) via the shared resolver, so the id sent here
     // always matches what `hicortex status` reports. No configured agentName →
     // agentId null → NO ?agent= (bare fetch): CC's default is the shared global
-    // context. A configured agentName that sanitizes to null → agentId null too
+    // identity. A configured agentName that sanitizes to null → agentId null too
     // (NO ?agent=), never a 400 that the fail-soft hook would silently swallow.
-    const agentName = (0, context_store_js_1.resolveAgentIdentity)(config).agentId;
+    const agentName = (0, identity_store_js_1.resolveAgentIdentity)(config).agentId;
     return {
         serverUrl,
         authToken: config.authToken,
@@ -133,7 +141,7 @@ async function fetchLessonsBlock(cfg) {
 /**
  * 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
+ * Exported so the OC plugin (index.ts) renders the `## Identity` block
  * identically to the CC hook rather than duplicating the logic.
  */
 function titleCaseSection(name) {
@@ -155,13 +163,13 @@ function orderSectionNames(names) {
     return [...primaries, ...rest];
 }
 /**
- * Render the `## Context` block from a resolved section map, or null when there
+ * Render the `## Identity` 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.
  */
-function renderContextBlock(sections) {
+function renderIdentityBlock(sections) {
     if (!sections || typeof sections !== "object" || Array.isArray(sections))
         return null;
     const names = orderSectionNames(Object.keys(sections));
@@ -174,28 +182,59 @@ function renderContextBlock(sections) {
     }
     if (bodyParts.length === 0)
         return null;
-    return ["## Context", "", ...bodyParts].join("\n");
+    return ["## Identity", "", ...bodyParts].join("\n");
 }
 /**
- * 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).
+ * Build the `hicortex_identity` MCP tool result from the SAME pure pipeline the
+ * REST `GET /identity` route and the SessionStart hook use (#264 CRITICAL fix:
+ * previously the tool was a closure inside `createMcpServer()` that tests
+ * re-implemented locally, so the production path was never exercised).
  *
- * `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 the server 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.
+ * Pipeline (kept identical to REST + hook by CONSTRUCTION, not by mirroring):
+ *  1. `handleIdentityGet` — the real GET /identity handler, with the optional
+ *     `agent` param forwarded so per-agent installs resolve the right scope
+ *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
+ *     with an override saw the wrong identity).
+ *  2. `injectMemorySection` — the synthetic product-owned `memory` section
+ *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
+ *     not, contradicting its "same data" docs).
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *     markdown the hook injects.
+ *
+ * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
+ * identity dir, which is the same I/O the REST route does). Takes the resolved
+ * `identityClients` / `identityAgents` the daemon already holds at boot.
  */
-function gateAndRenderContext(data, harness, opts) {
+function buildIdentityToolResult(identityDir, identityClients, identityAgents, opts) {
+    // WARNING-2: forward `agent` so per-agent installs resolve the right scope.
+    // An invalid id makes handleIdentityGet return a 400 → surfaced as isError.
+    const query = opts.agent ? { agent: opts.agent } : {};
+    const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, query, identityAgents);
+    if (r.status !== 200) {
+        const errBody = r.body;
+        return {
+            text: `Identity fetch failed: ${JSON.stringify(errBody.error ?? r.body)}`,
+            isError: true,
+        };
+    }
+    // WARNING-1: inject the synthetic `memory` section exactly like REST + the
+    // SessionStart hook. `injectMemorySection` is a no-op when disabled or when
+    // agent mode === "off".
+    (0, memory_instructions_js_1.injectMemorySection)(r.body, opts.memoryInstructionsEnabled);
+    const sections = r.body.sections ?? {};
+    const filtered = opts.name
+        ? (sections[opts.name] !== undefined ? { [opts.name]: sections[opts.name] } : {})
+        : sections;
+    const block = renderIdentityBlock(filtered);
+    if (block === null) {
+        const text = opts.name
+            ? `No identity section named '${opts.name}'.`
+            : "No identity sections configured.";
+        return { text };
+    }
+    return { text: block };
+}
+function gateAndRenderIdentity(data, harness, opts) {
     if (!data || typeof data !== "object")
         return null;
     const clients = Array.isArray(data.clients) ? data.clients : [];
@@ -203,21 +242,21 @@ function gateAndRenderContext(data, harness, opts) {
         return null;
     if (opts.requireAgentEcho && typeof data.agent !== "string")
         return null;
-    return renderContextBlock(data.sections ?? {});
+    return renderIdentityBlock(data.sections ?? {});
 }
 /**
- * Fetch /context and build the `## Context` block, or null when nothing should
+ * Fetch /identity and build the `## Identity` block, or null when nothing should
  * be injected: non-2xx, this harness not in `clients`, no sections, or all
  * sections empty. Throws propagate to the caller's fail-soft catch.
  */
-async function fetchContextBlock(cfg) {
+async function fetchIdentityBlock(cfg) {
     // Send ?agent= only when we have a valid id; the server does the merge and
     // returns the resolved sections, so the hook stays dumb (no client-side mode
     // logic). A null id (CC's default: no configured agentName, or a configured
-    // value that sanitizes to nothing) → bare /context → the shared global set.
+    // value that sanitizes to nothing) → bare /identity → the shared global set.
     const url = cfg.agentName
-        ? `${cfg.serverUrl}/context?agent=${encodeURIComponent(cfg.agentName)}`
-        : `${cfg.serverUrl}/context`;
+        ? `${cfg.serverUrl}/identity?agent=${encodeURIComponent(cfg.agentName)}`
+        : `${cfg.serverUrl}/identity`;
     const resp = await fetch(url, {
         headers: authHeaders(cfg.authToken),
         signal: AbortSignal.timeout(3000),
@@ -227,30 +266,35 @@ async function fetchContextBlock(cfg) {
     const data = await resp.json();
     // CC deliberately passes requireAgentEcho: false (NOT the OC/Hermes old-server
     // guard). A thin CC client auto-upgrades via npx BEFORE the server does, so
-    // mid-upgrade it may hit a 0.12 server that returns global context with no
+    // mid-upgrade it may hit a 0.12 server that returns global identity with no
     // `agent` echo — and a 0.12 server cannot hold per-agent config, so global is
-    // the intended state. Guarding here would blank ALL CC context in that window.
-    return gateAndRenderContext(data, THIS_HARNESS, { requireAgentEcho: false });
+    // the intended state. Guarding here would blank ALL CC identity in that window.
+    return gateAndRenderIdentity(data, THIS_HARNESS, { requireAgentEcho: false });
 }
 /**
- * Fetch context + lessons concurrently and return the combined Markdown block,
+ * Fetch identity + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints
- * nothing and exits 0). The `## Context` block is prepended before the existing
+ * nothing and exits 0). The `## Identity` block is prepended before the existing
  * `## Hicortex Memory` block.
  */
-async function fetchLessonsContext() {
+async function fetchLessonsIdentity() {
     const cfg = resolveConfig();
     if (!cfg)
         return null;
     // Independent fail-soft: each branch degrades to null without affecting the
     // other. Promise.all runs them concurrently — each carries its own 3 s
     // timeout, so worst-case latency stays ~3 s, not ~6 s (spec §7).
-    const [contextBlock, lessonsBlock] = await Promise.all([
-        fetchContextBlock(cfg).catch(() => null),
+    const [identityBlock, lessonsBlock] = await Promise.all([
+        fetchIdentityBlock(cfg).catch(() => null),
         fetchLessonsBlock(cfg).catch(() => null),
     ]);
-    const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+    const blocks = [identityBlock, lessonsBlock].filter((b) => b !== null && b !== "");
     if (blocks.length === 0)
         return null;
     return blocks.join("\n\n");
 }
+/** Backcompat alias (#264). */
+exports.fetchLessonsContext = fetchLessonsIdentity;
+/** Backcompat aliases (#264) for the renamed symbols. */
+exports.renderContextBlock = renderIdentityBlock;
+exports.gateAndRenderContext = gateAndRenderIdentity;

package/dist/mcp-server.d.ts

@@ -10,9 +10,11 @@
  *   GET  /sse        — SSE stream for MCP clients
  *   POST /messages   — message endpoint for MCP clients
  */
+import type { MemorySearchResult } from "./types.js";
 export declare function startServer(options?: {
     port?: number;
     host?: string;
     dbPath?: string;
     licenseKey?: string;
 }): Promise<void>;
+export declare function formatResults(results: MemorySearchResult[]): string;