@synapsor/runner 0.1.0-alpha.11 → 0.1.0-alpha.14

package/docs/rfcs/003-integrator-feedback-teardown.md

@@ -0,0 +1,97 @@
+ here's the detailed teardown of the OSS synapsor-runner specifically, split into (A) what trips up a serious dev, and (B) how an LLM actually experiences it. Everything below is from things I hit building and live-testing the lab, not theory. I'll keep Cloud-domain stuff out of it (RBAC, central ledger, etc. — those belong in hosted).
+
+A. Limitations for a serious dev/user
+
+1. Config authoring is the real onboarding cost.
+synapsor.runner.json is powerful but you mostly hand-write it. init --wizard exists, but multi-capability, executor-backed configs are manual, and there's no published JSON schema or one-page field reference — I learned the shape by running init and reading dist/runner.mjs. A serious dev wants: a versioned JSON Schema (so editors autocomplete + validate), and a "capability authoring" doc covering read vs proposal, patch (fixed/from_arg), allowed_columns, numeric_bounds, conflict_guard, executor.
+
+2. Env-var sprawl + historical credential ambiguity.
+There are a lot: SYNAPSOR_DATABASE_READ_URL, _WRITE_URL, legacy SYNAPSOR_DATABASE_URL, TENANT_ID, PRINCIPAL, RUNNER_HTTP_TOKEN, plus per-executor *_HANDLER_URL/_TOKEN. The apply-uses-SYNAPSOR_DATABASE_URL-vs-write_url_env thing cost me real debugging on alpha.6 (now documented). doctor is good but only checks presence; it doesn't prove the write path (attempt a rolled-back probe write with the writer cred) or handler reachability.
+
+3. Store ↔ server lifecycle is a footgun.
+The SQLite store is shared state, and the running server holds it open. Deleting/resetting the store under a live server gives corrupt/confusing behavior — I hit "database access issue" surfaced to the agent because I reset the store without restarting the server. There's no lock, warning, or coordinated reset. Also: running serve-http + serve-streamable-http on one store simultaneously is asking for contention, with no guardrail.
+
+4. The receipt-table permission gotcha.
+Direct writeback does CREATE TABLE IF NOT EXISTS synapsor_writeback_receipts, which a least-privilege writer can't do (PG15+ no CREATE on public). Now documented, but doctor could detect it and print the exact GRANT/DDL (or a flag to pre-create). I had to invent the dedicated-schema trick myself.
+
+5. App-owned handlers re-implement security by hand.
+The executor contract is "match the example": you must re-check tenant, parse change_set, enforce the expected_version stale-row guard, and do idempotency yourself. It's easy to write an insecure handler (skip the version check, forget tenant scope). There's no handler SDK/helper and no request signing — the only auth is a bearer token, so the handler trusts the POST body's tenant/version. A @synapsor/handler helper (verify + parse + enforce guards, optional HMAC signature) would remove a whole class of mistakes.
+
+6. Versioning discipline.
+@alpha is a moving tag and behavior changed meaningfully across alpha.6→11 (transport, arg types string→number, credential resolution). I had to pin and bump six times. A stable channel + changelog + semver promise is table stakes before serious devs build on it.
+
+7. Two serve modes are easy to confuse.
+serve-http (lightweight JSON-RPC, not real MCP) vs serve-streamable-http (spec MCP) on different ports, plus --alias-mode. I pointed the SDK at the wrong one. Consider: make serve-streamable-http the headline, rename serve-http to something like serve-bridge/--legacy-jsonrpc, and have mcp client-config always pair the client with the matching server command (it does for openai-agents — good).
+
+8. Observability is CLI-only.
+replay/activity are genuinely nice, but there's no structured event stream/webhook for proposal.created/approved/applied. Even a local webhook would let people build a review UI or Slack-notify a reviewer without polling. (The full ledger is Cloud's job; a local event hook isn't.)
+
+B. How easy is it for an LLM to use/understand?
+
+This is where you have the most leverage, and I have direct evidence.
+
+1. Tool descriptions are the single biggest reliability lever — and they're currently generic.
+On the JSON-RPC path my agent was reliable because my function-tool docstrings were rich ("Read an outage event — window, affected plan, credit policy; use this to decide if a waiver is justified"). On the native streamable path the model stalled and refused to propose, and a big reason was the auto-generated description: "Read public.outage_events through a reviewed Synapsor capability with trusted tenant context and evidence." That tells the model the plumbing, not what the tool is for or what it returns. The model didn't realize the outage tool gives it the policy it needed.
+→ Let capability config carry a model-facing description + per-arg descriptions + an optional "returns/when to use" hint, and surface them in tools/list. This alone would have made my streamable runs reliable. Right now authors can't easily improve what the model sees.
+
+2. Inconsistent result envelopes hurt the model (and the code).
+Success = {status:"ok", data:{...}, evidence_bundle_id, trusted_context, ...}. Not-found = {ok:false, code, error}. Two different shapes for the same tool means the model (and my client) must branch on multiple keys. → One envelope always: {ok: true/false, data?, error?, summary}, where summary is a one-line natural-language result the model can echo to the user. The proposal result (proposal_id, diff: {before, proposed}, source_database_changed:false) is the best-designed part — model-legible and unambiguous; mirror that everywhere.
+
+3. Leaky/raw errors confuse the model.
+A failed read surfaced connect ECONNREFUSED 127.0.0.1:5433 straight into the agent, which then told the user "database access issue." Raw infra errors are both a small info leak and bad for LLM behavior. → Safe, terse, actionable tool errors ("temporarily unavailable, retry later" / "not found in your tenant"), with details only in the local ledger.
+
+4. Dotted names vs aliases.
+alias-mode openai correctly makes names valid (billing__inspect_invoice), but the alias diverges from any example/instruction that uses the canonical dotted name — so prompts that say "call propose_late_fee_waiver" don't match the tool the model sees. I had to make my agent instructions tool-name-agnostic. → Keep openai-safe aliases as the default for the openai-agents config (you do), and put the canonical name + purpose in the description so the model can still reason about it.
+
+5. Evidence handles are slightly confusing in-loop.
+The model gets evidence_bundle_id but can't really do anything with it during the turn (it's for replay). Without a hint, a model may try to "use" it. A one-line "this is an audit handle; you don't need to act on it" in the description avoids wasted reasoning.
+
+6. No recommended agent-instruction snippet.
+The biggest gap for first-time LLM integrators: the propose-first pattern needs the model to inspect all evidence before proposing and follow referenced IDs. I had to write that system prompt myself (and rewrite it once for the streamable path). → mcp client-config could optionally emit a recommended instruction block ("gather evidence first; follow referenced ids like OUT-…; propose only within policy; you cannot write or approve"). That would make day-1 agent behavior reliable instead of something each integrator rediscovers.
+
+Net on LLM-friendliness: the conceptual model is excellent for LLMs — propose-only tools are inherently safe and easy for a model to call. The surface (generic descriptions, mixed envelopes, raw errors, alias/name divergence) is where reliability leaks. These are all fixable in the OSS runner and would noticeably raise the floor on agent reliability.
+
+C. If I were prioritizing your OSS updates
+
+P0 (adoption + LLM reliability):
+1. Author-supplied rich tool/arg descriptions in config, surfaced in tools/list.
+2. One consistent result envelope + safe terse errors + a summary field.
+3. Published config JSON Schema + a capability/executor authoring page.
+
+P1 (trust + safety):
+4. Stable release channel + changelog/semver.
+5. Handler helper/SDK (parse + enforce tenant/version/idempotency, optional HMAC) so app-owned writeback is safe-by-default.
+6. doctor that probes the real write path + handler and emits exact GRANT/DDL for receipts; store/server lifecycle guardrails (warn on store-removed-under-server).
+
+P2 (polish):
+7. Optional recommended agent-instruction snippet from mcp client-config.
+8. Local lifecycle webhook/event stream for proposals.
+
+
+
+---------------
+01-result-envelope-spec.md
+
+One envelope for every tool result, so ok is the only thing client code (and the model) must branch on:
+
+jsonc
+{ "ok": true, "summary": "<one-line NL the model reads/echoes>", "kind": "read|proposal",
+  "data": {…}|null, "proposal": {…}|null, "error": {"code","message","retryable"}|null,
+  "evidence": {…}|null, "source_database_changed": false, "_meta": {tenant, principal, canonical_capability} }
+
+Key decisions, all grounded in what broke in my live runs:
+- Kills the status vs ok / mixed-shape problem (today success uses status:"ok", errors use ok:false — two branches).
+- Mandatory summary field — the LLM reads it first; fixed my "model parroted infra error" issue.
+- Safe, stable error.code enum (9 codes, table included) — never raw ECONNREFUSED-style strings, which both leak and degrade agent behavior.
+- Author-supplied description / per-arg description / returns_hint surfaced in tools/list — this is the single biggest LLM lever; the streamable stall I hit was the outage tool's generic description not telling the model it returns the policy.
+- Migration path: result_format: 2 flag + dual-emit + old→new mapping table.
+
+02-handler-helper-interface.md
+
+A first-party helper so app-owned executors are safe by default instead of "match the example."
+- Formalizes (and versions) the request/receipt contract that's currently implicit.
+- createWritebackHandler (TS) + synapsor_handler (Python — since real handlers are app code) where the author writes only the INSERT/UPDATE and returns effects; the helper enforces auth + HMAC signature, tenant scope, expected_version stale-row guard, idempotency, atomicity, safe receipts for them.
+- Calls out request signing (today a handler trusts body-supplied tenant_id behind only a bearer token) and the receipts-table GRANT/DDL gap.
+- Rationale tied to your own thesis: rich writes are the executor's job, but that's only safe if the handler is safe — so make the secure path the easy path.
+
+Both are sized to drop into the repo as RFCs. If you want, next I can: turn the error-code enum into a concrete TypeScript type + a v1→v2 adapter shim, or sketch the Job/Tx type definitions for the handler helper so they're ready to implement.

package/docs/store-lifecycle.md

@@ -0,0 +1,83 @@
+# Store Lifecycle
+
+Synapsor Runner keeps local evidence, query audit, proposals, receipts, replay,
+and lifecycle events in a SQLite store.
+
+Default path:
+
+```bash
+./.synapsor/local.db
+```
+
+## Server leases
+
+MCP server modes write a small lease file next to the store:
+
+```text
+<store>.lease.json
+```
+
+The lease records the server pid, mode, transport, and start time. Destructive
+store operations refuse to run while that lease points at a live process.
+
+Use `--force` only after you have stopped the server or verified the lease is
+stale.
+
+## Prune safely
+
+Preview first:
+
+```bash
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
+```
+
+Apply after review:
+
+```bash
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes
+```
+
+Override an active/stale lease:
+
+```bash
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes --force
+```
+
+## Reset the local ledger
+
+Reset deletes only the local SQLite ledger files:
+
+```bash
+synapsor-runner store reset --store ./.synapsor/local.db --yes
+```
+
+It removes:
+
+```text
+local.db
+local.db-wal
+local.db-shm
+local.db.lease.json
+```
+
+It never touches your source Postgres/MySQL database. Like prune, reset refuses
+while an active server lease exists unless you pass `--force` after verifying
+the server is stopped or the lease is stale.
+
+## Deleted store under a running server
+
+If the store file disappears while a server is still running, model-facing tool
+calls fail safely with `TEMPORARILY_UNAVAILABLE`. Runner does not expose raw
+SQLite paths, corruption text, or filesystem errors to the model.
+
+Fix:
+
+1. Stop the running MCP server.
+2. Recreate the store by rerunning the demo/setup or restore the previous store.
+3. Restart the MCP server.
+
+## Concurrent server modes
+
+Running multiple server transports against the same SQLite store can cause
+contention and confusing local state. Runner refuses concurrent server leases by
+default. Use `--allow-concurrent-store` only for controlled local debugging.

package/docs/writeback-executors.md

@@ -88,6 +88,7 @@ literal values.
         "type": "bearer_env",
         "token_env": "SYNAPSOR_BILLING_HANDLER_TOKEN"
       },
+      "signing_secret_env": "SYNAPSOR_BILLING_HANDLER_SIGNING_SECRET",
       "timeout_ms": 5000
     }
   },
@@ -114,6 +115,17 @@ The handler receives proposal fields, the exact patch, evidence metadata,
 guards, and an idempotency key. It does not receive arbitrary model SQL or DB
 credentials from Synapsor Runner.
 
+When `signing_secret_env` is set, Runner signs the exact JSON body with HMAC
+SHA-256 and sends:
+
+- `X-Synapsor-Signature: sha256=...`
+- `X-Synapsor-Issued-At: ...`
+- `X-Synapsor-Proposal-Id: ...`
+- `Idempotency-Key: ...`
+
+Use signing for any handler that is not strictly loopback-only and protected by
+another trusted boundary.
+
 Handler responses:
 
 ```json
@@ -139,6 +151,12 @@ receipt is stored in replay.
 Use your application/API for business logic. Use Synapsor Runner for proposal,
 approval, evidence, policy boundary, and replay.
 
+For TypeScript services, use the source-level helper in `packages/handler`.
+It verifies bearer/HMAC auth, parses the request, locks the target row with the
+tenant guard, checks the expected version, handles idempotency, wraps the
+business effect in a transaction, and returns safe receipts without raw driver
+errors. See [Handler Helper](handler-helper.md).
+
 This is the recommended path for writes that are richer than the current
 `sql_update` scope, such as:
 

package/examples/app-owned-writeback/README.md

@@ -29,6 +29,7 @@ Add an executor and point one proposal capability at it:
         "type": "bearer_env",
         "token_env": "SYNAPSOR_APP_WRITEBACK_TOKEN"
       },
+      "signing_secret_env": "SYNAPSOR_APP_WRITEBACK_SIGNING_SECRET",
       "timeout_ms": 5000
     }
   },

package/examples/mcp-postgres-billing-app-handler/README.md

@@ -15,8 +15,12 @@ App-owned rich writeback:
 - model-facing MCP only creates a proposal;
 - approval happens outside MCP;
 - Runner calls `billing_app_handler`;
-- the app inserts an `account_credits` row and updates the invoice inside its
-  own transaction;
+- the app uses the first-party handler helper from the source workspace, or the
+  bundled `synapsor-handler.mjs` shim included in the runner npm package, to
+  verify bearer auth, HMAC signature, tenant scope, expected row version,
+  idempotency, and transaction/receipt shape;
+- the handler business code inserts an `account_credits` row and updates the
+  invoice inside the helper-owned transaction;
 - Runner records the handler receipt and replay.
 
 The model never receives `execute_sql`, approval tools, commit/apply tools,
@@ -46,6 +50,7 @@ export BILLING_APP_READ_URL="postgresql://synapsor_reader:synapsor_reader_passwo
 export BILLING_APP_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55437/synapsor_billing_app_handler"
 export BILLING_APP_HANDLER_URL="http://127.0.0.1:8787/synapsor/writeback"
 export BILLING_APP_HANDLER_TOKEN="dev-handler-token"
+export BILLING_APP_HANDLER_SIGNING_SECRET="dev-handler-signing-secret"
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_billing_operator"
 

package/examples/mcp-postgres-billing-app-handler/app-handler.mjs

@@ -1,43 +1,44 @@
 #!/usr/bin/env node
 import http from "node:http";
-import { createRequire } from "node:module";
 
-const { Pool } = await loadPg();
+const { createWritebackHandler } = await loadHandlerHelper();
 
 const port = Number(process.env.BILLING_APP_HANDLER_PORT || "8787");
-const expectedToken = process.env.BILLING_APP_HANDLER_TOKEN || "dev-handler-token";
-const databaseUrl = process.env.BILLING_APP_WRITE_URL;
 
-if (!databaseUrl) {
+if (!process.env.BILLING_APP_WRITE_URL) {
   console.error("BILLING_APP_WRITE_URL is required.");
   process.exit(1);
 }
 
-const pool = new Pool({ connectionString: databaseUrl });
+const writebackHandler = createWritebackHandler({
+  tokenEnv: "BILLING_APP_HANDLER_TOKEN",
+  signingSecretEnv: "BILLING_APP_HANDLER_SIGNING_SECRET",
+  source: {
+    engine: "postgres",
+    writeUrlEnv: "BILLING_APP_WRITE_URL",
+    receiptTable: {
+      schema: "public",
+      table: "synapsor_handler_receipts",
+    },
+  },
+  capabilities: {
+    "billing.propose_account_credit": applyAccountCredit,
+  },
+});
 
 const server = http.createServer(async (request, response) => {
-  try {
-    if (request.method === "GET" && request.url === "/healthz") {
-      return writeJson(response, 200, { ok: true });
-    }
-    if (request.method !== "POST" || request.url !== "/synapsor/writeback") {
-      return writeJson(response, 404, { status: "failed", safe_error_code: "NOT_FOUND", source_database_mutated: false });
-    }
-    if (request.headers.authorization !== `Bearer ${expectedToken}`) {
-      return writeJson(response, 401, { status: "failed", safe_error_code: "UNAUTHORIZED", source_database_mutated: false });
-    }
-    const body = await readJson(request);
-    const receipt = await applyAccountCredit(body);
-    return writeJson(response, 200, receipt);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return writeJson(response, 500, {
+  if (request.method === "GET" && request.url === "/healthz") {
+    return writeJson(response, 200, { ok: true });
+  }
+  if (request.method !== "POST" || request.url !== "/synapsor/writeback") {
+    return writeJson(response, 404, {
       status: "failed",
-      safe_error_code: "HANDLER_EXCEPTION",
+      rows_affected: 0,
+      safe_error_code: "NOT_FOUND",
       source_database_mutated: false,
-      details: { message: message.slice(0, 300) },
     });
   }
+  await writebackHandler(request, response);
 });
 
 server.listen(port, "127.0.0.1", () => {
@@ -49,136 +50,60 @@ process.once("SIGTERM", shutdown);
 
 async function shutdown() {
   server.close();
-  await pool.end();
   process.exit(0);
 }
 
-async function applyAccountCredit(request) {
-  const changeSet = request.change_set || request;
-  if (changeSet.action !== "billing.propose_account_credit") {
-    return {
-      status: "failed",
-      safe_error_code: "UNSUPPORTED_ACTION",
-      source_database_mutated: false,
-    };
+async function applyAccountCredit(job, tx) {
+  const amountCents = Number(job.patch.credit_requested_cents);
+  const reason = String(job.patch.credit_reason || "approved account credit");
+  if (!Number.isInteger(amountCents) || amountCents <= 0) {
+    throw new Error("credit amount must be a positive integer");
   }
 
-  const proposalId = String(request.proposal_id || "");
-  const idempotencyKey = String(request.idempotency_key || proposalId);
-  const tenantId = String(changeSet.scope?.tenant_id || changeSet.tenant_guard?.value || changeSet.guards?.tenant?.value || "");
-  const principal = String(changeSet.principal?.id || changeSet.runner_hint || "approved_operator");
-  const invoiceId = String(changeSet.scope?.object_id || changeSet.target?.primary_key?.value || changeSet.source?.primary_key?.value || "");
-  const amountCents = Number(changeSet.patch?.credit_requested_cents);
-  const reason = String(changeSet.patch?.credit_reason || "approved account credit");
-  const expectedVersion = changeSet.guards?.expected_version?.value;
-
-  if (!proposalId || !tenantId || !invoiceId || !Number.isInteger(amountCents) || amountCents <= 0 || !expectedVersion) {
-    return {
-      status: "failed",
-      safe_error_code: "BAD_WRITEBACK_REQUEST",
-      source_database_mutated: false,
-    };
+  const creditId = `CR-${job.proposalId.replace(/[^A-Za-z0-9]/g, "").slice(-12) || Date.now()}`;
+  await tx.insert("account_credits", {
+    id: creditId,
+    tenant_id: job.tenantId,
+    invoice_id: job.objectId,
+    customer_id: String(job.row.customer_id),
+    amount_cents: amountCents,
+    reason,
+    idempotency_key: job.idempotencyKey,
+    created_by: job.principal,
+  }, { schema: "public" });
+
+  const newVersion = new Date().toISOString();
+  const update = await tx.update("invoices", {
+    id: job.objectId,
+    tenant_id: job.tenantId,
+  }, {
+    credit_requested_cents: amountCents,
+    credit_reason: reason,
+    credited_cents: Number(job.row.credited_cents ?? 0) + amountCents,
+    updated_at: newVersion,
+  }, {
+    schema: "public",
+    returning: ["updated_at"],
+  });
+
+  if (update.rowCount !== 1) {
+    throw new Error("invoice update affected an unexpected number of rows");
   }
 
-  const client = await pool.connect();
-  try {
-    await client.query("BEGIN");
-
-    const duplicate = await client.query(
-      "SELECT id FROM public.account_credits WHERE idempotency_key = $1",
-      [idempotencyKey],
-    );
-    if (duplicate.rowCount && duplicate.rows[0]) {
-      await client.query("COMMIT");
-      return {
-        status: "already_applied",
-        rows_affected: 0,
-        source_database_mutated: false,
-        details: {
-          credit_id: duplicate.rows[0].id,
-        },
-      };
-    }
-
-    const invoiceResult = await client.query(
-      "SELECT id, tenant_id, customer_id, updated_at FROM public.invoices WHERE id = $1 AND tenant_id = $2 FOR UPDATE",
-      [invoiceId, tenantId],
-    );
-    const invoice = invoiceResult.rows[0];
-    if (!invoice) {
-      await client.query("ROLLBACK");
-      return {
-        status: "conflict",
-        rows_affected: 0,
-        safe_error_code: "INVOICE_NOT_FOUND_OR_WRONG_TENANT",
-        source_database_mutated: false,
-      };
-    }
-
-    const currentVersion = timestampString(invoice.updated_at);
-    const expected = timestampString(expectedVersion);
-    if (currentVersion !== expected) {
-      await client.query("ROLLBACK");
-      return {
-        status: "conflict",
-        rows_affected: 0,
-        previous_version: currentVersion,
-        safe_error_code: "ROW_CHANGED_AFTER_PROPOSAL",
-        source_database_mutated: false,
-      };
-    }
-
-    const creditId = `CR-${proposalId.replace(/[^A-Za-z0-9]/g, "").slice(-12) || Date.now()}`;
-    await client.query(
-      `INSERT INTO public.account_credits
-        (id, tenant_id, invoice_id, customer_id, amount_cents, reason, idempotency_key, created_by)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
-      [creditId, tenantId, invoiceId, invoice.customer_id, amountCents, reason, idempotencyKey, principal],
-    );
-    const update = await client.query(
-      `UPDATE public.invoices
-       SET credit_requested_cents = $1,
-           credit_reason = $2,
-           credited_cents = credited_cents + $1,
-           updated_at = now()
-       WHERE id = $3 AND tenant_id = $4
-       RETURNING updated_at`,
-      [amountCents, reason, invoiceId, tenantId],
-    );
-    await client.query("COMMIT");
-
-    return {
-      status: "applied",
-      rows_affected: 2,
-      previous_version: currentVersion,
-      new_version: timestampString(update.rows[0]?.updated_at),
-      source_database_mutated: true,
-      details: {
-        effects: [
-          { type: "db.insert", table: "account_credits", id: creditId },
-          { type: "db.update", table: "invoices", id: invoiceId },
-          { type: "event", name: "billing.account_credit_created" },
-        ],
-      },
-    };
-  } catch (error) {
-    await client.query("ROLLBACK").catch(() => {});
-    throw error;
-  } finally {
-    client.release();
-  }
+  return {
+    rowsAffected: 2,
+    newVersion: timestampString(update.rows[0]?.updated_at ?? newVersion),
+    effects: [
+      { type: "db.insert", table: "account_credits", id: creditId },
+      { type: "db.update", table: "invoices", id: job.objectId },
+      { type: "event", name: "billing.account_credit_created" },
+    ],
+  };
 }
 
 function timestampString(value) {
-  if (value instanceof Date) return value.toISOString().replace(".000Z", "Z");
-  return new Date(String(value)).toISOString().replace(".000Z", "Z");
-}
-
-async function readJson(request) {
-  const chunks = [];
-  for await (const chunk of request) chunks.push(Buffer.from(chunk));
-  const text = Buffer.concat(chunks).toString("utf8");
-  return text ? JSON.parse(text) : {};
+  if (value instanceof Date) return value.toISOString();
+  return new Date(String(value)).toISOString();
 }
 
 function writeJson(response, statusCode, body) {
@@ -187,11 +112,14 @@ function writeJson(response, statusCode, body) {
   response.end(`${JSON.stringify(body, null, 2)}\n`);
 }
 
-async function loadPg() {
+async function loadHandlerHelper() {
   try {
-    return await import("pg");
-  } catch {
-    const requireFromRunnerPackage = createRequire(new URL("../../apps/runner/package.json", import.meta.url));
-    return requireFromRunnerPackage("pg");
+    return await import("@synapsor/handler");
+  } catch (workspaceError) {
+    try {
+      return await import(new URL("./synapsor-handler.mjs", import.meta.url));
+    } catch {
+      throw workspaceError;
+    }
   }
 }

package/examples/mcp-postgres-billing-app-handler/scripts/run-demo.sh

@@ -45,6 +45,7 @@ export BILLING_APP_READ_URL="postgresql://synapsor_reader:synapsor_reader_passwo
 export BILLING_APP_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55437/synapsor_billing_app_handler"
 export BILLING_APP_HANDLER_URL="http://127.0.0.1:8787/synapsor/writeback"
 export BILLING_APP_HANDLER_TOKEN="dev-handler-token"
+export BILLING_APP_HANDLER_SIGNING_SECRET="dev-handler-signing-secret"
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_billing_operator"