negotium 0.1.7 → 0.1.9

package/dist/runtime/src/mcp/paddleocr-server.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { connectStdio } from "#mcp/mcp-helpers";
+import { errMsg } from "#platform/error";
+
+const PYTHON = process.env.PADDLEOCR_PYTHON;
+if (!PYTHON) {
+  throw new Error(
+    "PADDLEOCR_PYTHON not configured. Set PADDLEOCR_PYTHON in .env to your paddleocr venv python path. " +
+      "See INSTALL.md section 5 for setup instructions.",
+  );
+}
+const TIMEOUT_MS = Number.parseInt(process.env.PADDLEOCR_TIMEOUT_MS ?? "300000", 10);
+const DET_LIMIT_SIDE_LEN = Number.parseInt(process.env.PADDLEOCR_DET_LIMIT_SIDE_LEN ?? "1280", 10);
+
+const server = new McpServer({
+  name: "paddleocr",
+  version: "1.0.0",
+});
+
+const ALLOWED_LANGS = new Set([
+  "korean",
+  "ch",
+  "en",
+  "japan",
+  "latin",
+  "arabic",
+  "cyrillic",
+  "devanagari",
+]);
+
+// Inline Python script — runs in the venv, no temp file needed
+function runPaddleOCR(filePath: string, lang: string): string {
+  if (!ALLOWED_LANGS.has(lang)) {
+    throw new Error(`Unsupported lang: "${lang}". Allowed: ${[...ALLOWED_LANGS].join(", ")}`);
+  }
+  const script = `
+import sys, os
+os.environ["PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK"] = "True"
+import warnings, logging
+warnings.filterwarnings("ignore")
+logging.disable(logging.CRITICAL)
+
+from paddleocr import PaddleOCR
+ocr = PaddleOCR(
+    lang="${lang}",
+    use_doc_orientation_classify=False,
+    use_doc_unwarping=False,
+    use_textline_orientation=False,
+    text_det_limit_side_len=${Number.isFinite(DET_LIMIT_SIDE_LEN) ? DET_LIMIT_SIDE_LEN : 1280},
+    text_det_limit_type="max",
+)
+result = ocr.predict(sys.argv[1])
+for res in result:
+    for text in res.get("rec_texts", []):
+        if text.strip():
+            print(text.strip())
+`.trim();
+
+  return execFileSync(PYTHON!, ["-c", script, filePath], {
+    encoding: "utf-8",
+    timeout: Number.isFinite(TIMEOUT_MS) ? TIMEOUT_MS : 300000,
+    env: {
+      ...process.env,
+      PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK: "True",
+    },
+  }).trim();
+}
+
+// ── paddleocr_file ─────────────────────────────────────────────────────────
+server.tool(
+  "paddleocr_file",
+  [
+    "Extract text from an image using PaddleOCR (PP-OCRv5).",
+    "Better than macOS Vision for Korean, Chinese, Japanese, and mixed-language documents.",
+    "Supports: PNG, JPG, JPEG, WEBP, BMP, TIFF.",
+    "Use lang='korean' for Korean docs, 'ch' for Chinese, 'en' for English-only.",
+  ].join(" "),
+  {
+    file_path: z.string().describe("Absolute path to the image file"),
+    lang: z
+      .string()
+      .optional()
+      .default("korean")
+      .describe("OCR language: 'korean' (default), 'ch' (Chinese/mixed), 'en', 'japan'"),
+  },
+  async ({ file_path, lang }) => {
+    try {
+      const absPath = resolve(file_path);
+      const output = runPaddleOCR(absPath, lang ?? "korean");
+      if (!output) {
+        return { content: [{ type: "text", text: "No text found in the file." }] };
+      }
+      return { content: [{ type: "text", text: output }] };
+    } catch (err: unknown) {
+      return { content: [{ type: "text", text: `Error: ${errMsg(err)}` }], isError: true };
+    }
+  },
+);
+
+// ── main ───────────────────────────────────────────────────────────────────
+await connectStdio(server);

package/dist/runtime/src/mcp/peer-bridge.ts

@@ -0,0 +1,114 @@
+import type { McpToolResult } from "#agents/mcp-tools/common";
+import type { AgentKind, PeerRuntimeBridgeContext } from "#types";
+
+export interface PeerRuntimeSpawnRequest {
+  bridge: PeerRuntimeBridgeContext;
+  userId: string;
+  agent: AgentKind;
+  model?: string;
+  input: Record<string, unknown>;
+}
+
+export interface PeerRuntimeVisualRequest {
+  bridge: PeerRuntimeBridgeContext;
+  userId: string;
+  agent: AgentKind;
+  model?: string;
+  kind: "html" | "mermaid" | "image" | "video";
+  title?: string;
+  html?: string;
+  code?: string;
+  theme?: string;
+  fileId?: string;
+  mimeType?: string;
+  source?: string;
+}
+
+export type PeerRuntimeVisualResult =
+  | { ok: true; id: number; url: string; title: string | null }
+  | { ok: false; error: string };
+
+export interface PeerRuntimeFileRequest {
+  bridge: PeerRuntimeBridgeContext;
+  userId: string;
+  agent: AgentKind;
+  model?: string;
+  path: string;
+  source: string;
+}
+
+export interface PeerRuntimeAskUserRequest {
+  bridge: PeerRuntimeBridgeContext;
+  userId: string;
+  agent: AgentKind;
+  model?: string;
+  input: Record<string, unknown>;
+}
+
+export interface PeerRuntimeSelfConfigRequest {
+  bridge: PeerRuntimeBridgeContext;
+  userId: string;
+  tool: string;
+  input: Record<string, unknown>;
+  currentUserPrompt?: string;
+}
+
+export interface PeerRuntimeBridge {
+  spawnSubagent(request: PeerRuntimeSpawnRequest): Promise<McpToolResult>;
+  /** Wait until already-broadcast runtime events for this local turn have
+   *  reached the canonical host before an out-of-band bridge mutation. */
+  flushEvents?(localTopicId: string): Promise<boolean>;
+  showVisual?(request: PeerRuntimeVisualRequest): Promise<PeerRuntimeVisualResult>;
+  sendFile?(request: PeerRuntimeFileRequest): Promise<{ ok: true } | { ok: false; error: string }>;
+  askUser?(request: PeerRuntimeAskUserRequest): Promise<McpToolResult>;
+  selfConfig?(request: PeerRuntimeSelfConfigRequest): Promise<McpToolResult>;
+}
+
+export function flushPeerRuntimeEvents(localTopicId: string): Promise<boolean> {
+  return activeBridge?.flushEvents?.(localTopicId) ?? Promise.resolve(true);
+}
+
+let activeBridge: PeerRuntimeBridge | null = null;
+
+/**
+ * Install the channel/placement adapter that owns remote runtime mutations.
+ * Core carries the per-turn bridge identity, but deliberately does not know
+ * how a workspace hub is discovered or authenticated.
+ */
+export function registerPeerRuntimeBridge(bridge: PeerRuntimeBridge): () => void {
+  activeBridge = bridge;
+  return () => {
+    if (activeBridge === bridge) activeBridge = null;
+  };
+}
+
+/** Returns null when no placement adapter is active. */
+export function dispatchPeerRuntimeSpawn(
+  request: PeerRuntimeSpawnRequest,
+): Promise<McpToolResult> | null {
+  return activeBridge?.spawnSubagent(request) ?? null;
+}
+
+export function dispatchPeerRuntimeVisual(
+  request: PeerRuntimeVisualRequest,
+): Promise<PeerRuntimeVisualResult> | null {
+  return activeBridge?.showVisual?.(request) ?? null;
+}
+
+export function dispatchPeerRuntimeFile(
+  request: PeerRuntimeFileRequest,
+): Promise<{ ok: true } | { ok: false; error: string }> | null {
+  return activeBridge?.sendFile?.(request) ?? null;
+}
+
+export function dispatchPeerRuntimeAskUser(
+  request: PeerRuntimeAskUserRequest,
+): Promise<McpToolResult> | null {
+  return activeBridge?.askUser?.(request) ?? null;
+}
+
+export function dispatchPeerRuntimeSelfConfig(
+  request: PeerRuntimeSelfConfigRequest,
+): Promise<McpToolResult> | null {
+  return activeBridge?.selfConfig?.(request) ?? null;
+}

package/dist/runtime/src/mcp/runtime-spec.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime-MCP wiring shared between core (which injects the MCP into agent
+ * sessions) and @negotium/mcp (which serves the endpoint).
+ *
+ * The runtime process exposes one HTTP MCP endpoint; every agent turn gets a
+ * per-turn signed token carrying its full execution context, so the MCP layer
+ * never trusts the agent to say who it is. Ported from otium runtime-api
+ * `mcp/runtime-server.ts` (transport-agnostic parts only).
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { NEGOTIUM_PORT, RUNTIME_MCP_SECRET } from "#platform/config";
+import { type AgentKind, isAgentKind, type PeerRuntimeBridgeContext } from "#types";
+
+export const RUNTIME_MCP_KEY = "runtime";
+
+export const RUNTIME_MCP_BASE_PATH = "/mcp/runtime";
+const TOKEN_TTL_MS = 4 * 60 * 60 * 1000;
+const CLAUDE_MCP_TOOL_TIMEOUT_MS = 600_000;
+
+export interface RuntimeMcpContext {
+  userId: string;
+  topicId: string;
+  topicTitle: string;
+  queryId?: string;
+  cwd: string;
+  agent: AgentKind;
+  model?: string;
+  currentUserPrompt?: string;
+  autoContinue?: boolean;
+  /** Capability minted by the adapter. Visual tools are absent unless true. */
+  visualTools?: boolean;
+  peerBridge?: PeerRuntimeBridgeContext;
+}
+
+type RuntimeTokenPayload = {
+  v: 1;
+  exp: number;
+  ctx: RuntimeMcpContext;
+};
+
+let runtimePort = NEGOTIUM_PORT;
+
+/** The runtime host calls this once it knows which port it actually bound. */
+export function setRuntimeMcpPort(port: number): void {
+  runtimePort = port;
+}
+
+export function getRuntimeMcpPort(): number {
+  return runtimePort;
+}
+
+function encodeTokenPart(value: unknown): string {
+  return Buffer.from(JSON.stringify(value), "utf-8").toString("base64url");
+}
+
+function decodeTokenPart(part: string): unknown {
+  return JSON.parse(Buffer.from(part, "base64url").toString("utf-8")) as unknown;
+}
+
+function signTokenPayload(payloadPart: string): string {
+  return createHmac("sha256", RUNTIME_MCP_SECRET).update(payloadPart).digest("base64url");
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const aa = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return aa.length === bb.length && timingSafeEqual(aa, bb);
+}
+
+function isRuntimeMcpContext(value: unknown): value is RuntimeMcpContext {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const ctx = value as Partial<RuntimeMcpContext>;
+  return (
+    typeof ctx.userId === "string" &&
+    typeof ctx.topicId === "string" &&
+    typeof ctx.topicTitle === "string" &&
+    typeof ctx.cwd === "string" &&
+    typeof ctx.agent === "string" &&
+    isAgentKind(ctx.agent) &&
+    (ctx.queryId === undefined || typeof ctx.queryId === "string") &&
+    (ctx.model === undefined || typeof ctx.model === "string") &&
+    (ctx.currentUserPrompt === undefined || typeof ctx.currentUserPrompt === "string") &&
+    (ctx.autoContinue === undefined || typeof ctx.autoContinue === "boolean") &&
+    (ctx.visualTools === undefined || typeof ctx.visualTools === "boolean") &&
+    (ctx.peerBridge === undefined ||
+      (typeof ctx.peerBridge.hubCellId === "string" &&
+        typeof ctx.peerBridge.hostTopicId === "string" &&
+        typeof ctx.peerBridge.hostQueryId === "string" &&
+        typeof ctx.peerBridge.canSpawnSubagents === "boolean"))
+  );
+}
+
+export function issueRuntimeMcpToken(ctx: RuntimeMcpContext): string {
+  const payloadPart = encodeTokenPart({
+    v: 1,
+    exp: Date.now() + TOKEN_TTL_MS,
+    ctx,
+  } satisfies RuntimeTokenPayload);
+  return `${payloadPart}.${signTokenPayload(payloadPart)}`;
+}
+
+export function resolveRuntimeMcpToken(token: string | null): RuntimeMcpContext | null {
+  if (!token) return null;
+  const [payloadPart, signature, extra] = token.split(".");
+  if (!payloadPart || !signature || extra !== undefined) return null;
+  if (!safeEqual(signature, signTokenPayload(payloadPart))) return null;
+
+  try {
+    const payload = decodeTokenPart(payloadPart) as Partial<RuntimeTokenPayload>;
+    if (payload.v !== 1 || typeof payload.exp !== "number" || payload.exp <= Date.now())
+      return null;
+    if (!isRuntimeMcpContext(payload.ctx)) return null;
+    return payload.ctx;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * MCP server spec injected into an agent session's MCP config so the agent
+ * connects back to this node's runtime endpoint with its per-turn token.
+ */
+export function buildRuntimeMcpSpec(
+  agent: AgentKind,
+  ctx: RuntimeMcpContext,
+): Record<string, unknown> {
+  const token = issueRuntimeMcpToken(ctx);
+  const base = `http://127.0.0.1:${runtimePort}${RUNTIME_MCP_BASE_PATH}`;
+  const query = `token=${encodeURIComponent(token)}`;
+  if (agent === "codex") return { url: `${base}/mcp?${query}` };
+  return {
+    type: "sse" as const,
+    url: `${base}/sse?${query}`,
+    timeout: CLAUDE_MCP_TOOL_TIMEOUT_MS,
+  };
+}

package/dist/runtime/src/mcp/session-comm/bridge-ipc-config.ts

@@ -0,0 +1,27 @@
+export interface PeerSessionBridgeIpcConfig {
+  url: string;
+  token: string;
+}
+
+const registrations: Array<{ id: symbol; config: PeerSessionBridgeIpcConfig }> = [];
+
+export function registerPeerSessionBridgeIpcConfig(config: PeerSessionBridgeIpcConfig): () => void {
+  const registration = { id: Symbol("peer-session-bridge-ipc"), config: { ...config } };
+  registrations.push(registration);
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    const index = registrations.findIndex((entry) => entry.id === registration.id);
+    if (index >= 0) registrations.splice(index, 1);
+  };
+}
+
+export function peerSessionBridgeIpcEnv(): Record<string, string> | undefined {
+  const active = registrations.at(-1)?.config;
+  if (!active) return undefined;
+  return {
+    NEGOTIUM_PEER_SESSION_BRIDGE_URL: active.url,
+    NEGOTIUM_PEER_SESSION_BRIDGE_TOKEN: active.token,
+  };
+}

package/dist/runtime/src/mcp/session-comm/peer-forward.ts

@@ -0,0 +1,165 @@
+/**
+ * Remote-node forwarding adapter hook.
+ *
+ * Addressing keeps the `"<node>/<topic>"` shape so cross-node session-comm can
+ * plug in later (an otium-hub adapter, a negotium peer protocol, …) without
+ * changing tool contracts. On a standalone node every remote call fails
+ * gracefully and `peerSessionsForUser` contributes nothing to peek listings.
+ */
+
+export interface PeerForwardArgs {
+  action: "tell" | "ask" | "abort";
+  toNode: string;
+  toTopic: string;
+  userId: string;
+  fromKey?: string;
+  fromTitle?: string;
+  fromTopicId?: string;
+  message?: string;
+  requestId?: string;
+  depth?: number;
+  fromDepth?: number;
+  /** Hub turn authorizing a worker-originated peer call. */
+  sourceQueryId?: string;
+}
+
+export type PeerForwardResult = { ok: true } | { ok: false; error: string };
+
+export interface RemoteReplyRoute {
+  nodeName: string;
+  nodeCellId: string;
+  topicId: string;
+  userId: string;
+  requestId: string;
+}
+
+export interface PeerSessionBridge {
+  forward(args: PeerForwardArgs): Promise<PeerForwardResult>;
+  sessions(userId: string, sourceQueryId?: string): Promise<PeerSessionsResult>;
+  reply(
+    route: RemoteReplyRoute,
+    sourceTitle: string,
+    replyText: string,
+    kind: "reply" | "error",
+  ): Promise<boolean>;
+}
+
+let activeBridge: PeerSessionBridge | null = null;
+
+const PEER_BRIDGE_URL_ENV = "NEGOTIUM_PEER_SESSION_BRIDGE_URL";
+const PEER_BRIDGE_TOKEN_ENV = "NEGOTIUM_PEER_SESSION_BRIDGE_TOKEN";
+const PEER_BRIDGE_TIMEOUT_MS = 5_000;
+
+type IpcRequest =
+  | { action: "forward"; args: PeerForwardArgs }
+  | { action: "sessions"; userId: string; sourceQueryId?: string }
+  | {
+      action: "reply";
+      route: RemoteReplyRoute;
+      sourceTitle: string;
+      replyText: string;
+      kind: "reply" | "error";
+    };
+
+function loopbackBridgeConfig(): { url: string; token: string } | null {
+  const rawUrl = process.env[PEER_BRIDGE_URL_ENV]?.trim();
+  const token = process.env[PEER_BRIDGE_TOKEN_ENV]?.trim();
+  if (!rawUrl || !token) return null;
+  try {
+    const url = new URL(rawUrl);
+    if (url.protocol !== "http:" || !["127.0.0.1", "::1", "localhost"].includes(url.hostname)) {
+      return null;
+    }
+    return { url: url.toString(), token };
+  } catch {
+    return null;
+  }
+}
+
+async function callLoopbackBridge<T>(
+  request: IpcRequest,
+): Promise<{ configured: boolean; result: T | null }> {
+  const config = loopbackBridgeConfig();
+  if (!config) return { configured: false, result: null };
+  try {
+    const response = await fetch(config.url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(request),
+      signal: AbortSignal.timeout(PEER_BRIDGE_TIMEOUT_MS),
+    });
+    if (!response.ok) return { configured: true, result: null };
+    return { configured: true, result: (await response.json()) as T };
+  } catch {
+    return { configured: true, result: null };
+  }
+}
+
+export function registerPeerSessionBridge(bridge: PeerSessionBridge): () => void {
+  activeBridge = bridge;
+  return () => {
+    if (activeBridge === bridge) activeBridge = null;
+  };
+}
+
+export async function forwardToPeer(args: PeerForwardArgs): Promise<PeerForwardResult> {
+  if (activeBridge) return activeBridge.forward(args);
+  const forwarded = await callLoopbackBridge<PeerForwardResult>({ action: "forward", args });
+  if (forwarded.result) return forwarded.result;
+  return {
+    ok: false,
+    error: forwarded.configured
+      ? "remote session bridge is configured but unavailable"
+      : "remote nodes are not connected on this negotium node (standalone mode)",
+  };
+}
+
+export interface PeerSessionEntry {
+  name: string;
+  agent: string | null;
+  hasSession: boolean;
+  description?: string;
+}
+
+export interface PeerSessionsResult {
+  ok: boolean;
+  nodes?: Array<{ node: string; error?: string; sessions?: PeerSessionEntry[] }>;
+}
+
+export async function peerSessionsForUser(
+  userId: string,
+  sourceQueryId?: string,
+): Promise<PeerSessionsResult> {
+  if (activeBridge) return activeBridge.sessions(userId, sourceQueryId);
+  const sessions = await callLoopbackBridge<PeerSessionsResult>({
+    action: "sessions",
+    userId,
+    sourceQueryId,
+  });
+  if (sessions.result) return sessions.result;
+  if (sessions.configured) return { ok: false, nodes: [] };
+  return { ok: true, nodes: [] };
+}
+
+export async function deliverPeerReply(
+  route: RemoteReplyRoute,
+  sourceTitle: string,
+  replyText: string,
+  kind: "reply" | "error",
+): Promise<boolean> {
+  if (activeBridge) return activeBridge.reply(route, sourceTitle, replyText, kind);
+  return (
+    (
+      await callLoopbackBridge<boolean>({
+        action: "reply",
+        route,
+        sourceTitle,
+        replyText,
+        kind,
+      })
+    ).result ?? false
+  );
+}

package/dist/runtime/src/mcp/session-comm/runtime.ts

@@ -0,0 +1,115 @@
+/**
+ * Process-bootstrap layer for the session-comm MCP server.
+ *
+ * Owns CLI-arg parsing, runtime constants, the shared DB helper, and
+ * primitive helpers (parseJsonField, isDebugUser) that other layers
+ * (`topics.ts`, `topic-config.ts`) compose on top of.
+ *
+ * Importers should pull *only* what they need from here; the previous
+ * `utils.ts` mega-module conflated process state, topic queries, and
+ * current-topic mutations in one file.
+ */
+
+import { homedir } from "node:os";
+import { parseUserIdArg } from "#mcp/mcp-helpers";
+import {
+  PROGRESS_DIR as CONFIG_PROGRESS_DIR,
+  SESSIONS_DB as CONFIG_SESSIONS_DB,
+  DEBUG_FILE,
+  FALLBACK_AGENT,
+  PLAYWRIGHT_PORTS_DIR,
+  SESSION_INBOX_DIR,
+  SESSION_WORKSPACE_DIR,
+} from "#platform/config";
+import { readJsonFile } from "#platform/jsonl";
+import { Database } from "#storage/sqlite";
+import type { AgentKind } from "#types";
+// NOTE: import from "#types" — NOT "@/agents". The agents barrel re-exports
+// `maestroProvider`, which transitively pulls in `maestro-agent-sdk`. That SDK
+// runs `bootstrapHostPath()` at module-load and writes `[log] env-bootstrap…`
+// to *stdout* via its default console logger. Because this MCP server speaks
+// JSON-RPC over stdio, any rogue stdout write corrupts the channel and codex's
+// rmcp parser (`serde error expected value at line 1 column 2`) drops every
+// tool on this server. Pulling these symbols straight from `@/types` keeps the
+// SDK out of the import graph.
+import { isAgentKind } from "#types";
+
+export { PLAYWRIGHT_PORTS_DIR, SESSION_INBOX_DIR };
+
+// --- Constants & CLI args ---
+
+export const HOME = homedir();
+export const SESSIONS_DB = CONFIG_SESSIONS_DB;
+export const PROGRESS_DIR = CONFIG_PROGRESS_DIR;
+
+const args = process.argv.slice(2);
+export const userId = parseUserIdArg(args);
+export const currentTopic = args.find((a) => a.startsWith("--topic="))?.split("=")[1] || "";
+export const currentTopicId =
+  args.find((a) => a.startsWith("--topic-id="))?.slice("--topic-id=".length) || "";
+export const peerHostQueryId =
+  args.find((a) => a.startsWith("--peer-host-query-id="))?.slice("--peer-host-query-id=".length) ||
+  "";
+export const currentDepth = Number(
+  args.find((a) => a.startsWith("--depth="))?.split("=")[1] ?? "0",
+);
+// When true, the session is a silent fork generating an ask_session reply —
+// outbound tools (ask_session/tell_session/abort_session) are not registered.
+export const isReplyOnly = args.includes("--reply-only=true");
+const _agentArg = args.find((a) => a.startsWith("--agent="))?.split("=")[1];
+if (_agentArg !== undefined && !isAgentKind(_agentArg)) {
+  throw new Error(`Invalid --agent arg: ${_agentArg}`);
+}
+export const currentAgent: AgentKind = _agentArg ?? FALLBACK_AGENT;
+
+// Max tell_session relay depth — env parse/기본값 로직은 @/platform/config 로 이동.
+export { MAX_TELL_DEPTH } from "#platform/config";
+export const MAX_MESSAGE_LENGTH = 10_000;
+export const USER_CWD = SESSION_WORKSPACE_DIR;
+
+// --- DB helper ---
+
+export function withDb<T>(
+  fn: (db: InstanceType<typeof Database>) => T,
+  opts?: { write?: boolean },
+): T {
+  const db = new Database(SESSIONS_DB, opts?.write ? undefined : { readonly: true });
+  try {
+    db.exec(opts?.write ? "PRAGMA busy_timeout = 5000" : "PRAGMA busy_timeout = 3000");
+    if (opts?.write) db.exec("PRAGMA journal_mode = WAL");
+    return fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+export const isManagerTopic = currentTopicId
+  ? withDb((db) => {
+      const row = db.query("SELECT kind FROM api_topics WHERE id = ?").get(currentTopicId) as
+        | { kind?: string }
+        | undefined;
+      return row?.kind === "manager";
+    })
+  : false;
+
+// --- JSON field parser helper (shared by topics.ts + topic-config.ts) ---
+
+export function parseJsonField<T>(value: string | null | undefined, label: string): T | undefined {
+  if (!value) return undefined;
+  try {
+    return JSON.parse(value) as T;
+  } catch (e) {
+    process.stderr.write(`warn: session-comm: failed to parse ${label}: ${e}\n`);
+    return undefined;
+  }
+}
+
+// --- Debug helper ---
+
+let _isDebugUser: boolean | undefined;
+export function isDebugUser(): boolean {
+  if (_isDebugUser !== undefined) return _isDebugUser;
+  const users = readJsonFile<number[]>(DEBUG_FILE);
+  _isDebugUser = !!users?.includes(Number(userId));
+  return _isDebugUser;
+}