@synapsor/client 0.1.4 → 0.1.6

package/README.md

@@ -101,6 +101,30 @@ await run.complete({ decision: "waiver_proposed" }, { status: "waiting_approval"
 const graph = await run.explain();
 ```
 
+Find the persisted run/evidence/proposal later by business object, workflow,
+tenant, query fingerprint, or time window:
+
+```js
+const activity = await db.agentActivity.search({
+  tenantId: "acme",
+  businessObjectId: "T-1042",
+  workflow: "support.ticket_refund_flow",
+  timeRange: { from: 123, to: 456 },
+  limit: 50,
+});
+```
+
+This helper sends the native lookup form:
+
+```sql
+SELECT *
+FROM AGENT ACTIVITY
+WHERE tenant_id = 'acme'
+  AND business_object_id = 'T-1042'
+ORDER BY created_at DESC
+LIMIT 50;
+```
+
 Replay a stored capability run by using the numeric `agent_run_id` returned by
 Synapsor. Deterministic replay returns the captured persisted run; comparison
 modes can inspect the original snapshot, current state, a commit version, a
@@ -157,12 +181,33 @@ The worker validates Synapsor-provided mapping metadata, only writes allowlisted
 columns, adds tenant and primary-key guards, checks optional conflict columns,
 and reports `applied`, `conflict`, or `failed` back to Synapsor idempotently.
 
+## CLI MCP Risk Review
+
+The package installs a `synapsor` CLI. Use `synapsor mcp audit <target>` for a
+static MCP database risk review of exported tool manifests, remote `tools/list`
+endpoints, or stdio MCP servers.
+
+```bash
+synapsor mcp audit ./tools-manifest.json
+synapsor mcp audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+synapsor mcp audit 'stdio:node ./server.mjs' --timeout-ms 5000
+```
+
+The audit flags patterns such as generic `execute_sql` tools, model-controlled
+tenant/table/column inputs, model-callable approval or commit tools, missing
+proposal boundaries, missing structured output schemas, and missing idempotency
+or conflict-guard metadata. It never calls business tools during the audit.
+
+This is a static MCP database risk review, not proof that an MCP server is
+secure. MCP annotations are treated as descriptive hints, not enforcement.
+
 ## API Surface
 
 - `execute(sql)` and `query(sql)`
 - `setSession({...})`
 - `invokeAgentCapability(name, args, options)`
 - `agentRuns.start(...)`, `run.invokeCapability(...)`, `run.checkpoint(...)`, `run.complete(...)`, `run.explain(...)`
+- `agentActivity.search({ tenantId, businessObjectId, workflow, timeRange, limit })`
 - `replayAgentRun(id, { mode, version, timestamp, branchName })`
 - `externalActions.claim(...)` and `externalActions.confirm(...)`
 - `createAgentEval(...)` / `evals.create(...)` for run-history or `sourceTable` dataset evals

package/bin/synapsor.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
@@ -11,6 +12,7 @@ import { stdin as input, stdout as output } from "node:process";
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION } = require("../package.json");
 const DEFAULT_BASE_URL = "https://synapsor.ai";
+const MCP_AUDIT_DISCLAIMER = "This is a static MCP database risk review, not proof that an MCP server is secure.";
 const ERROR_HINTS = new Map([
   ["AUTH_REQUIRED", "Set SYNAPSOR_API_KEY or run `synapsor config set api-key`."],
   ["BILLING_REQUIRED", "Builder resources require active or trialing Builder billing."],
@@ -172,6 +174,17 @@ function csvFlag(args, name) {
   return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
 }
 
+function boolFlag(args, name) {
+  return args.includes(name);
+}
+
+function intFlag(args, name, fallback) {
+  const value = flagValue(args, name, "");
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
 function resolveSecretRef(value) {
   const text = String(value || "").trim();
   if (text.startsWith("env:")) {
@@ -217,6 +230,250 @@ async function readStdinSecret() {
   return value.trim();
 }
 
+async function loadMcpAuditTarget(target, args) {
+  if (!target) throw new Error("MCP_AUDIT_TARGET_REQUIRED: usage `synapsor mcp audit <target>`");
+  const timeoutMs = intFlag(args, "--timeout-ms", 5000);
+  if (/^https?:\/\//i.test(target)) {
+    return { target, kind: "remote_tools_list", payload: await fetchRemoteMcpTools(target, args, timeoutMs) };
+  }
+  if (target.startsWith("stdio:")) {
+    const command = target.slice("stdio:".length).trim();
+    if (!command) throw new Error("MCP_STDIO_COMMAND_REQUIRED: usage `synapsor mcp audit 'stdio:node server.js'`");
+    return { target, kind: "stdio_tools_list", payload: await fetchStdioMcpTools(command, timeoutMs) };
+  }
+  const raw = await readFile(target, "utf8");
+  return { target, kind: "manifest", payload: JSON.parse(raw) };
+}
+
+async function fetchRemoteMcpTools(url, args, timeoutMs) {
+  const bearerEnv = flagValue(args, "--bearer-env", "SYNAPSOR_MCP_AUDIT_BEARER");
+  const bearer = bearerEnv ? process.env[bearerEnv] || "" : "";
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      signal: controller.signal,
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json",
+        ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    });
+    const text = await response.text();
+    const payload = text.trim() ? JSON.parse(text) : {};
+    if (!response.ok) throw new Error(`MCP_AUDIT_REMOTE_FAILED: HTTP ${response.status}`);
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function splitCommand(command) {
+  const parts = [];
+  const matcher = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let match;
+  while ((match = matcher.exec(command)) !== null) {
+    parts.push(match[1] ?? match[2] ?? match[3]);
+  }
+  return parts;
+}
+
+async function fetchStdioMcpTools(command, timeoutMs) {
+  const [bin, ...args] = splitCommand(command);
+  if (!bin) throw new Error("MCP_STDIO_COMMAND_REQUIRED: empty stdio command");
+  return await new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`MCP_AUDIT_TIMEOUT: tools/list did not complete within ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+      const response = parseJsonRpcLine(stdout, 2);
+      if (response) {
+        clearTimeout(timer);
+        child.kill("SIGTERM");
+        resolve(response);
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", () => {
+      const response = parseJsonRpcLine(stdout, 2);
+      if (response) return;
+      clearTimeout(timer);
+      reject(new Error(`MCP_AUDIT_STDIO_FAILED: tools/list response not found${stderr ? `: ${stderr.slice(0, 240)}` : ""}`));
+    });
+    child.stdin.write(`${JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2025-11-25",
+        capabilities: {},
+        clientInfo: { name: "synapsor-mcp-audit", version: PACKAGE_VERSION },
+      },
+    })}\n`);
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} })}\n`);
+  });
+}
+
+function parseJsonRpcLine(text, id) {
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed.id === id) return parsed;
+    } catch {
+      // Ignore non-JSON logs from a local stdio server.
+    }
+  }
+  return null;
+}
+
+function extractMcpTools(payload) {
+  if (Array.isArray(payload)) return { tools: payload, source: "array_manifest" };
+  if (!payload || typeof payload !== "object") return { tools: [], source: "unknown" };
+  if (Array.isArray(payload.tools)) return { tools: payload.tools, source: "tool_manifest" };
+  if (Array.isArray(payload.result?.tools)) return { tools: payload.result.tools, source: "json_rpc_tools_list" };
+  if (Array.isArray(payload.tool_manifest?.tools)) return { tools: payload.tool_manifest.tools, source: "tool_manifest" };
+  if (payload.mcpServers && typeof payload.mcpServers === "object") {
+    return { tools: [], source: "mcp_client_config", serverCount: Object.keys(payload.mcpServers).length };
+  }
+  return { tools: [], source: "unknown" };
+}
+
+function propNames(schema) {
+  if (!schema || typeof schema !== "object") return [];
+  const properties = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+  return Object.keys(properties);
+}
+
+function schemaText(schema) {
+  try {
+    return JSON.stringify(schema || {}).toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function hasAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function buildMcpAuditReport(targetInfo) {
+  const { tools, source, serverCount } = extractMcpTools(targetInfo.payload);
+  const findings = [];
+  const add = (severity, code, message, details = {}) => findings.push({ severity, code, message, ...details });
+  if (source === "mcp_client_config") {
+    add(
+      "LOW",
+      "MCP_CLIENT_CONFIG_ONLY",
+      "MCP client config found; export or query tools/list for schema-level database risk review.",
+      { evidence: `${serverCount || 0} configured MCP server(s)` },
+    );
+  }
+  if (!tools.length && source !== "mcp_client_config") {
+    add("MEDIUM", "NO_TOOLS_FOUND", "No MCP tools were found in the target manifest or tools/list response.");
+  }
+
+  for (const tool of tools) {
+    const name = String(tool.name || tool.id || tool.title || "unnamed_tool");
+    const description = String(tool.description || "");
+    const inputSchema = tool.inputSchema || tool.input_schema || tool.parameters || {};
+    const outputSchema = tool.outputSchema || tool.output_schema || tool.resultSchema || tool.result_schema || null;
+    const props = propNames(inputSchema);
+    const propsLower = props.map((prop) => prop.toLowerCase());
+    const text = `${name} ${description} ${schemaText(inputSchema)} ${schemaText(outputSchema)}`.toLowerCase();
+    const writeTool = hasAny(text, [
+      /\b(writes?|written|updates?|updated|deletes?|deleted|inserts?|inserted|upserts?|upserted|mutates?|mutated|refunds?|refunded|waives?|waived|charges?|charged|credits?|credited|commits?|committed|settles?|settled|merges?|merged)\b/,
+      /(^|[._-])(approve|close|resolve|cancel)([._-]|$)/,
+    ]);
+    const readTool = hasAny(text, [/\b(read|get|list|query|inspect|fetch|search)\b/]);
+    const proposalBoundary = hasAny(text, [/\b(proposal|propose|approval|review_required|writeback|change[-_ ]?set|diff|evidence)\b/]);
+    const idempotency = hasAny(text, [/\b(idempotency|idempotent|request_id|requestid|idempotency_key|idempotencykey)\b/]);
+    const conflictGuard = hasAny(text, [/\b(expected_version|row_version|updated_at|etag|version|conflict_guard|conflict guard|optimistic)\b/]);
+
+    if (/(^|[._-])(execute_sql|exec_sql|run_query|raw_sql|sql_query|query_sql|execute_query)([._-]|$)/.test(name.toLowerCase())) {
+      add("HIGH", "GENERIC_SQL_TOOL", "Generic execute_sql or run_query-style database tool exposed.", { tool: name });
+    }
+    if (propsLower.some((prop) => ["sql", "query", "statement", "raw_sql"].includes(prop)) && writeTool) {
+      add("HIGH", "WRITE_ACCEPTS_SQL", "Write-capable tool accepts arbitrary SQL/query/statement input.", { tool: name, evidence: props.join(", ") });
+    }
+    if (propsLower.some((prop) => ["schema", "table", "table_name", "tablename", "column", "columns", "database", "db"].includes(prop))) {
+      add("HIGH", "MODEL_CONTROLLED_IDENTIFIER", "Tool accepts schema/table/column identifiers as ordinary model input.", { tool: name, evidence: props.join(", ") });
+    }
+    if (propsLower.some((prop) => ["tenant", "tenant_id", "tenantid"].includes(prop))) {
+      add("HIGH", "MODEL_CONTROLLED_TENANT", "Tool accepts tenant_id as ordinary model input instead of trusted session context.", { tool: name, evidence: props.join(", ") });
+    }
+    if (/(^|[._-])(approve|commit|settle|merge)[._-]?(proposal|write|change)|(^|[._-])(proposal|write|change)[._-]?(approve|commit|settle|merge)([._-]|$)/.test(name.toLowerCase())) {
+      add("HIGH", "MODEL_CALLABLE_APPROVAL", "Approval or commit operation is exposed as a model-callable MCP tool.", { tool: name });
+    }
+    if (writeTool && !proposalBoundary) {
+      add("HIGH", "NO_VISIBLE_PROPOSAL_BOUNDARY", "Write-capable tool has no visible proposal, approval, evidence, or writeback boundary.", { tool: name });
+    }
+    if (!outputSchema) {
+      add("MEDIUM", "NO_STRUCTURED_OUTPUT_SCHEMA", "Tool has no structured output schema visible in the manifest.", { tool: name });
+    }
+    if (writeTool && !idempotency) {
+      add("MEDIUM", "NO_IDEMPOTENCY_KEY", "Write/proposal tool has no visible idempotency or request-key metadata.", { tool: name });
+    }
+    if (writeTool && !conflictGuard) {
+      add("MEDIUM", "NO_CONFLICT_GUARD", "Write/proposal tool has no visible row-version or conflict-guard metadata.", { tool: name });
+    }
+    if (readTool && writeTool) {
+      add("MEDIUM", "AMBIGUOUS_READ_WRITE_TOOL", "Tool mixes read and write behavior ambiguously.", { tool: name });
+    }
+    if (!tool.annotations) {
+      add("LOW", "MISSING_TOOL_ANNOTATIONS", "Tool is missing descriptive MCP annotations. Annotations are hints, not enforcement.", { tool: name });
+    }
+  }
+
+  const severityRank = { HIGH: 0, MEDIUM: 1, LOW: 2 };
+  findings.sort((a, b) => severityRank[a.severity] - severityRank[b.severity] || String(a.tool || "").localeCompare(String(b.tool || "")) || a.code.localeCompare(b.code));
+  const summary = { high: 0, medium: 0, low: 0 };
+  for (const finding of findings) summary[finding.severity.toLowerCase()] += 1;
+  return {
+    ok: true,
+    target: targetInfo.target,
+    source,
+    inspected_at: new Date().toISOString(),
+    disclaimer: MCP_AUDIT_DISCLAIMER,
+    tool_count: tools.length,
+    summary,
+    findings,
+  };
+}
+
+function printMcpAudit(report, globals) {
+  if (globals.json) return print(report, globals);
+  console.log("Static MCP database risk review");
+  console.log(`Target: ${report.target}`);
+  console.log(`Tools inspected: ${report.tool_count}`);
+  console.log(`Summary: HIGH=${report.summary.high}  MEDIUM=${report.summary.medium}  LOW=${report.summary.low}`);
+  console.log(MCP_AUDIT_DISCLAIMER);
+  if (!report.findings.length) {
+    console.log("No matching database MCP risk patterns found. This is not a security guarantee.");
+    return;
+  }
+  console.log("\nFindings:");
+  for (const finding of report.findings) {
+    const tool = finding.tool ? `  tool=${finding.tool}` : "";
+    const evidence = finding.evidence ? `  evidence=${finding.evidence}` : "";
+    console.log(`${finding.severity.padEnd(6)} ${finding.code}${tool}${evidence}`);
+    console.log(`       ${finding.message}`);
+  }
+}
+
 async function main(argv = process.argv.slice(2)) {
   const { globals, args } = parse(argv);
   const [cmd, sub, third, ...rest] = args;
@@ -282,24 +539,35 @@ async function main(argv = process.argv.slice(2)) {
       const envHint = kind === "mysql" ? "APP_MYSQL_URL" : "APP_POSTGRES_URL";
       const name = flagValue(rest, "--name", defaultName);
       const url = resolveSecretRef(flagValue(rest, "--url", ""));
+      const cdcUrl = resolveSecretRef(flagValue(rest, "--cdc-url", ""));
       const ssl = flagValue(rest, "--ssl", "require");
-      const mode = flagValue(rest, "--mode", "read-only");
+      const mode = flagValue(rest, "--mode", "live_read");
       const projectId = scopedProject(globals);
       const databaseId = scopedDatabase(globals);
       if (!projectId || !databaseId) throw new Error("PROJECT_AND_DATABASE_REQUIRED: use --project <project_id> --db <database_id> or SYNAPSOR_PROJECT_ID/SYNAPSOR_DATABASE_ID");
       if (!url) throw new Error(`${kind.toUpperCase()}_URL_REQUIRED: usage \`synapsor sources create ${kind} --name ${defaultName} --url env:${envHint} --project <project> --db <database>\``);
-      return print(await request(globals, "POST", "/v1/control/external-sources", {
+      const body = {
         project_id: projectId,
         database_id: databaseId,
         kind,
         name,
         connection: { url, ssl_mode: ssl },
         mode,
-      }), globals);
+      };
+      if (cdcUrl) body.cdc_connection = { url: cdcUrl, ssl_mode: ssl };
+      if (mode === "cdc_mirror" || boolFlag(rest, "--cdc-ack")) body.cdc_acknowledged = true;
+      return print(await request(globals, "POST", "/v1/control/external-sources", body), globals);
     }
-    if (["test", "inspect", "generate", "doctor", "disable"].includes(sub)) {
+    if (["test", "inspect", "generate", "doctor", "disable", "cdc-status", "cdc-snapshot", "cdc-poll"].includes(sub)) {
       const sourceId = await resolveSourceId(globals, third);
       if (sub === "test") return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/test`, {}), globals);
+      if (sub === "cdc-status") return print(await request(globals, "GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/cdc/status`), globals);
+      if (sub === "cdc-snapshot" || sub === "cdc-poll") {
+        const tables = csvFlag(rest, "--tables");
+        const body = { cdc_acknowledged: true };
+        if (tables.length) body.tables = tables;
+        return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/cdc/${sub === "cdc-snapshot" ? "snapshot" : "poll"}`, body), globals);
+      }
       if (sub === "inspect") {
         const schema = flagValue(rest, "--schema", "public");
         const database = flagValue(rest, "--database", "");
@@ -340,10 +608,10 @@ async function main(argv = process.argv.slice(2)) {
       const database = flagValue(rest, "--database", "");
       const tables = csvFlag(rest, "--tables");
       const tenantColumn = flagValue(rest, "--tenant-column", "");
-      const mode = flagValue(rest, "--mode", "live-read");
+      const mode = flagValue(rest, "--mode", "live_read");
       if (!tables.length) throw new Error("TABLES_REQUIRED: pass --tables tickets,customers,policy_chunks");
       if (!tenantColumn && !rest.includes("--single-tenant")) throw new Error("TENANT_COLUMN_REQUIRED: pass --tenant-column tenant_id or --single-tenant");
-      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/import`, {
+      const body = {
         tables: tables.map((table) => ({
           ...(database ? { database } : {}),
           schema,
@@ -354,10 +622,17 @@ async function main(argv = process.argv.slice(2)) {
           single_tenant: rest.includes("--single-tenant"),
           mode,
         })),
-      }), globals);
+      };
+      if (mode === "cdc_mirror" || boolFlag(rest, "--cdc-ack")) body.cdc_acknowledged = true;
+      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/import`, body), globals);
     }
   }
 
+  if (cmd === "mcp" && sub === "audit") {
+    const targetInfo = await loadMcpAuditTarget(third, rest);
+    return printMcpAudit(buildMcpAuditReport(targetInfo), globals);
+  }
+
   if (cmd === "sql") {
     const db = globals.db || "";
     let sql = args.slice(1).join(" ").trim();
@@ -408,8 +683,8 @@ Usage:
   synapsor projects create <name>
   synapsor db list --project <project>
   synapsor db create <name> --project <project>
-  synapsor sources create postgres --name app_postgres --url env:APP_POSTGRES_URL --ssl require --mode read-only --project <project> --db <database>
-  synapsor sources create mysql --name app_mysql --url env:APP_MYSQL_URL --ssl require --mode read-only --project <project> --db <database>
+  synapsor sources create postgres --name app_postgres --url env:APP_POSTGRES_URL --ssl require --mode live_read --project <project> --db <database>
+  synapsor sources create mysql --name app_mysql --url env:APP_MYSQL_URL --ssl require --mode live_read --project <project> --db <database>
   synapsor sources test app_postgres --project <project>
   synapsor sources inspect app_postgres --schema public --project <project>
   synapsor sources inspect app_mysql --database shopdb --project <project>
@@ -421,6 +696,9 @@ Usage:
   synapsor sources show app_postgres --project <project>
   synapsor sources doctor app_postgres --project <project>
   synapsor sources disable app_postgres --project <project> --yes
+  synapsor mcp audit ./tools-manifest.json
+  synapsor mcp audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --json
+  synapsor mcp audit 'stdio:node ./server.mjs' --timeout-ms 5000
   synapsor sql --db <database> "SELECT 1;"
   synapsor sql --db <database> --file ./query.sql
   synapsor invoke <capability> --db <database> --json '{"ticket_id":"TICK-1001"}'
@@ -430,6 +708,13 @@ Usage:
   synapsor proposal reject <proposal-handle> --db <database> --yes
   synapsor replay <run-id> --db <database>
 
+Preview/dev CDC commands:
+  These are not the current public customer connector path. Use live_read unless you are running a reviewed dev/test CDC smoke.
+  synapsor sources import app_postgres --schema public --tables tickets --tenant-column tenant_id --mode cdc_mirror --cdc-ack --project <project>
+  synapsor sources cdc-snapshot app_postgres --tables external_support.tickets --project <project>
+  synapsor sources cdc-poll app_postgres --tables external_support.tickets --project <project>
+  synapsor sources cdc-status app_postgres --project <project>
+
 Environment:
   SYNAPSOR_API_KEY, SYNAPSOR_BASE_URL
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/client",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Node.js SDK for Synapsor, the agent-native database for auditable AI applications",
   "type": "module",
   "main": "./synapsor.mjs",

package/synapsor.mjs

@@ -19,6 +19,17 @@ export {
   PROTOCOL_VERSION,
 };
 
+export const WRITEBACK_LEASE_EXPIRED = "WRITEBACK_LEASE_EXPIRED";
+export const WRITEBACK_ALREADY_COMPLETED = "WRITEBACK_ALREADY_COMPLETED";
+export const WRITEBACK_CONFLICT = "WRITEBACK_CONFLICT";
+export const WRITEBACK_SAFETY_FAILURE = "WRITEBACK_SAFETY_FAILURE";
+export const WRITEBACK_ERROR_CODES = Object.freeze([
+  WRITEBACK_LEASE_EXPIRED,
+  WRITEBACK_ALREADY_COMPLETED,
+  WRITEBACK_CONFLICT,
+  WRITEBACK_SAFETY_FAILURE,
+]);
+
 export class SynapsorError extends Error {
   constructor(
     message,
@@ -80,6 +91,7 @@ export class Synapsor {
     this.apiKey = apiKey;
     this.process = process;
     this.timeoutMs = timeoutMs;
+    this.agentActivity = new AgentActivityNamespace(this);
     this.agentRuns = new AgentRunsNamespace(this);
     this.externalActions = new ExternalActionsNamespace(this);
     this.evals = new AgentEvalsNamespace(this);
@@ -268,6 +280,13 @@ export class Synapsor {
     return results.at(-1).result?.rows ?? [];
   }
 
+  async searchAgentActivity(filters = {}, options = {}) {
+    return this.query(buildAgentActivitySearchSql(filters, options), {
+      session: options.session,
+      asOf: options.asOf ?? options.as_of,
+    });
+  }
+
   async invokeAgentCapability(capability, args = {}, {
     session = undefined,
     traceId = undefined,
@@ -636,6 +655,10 @@ export class Synapsor {
     });
   }
 
+  async listAdapterTools(adapter, options = {}) {
+    return this.adapterTools(adapter, options);
+  }
+
   async callAdapterTool(adapter, tool, {
     arguments: args = {},
     runId = undefined,
@@ -661,6 +684,138 @@ export class Synapsor {
     return this.request("POST", "/v1/agent/adapters/call-tool", payload);
   }
 
+  async createWritebackRunnerToken(sourceId, {
+    runnerId = undefined,
+    runner_id = undefined,
+    tokenId = undefined,
+    token_id = undefined,
+    permissions = undefined,
+    expiresAt = undefined,
+    expires_at = undefined,
+  } = {}) {
+    const payload = {};
+    const runner = runnerId ?? runner_id;
+    const token = tokenId ?? token_id;
+    const expiry = expiresAt ?? expires_at;
+    if (runner !== undefined) payload.runner_id = runner;
+    if (token !== undefined) payload.token_id = token;
+    if (permissions !== undefined) payload.permissions = permissions;
+    if (expiry !== undefined) payload.expires_at = expiry;
+    return this.request("POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens`, payload);
+  }
+
+  async createRunnerToken(sourceId, options = {}) {
+    return this.createWritebackRunnerToken(sourceId, options);
+  }
+
+  async listWritebackRunnerTokens(sourceId) {
+    return this.request("GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens`);
+  }
+
+  async listWritebackRunners(sourceId) {
+    return this.request("GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runners`);
+  }
+
+  async listRunners(sourceId) {
+    return this.listWritebackRunners(sourceId);
+  }
+
+  async revokeWritebackRunnerToken(sourceId, tokenId, { reason = undefined } = {}) {
+    const payload = {};
+    if (reason !== undefined) payload.reason = reason;
+    return this.request("POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/writeback-runner-tokens/${encodeURIComponent(tokenId)}/revoke`, payload);
+  }
+
+  async listExternalWritebackProposals({
+    projectId = undefined,
+    project_id = undefined,
+    sourceId = undefined,
+    source_id = undefined,
+    status = undefined,
+    limit = undefined,
+  } = {}) {
+    return this.request("GET", withQuery("/v1/control/external-writebacks/proposals", {
+      project_id: projectId ?? project_id,
+      source_id: sourceId ?? source_id,
+      status,
+      limit,
+    }));
+  }
+
+  async getExternalWritebackProposal(proposalId) {
+    return this.request("GET", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}`);
+  }
+
+  async getProposal(proposalId) {
+    return this.getExternalWritebackProposal(proposalId);
+  }
+
+  async createExternalWritebackProposal(payload) {
+    return this.request("POST", "/v1/control/external-writebacks/proposals", payload);
+  }
+
+  async transitionExternalWritebackProposal(proposalId, action, payload = {}) {
+    return this.request("POST", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}/${encodeURIComponent(action)}`, payload);
+  }
+
+  async approveExternalWritebackProposal(proposalId, payload = {}) {
+    return this.transitionExternalWritebackProposal(proposalId, "approve", payload);
+  }
+
+  async rejectExternalWritebackProposal(proposalId, payload = {}) {
+    return this.transitionExternalWritebackProposal(proposalId, "reject", payload);
+  }
+
+  async recordExternalWritebackApplyResult(proposalId, payload) {
+    return this.request("POST", `/v1/control/external-writebacks/proposals/${encodeURIComponent(proposalId)}/apply-result`, payload);
+  }
+
+  async doctorWritebackRunner() {
+    return this.request("GET", "/v1/writeback/runner/doctor");
+  }
+
+  async registerRunner(payload) {
+    return this.request("POST", "/v1/runner/register", payload);
+  }
+
+  async heartbeatRunner(payload) {
+    return this.request("POST", "/v1/runner/heartbeat", payload);
+  }
+
+  async claimWritebackJob({
+    sourceId = undefined,
+    source_id = undefined,
+    limit = undefined,
+    leaseSeconds = undefined,
+    lease_seconds = undefined,
+  } = {}) {
+    const payload = {};
+    const source = sourceId ?? source_id;
+    const lease = leaseSeconds ?? lease_seconds;
+    if (source !== undefined) payload.source_id = source;
+    if (limit !== undefined) payload.limit = Number(limit);
+    if (lease !== undefined) payload.lease_seconds = Number(lease);
+    return this.request("POST", "/v1/writeback/jobs/claim", payload);
+  }
+
+  async renewWritebackLease(jobId, {
+    leaseSeconds = undefined,
+    lease_seconds = undefined,
+  } = {}) {
+    const payload = {};
+    const lease = leaseSeconds ?? lease_seconds;
+    if (lease !== undefined) payload.lease_seconds = Number(lease);
+    return this.request("POST", `/v1/writeback/jobs/${encodeURIComponent(jobId)}/heartbeat`, payload);
+  }
+
+  async completeWritebackJob(jobId, result) {
+    return this.request("POST", `/v1/writeback/jobs/${encodeURIComponent(jobId)}/result`, result);
+  }
+
+  async recordWritebackJobResult(jobId, result) {
+    return this.completeWritebackJob(jobId, result);
+  }
+
   async traceAgentRun(runId, { session = undefined } = {}) {
     return this.request("POST", "/v1/agent/runs/trace", {
       run_id: runId,
@@ -1045,6 +1200,10 @@ export class Synapsor {
     return this.request("POST", "/v1/agent/runs/replay", payload);
   }
 
+  async getReplay(runId, options = {}) {
+    return this.replayAgentRun(runId, options);
+  }
+
   async proposalLifecycle(action, proposal, { session = undefined, promoteBranch = undefined, promote_branch = undefined, targetBranch = undefined, target_branch = undefined, settlementPolicy = undefined, settlement_policy = undefined } = {}) {
     const payload = {
       proposal,
@@ -1131,6 +1290,16 @@ export class Synapsor {
   }
 }
 
+class AgentActivityNamespace {
+  constructor(client) {
+    this.client = client;
+  }
+
+  async search(filters = {}, options = {}) {
+    return this.client.searchAgentActivity(filters, options);
+  }
+}
+
 class AgentRunsNamespace {
   constructor(client) {
     this.client = client;
@@ -1396,6 +1565,60 @@ function typedSql(value) {
   return `${identifier(ref.type)}(${sqlLiteral(String(ref.id ?? ""))})`;
 }
 
+function buildAgentActivitySearchSql(filters = {}, options = {}) {
+  const where = [];
+  const addFilter = (column, ...keys) => {
+    for (const key of keys) {
+      if (filters[key] !== undefined && filters[key] !== null && filters[key] !== "") {
+        where.push(`${column} = ${sqlScalar(filters[key])}`);
+        return;
+      }
+    }
+  };
+  addFilter("activity_kind", "activityKind", "activity_kind");
+  addFilter("tenant_id", "tenantId", "tenant_id");
+  addFilter("principal", "principal");
+  addFilter("workflow", "workflow");
+  addFilter("capability", "capability");
+  addFilter("run_id", "runId", "run_id");
+  addFilter("evidence_bundle_id", "evidenceBundleId", "evidence_bundle_id");
+  addFilter("proposal_id", "proposalId", "proposal_id");
+  addFilter("replay_id", "replayId", "replay_id");
+  addFilter("business_object_type", "businessObjectType", "business_object_type");
+  addFilter("business_object_id", "businessObjectId", "business_object_id");
+  addFilter("query_fingerprint", "queryFingerprint", "query_fingerprint");
+
+  const timeRange = filters.timeRange ?? filters.time_range ?? {};
+  const from = timeRange.from ?? filters.createdFrom ?? filters.created_from;
+  const to = timeRange.to ?? filters.createdTo ?? filters.created_to;
+  if (from !== undefined && from !== null && from !== "") {
+    where.push(`created_at >= ${sqlScalar(from)}`);
+  }
+  if (to !== undefined && to !== null && to !== "") {
+    where.push(`created_at <= ${sqlScalar(to)}`);
+  }
+
+  const requestedLimit = options.limit ?? filters.limit ?? 50;
+  const limit = Number.isInteger(Number(requestedLimit)) && Number(requestedLimit) > 0
+    ? Math.min(Number(requestedLimit), 500)
+    : 50;
+  const whereSql = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+  return `SELECT * FROM AGENT ACTIVITY${whereSql} ORDER BY created_at DESC LIMIT ${limit};`;
+}
+
+function sqlScalar(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(Math.trunc(value));
+  }
+  if (typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "TRUE" : "FALSE";
+  }
+  return sqlLiteral(String(value));
+}
+
 function sqlLiteral(value) {
   return `'${String(value).replaceAll("'", "''")}'`;
 }
@@ -1407,6 +1630,17 @@ function identifier(value) {
   return value;
 }
 
+function withQuery(path, params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") {
+      query.set(key, String(value));
+    }
+  }
+  const queryText = query.toString();
+  return queryText ? `${path}?${queryText}` : path;
+}
+
 function repoRoot() {
   return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 }