@synapsor/client 0.1.4 → 0.1.5

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
@@ -163,6 +187,7 @@ and reports `applied`, `conflict`, or `failed` back to Synapsor idempotently.
 - `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

@@ -172,6 +172,10 @@ function csvFlag(args, name) {
   return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
 }
 
+function boolFlag(args, name) {
+  return args.includes(name);
+}
+
 function resolveSecretRef(value) {
   const text = String(value || "").trim();
   if (text.startsWith("env:")) {
@@ -282,24 +286,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 +355,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,7 +369,9 @@ 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);
     }
   }
 
@@ -408,8 +425,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>
@@ -430,6 +447,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.5",
   "description": "Node.js SDK for Synapsor, the agent-native database for auditable AI applications",
   "type": "module",
   "main": "./synapsor.mjs",

package/synapsor.mjs

@@ -80,6 +80,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 +269,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,
@@ -1131,6 +1139,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 +1414,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("'", "''")}'`;
 }