@synapsor/runner 0.1.0-alpha.3 → 0.1.0-alpha.5

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

@@ -0,0 +1,55 @@
+# OpenAI Agents SDK + Synapsor Runner over HTTP
+
+This example shows an OpenAI Agents SDK app calling a long-running Synapsor
+Runner HTTP MCP service.
+
+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.
+
+The model still sees a semantic action. It does not receive raw SQL, database
+URLs, write credentials, approval tools, or commit tools.
+
+## Terminal 1: Start Synapsor Runner HTTP MCP
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="openai_agent_demo"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+## Terminal 2: Run The Agent
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+
+export OPENAI_API_KEY="..."
+export SYNAPSOR_RUNNER_HTTP_URL="http://127.0.0.1:8765/mcp"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+export SYNAPSOR_INVOICE_ID="INV-3001"
+
+python agent.py
+```
+
+Expected behavior:
+
+- the agent calls `billing.inspect_invoice` through Synapsor HTTP MCP;
+- Synapsor applies trusted tenant/principal context from the server process;
+- the response includes scoped data and evidence handles;
+- no SQL/write/approval tool is exposed to the model;
+- evidence/query audit are saved in the local Runner store.
+
+For production-like deployment, keep HTTP MCP behind private networking/TLS,
+bearer auth, and rate limits. See [HTTP MCP](../../docs/http-mcp.md).

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

@@ -0,0 +1,90 @@
+import asyncio
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+try:
+    from agents import Agent, Runner, function_tool
+except ImportError as exc:
+    raise SystemExit(
+        "This example requires the OpenAI Agents SDK. "
+        "Install with: pip install -r requirements.txt"
+    ) from exc
+
+
+def call_synapsor_http_mcp(method: str, params: dict) -> dict:
+    url = os.environ.get("SYNAPSOR_RUNNER_HTTP_URL", "http://127.0.0.1:8765/mcp")
+    token = os.environ.get("SYNAPSOR_RUNNER_HTTP_TOKEN")
+    if not token:
+        raise RuntimeError("SYNAPSOR_RUNNER_HTTP_TOKEN is not set")
+
+    payload = json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": method,
+        "params": params,
+    }).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "authorization": f"Bearer {token}",
+            "content-type": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8")
+        raise RuntimeError(f"Synapsor HTTP MCP returned HTTP {exc.code}: {body}") from exc
+
+    parsed = json.loads(body)
+    if "error" in parsed:
+        raise RuntimeError(f"Synapsor HTTP MCP error: {parsed['error']}")
+    return parsed["result"]
+
+
+@function_tool
+def billing_inspect_invoice(invoice_id: str) -> str:
+    """Inspect one scoped invoice through Synapsor Runner HTTP MCP."""
+    result = call_synapsor_http_mcp("tools/call", {
+        "name": "billing.inspect_invoice",
+        "arguments": {"invoice_id": invoice_id},
+    })
+    return json.dumps(result.get("structuredContent", result), indent=2)
+
+
+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")
+    agent = Agent(
+        name="Synapsor HTTP MCP demo agent",
+        instructions=(
+            "Use the billing_inspect_invoice tool to inspect scoped invoice data. "
+            "Do not claim that you can run SQL, approve proposals, or commit writes."
+        ),
+        tools=[billing_inspect_invoice],
+    )
+    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,62 @@
+# 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 such as `billing.inspect_invoice`. It
+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 demo
+```
+
+or connect your own staging database:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor init --wizard --from-env DATABASE_URL --mode read_only
+```
+
+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;
+- 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 HTTP example, which wraps Synapsor HTTP MCP with a small JSON-RPC
+client.

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",
+            "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

@@ -54,11 +54,62 @@ 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 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 propose billing.propose_late_fee_waiver --sample
+npx -y -p @synapsor/runner@alpha synapsor proposals show latest
+npx -y -p @synapsor/runner@alpha synapsor proposals approve latest --yes
+npx -y -p @synapsor/runner@alpha synapsor apply latest
+npx -y -p @synapsor/runner@alpha synapsor 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 propose support.propose_plan_credit --sample
+npx -y -p @synapsor/runner@alpha synapsor 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:

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

@@ -11,6 +11,8 @@ CREATE TABLE IF NOT EXISTS public.customers (
   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()
 );
@@ -36,6 +38,15 @@ CREATE TABLE IF NOT EXISTS public.invoices (
   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
@@ -50,6 +61,8 @@ $$;
 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 TO synapsor_reader, 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/seed.sql

@@ -4,12 +4,12 @@ VALUES
   ('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, created_at, 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', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_acme_2', 'acme', 'Acme Field Ops', 'field@example.invalid', 'builder', '2026-06-20T10:00:00Z', '2026-06-20T10:00:00Z'),
-  ('cust_other_1', 'otherco', 'OtherCo Labs', 'ops@otherco.invalid', 'builder', '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, updated_at = EXCLUDED.updated_at;
+  ('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
@@ -24,3 +24,10 @@ VALUES
   ('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

@@ -83,6 +83,56 @@
       "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",
@@ -131,6 +181,61 @@
       },
       "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,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,8 @@
     "dist/runner.mjs",
     "docs/**/*.md",
     "examples/dangerous-mcp-tools.json",
+    "examples/openai-agents-http/**",
+    "examples/openai-agents-stdio/**",
     "examples/reference-support-billing-app/**",
     "recipes/**/*.json",
     "README.md",