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

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

@@ -0,0 +1,54 @@
+import asyncio
+import os
+import sys
+
+try:
+    from agents import Agent, Runner
+    from agents.mcp import MCPServerStreamableHttp
+except ImportError as exc:
+    raise SystemExit(
+        "This example requires the OpenAI Agents SDK with Streamable HTTP MCP support. "
+        "Install with: pip install -r requirements.txt"
+    ) from exc
+
+
+async def main() -> None:
+    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    missing = [name for name in required if not os.environ.get(name)]
+    if missing:
+        raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
+
+    invoice_id = os.environ.get("SYNAPSOR_INVOICE_ID", "INV-3001")
+    mcp_url = os.environ["SYNAPSOR_RUNNER_HTTP_URL"]
+    token = os.environ["SYNAPSOR_RUNNER_HTTP_TOKEN"]
+
+    async with MCPServerStreamableHttp(
+        params={
+            "url": mcp_url,
+            "headers": {"Authorization": f"Bearer {token}"},
+            "timeout": 15,
+        }
+    ) as mcp_server:
+        agent = Agent(
+            name="Synapsor Streamable HTTP 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-http/requirements.txt

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

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

@@ -0,0 +1,66 @@
+# OpenAI Agents SDK + Synapsor Runner over stdio
+
+This example shows an OpenAI Agents SDK app launching Synapsor Runner as a
+local stdio MCP server.
+
+Use stdio when the agent process can start the MCP server on the same machine.
+The model sees Synapsor semantic tools through OpenAI-safe aliases such as
+`billing__inspect_invoice`. Runner keeps the canonical Synapsor capability
+name, such as `billing.inspect_invoice`, in MCP metadata and maps calls back to
+it. The model
+does not receive raw SQL, database URLs, write credentials, approval tools, or
+commit tools.
+
+## Prerequisites
+
+Generate `synapsor.runner.json` first:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner demo
+```
+
+or connect your own staging database:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner onboard db --from-env DATABASE_URL
+```
+
+Then install the Python dependencies:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run
+
+```bash
+export OPENAI_API_KEY="..."
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="openai_agent_demo"
+
+python agent.py
+```
+
+Optional env:
+
+```bash
+export SYNAPSOR_CONFIG="./synapsor.runner.json"
+export SYNAPSOR_STORE="./.synapsor/local.db"
+export SYNAPSOR_TOOL="billing.inspect_invoice"
+export SYNAPSOR_INVOICE_ID="INV-3001"
+```
+
+Expected behavior:
+
+- the agent can inspect the scoped invoice through Synapsor using an
+  OpenAI-safe tool alias;
+- Runner maps the alias back to the canonical Synapsor capability;
+- the agent cannot run SQL;
+- the agent cannot approve or commit writes;
+- evidence/query audit are saved in the local Runner store.
+
+If your installed OpenAI Agents SDK does not expose `MCPServerStdio`, update the
+SDK or use the Streamable HTTP example.

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

@@ -0,0 +1,72 @@
+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,
+            "--alias-mode",
+            "openai",
+        ],
+        "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;