@synapsor/runner 0.1.0 → 0.1.2

package/examples/support-billing-agent/app/README.md

@@ -0,0 +1,13 @@
+# App Surface
+
+This folder marks the customer application boundary for the flagship demo.
+
+The model talks to Synapsor Runner MCP tools. It does not receive application
+write credentials or direct SQL authority. After approval, the trusted runner
+uses the reviewed `synapsor.runner.json` contract to apply the one-row
+writeback with tenant, primary-key, allowed-column, idempotency, and
+`updated_at` conflict guards.
+
+For richer app actions, such as inserting a credit ledger row and emitting an
+event, use the app-owned handler examples in `../app-owned-writeback/` and
+`../mcp-postgres-billing-app-handler/`.

package/examples/support-billing-agent/db/schema.sql

@@ -0,0 +1,91 @@
+CREATE TABLE IF NOT EXISTS public.tenants (
+  id text PRIMARY KEY,
+  name text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  name text NOT NULL,
+  email text,
+  plan text NOT NULL,
+  plan_credit_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.support_tickets (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  subject text NOT NULL,
+  status text NOT NULL,
+  resolution_note text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  balance_cents integer NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.credits (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  invoice_id text REFERENCES public.invoices(id),
+  amount_cents integer NOT NULL,
+  reason text NOT NULL,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.agent_actions (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  action_type text NOT NULL,
+  target_type text NOT NULL,
+  target_id text NOT NULL,
+  proposal_id text,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.orders (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  status_change_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
+    CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_writer') THEN
+    CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  END IF;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_support_billing_agent TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT CREATE ON SCHEMA public TO synapsor_writer;
+GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
+GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
+GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
+GRANT UPDATE (status, status_change_reason, updated_at) ON public.orders TO synapsor_writer;

package/examples/support-billing-agent/db/seed.sql

@@ -0,0 +1,43 @@
+INSERT INTO public.tenants (id, name, created_at, updated_at)
+VALUES
+  ('acme', 'Acme Robotics', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('otherco', 'OtherCo Labs', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.customers (id, tenant_id, name, email, plan, plan_credit_cents, credit_reason, created_at, updated_at)
+VALUES
+  ('cust_acme_1', 'acme', 'Acme Robotics', 'ops@example.invalid', 'enterprise', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
+  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', 0, NULL, '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, name = EXCLUDED.name, email = EXCLUDED.email, plan = EXCLUDED.plan, plan_credit_cents = EXCLUDED.plan_credit_cents, credit_reason = EXCLUDED.credit_reason, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.support_tickets (id, tenant_id, customer_id, subject, status, resolution_note, updated_at)
+VALUES
+  ('T-1042', 'acme', 'cust_acme_1', 'Late fee waiver request for INV-3001', 'open', NULL, '2026-06-20T12:00:00Z'),
+  ('T-1043', 'acme', 'cust_acme_2', 'Duplicate card charge question', 'open', NULL, '2026-06-20T12:05:00Z'),
+  ('T-9001', 'otherco', 'cust_other_1', 'OtherCo private billing ticket', 'open', NULL, '2026-06-20T12:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, subject = EXCLUDED.subject, status = EXCLUDED.status, resolution_note = EXCLUDED.resolution_note, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.invoices (id, tenant_id, customer_id, status, balance_cents, late_fee_cents, waiver_reason, updated_at)
+VALUES
+  ('INV-3001', 'acme', 'cust_acme_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z'),
+  ('INV-3002', 'acme', 'cust_acme_2', 'paid', 0, 0, NULL, '2026-06-20T14:40:00Z'),
+  ('INV-9001', 'otherco', 'cust_other_1', 'overdue', 25500, 5500, NULL, '2026-06-20T14:31:08Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, balance_cents = EXCLUDED.balance_cents, late_fee_cents = EXCLUDED.late_fee_cents, waiver_reason = EXCLUDED.waiver_reason, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.credits (id, tenant_id, customer_id, invoice_id, amount_cents, reason, status, created_at, updated_at)
+VALUES
+  ('CR-1001', 'acme', 'cust_acme_1', 'INV-3001', 1000, 'Seeded goodwill credit for review flow', 'draft', '2026-06-20T15:00:00Z', '2026-06-20T15:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, invoice_id = EXCLUDED.invoice_id, amount_cents = EXCLUDED.amount_cents, reason = EXCLUDED.reason, status = EXCLUDED.status, updated_at = EXCLUDED.updated_at;
+
+INSERT INTO public.agent_actions (id, tenant_id, action_type, target_type, target_id, proposal_id, status, created_at)
+VALUES
+  ('ACT-1001', 'acme', 'late_fee_review', 'invoice', 'INV-3001', NULL, 'seeded', '2026-06-20T15:05:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, action_type = EXCLUDED.action_type, target_type = EXCLUDED.target_type, target_id = EXCLUDED.target_id, proposal_id = EXCLUDED.proposal_id, status = EXCLUDED.status, created_at = EXCLUDED.created_at;
+
+INSERT INTO public.orders (id, tenant_id, customer_id, status, status_change_reason, updated_at)
+VALUES
+  ('O-1001', 'acme', 'cust_acme_1', 'paid', NULL, '2026-06-20T13:00:00Z'),
+  ('O-1002', 'acme', 'cust_acme_2', 'processing', NULL, '2026-06-20T13:05:00Z'),
+  ('O-9001', 'otherco', 'cust_other_1', 'paid', NULL, '2026-06-20T13:00:00Z')
+ON CONFLICT (id) DO UPDATE SET tenant_id = EXCLUDED.tenant_id, customer_id = EXCLUDED.customer_id, status = EXCLUDED.status, status_change_reason = EXCLUDED.status_change_reason, updated_at = EXCLUDED.updated_at;

package/examples/support-billing-agent/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: synapsor_runner_support_billing_agent
+    environment:
+      POSTGRES_DB: synapsor_support_billing_agent
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55436:5432"
+    volumes:
+      - ./db/schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
+      - ./db/seed.sql:/docker-entrypoint-initdb.d/002_seed.sql:ro

package/examples/support-billing-agent/scripts/run-demo.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+SYNAPSOR_REFERENCE_EXAMPLE_DIR="examples/support-billing-agent" \
+SYNAPSOR_REFERENCE_CONFIG_PATH="examples/support-billing-agent/synapsor.runner.json" \
+SYNAPSOR_REFERENCE_TMP_DIR="tmp/support-billing-agent" \
+SYNAPSOR_REFERENCE_CONTAINER="synapsor_runner_support_billing_agent" \
+SYNAPSOR_REFERENCE_DB="synapsor_support_billing_agent" \
+SYNAPSOR_REFERENCE_PORT="55436" \
+SYNAPSOR_REFERENCE_EXPECTED_TOOLS="support.inspect_ticket,support.propose_plan_credit,billing.inspect_invoice,billing.propose_late_fee_waiver" \
+SYNAPSOR_REFERENCE_EXACT_TOOLS="1" \
+node scripts/smoke-reference-support-billing-app.mjs

package/examples/support-billing-agent/synapsor.runner.json

@@ -0,0 +1,233 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/support-billing-agent/local.db"
+  },
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "REFERENCE_POSTGRES_READ_URL",
+      "write_url_env": "REFERENCE_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "contexts": {
+    "local_operator": {
+      "provider": "environment",
+      "values": {
+        "tenant_id_env": "SYNAPSOR_TENANT_ID",
+        "principal_env": "SYNAPSOR_PRINCIPAL"
+      }
+    }
+  },
+  "capabilities": [
+    {
+      "name": "support.inspect_ticket",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "support_tickets",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "ticket_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "ticket_id"
+      },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "subject",
+        "status",
+        "resolution_note",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "support.propose_plan_credit",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "customers",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "customer_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        },
+        "credit_cents": {
+          "type": "number",
+          "required": true,
+          "minimum": 0,
+          "maximum": 5000
+        },
+        "reason": {
+          "type": "string",
+          "required": true,
+          "max_length": 500
+        }
+      },
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "name",
+        "plan",
+        "plan_credit_cents",
+        "credit_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "plan_credit_cents": {
+          "from_arg": "credit_cents"
+        },
+        "credit_reason": {
+          "from_arg": "reason"
+        }
+      },
+      "allowed_columns": [
+        "plan_credit_cents",
+        "credit_reason"
+      ],
+      "numeric_bounds": {
+        "plan_credit_cents": {
+          "minimum": 0,
+          "maximum": 5000
+        }
+      },
+      "conflict_guard": {
+        "column": "updated_at"
+      },
+      "approval": {
+        "mode": "human",
+        "required_role": "support_lead"
+      }
+    },
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        },
+        "reason": {
+          "type": "string",
+          "required": true,
+          "max_length": 500
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "late_fee_cents": {
+          "fixed": 0
+        },
+        "waiver_reason": {
+          "from_arg": "reason"
+        }
+      },
+      "allowed_columns": [
+        "late_fee_cents",
+        "waiver_reason"
+      ],
+      "numeric_bounds": {
+        "late_fee_cents": {
+          "minimum": 0,
+          "maximum": 10000
+        }
+      },
+      "conflict_guard": {
+        "column": "updated_at"
+      },
+      "approval": {
+        "mode": "human",
+        "required_role": "billing_lead"
+      }
+    }
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0",
-  "description": "Commit-safe MCP runner for Postgres and MySQL agents",
+  "version": "0.1.2",
+  "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -17,10 +17,15 @@
     "docs/**/*.md",
     "examples/dangerous-mcp-tools.json",
     "examples/app-owned-writeback/**",
+    "examples/claude-desktop-postgres/**",
+    "examples/cursor-postgres/**",
     "examples/mcp-postgres-billing-app-handler/**",
+    "examples/mysql-refund-agent/**",
     "examples/openai-agents-http/**",
     "examples/openai-agents-stdio/**",
+    "examples/raw-sql-vs-synapsor/**",
     "examples/reference-support-billing-app/**",
+    "examples/support-billing-agent/**",
     "fixtures/**",
     "schemas/**",
     "recipes/**/*.json",
@@ -30,14 +35,23 @@
     "NOTICE",
     "TRADEMARKS.md"
   ],
+  "keywords": [
+    "mcp",
+    "postgres",
+    "mysql",
+    "ai-agents",
+    "sql-safety",
+    "database-safety",
+    "openai-agents",
+    "claude",
+    "cursor",
+    "writeback",
+    "replay",
+    "model-context-protocol"
+  ],
   "engines": {
     "node": ">=22.5.0"
   },
-  "scripts": {
-    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
-    "prepack": "cd ../.. && corepack pnpm build:runner-package",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "mysql2": "^3.11.0",
@@ -57,7 +71,10 @@
     "url": "https://synapsor.ai/contact"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/build-runner-package.mjs",
+    "test": "vitest run"
   }
-}
+}