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

package/examples/app-owned-writeback/business-actions.md

@@ -0,0 +1,221 @@
+# App-Owned Business Action Examples
+
+These examples show the kinds of approved proposals an app-owned handler can
+apply. They are intentionally not direct SQL examples. Your application service
+owns the write transaction, re-checks authorization and row/version guards, and
+returns a terminal receipt to Synapsor Runner.
+
+Each request uses the same boundary:
+
+```text
+model-facing MCP tool -> proposal
+human/operator approval -> app-owned handler
+handler transaction -> applied/conflict/failed receipt
+local replay
+```
+
+The handler must not trust request fields blindly. Re-check tenant,
+principal/role, idempotency, row versions, and business policy before mutating
+state.
+
+## Create A Refund Review
+
+Use this when an agent may request a refund review, but your application must
+create the review record through normal business logic.
+
+Capability:
+
+```text
+refunds.propose_refund_review(order_id, reason, requested_amount_cents)
+```
+
+Handler request:
+
+```json
+{
+  "schema_version": "synapsor.handler-writeback.v1",
+  "writeback_job_id": "hwb_wrp_refund_001",
+  "proposal_id": "wrp_refund_001",
+  "idempotency_key": "wrp_refund_001",
+  "change_set": {
+    "action": "refunds.propose_refund_review",
+    "scope": {
+      "tenant_id": "acme",
+      "principal": "support_lead@example.com",
+      "object_type": "order",
+      "object_id": "ORD-3001"
+    },
+    "before": {
+      "order_status": "delivered",
+      "refund_review_id": null
+    },
+    "patch": {
+      "requested_amount_cents": 2500,
+      "reason": "duplicate charge"
+    },
+    "after": {
+      "refund_review_status": "pending_review"
+    },
+    "guards": {
+      "expected_version": {
+        "column": "updated_at",
+        "value": "2026-06-20T14:31:08Z"
+      }
+    },
+    "evidence": {
+      "bundle_id": "ev_refund_001"
+    }
+  },
+  "executor": "app_writeback_api",
+  "dry_run": false
+}
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify principal can request refunds for tenant acme
+  verify order ORD-3001 still belongs to tenant acme
+  verify order.updated_at still matches expected_version
+  verify no receipt exists for idempotency_key
+  INSERT INTO refund_reviews (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 1,
+  "new_object_id": "RR-9001",
+  "source_database_mutated": true
+}
+```
+
+## Insert An Account Credit Row
+
+Use this when the safe write is an append-only ledger/accounting operation.
+
+Capability:
+
+```text
+credits.propose_account_credit(customer_id, amount_cents, reason)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify customer belongs to trusted tenant
+  verify amount is within app policy
+  verify idempotency_key has not already created a credit
+  INSERT INTO account_credits (...)
+  UPDATE customers SET credit_balance_cents = credit_balance_cents + amount
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Conflict receipt if the app policy no longer allows the credit:
+
+```json
+{
+  "status": "conflict",
+  "safe_error_code": "CREDIT_POLICY_CHANGED",
+  "source_database_mutated": false,
+  "details": {
+    "reason": "customer credit limit changed after proposal"
+  }
+}
+```
+
+## Open A Support Ticket
+
+Use this when the agent may propose opening a ticket, but ticket creation must
+go through your helpdesk/application service.
+
+Capability:
+
+```text
+support.propose_open_ticket(customer_id, subject, body)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify principal can open support tickets for tenant
+  verify customer belongs to tenant
+  validate subject/body against app policy
+  INSERT INTO support_tickets (...)
+  INSERT INTO ticket_events (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 2,
+  "new_object_id": "T-9100",
+  "source_database_mutated": true
+}
+```
+
+## Update Multiple Related Rows
+
+Use this when an approved business action spans several tables and should stay
+inside your normal application transaction.
+
+Capability:
+
+```text
+subscriptions.propose_trial_extension(customer_id, extension_days, reason)
+```
+
+Handler transaction sketch:
+
+```text
+BEGIN
+  verify tenant/principal authorization
+  SELECT subscription FOR UPDATE
+  verify expected subscription version
+  UPDATE subscriptions SET trial_ends_at = ...
+  INSERT INTO customer_events (...)
+  INSERT INTO billing_notes (...)
+  INSERT INTO synapsor_app_receipts (...)
+COMMIT
+```
+
+Receipt:
+
+```json
+{
+  "status": "applied",
+  "rows_affected": 3,
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:34:19Z",
+  "source_database_mutated": true
+}
+```
+
+## Idempotent Retry
+
+If the same `idempotency_key` reaches your handler again after a successful
+apply, return `already_applied` and the original receipt details rather than
+running the transaction again.
+
+```json
+{
+  "status": "already_applied",
+  "rows_affected": 0,
+  "source_database_mutated": false,
+  "details": {
+    "original_receipt_id": "rct_abc123"
+  }
+}
+```

package/examples/app-owned-writeback/command-handler.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const chunks = [];
+for await (const chunk of process.stdin) chunks.push(chunk);
+
+const request = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+const changeSet = request.change_set || {};
+
+if (!request.proposal_id || !request.idempotency_key || !changeSet.scope?.tenant_id) {
+  process.stdout.write(JSON.stringify({
+    status: "failed",
+    safe_error_code: "BAD_WRITEBACK_REQUEST",
+    source_database_mutated: false,
+  }));
+  process.exit(0);
+}
+
+if (request.dry_run) {
+  process.stdout.write(JSON.stringify({
+    status: "applied",
+    rows_affected: 0,
+    source_database_mutated: false,
+    details: { dry_run: true },
+  }));
+  process.exit(0);
+}
+
+/*
+ * Put your app-owned command transaction here.
+ *
+ * Examples:
+ * - call an internal service;
+ * - enqueue a review job;
+ * - run an app migration-safe script that uses your normal ORM.
+ *
+ * Re-check tenant/principal authorization, idempotency, row/version guards,
+ * and business policy before mutating application state.
+ */
+
+process.stdout.write(JSON.stringify({
+  status: "applied",
+  rows_affected: 1,
+  previous_version: String(changeSet.guards?.expected_version?.value || ""),
+  new_version: new Date().toISOString(),
+  source_database_mutated: true,
+}));

package/examples/app-owned-writeback/node-fastify-handler.mjs

@@ -0,0 +1,55 @@
+import Fastify from "fastify";
+
+const port = Number(process.env.PORT || 8787);
+const expectedToken = process.env.SYNAPSOR_APP_WRITEBACK_TOKEN || "dev-handler-token";
+
+const app = Fastify({ logger: true });
+
+app.post("/synapsor/writeback", async (request, reply) => {
+  const auth = request.headers.authorization || "";
+  if (auth !== `Bearer ${expectedToken}`) {
+    return reply.code(401).send({ status: "failed", error_code: "UNAUTHORIZED" });
+  }
+
+  const body = request.body || {};
+  const changeSet = body.change_set || {};
+
+  if (!body.proposal_id || !body.idempotency_key || !changeSet.scope?.tenant_id) {
+    return reply.code(400).send({ status: "failed", error_code: "BAD_WRITEBACK_REQUEST" });
+  }
+
+  if (body.dry_run) {
+    return {
+      status: "applied",
+      rows_affected: 0,
+      source_database_mutated: false,
+      details: { dry_run: true },
+    };
+  }
+
+  /*
+   * Put your app-owned transaction here.
+   *
+   * Examples:
+   * - insert a refund_review row;
+   * - insert an account_credit row;
+   * - open a support_ticket row;
+   * - update invoice + ledger rows together.
+   *
+   * Re-check:
+   * - tenant and principal authorization;
+   * - idempotency_key has not already been applied;
+   * - row/version guards still match;
+   * - requested business action is allowed by your app policy.
+   */
+
+  return {
+    status: "applied",
+    rows_affected: 1,
+    previous_version: String(changeSet.guards?.expected_version?.value || ""),
+    new_version: new Date().toISOString(),
+    source_database_mutated: true,
+  };
+});
+
+app.listen({ host: "127.0.0.1", port });

package/examples/app-owned-writeback/python-fastapi-handler.py

@@ -0,0 +1,57 @@
+import os
+from datetime import datetime, timezone
+
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+
+
+class HandlerRequest(BaseModel):
+    schema_version: str
+    writeback_job_id: str
+    proposal_id: str
+    idempotency_key: str
+    change_set: dict
+    executor: str | None = None
+    dry_run: bool = False
+
+
+app = FastAPI()
+EXPECTED_TOKEN = os.environ.get("SYNAPSOR_APP_WRITEBACK_TOKEN", "dev-handler-token")
+
+
+@app.post("/synapsor/writeback")
+def writeback(request: HandlerRequest, authorization: str | None = Header(default=None)):
+    if authorization != f"Bearer {EXPECTED_TOKEN}":
+        raise HTTPException(status_code=401, detail="UNAUTHORIZED")
+
+    scope = request.change_set.get("scope", {})
+    if not scope.get("tenant_id"):
+        raise HTTPException(status_code=400, detail="BAD_WRITEBACK_REQUEST")
+
+    if request.dry_run:
+        return {
+            "status": "applied",
+            "rows_affected": 0,
+            "source_database_mutated": False,
+            "details": {"dry_run": True},
+        }
+
+    # Put your app-owned transaction here.
+    #
+    # Examples:
+    # - insert a refund_review row;
+    # - insert an account_credit row;
+    # - open a support_ticket row;
+    # - update invoice + ledger rows together.
+    #
+    # Re-check tenant/principal authorization, idempotency, row/version guards,
+    # and business policy before mutating application state.
+
+    expected = request.change_set.get("guards", {}).get("expected_version", {})
+    return {
+        "status": "applied",
+        "rows_affected": 1,
+        "previous_version": str(expected.get("value", "")),
+        "new_version": datetime.now(timezone.utc).isoformat(),
+        "source_database_mutated": True,
+    }

package/examples/dangerous-mcp-tools.json

@@ -0,0 +1,88 @@
+{
+  "tools": [
+    {
+      "name": "execute_sql",
+      "description": "Execute arbitrary SQL against the application database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "sql": { "type": "string" }
+        },
+        "required": ["sql"]
+      }
+    },
+    {
+      "name": "run_query",
+      "description": "Run any query and return database rows.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["query"]
+      }
+    },
+    {
+      "name": "approve_refund",
+      "description": "Approve and issue a customer refund immediately.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "refund_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "amount_cents": { "type": "number" }
+        },
+        "required": ["refund_id", "tenant_id", "amount_cents"]
+      }
+    },
+    {
+      "name": "update_customer",
+      "description": "Update a customer record directly.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "customer_id": { "type": "string" },
+          "tenant_id": { "type": "string" },
+          "column": { "type": "string" },
+          "value": { "type": "string" }
+        },
+        "required": ["customer_id", "tenant_id", "column", "value"]
+      }
+    },
+    {
+      "name": "delete_order",
+      "description": "Delete an order from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "order_id": { "type": "string" },
+          "tenant_id": { "type": "string" }
+        },
+        "required": ["order_id", "tenant_id"]
+      }
+    },
+    {
+      "name": "query_database",
+      "description": "Query arbitrary tables and columns from the database.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "database": { "type": "string" },
+          "schema": { "type": "string" },
+          "table": { "type": "string" },
+          "columns": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "where": { "type": "string" }
+        },
+        "required": ["table"]
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,56 @@
+# OpenAI Agents SDK + Synapsor Runner Streamable HTTP MCP
+
+This example shows an OpenAI Agents SDK app connecting to a long-running
+Synapsor Runner Streamable HTTP MCP server.
+
+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.
+
+This example uses `synapsor-runner mcp serve-streamable-http`, the
+spec-compatible HTTP MCP transport with `initialize` and session behavior. Use
+`synapsor-runner mcp serve-http` only when you intentionally want the smaller
+JSON-RPC bridge and an app-owned wrapper.
+
+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-runner mcp serve-streamable-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:8766/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,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,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-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;
+- 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.