@synapsor/runner 0.1.0-alpha.1 → 0.1.0-alpha.10

package/examples/openai-agents-stdio/agent.py

@@ -0,0 +1,70 @@
+import asyncio
+import os
+import sys
+
+try:
+    from agents import Agent, Runner
+    from agents.mcp import MCPServerStdio
+except ImportError as exc:
+    raise SystemExit(
+        "This example requires the OpenAI Agents SDK with MCP stdio support. "
+        "Install with: pip install -r requirements.txt"
+    ) from exc
+
+
+async def main() -> None:
+    config_path = os.environ.get("SYNAPSOR_CONFIG", "./synapsor.runner.json")
+    store_path = os.environ.get("SYNAPSOR_STORE", "./.synapsor/local.db")
+    invoice_id = os.environ.get("SYNAPSOR_INVOICE_ID", "INV-3001")
+
+    required = ["OPENAI_API_KEY", "DATABASE_URL", "SYNAPSOR_TENANT_ID", "SYNAPSOR_PRINCIPAL"]
+    missing = [name for name in required if not os.environ.get(name)]
+    if missing:
+        raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
+
+    params = {
+        "command": "npx",
+        "args": [
+            "-y",
+            "-p",
+            "@synapsor/runner@alpha",
+            "synapsor-runner",
+            "mcp",
+            "serve",
+            "--config",
+            config_path,
+            "--store",
+            store_path,
+        ],
+        "env": {
+            **os.environ,
+            "DATABASE_URL": os.environ["DATABASE_URL"],
+            "SYNAPSOR_TENANT_ID": os.environ["SYNAPSOR_TENANT_ID"],
+            "SYNAPSOR_PRINCIPAL": os.environ["SYNAPSOR_PRINCIPAL"],
+        },
+    }
+
+    async with MCPServerStdio(params=params) as mcp_server:
+        agent = Agent(
+            name="Synapsor stdio MCP demo agent",
+            instructions=(
+                "Use Synapsor MCP tools to inspect scoped database data. "
+                "Do not claim that you can run SQL, approve proposals, or commit writes."
+            ),
+            mcp_servers=[mcp_server],
+        )
+        result = await Runner.run(
+            agent,
+            (
+                f"Inspect invoice {invoice_id} using Synapsor. "
+                "Explain what you saw and whether you have write authority."
+            ),
+        )
+        print(result.final_output)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.exit(130)

package/examples/openai-agents-stdio/requirements.txt

@@ -0,0 +1 @@
+openai-agents>=0.1.0

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

@@ -0,0 +1,137 @@
+# Reference Support/Billing App
+
+This is the main local reference app for Synapsor Runner.
+
+It shows the commit-safe MCP loop against a disposable Postgres app database:
+
+1. The MCP model sees semantic tools, not `execute_sql`.
+2. Reads are scoped by trusted `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`.
+3. Proposal tools create exact diffs and leave the source database unchanged.
+4. Approval happens through the local CLI or UI, outside MCP.
+5. The trusted runner applies one guarded update with tenant, allowed-column, idempotency, and `updated_at` conflict checks.
+6. Replay exports evidence, diff, approval, writeback receipt, and conflict outcome.
+
+The app fixture is split into `schema.sql` and `seed.sql` so the database shape
+and demo data are easy to inspect.
+
+## Start
+
+From the repository root:
+
+```bash
+docker compose -f examples/reference-support-billing-app/docker-compose.yml up -d
+
+export REFERENCE_POSTGRES_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55435/synapsor_reference_support_billing"
+export REFERENCE_POSTGRES_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55435/synapsor_reference_support_billing"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_support_operator"
+```
+
+Or run the complete success/conflict/replay smoke:
+
+```bash
+examples/reference-support-billing-app/scripts/run-demo.sh
+```
+
+Validate the reviewed contract:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config examples/reference-support-billing-app/synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config examples/reference-support-billing-app/synapsor.runner.json
+```
+
+Serve MCP:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+  --config examples/reference-support-billing-app/synapsor.runner.json \
+  --store ./tmp/reference-support-billing/local.db
+```
+
+## Tools
+
+The model-facing MCP tools are:
+
+- `support.inspect_ticket`
+- `support.propose_ticket_resolution`
+- `support.inspect_customer_account`
+- `support.propose_plan_credit`
+- `billing.inspect_invoice`
+- `billing.propose_late_fee_waiver`
+- `orders.inspect_order`
+- `orders.propose_status_change`
+
+The model does not receive approval tools, commit tools, write credentials, raw SQL, arbitrary table names, arbitrary column names, or tenant authority.
+
+## Safe Write Examples
+
+After `synapsor-runner demo` or after starting this fixture manually, try the same
+proposal-first loop without connecting an MCP client:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner propose billing.propose_late_fee_waiver --sample
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show latest
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve latest --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner apply latest
+npx -y -p @synapsor/runner@alpha synapsor-runner replay latest
+```
+
+Expected safety output:
+
+```text
+Source DB changed:
+no
+
+Guarded writeback applied.
+* proposal approved: yes
+* primary key matched: yes
+* tenant guard matched: yes
+* allowed columns only: yes
+* conflict guard passed: yes
+```
+
+Other proposal examples use the same review/apply/replay path:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner propose support.propose_plan_credit --sample
+npx -y -p @synapsor/runner@alpha synapsor-runner propose orders.propose_status_change --sample
+```
+
+Safety guarantees:
+
+- proposals store evidence, a before/after diff, trusted tenant/principal
+  context, and query audit before any write;
+- approval stays outside the model-facing MCP tool surface;
+- writeback is single-row, primary-key targeted, tenant guarded,
+  allowed-column checked, idempotent, and conflict guarded;
+- stale rows return `conflict` and are replayable.
+
+Current limitation: v0.1 is intentionally local and single-user. It does not
+provide hosted RBAC, workflow DAGs, branches, settlement policies, auto-merge,
+or production-scale runner orchestration.
+
+## Review And Replay
+
+After a proposal exists:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve <proposal_id> --store ./tmp/reference-support-billing/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job <proposal_id> --store ./tmp/reference-support-billing/local.db --output ./tmp/reference-support-billing/job.json
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job ./tmp/reference-support-billing/job.json --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export <proposal_id> --store ./tmp/reference-support-billing/local.db --output ./tmp/reference-support-billing/replay.json
+```
+
+To inspect locally in a browser:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner ui \
+  --config examples/reference-support-billing-app/synapsor.runner.json \
+  --store ./tmp/reference-support-billing/local.db
+```
+
+## Stop
+
+```bash
+docker compose -f examples/reference-support-billing-app/docker-compose.yml down -v
+```

package/examples/reference-support-billing-app/docker-compose.yml

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

package/examples/reference-support-billing-app/mcp-client.generic.json

@@ -0,0 +1,11 @@
+{
+  "command": "synapsor-runner",
+  "args": [
+    "mcp",
+    "serve",
+    "--config",
+    "examples/reference-support-billing-app/synapsor.runner.json",
+    "--store",
+    "./tmp/reference-support-billing/local.db"
+  ]
+}

package/examples/reference-support-billing-app/schema.sql

@@ -0,0 +1,68 @@
+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.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_reference_support_billing 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.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/reference-support-billing-app/scripts/run-demo.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+corepack pnpm test:reference-app

package/examples/reference-support-billing-app/seed.sql

@@ -0,0 +1,33 @@
+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.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/reference-support-billing-app/synapsor.runner.json

@@ -0,0 +1,241 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/reference-support-billing/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_ticket_resolution",
+      "kind": "proposal",
+      "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 },
+        "resolution_note": { "type": "string", "required": true, "max_length": 1000 }
+      },
+      "lookup": { "id_from_arg": "ticket_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "subject", "status", "resolution_note", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "status": { "fixed": "pending_review" },
+        "resolution_note": { "from_arg": "resolution_note" }
+      },
+      "allowed_columns": ["status", "resolution_note"],
+      "transition_guards": {
+        "status": {
+          "allowed": {
+            "open": ["pending_review"],
+            "pending_review": ["resolved"]
+          }
+        }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "support_lead" }
+    },
+    {
+      "name": "support.inspect_customer_account",
+      "kind": "read",
+      "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 }
+      },
+      "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
+    },
+    {
+      "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" }
+    },
+    {
+      "name": "orders.inspect_order",
+      "kind": "read",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "orders",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "order_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "order_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "status_change_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "orders.propose_status_change",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "orders",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "order_id": { "type": "string", "required": true, "max_length": 128 },
+        "status": { "type": "string", "required": true, "enum": ["ready_to_ship", "canceled"] },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "order_id" },
+      "visible_columns": ["id", "tenant_id", "customer_id", "status", "status_change_reason", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "status": { "from_arg": "status" },
+        "status_change_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["status", "status_change_reason"],
+      "transition_guards": {
+        "status": {
+          "allowed": {
+            "paid": ["ready_to_ship", "canceled"],
+            "processing": ["ready_to_ship"]
+          }
+        }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "orders_lead" }
+    }
+  ]
+}

package/package.json

@@ -1,22 +1,30 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "synapsor-runner": "dist/bin.cjs"
+    "synapsor-runner": "dist/cli.js"
   },
   "files": [
-    "dist/bin.cjs",
     "dist/cli.js",
     "dist/cli.d.ts",
     "dist/cli.d.ts.map",
     "dist/local-ui.d.ts",
     "dist/local-ui.d.ts.map",
+    "dist/runner.mjs",
+    "docs/**/*.md",
+    "examples/dangerous-mcp-tools.json",
+    "examples/app-owned-writeback/**",
+    "examples/openai-agents-http/**",
+    "examples/openai-agents-stdio/**",
+    "examples/reference-support-billing-app/**",
+    "recipes/**/*.json",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "TRADEMARKS.md"
   ],
   "engines": {
     "node": ">=22.5.0"

package/recipes/accounts.trial_extension.json

@@ -0,0 +1,42 @@
+{
+  "id": "accounts.trial_extension",
+  "title": "Trial extension",
+  "summary": "Inspect one account and propose a bounded trial extension.",
+  "expected_table_type": "accounts or subscriptions table",
+  "required_columns": ["id", "tenant_id", "trial_ends_at", "extension_reason", "updated_at"],
+  "recommended_primary_key": "id",
+  "recommended_tenant_key": "tenant_id",
+  "recommended_conflict_column": "updated_at",
+  "visible_columns": ["id", "tenant_id", "plan", "trial_ends_at", "extension_reason", "updated_at"],
+  "allowed_write_columns": ["trial_ends_at", "extension_reason"],
+  "semantic_tools": ["accounts.inspect_account", "accounts.propose_trial_extension"],
+  "notes": [
+    "Use a handler executor if trial changes must go through your billing service."
+  ],
+  "spec": {
+    "version": 1,
+    "engine": "postgres",
+    "mode": "review",
+    "schema": "public",
+    "table": "accounts",
+    "primary_key": "id",
+    "tenant_key": "tenant_id",
+    "conflict_column": "updated_at",
+    "namespace": "accounts",
+    "object_name": "account",
+    "inspect_tool_name": "accounts.inspect_account",
+    "proposal_tool_name": "accounts.propose_trial_extension",
+    "lookup_arg": "account_id",
+    "visible_columns": ["id", "tenant_id", "plan", "trial_ends_at", "extension_reason", "updated_at"],
+    "allowed_columns": ["trial_ends_at", "extension_reason"],
+    "patch": {
+      "trial_ends_at": { "from_arg": "trial_ends_at" },
+      "extension_reason": { "from_arg": "reason" }
+    },
+    "patch_args": {
+      "trial_ends_at": { "type": "string", "required": true, "max_length": 64 },
+      "reason": { "type": "string", "required": true, "max_length": 500 }
+    },
+    "approval": { "required_role": "account_admin" }
+  }
+}