@synapsor/runner 0.1.0-alpha.9 → 0.1.0

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

@@ -1,63 +1,17 @@
 import asyncio
-import json
 import os
 import sys
-import urllib.error
-import urllib.request
 
 try:
-    from agents import Agent, Runner, function_tool
+    from agents import Agent, Runner
+    from agents.mcp import MCPServerStreamableHttp
 except ImportError as exc:
     raise SystemExit(
-        "This example requires the OpenAI Agents SDK. "
+        "This example requires the OpenAI Agents SDK with Streamable HTTP MCP support. "
         "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)]
@@ -65,22 +19,32 @@ async def main() -> None:
         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)
+    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__":

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

@@ -4,7 +4,10 @@ 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
+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.
 
@@ -13,13 +16,13 @@ commit tools.
 Generate `synapsor.runner.json` first:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner demo
+npx -y -p @synapsor/runner synapsor-runner demo
 ```
 
 or connect your own staging database:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init --wizard --from-env DATABASE_URL --mode read_only
+npx -y -p @synapsor/runner synapsor-runner onboard db --from-env DATABASE_URL
 ```
 
 Then install the Python dependencies:
@@ -52,11 +55,12 @@ export SYNAPSOR_INVOICE_ID="INV-3001"
 
 Expected behavior:
 
-- the agent can inspect the scoped invoice through Synapsor;
+- 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 HTTP example, which wraps Synapsor HTTP MCP with a small JSON-RPC
-client.
+SDK or use the Streamable HTTP example.

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

@@ -27,14 +27,16 @@ async def main() -> None:
         "args": [
             "-y",
             "-p",
-            "@synapsor/runner@alpha",
-            "synapsor",
+            "@synapsor/runner",
+            "synapsor-runner",
             "mcp",
             "serve",
             "--config",
             config_path,
             "--store",
             store_path,
+            "--alias-mode",
+            "openai",
         ],
         "env": {
             **os.environ,

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

@@ -36,14 +36,14 @@ 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
+npx -y -p @synapsor/runner synapsor-runner config validate --config examples/reference-support-billing-app/synapsor.runner.json
+npx -y -p @synapsor/runner 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 \
+npx -y -p @synapsor/runner synapsor-runner mcp serve \
   --config examples/reference-support-billing-app/synapsor.runner.json \
   --store ./tmp/reference-support-billing/local.db
 ```
@@ -69,11 +69,11 @@ After `synapsor-runner demo` or after starting this fixture manually, try the sa
 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
+npx -y -p @synapsor/runner synapsor-runner propose billing.propose_late_fee_waiver --sample
+npx -y -p @synapsor/runner synapsor-runner proposals show latest
+npx -y -p @synapsor/runner synapsor-runner proposals approve latest --yes
+npx -y -p @synapsor/runner synapsor-runner apply latest
+npx -y -p @synapsor/runner synapsor-runner replay latest
 ```
 
 Expected safety output:
@@ -93,8 +93,8 @@ Guarded writeback applied.
 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
+npx -y -p @synapsor/runner synapsor-runner propose support.propose_plan_credit --sample
+npx -y -p @synapsor/runner synapsor-runner propose orders.propose_status_change --sample
 ```
 
 Safety guarantees:
@@ -115,17 +115,17 @@ or production-scale runner orchestration.
 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
+npx -y -p @synapsor/runner synapsor-runner proposals list --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner synapsor-runner proposals approve <proposal_id> --store ./tmp/reference-support-billing/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner 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 synapsor-runner apply --job ./tmp/reference-support-billing/job.json --store ./tmp/reference-support-billing/local.db
+npx -y -p @synapsor/runner 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 \
+npx -y -p @synapsor/runner synapsor-runner ui \
   --config examples/reference-support-billing-app/synapsor.runner.json \
   --store ./tmp/reference-support-billing/local.db
 ```

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

@@ -1,5 +1,5 @@
 {
-  "command": "synapsor",
+  "command": "synapsor-runner",
   "args": [
     "mcp",
     "serve",

package/fixtures/benchmark/mcp-efficiency.json

@@ -0,0 +1,53 @@
+{
+  "benchmark": "mcp-efficiency",
+  "fixture": "late-fee-waiver",
+  "tokenizer": {
+    "name": "synapsor-fixture-tokenizer-v1",
+    "version": 1,
+    "method": "deterministic regex tokenization for fixture comparison; not a model billing tokenizer"
+  },
+  "note": "This benchmark compares the included fixture/reference workflow only. It is not a universal token-savings claim.",
+  "paths": {
+    "generic_database_mcp_reference": {
+      "exposed_tools": 4,
+      "serialized_tools_list_bytes": 822,
+      "serialized_tools_list_tokens": 298,
+      "schema_context_bytes": 215,
+      "schema_context_tokens": 75,
+      "business_result_bytes": 199,
+      "business_result_tokens": 77,
+      "scripted_tool_calls": 5,
+      "exposes_raw_sql": true,
+      "exposes_write_credentials": false,
+      "approval_separated": false,
+      "stale_row_conflict_checked": false
+    },
+    "synapsor_runner_semantic_path": {
+      "exposed_tools": 2,
+      "serialized_tools_list_bytes": 728,
+      "serialized_tools_list_tokens": 236,
+      "schema_context_bytes": 331,
+      "schema_context_tokens": 87,
+      "business_result_bytes": 277,
+      "business_result_tokens": 91,
+      "scripted_tool_calls": 2,
+      "exposes_raw_sql": false,
+      "exposes_write_credentials": false,
+      "approval_separated": true,
+      "stale_row_conflict_checked": true
+    }
+  },
+  "scripted_plans": {
+    "generic_database_mcp_reference": [
+      "list_tables",
+      "describe_table invoices",
+      "query_database SELECT invoice",
+      "formulate raw UPDATE",
+      "execute_sql UPDATE invoice"
+    ],
+    "synapsor_runner_semantic_path": [
+      "billing.inspect_invoice",
+      "billing.propose_late_fee_waiver"
+    ]
+  }
+}

package/fixtures/benchmark/mcp-efficiency.txt

@@ -0,0 +1,25 @@
+MCP efficiency benchmark: late-fee-waiver fixture
+Tokenizer: synapsor-fixture-tokenizer-v1 (deterministic fixture tokenizer; not a model billing tokenizer)
+Scope: included fixture/reference workflow only; not a universal savings claim.
+
+Generic database MCP reference:
+  exposed tools: 4
+  tools/list: 822 bytes, 298 tokens
+  scripted tool calls: 5
+  schema/context: 215 bytes, 75 tokens
+  business result: 199 bytes, 77 tokens
+  raw SQL exposed: yes
+  approval separated: no
+  stale-row conflict checked: no
+
+Synapsor Runner semantic path:
+  exposed tools: 2
+  tools/list: 728 bytes, 236 tokens
+  scripted tool calls: 2
+  schema/context: 331 bytes, 87 tokens
+  business result: 277 bytes, 91 tokens
+  raw SQL exposed: no
+  approval separated: yes
+  stale-row conflict checked: yes
+
+Run with --json to inspect machine-readable measurements and scripted plans.

package/fixtures/protocol/MANIFEST.json

@@ -0,0 +1,54 @@
+{
+  "schema_version": "synapsor.protocol-manifest.v1",
+  "protocol_set": "database-mcp-writeback",
+  "version": "0.1.0-alpha",
+  "hash_algorithm": "sha256",
+  "note": "This manifest is copied in Synapsor main protocol/MANIFEST.json and synapsor-runner fixtures/protocol/MANIFEST.json. Hashes are over the checked-in JSON artifact bytes.",
+  "artifacts": [
+    {
+      "kind": "fixture",
+      "name": "change-set.late-fee-waiver.v1.json",
+      "sha256": "7112d0f28832e61b4ac5846d169666c0476ba92eb68c6790c10ac614ee3f2b33"
+    },
+    {
+      "kind": "fixture",
+      "name": "execution-receipt.applied.v1.json",
+      "sha256": "5af8be1b72b03d5a4c7af22748d9ade9f0febbf5e9503931054361ef998b5870"
+    },
+    {
+      "kind": "fixture",
+      "name": "execution-receipt.conflict.v1.json",
+      "sha256": "64e8a5fd90cdeafa2dd92a2c67cad1307b9d09e585cc82b06b987bde382f7733"
+    },
+    {
+      "kind": "fixture",
+      "name": "runner-registration.v1.json",
+      "sha256": "3eaf844cdc94a4274601cedfed7252d65dd837a345c8c3b0f17ab6bbdf7f75da"
+    },
+    {
+      "kind": "fixture",
+      "name": "writeback-job.late-fee-waiver.v1.json",
+      "sha256": "577e7987427031b55134c3d7296e644b1c8b7adec495758d4cff3665e954dbc8"
+    },
+    {
+      "kind": "schema",
+      "name": "change-set.v1.schema.json",
+      "sha256": "4e52b369b0d3bea30b0ed7b61ec239fc67de3dc691ed4014d6d5eabc7d2be4de"
+    },
+    {
+      "kind": "schema",
+      "name": "execution-receipt.v1.schema.json",
+      "sha256": "69504ce51fa66440e42d57ef6cb36cc6d8543427d8d385c9ccff954ecae5ec83"
+    },
+    {
+      "kind": "schema",
+      "name": "runner-registration.v1.schema.json",
+      "sha256": "86242555545b44ae747965ddb8aa35e2982587c76c2538f0f646e8b63994286b"
+    },
+    {
+      "kind": "schema",
+      "name": "writeback-job.v1.schema.json",
+      "sha256": "eab35194dd6b6caa7694aa8f14afbf265338d6ee8ed3d3db5d08ec83c4e7092e"
+    }
+  ]
+}

package/fixtures/protocol/change-set.late-fee-waiver.v1.json

@@ -0,0 +1,72 @@
+{
+  "schema_version": "synapsor.change-set.v1",
+  "proposal_id": "wrp_123",
+  "proposal_version": 1,
+  "action": "billing.waive_late_fee",
+  "mode": "review_required",
+  "principal": {
+    "id": "support_agent_17",
+    "source": "trusted_session"
+  },
+  "scope": {
+    "tenant_id": "acme",
+    "business_object": "invoice",
+    "object_id": "INV-3001"
+  },
+  "source": {
+    "kind": "external_postgres",
+    "source_id": "src_pg_acme",
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": {
+      "column": "id",
+      "value": "INV-3001"
+    }
+  },
+  "before": {
+    "late_fee_cents": 5500,
+    "waiver_reason": null,
+    "updated_at": "2026-06-20T14:31:08Z"
+  },
+  "patch": {
+    "late_fee_cents": 0,
+    "waiver_reason": "customer requested review"
+  },
+  "after": {
+    "late_fee_cents": 0,
+    "waiver_reason": "customer requested review",
+    "updated_at": "2026-06-20T14:31:08Z"
+  },
+  "guards": {
+    "tenant": {
+      "column": "tenant_id",
+      "value": "acme"
+    },
+    "allowed_columns": [
+      "late_fee_cents",
+      "waiver_reason"
+    ],
+    "expected_version": {
+      "column": "updated_at",
+      "value": "2026-06-20T14:31:08Z"
+    }
+  },
+  "evidence": {
+    "bundle_id": "ev_456",
+    "query_fingerprint": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+    "items": []
+  },
+  "approval": {
+    "status": "pending",
+    "required_role": "support_lead"
+  },
+  "writeback": {
+    "status": "not_applied",
+    "mode": "trusted_worker_required"
+  },
+  "source_database_mutated": false,
+  "integrity": {
+    "proposal_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222"
+  },
+  "created_at": "2026-06-20T14:31:09Z"
+}

package/fixtures/protocol/execution-receipt.applied.v1.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": "synapsor.execution-receipt.v1",
+  "writeback_job_id": "wbj_123",
+  "proposal_id": "wrp_123",
+  "runner_id": "runner_123",
+  "status": "applied",
+  "rows_affected": 1,
+  "idempotency_key": "wrp_123:INV-3001",
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:34:19Z",
+  "source_database_mutated": true,
+  "executed_at": "2026-06-20T14:34:19Z",
+  "receipt_hash": "sha256:3333333333333333333333333333333333333333333333333333333333333333"
+}

package/fixtures/protocol/execution-receipt.conflict.v1.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": "synapsor.execution-receipt.v1",
+  "writeback_job_id": "wbj_124",
+  "proposal_id": "wrp_124",
+  "runner_id": "runner_123",
+  "status": "conflict",
+  "rows_affected": 0,
+  "idempotency_key": "wrp_124:INV-3001",
+  "previous_version": "2026-06-20T14:31:08Z",
+  "new_version": "2026-06-20T14:39:19Z",
+  "source_database_mutated": false,
+  "executed_at": "2026-06-20T14:40:19Z",
+  "safe_error_code": "VERSION_CONFLICT",
+  "receipt_hash": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
+}

package/fixtures/protocol/runner-registration.v1.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": "synapsor.runner-registration.v1",
+  "runner_id": "runner_123",
+  "runner_version": "0.1.0-alpha.0",
+  "engines": [
+    "postgres",
+    "mysql"
+  ],
+  "capabilities": [
+    "single_row_update",
+    "idempotency_receipts",
+    "version_conflict_guard"
+  ],
+  "scope": {
+    "project_id": "acme-support",
+    "source_ids": [
+      "src_pg_acme",
+      "src_mysql_acme"
+    ]
+  },
+  "registered_at": "2026-06-20T14:30:00Z"
+}

package/fixtures/protocol/writeback-job.late-fee-waiver.v1.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": "synapsor.writeback-job.v1",
+  "writeback_job_id": "wbj_123",
+  "proposal_id": "wrp_123",
+  "proposal_version": 1,
+  "proposal_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+  "runner_scope": {
+    "project_id": "acme-support",
+    "source_id": "src_pg_acme"
+  },
+  "engine": "postgres",
+  "operation": "single_row_update",
+  "target": {
+    "schema": "public",
+    "table": "invoices",
+    "primary_key": {
+      "column": "id",
+      "value": "INV-3001"
+    }
+  },
+  "tenant_guard": {
+    "column": "tenant_id",
+    "value": "acme"
+  },
+  "allowed_columns": [
+    "late_fee_cents",
+    "waiver_reason"
+  ],
+  "patch": {
+    "late_fee_cents": 0,
+    "waiver_reason": "approved support waiver"
+  },
+  "conflict_guard": {
+    "kind": "column",
+    "column": "updated_at",
+    "expected_value": "2026-06-20T14:31:08Z"
+  },
+  "idempotency_key": "wrp_123:INV-3001",
+  "lease": {
+    "lease_id": "lease_123",
+    "attempt": 1,
+    "expires_at": "2026-06-20T14:36:00Z"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0",
   "description": "Commit-safe MCP runner for Postgres and MySQL agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,11 +16,16 @@
     "dist/runner.mjs",
     "docs/**/*.md",
     "examples/dangerous-mcp-tools.json",
+    "examples/app-owned-writeback/**",
+    "examples/mcp-postgres-billing-app-handler/**",
     "examples/openai-agents-http/**",
     "examples/openai-agents-stdio/**",
     "examples/reference-support-billing-app/**",
+    "fixtures/**",
+    "schemas/**",
     "recipes/**/*.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE",
     "TRADEMARKS.md"