@aliyunrds/ctxdb 0.0.9 → 0.0.10

package/dist/opencode/src/capture.ts

@@ -0,0 +1,187 @@
+// Capture path: read transcript via SDK → convert to ParsedMessage[] →
+// run shared B-rule filtering / slicing → fingerprint dedup → POST to
+// /v3/memories/add/.
+//
+// The hook layer wraps this and never throws; this module raises only
+// when the SDK explicitly throws (we set throwOnError: true so 404/500
+// surface as exceptions for the caller's stderr-log path).
+
+import { createHash } from "node:crypto";
+import {
+  filterMessagesForExtraction,
+  selectTurnMessages,
+  type ParsedMessage,
+} from "@aliyunrds/ctxdb-shared";
+import type { Message, Part } from "@opencode-ai/sdk";
+import type { OpencodeConfig } from "./config.ts";
+import type { HttpClient } from "./http-client.ts";
+
+export interface SDKMessage {
+  info: Message;
+  parts: Part[];
+}
+
+export interface CaptureOutcome {
+  captured: boolean;
+  reason: string;
+  messageCount: number;
+  fingerprint: string | null;
+  serverResponse?: unknown;
+}
+
+const EMPTY: CaptureOutcome = {
+  captured: false,
+  reason: "",
+  messageCount: 0,
+  fingerprint: null,
+};
+
+/**
+ * Convert SDK `messages()` response into ctxdb-shared's ParsedMessage
+ * format. Only keeps text parts (skips synthetic/ignored), concatenates
+ * multiple text parts in a single message into one content string.
+ *
+ * `index` is the original index in the input array; `isSummary` is true
+ * for assistant messages that the SDK marked summary === true (these
+ * get filtered out by the shared turn-selection logic).
+ */
+export function toParsedMessages(messages: unknown[]): ParsedMessage[] {
+  const parsed: ParsedMessage[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    const converted = toParsedMessage(m, i);
+    if (converted) parsed.push(converted);
+  }
+  return parsed;
+}
+
+export function unwrapSessionMessagesResponse(resp: unknown): unknown[] {
+  if (Array.isArray(resp)) return resp;
+  if (!resp || typeof resp !== "object") return [];
+  const root = resp as Record<string, unknown>;
+  if (Array.isArray(root.data)) return root.data;
+  if (root.data && typeof root.data === "object") {
+    const nested = root.data as Record<string, unknown>;
+    if (Array.isArray(nested.data)) return nested.data;
+  }
+  if (Array.isArray(root.messages)) return root.messages;
+  return [];
+}
+
+function toParsedMessage(m: unknown, index: number): ParsedMessage | null {
+  if (!m || typeof m !== "object") return null;
+  const obj = m as Record<string, unknown>;
+
+  if (obj.info && typeof obj.info === "object" && Array.isArray(obj.parts)) {
+    const info = obj.info as { role?: unknown; summary?: unknown };
+    const role = info.role;
+    if (role !== "user" && role !== "assistant") return null;
+    const textChunks: string[] = [];
+    for (const rawPart of obj.parts) {
+      if (!rawPart || typeof rawPart !== "object") continue;
+      const p = rawPart as { type?: unknown; synthetic?: unknown; ignored?: unknown; text?: unknown };
+      if (p.type !== "text") continue;
+      if (p.synthetic === true || p.ignored === true) continue;
+      if (typeof p.text === "string" && p.text) textChunks.push(p.text);
+    }
+    const content = textChunks.join("\n").trim();
+    if (!content) return null;
+    const isSummary =
+      role === "assistant" && info.summary === true;
+    return { role, content, index, isSummary };
+  }
+
+  if (obj.type === "user") {
+    const content = typeof obj.text === "string" ? obj.text.trim() : "";
+    return content ? { role: "user", content, index, isSummary: false } : null;
+  }
+
+  if (obj.type === "assistant" && Array.isArray(obj.content)) {
+    const textChunks: string[] = [];
+    for (const rawPart of obj.content) {
+      if (!rawPart || typeof rawPart !== "object") continue;
+      const p = rawPart as { type?: unknown; text?: unknown };
+      if (p.type === "text" && typeof p.text === "string" && p.text) {
+        textChunks.push(p.text);
+      }
+    }
+    const content = textChunks.join("\n").trim();
+    return content ? { role: "assistant", content, index, isSummary: false } : null;
+  }
+
+  return null;
+}
+
+export function fingerprintMessages(messages: { role: string; content: string }[]): string {
+  const h = createHash("sha256");
+  for (const m of messages) {
+    h.update(m.role);
+    h.update("\u0000");
+    h.update(m.content);
+    h.update("\u0001");
+  }
+  return h.digest("hex");
+}
+
+/**
+ * Run the full capture pipeline given a transcript already fetched from
+ * the SDK. Returns `captured: true` only when the POST to
+ * /v3/memories/add/ succeeds. Dedup is the caller's job (compare
+ * `fingerprint` against last successful capture for this session).
+ */
+export async function runCapture(
+  messages: unknown[],
+  cfg: OpencodeConfig,
+  client: HttpClient,
+  timeoutMs: number,
+  lastFingerprint: string | null,
+): Promise<CaptureOutcome> {
+  if (!cfg.autoCapture) return { ...EMPTY, reason: "auto_capture_disabled" };
+  if (!cfg.baseUrl) return { ...EMPTY, reason: "config_incomplete" };
+  if (messages.length === 0) return { ...EMPTY, reason: "empty_transcript" };
+
+  const parsed = toParsedMessages(messages);
+  if (parsed.length === 0) return { ...EMPTY, reason: "transcript_no_text_parts" };
+
+  const turn = selectTurnMessages(parsed);
+  if (turn.length === 0) return { ...EMPTY, reason: "empty_turn_slice" };
+  if (!turn.some((m) => m.role === "user")) return { ...EMPTY, reason: "no_user_in_turn" };
+  if (!turn.some((m) => m.role === "assistant")) {
+    return { ...EMPTY, reason: "no_assistant_in_turn" };
+  }
+
+  const raw = turn.map((m) => ({ role: m.role, content: m.content }));
+  const filtered = filterMessagesForExtraction(raw);
+  if (filtered.length === 0) return { ...EMPTY, reason: "all_filtered" };
+
+  const fingerprint = fingerprintMessages(filtered);
+  if (fingerprint === lastFingerprint) {
+    return { ...EMPTY, reason: "duplicate_fingerprint", fingerprint };
+  }
+
+  const payload = {
+    messages: filtered,
+    user_id: cfg.userId,
+    async_mode: true,
+  };
+
+  let resp: unknown;
+  try {
+    resp = await client.postJson("/v3/memories/add/", payload, { timeoutMs });
+  } catch (err) {
+    return {
+      ...EMPTY,
+      reason: `http_error: ${(err as Error).message}`,
+      messageCount: filtered.length,
+      fingerprint,
+    };
+  }
+
+  return {
+    captured: true,
+    reason: "ok",
+    messageCount: filtered.length,
+    fingerprint,
+    serverResponse: resp,
+  };
+}

package/dist/opencode/src/config.ts

@@ -0,0 +1,160 @@
+// Read-only loader for `~/.ctxdb/ctxdb.json` `agents.opencode` section.
+//
+// The plugin never writes config — `ctxdb setup --agent opencode` is the
+// sole writer (via the ctxdb package's lib/config.ts). This file mirrors
+// just enough of that schema to drive the in-process hooks, with the same
+// CTXDB_* env-var precedence as other agent integrations.
+//
+// Schema reminder (v2):
+//   { version: 2, agents: { opencode: { base_url, auto_recall, ... } } }
+// Anything else (missing file, missing section, malformed JSON) → defaults,
+// but the plugin is considered disabled until an API key is present via
+// agents.opencode.api_key or CTXDB_API_KEY.
+
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_BASE_URL = "https://context-database.aliyuncs.com";
+export const DEFAULT_USER_ID = "default";
+export const DEFAULT_TOP_K = 5;
+export const DEFAULT_THRESHOLD = 0.4;
+export const DEFAULT_KNOWLEDGE_TOP_K = 6;
+
+export type KbCatalogInjection = "session_start" | "user_prompt_submit" | "off";
+export const DEFAULT_KB_CATALOG_INJECTION: KbCatalogInjection = "session_start";
+
+export interface OpencodeConfig {
+  apiKey: string | null;
+  baseUrl: string;
+  userId: string;
+  autoCapture: boolean;
+  autoRecall: boolean;
+  warmupRecall: boolean;
+  recallKnowledge: boolean;
+  topK: number;
+  threshold: number;
+  knowledgeTopK: number;
+  debug: boolean;
+  kbCatalogInjection: KbCatalogInjection;
+}
+
+export interface LoadOptions {
+  path?: string;
+  env?: Record<string, string | undefined>;
+}
+
+type RawObject = Record<string, unknown>;
+
+function defaultPath(env: Record<string, string | undefined>): string {
+  if (env.CTXDB_CONFIG_PATH) return env.CTXDB_CONFIG_PATH;
+  return join(homedir(), ".ctxdb", "ctxdb.json");
+}
+
+function makeDefault(): OpencodeConfig {
+  return {
+    apiKey: null,
+    baseUrl: DEFAULT_BASE_URL,
+    userId: DEFAULT_USER_ID,
+    autoCapture: true,
+    autoRecall: true,
+    warmupRecall: true,
+    recallKnowledge: false,
+    topK: DEFAULT_TOP_K,
+    threshold: DEFAULT_THRESHOLD,
+    knowledgeTopK: DEFAULT_KNOWLEDGE_TOP_K,
+    debug: false,
+    kbCatalogInjection: DEFAULT_KB_CATALOG_INJECTION,
+  };
+}
+
+function coerceInt(v: unknown, fallback: number): number {
+  if (v === null || v === undefined || v === "") return fallback;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? Math.trunc(n) : fallback;
+}
+
+function coerceFloat(v: unknown, fallback: number): number {
+  if (v === null || v === undefined || v === "") return fallback;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function coerceBool(v: unknown, fallback: boolean): boolean {
+  if (typeof v === "boolean") return v;
+  if (v === undefined || v === null) return fallback;
+  return Boolean(v);
+}
+
+function coerceKbCatalogInjection(v: unknown): KbCatalogInjection {
+  if (v === "session_start" || v === "user_prompt_submit" || v === "off") return v;
+  return DEFAULT_KB_CATALOG_INJECTION;
+}
+
+function readRaw(path: string): RawObject {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as RawObject;
+    }
+  } catch {
+    // malformed → defaults
+  }
+  return {};
+}
+
+function agentRaw(raw: RawObject): RawObject {
+  if (!(raw.version === 2)) return {};
+  const agents = raw.agents;
+  if (!agents || typeof agents !== "object" || Array.isArray(agents)) return {};
+  const section = (agents as RawObject).opencode;
+  if (!section || typeof section !== "object" || Array.isArray(section)) return {};
+  return section as RawObject;
+}
+
+function applyEnv(cfg: OpencodeConfig, env: Record<string, string | undefined>): OpencodeConfig {
+  if (env.CTXDB_API_KEY) cfg.apiKey = env.CTXDB_API_KEY;
+  if (env.CTXDB_BASE_URL) cfg.baseUrl = env.CTXDB_BASE_URL.replace(/\/+$/, "");
+  if (env.CTXDB_USER_ID) cfg.userId = env.CTXDB_USER_ID;
+  return cfg;
+}
+
+export function loadOpencodeConfig(options: LoadOptions = {}): OpencodeConfig {
+  const env = options.env ?? process.env;
+  const path = options.path ?? defaultPath(env);
+  const raw = readRaw(path);
+  const section = agentRaw(raw);
+
+  const cfg: OpencodeConfig = {
+    apiKey:
+      typeof section.api_key === "string" && section.api_key ? section.api_key : null,
+    baseUrl:
+      typeof section.base_url === "string" && section.base_url
+        ? String(section.base_url).replace(/\/+$/, "")
+        : DEFAULT_BASE_URL,
+    userId:
+      typeof section.user_id === "string" && section.user_id
+        ? section.user_id
+        : DEFAULT_USER_ID,
+    autoCapture: coerceBool(section.auto_capture, true),
+    autoRecall: coerceBool(section.auto_recall, true),
+    warmupRecall: coerceBool(section.warmup_recall, true),
+    recallKnowledge: coerceBool(section.recall_knowledge, false),
+    topK: coerceInt(section.top_k, DEFAULT_TOP_K),
+    threshold: coerceFloat(section.threshold, DEFAULT_THRESHOLD),
+    knowledgeTopK: coerceInt(section.knowledge_top_k, DEFAULT_KNOWLEDGE_TOP_K),
+    debug: coerceBool(section.debug, false),
+    kbCatalogInjection: coerceKbCatalogInjection(section.kb_catalog_injection),
+  };
+
+  return applyEnv(cfg, env);
+}
+
+export function isConfigured(cfg: OpencodeConfig): boolean {
+  return Boolean(cfg.apiKey && cfg.baseUrl);
+}
+
+export function makeDefaultConfig(): OpencodeConfig {
+  return makeDefault();
+}

package/dist/opencode/src/hooks.ts

@@ -0,0 +1,252 @@
+// Plugin hooks: chat.message (prompt capture), system.transform (recall +
+// KB injection), event (session.idle → capture). All three share state
+// via the per-plugin-instance sessionState map.
+//
+// State eviction:
+//   - TTL 15 min: any session entry older than that is dropped on touch
+//   - LRU max 100: keep memory bounded across long-running OpenCode runs
+//
+// Failure policy: every hook handler wraps its work in try/catch and
+// resolves normally on any error. Debug logs go to stderr only when
+// agents.opencode.debug is true; nothing is rethrown.
+
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+import type { Part } from "@opencode-ai/sdk";
+
+import { isConfigured, loadOpencodeConfig, type OpencodeConfig } from "./config.ts";
+import { HttpClient } from "./http-client.ts";
+import { searchAndFormatRecall } from "./recall.ts";
+import { fetchKbCatalogBlock } from "./kb-catalog.ts";
+import { buildWarmupQuery, collectGitSignals } from "./warmup.ts";
+import { runCapture, unwrapSessionMessagesResponse } from "./capture.ts";
+
+const SESSION_TTL_MS = 15 * 60 * 1000;
+const SESSION_MAX = 100;
+
+const RECALL_TIMEOUT_MS = 5_000;
+const CAPTURE_TIMEOUT_MS = 8_000;
+
+export interface SessionState {
+  lastPrompt: string;
+  initialized: boolean;
+  lastFingerprint: string | null;
+  touched: number;
+}
+
+export interface PluginRuntime {
+  config: OpencodeConfig;
+  http: HttpClient;
+  sessionState: Map<string, SessionState>;
+  cwd: string;
+}
+
+export function buildRuntime(config: OpencodeConfig, cwd: string): PluginRuntime {
+  return {
+    config,
+    http: new HttpClient({ baseUrl: config.baseUrl, apiKey: config.apiKey }),
+    sessionState: new Map(),
+    cwd,
+  };
+}
+
+export function touchSession(rt: PluginRuntime, sessionID: string): SessionState {
+  pruneSessions(rt.sessionState);
+  let s = rt.sessionState.get(sessionID);
+  if (!s) {
+    s = { lastPrompt: "", initialized: false, lastFingerprint: null, touched: Date.now() };
+    rt.sessionState.set(sessionID, s);
+  } else {
+    s.touched = Date.now();
+  }
+  return s;
+}
+
+export function pruneSessions(state: Map<string, SessionState>): void {
+  const now = Date.now();
+  for (const [id, s] of state) {
+    if (now - s.touched > SESSION_TTL_MS) state.delete(id);
+  }
+  if (state.size > SESSION_MAX) {
+    const overflow = state.size - SESSION_MAX;
+    const sorted = [...state.entries()].sort((a, b) => a[1].touched - b[1].touched);
+    for (let i = 0; i < overflow; i++) state.delete(sorted[i][0]);
+  }
+}
+
+export function extractTextPrompt(parts: Part[]): string {
+  const chunks: string[] = [];
+  for (const p of parts) {
+    if (p.type !== "text") continue;
+    if (p.synthetic === true || p.ignored === true) continue;
+    if (typeof p.text === "string" && p.text) chunks.push(p.text);
+  }
+  return chunks.join("\n").trim();
+}
+
+export async function buildHooks(input: PluginInput): Promise<Hooks> {
+  const config = loadOpencodeConfig();
+  if (!isConfigured(config)) {
+    logDebug(
+      config,
+      "config",
+      "opencode integration disabled: missing agents.opencode.api_key in ~/.ctxdb/ctxdb.json or CTXDB_API_KEY",
+    );
+    return {};
+  }
+
+  const cwd = input.directory || input.worktree || process.cwd();
+  const rt = buildRuntime(config, cwd);
+
+  const hooks: Hooks = {
+    "chat.message": async (input, output) => {
+      try {
+        const text = extractTextPrompt(output.parts);
+        if (!text) return;
+        const s = touchSession(rt, input.sessionID);
+        s.lastPrompt = text;
+      } catch (err) {
+        logError(rt.config, "chat.message", err);
+      }
+    },
+
+    "experimental.chat.system.transform": async (input, output) => {
+      try {
+        const sessionID = input.sessionID;
+        // First-message detection only works when sessionID is present;
+        // when undefined we degrade to "every-message" recall and skip
+        // first-time-only branches.
+        const state = sessionID ? touchSession(rt, sessionID) : null;
+        const isFirstMessage = state ? !state.initialized : false;
+
+        const prompt = state?.lastPrompt ?? "";
+
+        const tasks: Promise<string>[] = [];
+
+        if (rt.config.autoRecall && prompt) {
+          tasks.push(
+            searchAndLogRecall("system.transform.recall", prompt, rt),
+          );
+        }
+
+        if (rt.config.warmupRecall && isFirstMessage) {
+          const git = collectGitSignals(rt.cwd);
+          const query = buildWarmupQuery(rt.cwd, git);
+          tasks.push(
+            searchAndLogRecall("system.transform.warmupRecall", query, rt),
+          );
+        }
+
+        const kbMode = rt.config.kbCatalogInjection;
+        const kbThisTurn =
+          kbMode === "user_prompt_submit" ||
+          (kbMode === "session_start" && isFirstMessage);
+        if (kbThisTurn) {
+          tasks.push(fetchKbCatalogBlock(rt.http, RECALL_TIMEOUT_MS));
+        }
+
+        const blocks = (await Promise.all(tasks)).filter((b) => b && b.length > 0);
+        for (const b of blocks) output.system.push(b);
+
+        if (state) state.initialized = true;
+      } catch (err) {
+        logError(rt.config, "system.transform", err);
+      }
+    },
+    "event": async (evtInput) => {
+      try {
+        const ev = evtInput.event;
+        if (!ev || ev.type !== "session.idle") return;
+        const sessionID = ev.properties?.sessionID;
+        if (!sessionID) return;
+        if (!rt.config.autoCapture) return;
+
+        const state = touchSession(rt, sessionID);
+
+        let messages: unknown[];
+        try {
+          const data = await withTimeout(
+            input.client.session.messages({
+              path: { id: sessionID },
+              query: { limit: 24 },
+              throwOnError: true,
+            }),
+            CAPTURE_TIMEOUT_MS,
+            "session.messages",
+          );
+          messages = unwrapSessionMessagesResponse(data);
+        } catch (err) {
+          logError(rt.config, "event.fetchMessages", err);
+          return;
+        }
+        if (messages.length === 0) return;
+
+        const outcome = await runCapture(
+          messages,
+          rt.config,
+          rt.http,
+          CAPTURE_TIMEOUT_MS,
+          state.lastFingerprint,
+        );
+        if (outcome.captured && outcome.fingerprint) {
+          state.lastFingerprint = outcome.fingerprint;
+        }
+        if (!outcome.captured && outcome.reason.startsWith("http_error:")) {
+          logError(rt.config, "event.capture", new Error(outcome.reason));
+        }
+        logDebug(
+          rt.config,
+          "event.capture",
+          `sessionID=${sessionID} captured=${outcome.captured} reason=${outcome.reason} count=${outcome.messageCount}`,
+        );
+      } catch (err) {
+        logError(rt.config, "event", err);
+      }
+    },
+  };
+
+  return hooks;
+}
+
+async function searchAndLogRecall(
+  scope: string,
+  query: string,
+  rt: PluginRuntime,
+): Promise<string> {
+  const result = await searchAndFormatRecall(query, rt.config, rt.http, RECALL_TIMEOUT_MS);
+  if (result.reason.startsWith("http_error:")) {
+    logError(rt.config, scope, new Error(result.reason));
+  }
+  return result.block;
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  label: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`${label} timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function logDebug(config: OpencodeConfig, scope: string, message: string): void {
+  if (!config.debug) return;
+  try {
+    process.stderr.write(`[ctxdb-opencode] ${scope}: ${message}\n`);
+  } catch {
+    // never block hook return on logging failure
+  }
+}
+
+function logError(config: OpencodeConfig, scope: string, err: unknown): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  logDebug(config, scope, msg);
+}