@synapsor/runner 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -7,6 +7,25 @@ Runner lets an MCP agent inspect scoped data and request database-backed
 business actions without receiving raw SQL, write credentials, approval tools,
 or commit tools.
 
+## Alpha Operational Notes
+
+These are current alpha requirements, not hidden behavior:
+
+- Writeback with `--config ./synapsor.runner.json` reads the trusted writer
+  connection from the source `write_url_env`, for example
+  `SYNAPSOR_DATABASE_WRITE_URL`. `SYNAPSOR_DATABASE_URL` is only the legacy
+  fallback when you run direct worker/apply flows without a local config.
+- `synapsor-runner mcp serve-http` is a small authenticated JSON-RPC endpoint
+  for `tools/list`, `tools/call`, and `resources/read`. It is not full MCP
+  Streamable HTTP and does not implement the `initialize`/SSE handshake. Use
+  stdio MCP for standard local MCP clients, or wrap the HTTP endpoint like the
+  OpenAI HTTP example.
+- Direct SQL writeback creates or writes `synapsor_writeback_receipts` for
+  idempotency and replay. The trusted writer needs permission for that table,
+  or an administrator must pre-create it and grant access. Use an app-owned
+  `http_handler` or `command_handler` if Runner should not create receipt
+  tables in your application schema.
+
 ```text
 AI agent or MCP client
 (Claude, Cursor, OpenAI Agents SDK, LangGraph)
@@ -171,6 +190,12 @@ HTTP defaults to `127.0.0.1:8765`, requires bearer auth by default, and should
 use private networking, TLS, and rate limits before being exposed beyond a
 local machine.
 
+HTTP alpha scope: `serve-http` is a JSON-RPC endpoint for `tools/list`,
+`tools/call`, and `resources/read`. It is not full MCP Streamable HTTP and does
+not implement `initialize`/SSE. If an SDK HTTP MCP client expects that
+handshake, use stdio mode or wrap the HTTP endpoint like the OpenAI HTTP
+example.
+
 OpenAI Agents SDK examples:
 
 ```text
@@ -347,6 +372,13 @@ your application service already owns business writes, configure an
 `http_handler` or `command_handler` executor. Approval still happens outside
 MCP, and the handler returns an applied/conflict/failed receipt for replay.
 
+For direct SQL writeback, set the writer env var named by the source
+`write_url_env`, for example `SYNAPSOR_DATABASE_WRITE_URL`. Runner also creates
+or writes `synapsor_writeback_receipts` for idempotency/replay, so the writer
+needs permission for that receipt table or an administrator must pre-create and
+grant it. Use app-owned handlers when you do not want Runner creating receipt
+tables in your application schema.
+
 ## Command Name
 
 This package installs `synapsor-runner` as the OSS runner binary. The `synapsor`

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type WritebackJob } from "@synapsor-runner/protocol";
 import { type SchemaInspection } from "@synapsor-runner/schema-inspector";
 export declare function main(argv: string[]): Promise<number>;
 type WizardAsk = (question: string, defaultValue?: string) => Promise<string>;
@@ -8,5 +9,6 @@ export declare function runInitWizard(args: string[], options?: {
     inspection?: SchemaInspection;
     stdout?: Pick<NodeJS.WriteStream, "write">;
 }): Promise<number>;
+export declare function resolveSqlWriteDatabaseUrl(job: WritebackJob, configPath: string, env: NodeJS.ProcessEnv): Promise<string>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+BA,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CAiLjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CAiLjB;AAsyCD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}

package/dist/runner.mjs

@@ -2685,7 +2685,7 @@ function createMcpRuntime(config, options = {}) {
 }
 function createSynapsorMcpServer(runtime) {
   const server = new McpServer(
-    { name: "synapsor-runner", version: "0.1.0-alpha.7" },
+    { name: "synapsor-runner", version: "0.1.0-alpha.9" },
     { capabilities: { tools: {}, resources: {} } }
   );
   if (runtime.config.mode === "cloud") {
@@ -3748,7 +3748,7 @@ function failed(job, config, code) {
 }
 var mysqlAdapter = {
   async doctor(config) {
-    if (!config.databaseUrl) return { ok: false, details: { error: "SYNAPSOR_DATABASE_URL required" } };
+    if (!config.databaseUrl) return { ok: false, details: { error: "database URL required; local config apply reads source.write_url_env, legacy workers use SYNAPSOR_DATABASE_URL" } };
     const connection = await mysql2.createConnection({ uri: config.databaseUrl, dateStrings: true });
     try {
       const [rows] = await connection.query("SELECT VERSION() AS version");
@@ -3963,7 +3963,7 @@ function failed2(job, config, code) {
 }
 var postgresAdapter = {
   async doctor(config) {
-    if (!config.databaseUrl) return { ok: false, details: { error: "SYNAPSOR_DATABASE_URL required" } };
+    if (!config.databaseUrl) return { ok: false, details: { error: "database URL required; local config apply reads source.write_url_env, legacy workers use SYNAPSOR_DATABASE_URL" } };
     const pool = new Pool2({ connectionString: config.databaseUrl });
     const client = await pool.connect();
     try {
@@ -7386,12 +7386,13 @@ async function apply(args) {
     }
     await verifyLocalWritebackAuthority(job, configPath, storePath);
   }
+  const databaseUrl = configPath ? await resolveSqlWriteDatabaseUrl(job, configPath, process2.env) : process2.env.SYNAPSOR_DATABASE_URL || "";
   const config = {
     controlPlaneUrl: process2.env.SYNAPSOR_CONTROL_PLANE_URL || "http://localhost:8000",
     runnerToken: process2.env.SYNAPSOR_RUNNER_TOKEN || "local-dry-run-token",
     runnerId: process2.env.SYNAPSOR_RUNNER_ID || "local-runner",
     sourceId: process2.env.SYNAPSOR_SOURCE_ID || job.source_id,
-    databaseUrl: process2.env.SYNAPSOR_DATABASE_URL || "",
+    databaseUrl,
     engine: job.engine,
     pollIntervalMs: Number(process2.env.SYNAPSOR_POLL_INTERVAL_MS || "5000"),
     logLevel: process2.env.SYNAPSOR_LOG_LEVEL || "info",
@@ -7468,12 +7469,13 @@ async function applyProposal(args, proposalId) {
 async function applySqlJob(job, configPath, storePath, dryRun, env = process2.env) {
   const parsedJob = parseWritebackJob(job);
   await verifyLocalWritebackAuthority(parsedJob, configPath, storePath);
+  const databaseUrl = await resolveSqlWriteDatabaseUrl(parsedJob, configPath, env);
   const config = {
     controlPlaneUrl: env.SYNAPSOR_CONTROL_PLANE_URL || "http://localhost:8000",
     runnerToken: env.SYNAPSOR_RUNNER_TOKEN || "local-dry-run-token",
     runnerId: env.SYNAPSOR_RUNNER_ID || "local-runner",
     sourceId: env.SYNAPSOR_SOURCE_ID || parsedJob.source_id,
-    databaseUrl: env.SYNAPSOR_DATABASE_URL || "",
+    databaseUrl,
     engine: parsedJob.engine,
     pollIntervalMs: Number(env.SYNAPSOR_POLL_INTERVAL_MS || "5000"),
     logLevel: env.SYNAPSOR_LOG_LEVEL || "info",
@@ -7491,6 +7493,13 @@ async function applySqlJob(job, configPath, storePath, dryRun, env = process2.en
   }
   return result;
 }
+async function resolveSqlWriteDatabaseUrl(job, configPath, env) {
+  const config = JSON.parse(await fs3.readFile(configPath, "utf8"));
+  const source = config.sources?.[job.source_id];
+  const writeUrlEnv = source?.write_url_env;
+  if (writeUrlEnv && env[writeUrlEnv]) return env[writeUrlEnv] ?? "";
+  return env.SYNAPSOR_DATABASE_URL || "";
+}
 function sourceNeedsSqlWriteback(config, sourceName) {
   return (config.capabilities ?? []).some((capability) => {
     if (capability.kind !== "proposal" || capability.source !== sourceName) return false;
@@ -7977,7 +7986,7 @@ async function cloudConnect(args) {
     return 1;
   }
   const runnerId = String(parsed.cloud.runner_id || process2.env.SYNAPSOR_RUNNER_ID || "synapsor_runner_local").trim();
-  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.7").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.9").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -11435,7 +11444,7 @@ function starterCloudConfig() {
       base_url_env: "SYNAPSOR_CLOUD_BASE_URL",
       runner_token_env: "SYNAPSOR_RUNNER_TOKEN",
       runner_id: "synapsor_runner_local",
-      runner_version: "0.1.0-alpha.7",
+      runner_version: "0.1.0-alpha.9",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -11560,7 +11569,10 @@ Start the stdio MCP server for local MCP clients such as Claude Desktop, Cursor,
   export SYNAPSOR_RUNNER_HTTP_TOKEN=...
   ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8765] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN]
 
-Start the HTTP MCP server for app/server deployments. Bearer auth is required by default.
+Start the HTTP JSON-RPC MCP endpoint for app/server deployments. Bearer auth is required by default.
+
+Alpha scope: supports POST /mcp methods tools/list, tools/call, and resources/read.
+It does not implement full MCP Streamable HTTP initialize/SSE sessions.
 
 Security:
   - Defaults to 127.0.0.1:8765.
@@ -11643,6 +11655,14 @@ Inspect local query fingerprints, table names, row counts, and redacted-paramete
   ${cmd} apply --job job.json --config ./synapsor.runner.json --store ./.synapsor/local.db
 
 Apply an approved proposal through guarded writeback. Requires a trusted write credential.
+
+With --config, the writer connection comes from source.write_url_env, such as
+SYNAPSOR_DATABASE_WRITE_URL. SYNAPSOR_DATABASE_URL is only the legacy fallback
+for direct worker/apply flows without a local config.
+
+Direct SQL writeback creates or writes synapsor_writeback_receipts for
+idempotency and replay, so the trusted writer needs permission for that table
+or an administrator must pre-create and grant it.
 `,
     replay: `Usage:
   ${cmd} replay list [--tenant acme] [--object invoice:INV-3001]
@@ -11714,5 +11734,6 @@ function formatCliErrorHint(message) {
 }
 export {
   main,
+  resolveSqlWriteDatabaseUrl,
   runInitWizard
 };

package/docs/getting-started-own-database.md

@@ -368,10 +368,14 @@ Apply through the trusted worker path with a separate writer credential:
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
 SYNAPSOR_ENGINE=postgres \
-SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
 npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+For `apply --job ... --config ...`, Runner reads the write credential from the
+source `write_url_env` in `synapsor.runner.json`, such as
+`SYNAPSOR_DATABASE_WRITE_URL`. `SYNAPSOR_DATABASE_URL` is accepted only as a
+legacy fallback for direct worker flows that do not pass a local config.
+
 If your application/API should own the business write, use an `http_handler`
 executor instead of direct SQL writeback. Handler URLs and bearer tokens come
 from environment variables, and the handler receives a structured proposal/job

package/docs/http-mcp.md

@@ -6,6 +6,13 @@ needs to connect to a long-running Synapsor Runner service.
 Use stdio MCP when a local MCP client such as Claude Desktop, Cursor, or a
 local agent tool can launch Synapsor Runner directly.
 
+Current alpha scope: `serve-http` exposes a small authenticated JSON-RPC
+endpoint at `POST /mcp` for `tools/list`, `tools/call`, and `resources/read`.
+It is not the full MCP Streamable HTTP transport and does not implement an
+`initialize`/SSE session handshake. If your SDK expects full HTTP MCP
+initialization, use stdio mode or wrap this endpoint with a thin tool/function
+adapter like the OpenAI HTTP example.
+
 ## Start The HTTP Server
 
 ```bash
@@ -196,5 +203,6 @@ examples/openai-agents-stdio/
 The stdio example uses the MCP client integration from the OpenAI Agents SDK
 when available. The HTTP example uses a minimal JSON-RPC client wrapped as an
 OpenAI function tool because native HTTP MCP client support can vary by SDK
-version. The boundary is the same: the agent calls a semantic Synapsor tool,
-not raw SQL.
+version and Runner's HTTP alpha endpoint is intentionally limited to JSON-RPC
+tool/resource calls. The boundary is the same: the agent calls a semantic
+Synapsor tool, not raw SQL.

package/docs/local-mode.md

@@ -158,11 +158,15 @@ npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123
 The generated job uses the public `synapsor.writeback-job.v1` protocol and can be applied by the guarded worker:
 
 ```bash
+export SYNAPSOR_DATABASE_WRITE_URL="postgresql://writer:<password>@localhost:5432/app"
 SYNAPSOR_ENGINE=postgres \
-SYNAPSOR_DATABASE_URL="postgresql://writer:<password>@localhost:5432/app" \
 npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+When `--config` is passed, direct SQL writeback reads the writer connection from
+the source `write_url_env` in that config. `SYNAPSOR_DATABASE_URL` is only a
+legacy fallback for direct worker flows without a local runner config.
+
 Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally. Replay then links the proposal, approval, writeback job, applied/conflict/failed receipt, evidence, and query audit.
 
 Reject:

package/docs/mcp-client-setup.md

@@ -38,6 +38,11 @@ Stdio keeps the MCP protocol on process stdin/stdout and is the simplest local
 developer path. HTTP uses JSON-RPC over an authenticated `/mcp` endpoint and is
 better for app/server deployments.
 
+Important alpha limitation: HTTP mode is not full MCP Streamable HTTP. It does
+not implement `initialize` or an SSE session handshake. Standard SDK HTTP MCP
+clients that require initialization may fail. Use stdio for those clients, or
+call Runner's HTTP JSON-RPC endpoint through a thin app/server wrapper.
+
 HTTP requires bearer auth by default:
 
 ```bash

package/docs/security-boundary.md

@@ -65,6 +65,13 @@ outside the model-facing MCP server and verifies:
 
 If any authority check cannot be verified, the write fails closed.
 
+For direct SQL writeback, the writer connection is the env var named by the
+source `write_url_env` in `synapsor.runner.json`. Direct SQL writeback also
+creates or writes `synapsor_writeback_receipts` for idempotency and replay, so
+the writer needs permission for that receipt table or an administrator must
+pre-create and grant it. If your database policy forbids Runner-managed receipt
+tables, use an app-owned `http_handler` or `command_handler` executor instead.
+
 When a capability uses an `http_handler` or `command_handler` executor, the
 same approval boundary applies. The runner sends a structured proposal/job
 payload to the configured handler after approval. Handler URLs, commands, bearer

package/docs/writeback-executors.md

@@ -24,6 +24,38 @@ It applies one guarded `UPDATE` through the database adapter:
 Use this when the trusted runner is allowed to update the selected business row
 directly.
 
+The source config controls which writer env var is used:
+
+```json
+{
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  }
+}
+```
+
+For `synapsor-runner apply --job ... --config ...`, set the env var named by
+`write_url_env`. `SYNAPSOR_DATABASE_URL` is only a legacy fallback for direct
+worker flows that do not pass a local config.
+
+Direct SQL writeback also stores idempotency receipts in the source database.
+By default it runs:
+
+```sql
+CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts (...);
+```
+
+That means the writer needs permission to create and write that receipt table in
+the target schema/database, or the table must be pre-created by an administrator
+and granted to the writer. If you do not want Runner to create a table in the
+application schema, create a dedicated schema/database for receipts where your
+database policy allows it, or use `http_handler`/`command_handler` so your
+application owns receipt storage and business writes.
+
 ## `http_handler`
 
 Use `http_handler` when your application/API should own business execution.

package/examples/openai-agents-http/README.md

@@ -7,9 +7,11 @@ Use HTTP when your agent runs as an app/server and should connect to Runner
 over a local/private network endpoint instead of launching a stdio child
 process.
 
-Native HTTP MCP client support can vary by SDK version. This example is honest
-about that: it uses the OpenAI Agents SDK for the agent and wraps Synapsor's
-HTTP MCP JSON-RPC endpoint as an OpenAI function tool.
+Runner's HTTP alpha endpoint is a small authenticated JSON-RPC surface for
+`tools/list`, `tools/call`, and `resources/read`. It is not the full MCP
+Streamable HTTP transport and does not implement `initialize`/SSE. This example
+therefore uses the OpenAI Agents SDK for the agent and wraps Synapsor's HTTP
+JSON-RPC endpoint as an OpenAI function tool.
 
 The model still sees a semantic action. It does not receive raw SQL, database
 URLs, write credentials, approval tools, or commit tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",