@synapsor/client 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# Synapsor Node.js Adapter
+
+The Node.js adapter is a thin ESM client over `synapsor_server` HTTP/JSON APIs.
+It keeps Synapsor semantics in C++ and exposes a compact JavaScript API.
+
+## Local Usage
+
+```js
+import { Synapsor } from "@synapsor/client";
+
+const db = await Synapsor.connect("app.db", { autoStart: true });
+db.setSession({
+  tenant_id: "acme",
+  principal: "support_agent_17",
+  session_id: "agent_run_1",
+});
+
+await db.execute("CREATE TABLE messages (id INT, body VARCHAR);");
+await db.execute("INSERT INTO messages VALUES (1, 'hello');");
+const rows = await db.query("SELECT * FROM messages;");
+
+const proposal = await db.proposeMemoryFact({
+  scope: ["tenant", "acme"],
+  subject: ["preference", "answer_style"],
+  claim: "The operator prefers concise answers.",
+  source: ["turn", "msg_1"],
+  trust: "verified",
+  approval: "approved",
+  reason: "stable preference extracted from chat",
+});
+await db.approveMemoryProposal(proposal.proposal.proposal_id, "operator approved");
+
+await db.close();
+```
+
+## Hosted Usage
+
+Install from npm after the package is published:
+
+```bash
+npm install @synapsor/client
+```
+
+```js
+import { Synapsor } from "@synapsor/client";
+
+const db = await Synapsor.connect("https://dev-api.synapsor.ai", {
+  apiKey: process.env.SYNAPSOR_API_KEY,
+});
+
+db.setSession({
+  tenant_id: "acme",
+  principal: "app_user_1",
+  session_id: "first_hosted_run",
+});
+
+console.log(await db.query("SELECT 1;"));
+const ctx = await db.invokeAgentCapability("chat.prepare_llm_context", { question: "..." });
+```
+
+Use database-scoped API keys from the Synapsor control panel for hosted projects.
+The cloud gateway pins those keys to the database runtime branch before forwarding
+requests to the single-node runtime.
+
+## API Surface
+
+- `execute(sql)` and `query(sql)`
+- `setSession({...})`
+- `invokeAgentCapability(name, args)`
+- `listCapabilities(query)`
+- `rememberFact({...})`
+- `proposeMemoryFact({...})`
+- `approveMemoryProposal(id, reason)`
+- `rejectMemoryProposal(id, reason)`
+- `listMemoryProposals({...})`
+- `recallMemory({...})`
+- `retireFact(id, {...})` and `forgetFact(id, reason)`
+- `checkFactForAction({...})`
+- branch helpers: `createBranch`, `useBranch`, `diffBranch`, `mergeBranch`, `dropBranch`
+- write lifecycle helpers: `previewWrite`, `approveWrite`, `commitWrite`, `rejectWrite`
+- `readResource(uri)`
+
+Errors from Synapsor become `SynapsorError` with `status` and `payload`.

package/generated-contract.mjs

@@ -0,0 +1,273 @@
+// Generated by tools/generate_openapi_sdk_contract.py. Do not edit by hand.
+export const PROTOCOL_VERSION = "v1";
+export const CONTRACT_SHA256 = "f738189b0873fe48c5900cbffafb7d4eed90acbe9fc8c7cfcd4db89ad78f106a";
+export const OPENAPI_OPERATIONS = Object.freeze({
+  "approveAgentProposal": {
+    "method": "POST",
+    "node_method": "approveWrite",
+    "path": "/v1/agent/proposals/approve",
+    "public": false,
+    "python_method": "approve_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
+  },
+  "cancelAgentProposal": {
+    "method": "POST",
+    "node_method": "cancelWrite",
+    "path": "/v1/agent/proposals/cancel",
+    "public": false,
+    "python_method": "cancel_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
+  },
+  "cancelHybridReembedJob": {
+    "method": "POST",
+    "node_method": "cancelHybridReembedJob",
+    "path": "/v1/admin/hybrid/reembed-jobs/cancel",
+    "public": false,
+    "python_method": "cancel_hybrid_reembed_job",
+    "request_schema": "#/components/schemas/HybridReembedJobActionRequest"
+  },
+  "commitAgentProposal": {
+    "method": "POST",
+    "node_method": "commitWrite",
+    "path": "/v1/agent/proposals/commit",
+    "public": false,
+    "python_method": "commit_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
+  },
+  "createAdminBackup": {
+    "method": "POST",
+    "node_method": "createAdminBackup",
+    "path": "/v1/admin/backups/create",
+    "public": false,
+    "python_method": "create_admin_backup",
+    "request_schema": null
+  },
+  "getAdminCheck": {
+    "method": "GET",
+    "node_method": "adminCheck",
+    "path": "/v1/admin/check",
+    "public": false,
+    "python_method": "admin_check",
+    "request_schema": null
+  },
+  "getAdminDiagnostics": {
+    "method": "GET",
+    "node_method": "adminDiagnostics",
+    "path": "/v1/admin/diagnostics",
+    "public": false,
+    "python_method": "admin_diagnostics",
+    "request_schema": null
+  },
+  "getAdminMetrics": {
+    "method": "GET",
+    "node_method": "adminMetrics",
+    "path": "/v1/admin/metrics",
+    "public": false,
+    "python_method": "admin_metrics",
+    "request_schema": null
+  },
+  "getAdminOtelTraces": {
+    "method": "GET",
+    "node_method": "adminOtelTraces",
+    "path": "/v1/admin/otel/traces",
+    "public": false,
+    "python_method": "admin_otel_traces",
+    "request_schema": null
+  },
+  "getAdminPrometheusMetrics": {
+    "method": "GET",
+    "node_method": "adminPrometheusMetrics",
+    "path": "/v1/admin/metrics/prometheus",
+    "public": false,
+    "python_method": "admin_prometheus_metrics",
+    "request_schema": null
+  },
+  "getHealth": {
+    "method": "GET",
+    "node_method": "health",
+    "path": "/v1/health",
+    "public": true,
+    "python_method": "health",
+    "request_schema": null
+  },
+  "getHybridReembedJobs": {
+    "method": "GET",
+    "node_method": "hybridReembedJobs",
+    "path": "/v1/admin/hybrid/reembed-jobs",
+    "public": false,
+    "python_method": "hybrid_reembed_jobs",
+    "request_schema": null
+  },
+  "getOpenApi": {
+    "method": "GET",
+    "node_method": "openapi",
+    "path": "/v1/openapi.json",
+    "public": true,
+    "python_method": "openapi",
+    "request_schema": null
+  },
+  "pauseHybridReembedJob": {
+    "method": "POST",
+    "node_method": "pauseHybridReembedJob",
+    "path": "/v1/admin/hybrid/reembed-jobs/pause",
+    "public": false,
+    "python_method": "pause_hybrid_reembed_job",
+    "request_schema": "#/components/schemas/HybridReembedJobActionRequest"
+  },
+  "postAdminShutdown": {
+    "method": "POST",
+    "node_method": "shutdown",
+    "path": "/v1/admin/shutdown",
+    "public": false,
+    "python_method": "shutdown",
+    "request_schema": null
+  },
+  "postAgentCapabilities": {
+    "method": "POST",
+    "node_method": "listCapabilities",
+    "path": "/v1/agent/capabilities",
+    "public": false,
+    "python_method": "list_capabilities",
+    "request_schema": "#/components/schemas/CapabilityDiscoveryRequest"
+  },
+  "postAgentInvoke": {
+    "method": "POST",
+    "node_method": "invokeAgentCapability",
+    "path": "/v1/agent/invoke",
+    "public": false,
+    "python_method": "invoke_agent_capability",
+    "request_schema": "#/components/schemas/AgentInvokeRequest"
+  },
+  "postAgentMemory": {
+    "method": "POST",
+    "node_method": "memoryCommand",
+    "path": "/v1/agent/memory",
+    "public": false,
+    "python_method": "memory_command",
+    "request_schema": "#/components/schemas/AgentMemoryRequest"
+  },
+  "postAgentRunReplay": {
+    "method": "POST",
+    "node_method": "replayAgentRun",
+    "path": "/v1/agent/runs/replay",
+    "public": false,
+    "python_method": "replay_agent_run",
+    "request_schema": "#/components/schemas/AgentRunReplayRequest"
+  },
+  "postQuery": {
+    "method": "POST",
+    "node_method": "query",
+    "path": "/v1/query",
+    "public": false,
+    "python_method": "query",
+    "request_schema": "#/components/schemas/SqlRequest"
+  },
+  "postResourceRead": {
+    "method": "POST",
+    "node_method": "readResource",
+    "path": "/v1/resources/read",
+    "public": false,
+    "python_method": "read_resource",
+    "request_schema": "#/components/schemas/ResourceReadRequest"
+  },
+  "postSql": {
+    "method": "POST",
+    "node_method": "execute",
+    "path": "/v1/sql",
+    "public": false,
+    "python_method": "execute",
+    "request_schema": "#/components/schemas/SqlRequest"
+  },
+  "previewAgentProposal": {
+    "method": "POST",
+    "node_method": "previewWrite",
+    "path": "/v1/agent/proposals/preview",
+    "public": false,
+    "python_method": "preview_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
+  },
+  "rejectAgentProposal": {
+    "method": "POST",
+    "node_method": "rejectWrite",
+    "path": "/v1/agent/proposals/reject",
+    "public": false,
+    "python_method": "reject_write",
+    "request_schema": "#/components/schemas/ProposalLifecycleRequest"
+  },
+  "resumeHybridReembedJob": {
+    "method": "POST",
+    "node_method": "resumeHybridReembedJob",
+    "path": "/v1/admin/hybrid/reembed-jobs/resume",
+    "public": false,
+    "python_method": "resume_hybrid_reembed_job",
+    "request_schema": "#/components/schemas/HybridReembedJobActionRequest"
+  },
+  "runHybridReembedJobs": {
+    "method": "POST",
+    "node_method": "runHybridReembedJobs",
+    "path": "/v1/admin/hybrid/reembed-jobs/run",
+    "public": false,
+    "python_method": "run_hybrid_reembed_jobs",
+    "request_schema": "#/components/schemas/HybridReembedRunRequest"
+  }
+});
+export const PYTHON_OPERATION_METHODS = Object.freeze({
+  "approveAgentProposal": "approve_write",
+  "cancelAgentProposal": "cancel_write",
+  "cancelHybridReembedJob": "cancel_hybrid_reembed_job",
+  "commitAgentProposal": "commit_write",
+  "createAdminBackup": "create_admin_backup",
+  "getAdminCheck": "admin_check",
+  "getAdminDiagnostics": "admin_diagnostics",
+  "getAdminMetrics": "admin_metrics",
+  "getAdminOtelTraces": "admin_otel_traces",
+  "getAdminPrometheusMetrics": "admin_prometheus_metrics",
+  "getHealth": "health",
+  "getHybridReembedJobs": "hybrid_reembed_jobs",
+  "getOpenApi": "openapi",
+  "pauseHybridReembedJob": "pause_hybrid_reembed_job",
+  "postAdminShutdown": "shutdown",
+  "postAgentCapabilities": "list_capabilities",
+  "postAgentInvoke": "invoke_agent_capability",
+  "postAgentMemory": "memory_command",
+  "postAgentRunReplay": "replay_agent_run",
+  "postQuery": "query",
+  "postResourceRead": "read_resource",
+  "postSql": "execute",
+  "previewAgentProposal": "preview_write",
+  "rejectAgentProposal": "reject_write",
+  "resumeHybridReembedJob": "resume_hybrid_reembed_job",
+  "runHybridReembedJobs": "run_hybrid_reembed_jobs"
+});
+export const NODE_OPERATION_METHODS = Object.freeze({
+  "approveAgentProposal": "approveWrite",
+  "cancelAgentProposal": "cancelWrite",
+  "cancelHybridReembedJob": "cancelHybridReembedJob",
+  "commitAgentProposal": "commitWrite",
+  "createAdminBackup": "createAdminBackup",
+  "getAdminCheck": "adminCheck",
+  "getAdminDiagnostics": "adminDiagnostics",
+  "getAdminMetrics": "adminMetrics",
+  "getAdminOtelTraces": "adminOtelTraces",
+  "getAdminPrometheusMetrics": "adminPrometheusMetrics",
+  "getHealth": "health",
+  "getHybridReembedJobs": "hybridReembedJobs",
+  "getOpenApi": "openapi",
+  "pauseHybridReembedJob": "pauseHybridReembedJob",
+  "postAdminShutdown": "shutdown",
+  "postAgentCapabilities": "listCapabilities",
+  "postAgentInvoke": "invokeAgentCapability",
+  "postAgentMemory": "memoryCommand",
+  "postAgentRunReplay": "replayAgentRun",
+  "postQuery": "query",
+  "postResourceRead": "readResource",
+  "postSql": "execute",
+  "previewAgentProposal": "previewWrite",
+  "rejectAgentProposal": "rejectWrite",
+  "resumeHybridReembedJob": "resumeHybridReembedJob",
+  "runHybridReembedJobs": "runHybridReembedJobs"
+});
+export const PUBLIC_OPERATIONS = Object.freeze([
+  "getHealth",
+  "getOpenApi"
+]);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@synapsor/client",
+  "version": "0.1.0",
+  "description": "Node.js client for Synapsor HTTP/JSON APIs",
+  "type": "module",
+  "main": "./synapsor.mjs",
+  "exports": {
+    ".": "./synapsor.mjs"
+  },
+  "files": [
+    "synapsor.mjs",
+    "generated-contract.mjs",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "node --check synapsor.mjs && node --check generated-contract.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "synapsor",
+    "database",
+    "agents",
+    "sql",
+    "rag",
+    "audit"
+  ],
+  "homepage": "https://synapsor.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandeshtiwari/Synapsor.git"
+  },
+  "bugs": {
+    "url": "https://synapsor.ai/contact"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/synapsor.mjs

@@ -0,0 +1,611 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  CONTRACT_SHA256 as OPENAPI_CONTRACT_SHA256,
+  NODE_OPERATION_METHODS,
+  OPENAPI_OPERATIONS,
+  PROTOCOL_VERSION,
+} from "./generated-contract.mjs";
+
+export {
+  NODE_OPERATION_METHODS,
+  OPENAPI_CONTRACT_SHA256,
+  OPENAPI_OPERATIONS,
+  PROTOCOL_VERSION,
+};
+
+export class SynapsorError extends Error {
+  constructor(message, { status = undefined, payload = undefined } = {}) {
+    super(message);
+    this.name = "SynapsorError";
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export class SynapsorBadRequestError extends SynapsorError {}
+export class SynapsorUnauthenticatedError extends SynapsorError {}
+export class SynapsorPermissionDeniedError extends SynapsorError {}
+export class SynapsorNotFoundError extends SynapsorError {}
+export class SynapsorConflictError extends SynapsorError {}
+export class SynapsorTimeoutError extends SynapsorError {}
+export class SynapsorResourceExhaustedError extends SynapsorError {}
+export class SynapsorUnavailableError extends SynapsorError {}
+export class SynapsorInternalError extends SynapsorError {}
+
+const ERROR_BY_STATUS = new Map([
+  [400, SynapsorBadRequestError],
+  [401, SynapsorUnauthenticatedError],
+  [403, SynapsorPermissionDeniedError],
+  [404, SynapsorNotFoundError],
+  [408, SynapsorTimeoutError],
+  [409, SynapsorConflictError],
+  [413, SynapsorResourceExhaustedError],
+  [500, SynapsorInternalError],
+  [503, SynapsorUnavailableError],
+]);
+
+export async function connect(target, options = {}) {
+  return Synapsor.connect(target, options);
+}
+
+export class Synapsor {
+  static openApiContractSha256 = OPENAPI_CONTRACT_SHA256;
+  static openApiOperations = OPENAPI_OPERATIONS;
+  static sdkOperationMethods = NODE_OPERATION_METHODS;
+
+  constructor({ baseUrl, session = {}, apiKey = undefined, process = undefined, timeoutMs = 5000 }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.session = { ...session };
+    this.apiKey = apiKey;
+    this.process = process;
+    this.timeoutMs = timeoutMs;
+  }
+
+  static async connect(target, options = {}) {
+    const targetText = String(target);
+    if (targetText.startsWith("http://") || targetText.startsWith("https://")) {
+      if (options.autoStart) {
+        throw new Error("autoStart cannot be used with an HTTP Synapsor URL");
+      }
+      return new Synapsor({
+        baseUrl: targetText,
+        session: options.session,
+        apiKey: options.apiKey,
+        timeoutMs: options.timeoutMs,
+      });
+    }
+
+    if (!options.autoStart) {
+      throw new Error("local database paths require autoStart: true for the HTTP adapter");
+    }
+
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? (await findFreePort(host));
+    const binary = options.serverBinary ?? defaultServerBinary();
+    if (!existsSync(binary)) {
+      throw new Error(`synapsor_server binary not found: ${binary}`);
+    }
+
+    const args = ["--db", targetText, "--host", host, "--port", String(port)];
+    if (Array.isArray(options.extraServerArgs)) {
+      args.push(...options.extraServerArgs.map(String));
+    }
+    const child = spawn(binary, args, {
+      cwd: repoRoot(),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(String(chunk)));
+    child.stderr.on("data", (chunk) => stderr.push(String(chunk)));
+
+    const client = new Synapsor({
+      baseUrl: `http://${host}:${port}`,
+      session: options.session,
+      apiKey: options.apiKey,
+      process: child,
+      timeoutMs: options.timeoutMs,
+    });
+    await client.waitUntilReady(() => stderr.join("") || stdout.join(""));
+    return client;
+  }
+
+  async close() {
+    if (!this.process) {
+      return;
+    }
+    try {
+      await this.shutdown();
+    } catch {
+      // Local close must still terminate the process if shutdown returned an error.
+    }
+    if (this.process.exitCode === null && this.process.signalCode === null) {
+      this.process.kill("SIGTERM");
+      await onceExitOrTimeout(this.process, 2000);
+      if (this.process.exitCode === null && this.process.signalCode === null) {
+        this.process.kill("SIGKILL");
+        await onceExitOrTimeout(this.process, 2000);
+      }
+    }
+    this.process = undefined;
+  }
+
+  setSession(session) {
+    this.session = { ...this.session, ...session };
+    return this;
+  }
+
+  async health() {
+    return this.request("GET", "/v1/health");
+  }
+
+  async openapi() {
+    return this.request("GET", "/v1/openapi.json");
+  }
+
+  async adminMetrics() {
+    return this.request("GET", "/v1/admin/metrics");
+  }
+
+  async adminPrometheusMetrics() {
+    return this.request("GET", "/v1/admin/metrics/prometheus");
+  }
+
+  async adminDiagnostics() {
+    return this.request("GET", "/v1/admin/diagnostics");
+  }
+
+  async adminOtelTraces() {
+    return this.request("GET", "/v1/admin/otel/traces");
+  }
+
+  async adminCheck() {
+    return this.request("GET", "/v1/admin/check");
+  }
+
+  async createAdminBackup(backupDir, { overwrite = false, verify = false } = {}) {
+    return this.request("POST", "/v1/admin/backups/create", {
+      backup_dir: String(backupDir),
+      overwrite: Boolean(overwrite),
+      verify: Boolean(verify),
+    });
+  }
+
+  async shutdown() {
+    return this.request("POST", "/v1/admin/shutdown", {});
+  }
+
+  async hybridReembedJobs() {
+    return this.request("GET", "/v1/admin/hybrid/reembed-jobs");
+  }
+
+  async runHybridReembedJobs(options = {}) {
+    const payload = {};
+    if (options.index !== undefined) {
+      payload.index = options.index;
+    }
+    if (options.indexName !== undefined) {
+      payload.index_name = options.indexName;
+    }
+    if (options.maxIndexes !== undefined) {
+      payload.max_indexes = Number(options.maxIndexes);
+    }
+    if (options.max_chunks_per_index !== undefined) {
+      payload.max_chunks_per_index = Number(options.max_chunks_per_index);
+    } else if (options.maxChunksPerIndex !== undefined) {
+      payload.max_chunks_per_index = Number(options.maxChunksPerIndex);
+    }
+    return this.request("POST", "/v1/admin/hybrid/reembed-jobs/run", payload);
+  }
+
+  async pauseHybridReembedJob(index) {
+    return this.request("POST", "/v1/admin/hybrid/reembed-jobs/pause", { index });
+  }
+
+  async resumeHybridReembedJob(index) {
+    return this.request("POST", "/v1/admin/hybrid/reembed-jobs/resume", { index });
+  }
+
+  async cancelHybridReembedJob(index) {
+    return this.request("POST", "/v1/admin/hybrid/reembed-jobs/cancel", { index });
+  }
+
+  async execute(sql, { session = undefined, asOf = undefined } = {}) {
+    const payload = { sql };
+    const requestSession = session ?? this.session;
+    if (Object.keys(requestSession).length > 0) {
+      payload.session = requestSession;
+    }
+    if (asOf !== undefined) {
+      payload.as_of = asOf;
+    }
+    return this.request("POST", asOf !== undefined ? "/v1/query" : "/v1/sql", payload);
+  }
+
+  async query(sql, options = {}) {
+    const response = await this.execute(sql, options);
+    const results = response.results ?? [];
+    if (results.length === 0) {
+      return [];
+    }
+    return results.at(-1).result?.rows ?? [];
+  }
+
+  async invokeAgentCapability(capability, args = {}, { session = undefined, traceId = undefined } = {}) {
+    const payload = {
+      capability,
+      arguments: args,
+      session: this.requireSession(session),
+    };
+    if (traceId !== undefined) {
+      payload.trace_id = traceId;
+    }
+    return this.request("POST", "/v1/agent/invoke", payload);
+  }
+
+  async listCapabilities(query = "", { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/capabilities", {
+      query,
+      session: this.requireSession(session),
+    });
+  }
+
+  async memoryCommand(command, { session = undefined } = {}) {
+    return this.request("POST", "/v1/agent/memory", {
+      session: this.requireSession(session),
+      command,
+    });
+  }
+
+  async rememberFact(options) {
+    return this.memoryCommand(factCommand("agent_memory.remember_fact", options), options);
+  }
+
+  async proposeMemoryFact(options) {
+    const command = factCommand("agent_memory.propose_fact", options);
+    command.replace_subject = Boolean(options.replaceSubject ?? options.replace_subject ?? false);
+    if (options.reason !== undefined) {
+      command.reason = options.reason;
+    }
+    return this.memoryCommand(command, options);
+  }
+
+  async approveMemoryProposal(proposalId, reason, options = {}) {
+    return this.memoryCommand({
+      kind: "agent_memory.approve_memory_proposal",
+      proposal_id: proposalId,
+      reason,
+    }, options);
+  }
+
+  async rejectMemoryProposal(proposalId, reason, options = {}) {
+    return this.memoryCommand({
+      kind: "agent_memory.reject_memory_proposal",
+      proposal_id: proposalId,
+      reason,
+    }, options);
+  }
+
+  async listMemoryProposals(options = {}) {
+    const command = { kind: "agent_memory.proposals" };
+    if (options.state !== undefined) {
+      command.state = options.state;
+    }
+    if (options.scope !== undefined) {
+      command.scope = typedRef(options.scope);
+    }
+    if (options.subject !== undefined) {
+      command.subject = typedRef(options.subject);
+    }
+    return this.memoryCommand(command, options);
+  }
+
+  async recallMemory(options = {}) {
+    const command = { kind: "agent_memory.recall" };
+    if (options.scope !== undefined) {
+      command.scope = typedRef(options.scope);
+    }
+    if (options.subject !== undefined) {
+      command.subject = typedRef(options.subject);
+    }
+    for (const [from, to] of [
+      ["asOf", "as_of"],
+      ["budgetTokens", "budget_tokens"],
+      ["profile", "profile"],
+      ["inlineEvidence", "inline_evidence"],
+      ["preferHandles", "prefer_handles"],
+      ["maxReasonCount", "max_reason_count"],
+    ]) {
+      if (options[from] !== undefined) {
+        command[to] = options[from];
+      }
+    }
+    return this.memoryCommand(command, options);
+  }
+
+  async retireFact(memoryId, { validTo, reason, session = undefined }) {
+    return this.memoryCommand({
+      kind: "agent_memory.retire_fact",
+      memory_id: memoryId,
+      valid_to: validTo,
+      reason,
+    }, { session });
+  }
+
+  async forgetFact(memoryId, reason, options = {}) {
+    return this.memoryCommand({
+      kind: "agent_memory.forget_fact",
+      memory_id: memoryId,
+      reason,
+    }, options);
+  }
+
+  async checkFactForAction({ claim, scope = undefined, subject = undefined, asOf = undefined, action = "policy", session = undefined }) {
+    const args = [`claim => ${sqlLiteral(claim)}`, `action => ${sqlLiteral(action)}`];
+    if (scope !== undefined) {
+      args.push(`scope => ${typedSql(scope)}`);
+    }
+    if (subject !== undefined) {
+      args.push(`subject => ${typedSql(subject)}`);
+    }
+    if (asOf !== undefined) {
+      args.push(`as_of => ${Number(asOf)}`);
+    }
+    const response = await this.execute(`CALL memory.check_fact_for_action(${args.join(", ")});`, { session });
+    return response.results.at(-1).result;
+  }
+
+  async createBranch(name, parent = "main") {
+    return this.execute(`CREATE BRANCH ${identifier(name)} FROM ${identifier(parent)};`);
+  }
+
+  async useBranch(name) {
+    const result = await this.execute(`USE BRANCH ${identifier(name)};`);
+    this.session.branch_id = name;
+    return result;
+  }
+
+  async diffBranch(source, target = "main") {
+    const response = await this.execute(`DIFF BRANCH ${identifier(source)} AGAINST ${identifier(target)};`);
+    return response.results.at(-1).result;
+  }
+
+  async mergeBranch(source, target = "main") {
+    return this.execute(`MERGE BRANCH ${identifier(source)} INTO ${identifier(target)};`);
+  }
+
+  async dropBranch(name) {
+    const result = await this.execute(`DROP BRANCH ${identifier(name)};`);
+    if (this.session.branch_id === name) {
+      this.session.branch_id = "main";
+    }
+    return result;
+  }
+
+  async readResource(uri, options = {}) {
+    return this.request("POST", "/v1/resources/read", {
+      uri,
+      session: this.requireSession(options.session),
+    });
+  }
+
+  async previewWrite(proposal, options = {}) {
+    return this.proposalLifecycle("preview", proposal, options);
+  }
+
+  async approveWrite(proposal, options = {}) {
+    return this.proposalLifecycle("approve", proposal, options);
+  }
+
+  async commitWrite(proposal, options = {}) {
+    return this.proposalLifecycle("commit", proposal, options);
+  }
+
+  async rejectWrite(proposal, options = {}) {
+    return this.proposalLifecycle("reject", proposal, options);
+  }
+
+  async cancelWrite(proposal, options = {}) {
+    return this.proposalLifecycle("cancel", proposal, options);
+  }
+
+  async replayAgentRun(runId, options = {}) {
+    return this.request("POST", "/v1/agent/runs/replay", {
+      run_id: Number(runId),
+      session: this.requireSession(options.session),
+      include_sensitive_memory: Boolean(options.includeSensitiveMemory ?? options.include_sensitive_memory ?? false),
+    });
+  }
+
+  async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined } = {}) {
+    const payload = {
+      proposal,
+      session: this.requireSession(session),
+    };
+    const shouldPromote = promoteBranch ?? promote_branch;
+    const target = targetBranch ?? target_branch;
+    if (shouldPromote !== undefined) {
+      payload.promote_branch = Boolean(shouldPromote);
+    }
+    if (target !== undefined) {
+      payload.target_branch = target;
+    }
+    return this.request("POST", `/v1/agent/proposals/${action}`, payload);
+  }
+
+  requireSession(session = undefined) {
+    const requestSession = session ?? this.session;
+    if (!requestSession || Object.keys(requestSession).length === 0) {
+      throw new Error("agent APIs require a session with principal and tenant_id");
+    }
+    if (requestSession.principal === undefined || requestSession.tenant_id === undefined) {
+      throw new Error("agent session requires principal and tenant_id");
+    }
+    return requestSession;
+  }
+
+  async request(method, path, payload = undefined) {
+    const headers = { accept: "application/json" };
+    const init = { method, headers };
+    if (payload !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(payload);
+    }
+    if (this.apiKey) {
+      headers.authorization = `Bearer ${this.apiKey}`;
+    }
+    const response = await fetch(this.baseUrl + path, init);
+    const text = await response.text();
+    let body = {};
+    if (text.length > 0) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = { error: text };
+      }
+    }
+    if (!response.ok) {
+      const ErrorType = ERROR_BY_STATUS.get(response.status) ?? SynapsorError;
+      throw new ErrorType(body.error ?? `Synapsor HTTP ${response.status}`, {
+        status: response.status,
+        payload: body,
+      });
+    }
+    return body;
+  }
+
+  async waitUntilReady(errorText) {
+    const deadline = Date.now() + this.timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+      if (this.process && this.process.exitCode !== null) {
+        throw new SynapsorError(`synapsor_server exited early: ${errorText()}`);
+      }
+      try {
+        await this.health();
+        return;
+      } catch (err) {
+        lastError = err;
+        await sleep(50);
+      }
+    }
+    throw new SynapsorError(`synapsor_server did not become ready: ${lastError}`);
+  }
+}
+
+function factCommand(kind, options) {
+  const command = {
+    kind,
+    claim: options.claim,
+    source: typedRef(options.source),
+    trust: options.trust ?? "unverified",
+    approval: options.approval ?? "pending",
+  };
+  if (options.scope !== undefined) {
+    command.scope = typedRef(options.scope);
+  }
+  if (options.subject !== undefined) {
+    command.subject = typedRef(options.subject);
+  }
+  if (options.validFrom !== undefined) {
+    command.valid_from = options.validFrom;
+  }
+  if (options.valid_from !== undefined) {
+    command.valid_from = options.valid_from;
+  }
+  if (options.validTo !== undefined) {
+    command.valid_to = options.validTo;
+  }
+  if (options.valid_to !== undefined) {
+    command.valid_to = options.valid_to;
+  }
+  return command;
+}
+
+function typedRef(value) {
+  if (Array.isArray(value) && value.length === 2) {
+    return { type: String(value[0]), id: String(value[1]) };
+  }
+  if (value && typeof value === "object" && typeof value.type === "string") {
+    return { ...value };
+  }
+  throw new TypeError("typed reference must be [type, id] or {type, id}");
+}
+
+function typedSql(value) {
+  const ref = typedRef(value);
+  return `${identifier(ref.type)}(${sqlLiteral(String(ref.id ?? ""))})`;
+}
+
+function sqlLiteral(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function identifier(value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`unsafe Synapsor identifier: ${value}`);
+  }
+  return value;
+}
+
+function repoRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+}
+
+function defaultServerBinary() {
+  if (process.env.SYNAPSOR_SERVER) {
+    return process.env.SYNAPSOR_SERVER;
+  }
+  const root = repoRoot();
+  for (const candidate of [
+    join(root, "build", "synapsor_server"),
+    join(root, "build", "debug", "synapsor_server"),
+    join(root, "build", "bin", "synapsor_server"),
+  ]) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return join(root, "build", "synapsor_server");
+}
+
+function findFreePort(host) {
+  return new Promise((resolvePort, reject) => {
+    const server = net.createServer();
+    server.on("error", reject);
+    server.listen(0, host, () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : undefined;
+      server.close(() => {
+        if (port === undefined) {
+          reject(new Error("could not allocate a free port"));
+        } else {
+          resolvePort(port);
+        }
+      });
+    });
+  });
+}
+
+function onceExitOrTimeout(child, timeoutMs) {
+  return new Promise((resolveDone) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolveDone();
+      return;
+    }
+    const timer = setTimeout(resolveDone, timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolveDone();
+    });
+  });
+}
+
+function sleep(ms) {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}