@synapsor/runner 0.1.0-alpha.9 → 0.1.0

package/docs/http-mcp.md

@@ -6,14 +6,73 @@ needs to connect to a long-running Synapsor Runner service.
 Use stdio MCP when a local MCP client such as Claude Desktop, Cursor, or a
 local agent tool can launch Synapsor Runner directly.
 
-Current alpha scope: `serve-http` exposes a small authenticated JSON-RPC
-endpoint at `POST /mcp` for `tools/list`, `tools/call`, and `resources/read`.
-It is not the full MCP Streamable HTTP transport and does not implement an
-`initialize`/SSE session handshake. If your SDK expects full HTTP MCP
-initialization, use stdio mode or wrap this endpoint with a thin tool/function
-adapter like the OpenAI HTTP example.
+Synapsor Runner has two HTTP modes:
 
-## Start The HTTP Server
+- `mcp serve-streamable-http`: spec-compatible MCP Streamable HTTP. Use this
+  when an MCP SDK/client expects `initialize`, session IDs, POST/GET/DELETE, and
+  standard HTTP MCP behavior.
+- `mcp serve-http`: a lightweight authenticated JSON-RPC bridge for
+  `tools/list`, `tools/call`, and `resources/read`. Use this when your app wants
+  simple POST calls or an explicit wrapper around Runner tools.
+
+## Start Standard Streamable HTTP MCP
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor-runner mcp serve-streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+For OpenAI Agents SDK, expose OpenAI-safe aliases because OpenAI function names
+cannot contain dots:
+
+```bash
+synapsor-runner mcp serve-streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+Equivalent unified command:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+The model sees aliases such as `billing__inspect_invoice`. MCP tool metadata
+still includes `synapsor.canonical_tool_name`, and Runner maps calls back to
+the canonical Synapsor capability such as `billing.inspect_invoice`. Use
+`--alias-mode both` only during migrations where some clients still need
+canonical dotted names.
+
+Defaults:
+
+```text
+host: 127.0.0.1
+port: 8766
+auth: bearer token required
+cors: disabled
+sessions: in-memory
+```
+
+Use `/mcp` as the MCP endpoint. Health is available at `/healthz`.
+
+## Start The JSON-RPC Bridge
 
 ```bash
 export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
@@ -35,12 +94,17 @@ auth: bearer token required
 cors: disabled
 ```
 
+Bridge scope: `serve-http` does not implement MCP Streamable HTTP
+`initialize`/session behavior. Standard SDK HTTP MCP clients should use
+`serve-streamable-http` instead.
+
 Startup output prints the URL, config path, store path, and token environment
 variable name. It does not print token values or database URLs.
 
 ## Health Check
 
 ```bash
+curl -i http://127.0.0.1:8766/healthz
 curl -i http://127.0.0.1:8765/healthz
 ```
 
@@ -49,13 +113,13 @@ The health endpoint is secret-free:
 ```json
 {
   "ok": true,
-  "transport": "http",
+  "transport": "streamable-http",
   "tools": 1,
   "mode": "read_only"
 }
 ```
 
-## List Tools
+## List Tools Through The JSON-RPC Bridge
 
 Unauthorized requests fail:
 
@@ -96,7 +160,7 @@ model-controlled tenant authority
 arbitrary table or column names
 ```
 
-## Call A Tool
+## Call A Tool Through The JSON-RPC Bridge
 
 ```bash
 curl -i \
@@ -118,7 +182,7 @@ The response includes scoped data, trusted context, evidence handles, and
 `source_database_mutated: false`. The agent still does not receive SQL,
 database credentials, or approval/commit authority.
 
-## Read Evidence Or Replay Resources
+## Read Evidence Or Replay Resources Through The JSON-RPC Bridge
 
 Use `resources/read` with a `synapsor://...` handle returned by a tool call:
 
@@ -200,9 +264,13 @@ examples/openai-agents-http/
 examples/openai-agents-stdio/
 ```
 
-The stdio example uses the MCP client integration from the OpenAI Agents SDK
-when available. The HTTP example uses a minimal JSON-RPC client wrapped as an
-OpenAI function tool because native HTTP MCP client support can vary by SDK
-version and Runner's HTTP alpha endpoint is intentionally limited to JSON-RPC
-tool/resource calls. The boundary is the same: the agent calls a semantic
-Synapsor tool, not raw SQL.
+Both examples use the MCP client integration from the OpenAI Agents SDK when it
+is available. The stdio example launches Runner as a child process. The HTTP
+example connects to `synapsor-runner mcp serve-streamable-http` through
+`MCPServerStreamableHttp`. Use the JSON-RPC bridge only when you intentionally
+want a small app-owned wrapper instead of standard HTTP MCP.
+
+The boundary is the same in both modes: the agent calls a semantic Synapsor
+tool, not raw SQL. OpenAI-facing examples use `--alias-mode openai` so
+the model sees OpenAI-valid aliases while Runner preserves canonical Synapsor
+tool names in metadata.

package/docs/licensing.md

@@ -0,0 +1,36 @@
+# Licensing
+
+Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
+
+This page is a plain-English summary, not legal advice. If this summary
+conflicts with `../LICENSE`, the `LICENSE` file controls.
+
+Apache-2.0 applies to the code in this runner repository. It grants copyright
+and patent rights under the license terms.
+
+Apache-2.0 does not grant trademark rights. The Synapsor name, Synapsor Runner
+name, logos, hosted Cloud service, and proprietary Synapsor platform features
+remain separate. See `../TRADEMARKS.md`.
+
+This license applies only to `synapsor-runner`. It does not open source:
+
+- Synapsor Cloud;
+- the hosted control plane;
+- hosted capability registry;
+- advanced policy/capability compiler;
+- team approvals, RBAC, or SSO;
+- hosted audit/evidence ledger;
+- managed runners;
+- production writeback orchestration;
+- workflow builder;
+- native Synapsor engine;
+- C++/DBMS internals;
+- branching, time travel, or settlement;
+- compliance exports or production support/SLA.
+
+Synapsor Cloud is a separate hosted commercial service. Use Cloud when your team
+needs shared approvals, RBAC, hosted evidence/replay search, runner fleet
+status, leases, retention, audit visibility, enterprise controls, and support.
+
+Before public release, license and trademark text should be reviewed by the
+release owner or qualified counsel.

package/docs/local-mode.md

@@ -43,13 +43,13 @@ want to change your host Node version.
 Create a starter config without putting credentials in the file:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init --engine postgres --mode review
+npx -y -p @synapsor/runner synapsor-runner init --engine postgres --mode review
 ```
 
 For MySQL:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init --engine mysql --mode review --output synapsor.mysql.runner.json
+npx -y -p @synapsor/runner synapsor-runner init --engine mysql --mode review --output synapsor.mysql.runner.json
 ```
 
 The generated config uses environment-variable names for read/write URLs and trusted context. Edit the table, column, and capability names before serving tools.
@@ -62,8 +62,8 @@ persisted into proposals, evidence, query audit, runner state, or replay.
 For a reviewed own-database setup generated from explicit selections, use:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init --spec onboarding-selection.json --non-interactive
-npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner init --spec onboarding-selection.json --non-interactive
+npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
 ```
 
 `doctor --config` checks config validation, required environment variables,
@@ -75,25 +75,27 @@ and the semantic MCP tool boundary without printing credential values.
 Use stdio for local MCP clients that launch Synapsor Runner:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+npx -y -p @synapsor/runner synapsor-runner mcp serve \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
 
-Use HTTP when your app/server agent connects to a long-running Runner process:
+Use Streamable HTTP when your app/server agent connects through a standard HTTP
+MCP client:
 
 ```bash
 export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
 
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
-HTTP defaults to `127.0.0.1:8765`, requires bearer auth by default, and should
-run behind private networking/TLS before production-like exposure. Details:
-[HTTP MCP](http-mcp.md).
+Streamable HTTP defaults to `127.0.0.1:8766`, requires bearer auth by default,
+and should run behind private networking/TLS before production-like exposure.
+Use `synapsor-runner mcp serve-http` only when you explicitly want the smaller
+JSON-RPC bridge. Details: [HTTP MCP](http-mcp.md).
 
 ## Local safety modes
 
@@ -125,19 +127,19 @@ If neither is set, the CLI uses:
 List proposals:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner proposals list --store ./.synapsor/local.db
 ```
 
 Show a proposal:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
 ```
 
 Approve:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 \
+npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 \
   --store ./.synapsor/local.db \
   --actor local_reviewer \
   --yes
@@ -148,7 +150,7 @@ Before approval, the CLI prints the reviewer-critical proposal details: trusted
 Create a guarded writeback job from an approved proposal:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 \
+npx -y -p @synapsor/runner synapsor-runner proposals writeback-job wrp_123 \
   --store ./.synapsor/local.db \
   --project local \
   --runner local_runner \
@@ -160,7 +162,7 @@ The generated job uses the public `synapsor.writeback-job.v1` protocol and can b
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="postgresql://writer:<password>@localhost:5432/app"
 SYNAPSOR_ENGINE=postgres \
-npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 When `--config` is passed, direct SQL writeback reads the writer connection from
@@ -172,7 +174,7 @@ Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally.
 Reject:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner proposals reject wrp_123 \
+npx -y -p @synapsor/runner synapsor-runner proposals reject wrp_123 \
   --store ./.synapsor/local.db \
   --reason "policy evidence is incomplete" \
   --yes
@@ -189,7 +191,7 @@ Shadow-mode proposals are inspectable through `proposals show` and `replay show`
 Start a localhost-only review UI:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner ui --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner ui --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 The UI shows setup summary, semantic tools, proposal states, exact diffs,
@@ -205,20 +207,20 @@ tools, MCP commit tools, or controls that widen configured tables/columns.
 Show replay:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner replay show --proposal wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner replay show --replay replay_wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor-runner replay show --evidence ev_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner replay show --proposal wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner replay show --replay replay_wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner replay show --evidence ev_123 --store ./.synapsor/local.db
 ```
 
 Export replay:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner replay export wrp_123 \
+npx -y -p @synapsor/runner synapsor-runner replay export wrp_123 \
   --store ./.synapsor/local.db \
   --output replay.json
 
-npx -y -p @synapsor/runner@alpha synapsor-runner replay export --proposal wrp_123 \
+npx -y -p @synapsor/runner synapsor-runner replay export --proposal wrp_123 \
   --format markdown \
   --store ./.synapsor/local.db \
   --output replay.md
@@ -271,13 +273,30 @@ or prune it without touching your source Postgres/MySQL database:
 
 ```bash
 synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner events tail --store ./.synapsor/local.db
+synapsor-runner events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created --store ./.synapsor/local.db
 synapsor-runner store vacuum --store ./.synapsor/local.db
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes --force
+synapsor-runner store reset --store ./.synapsor/local.db --yes
 ```
 
-`store prune` defaults to dry-run. Use `--yes` only after reviewing the row
-counts it will remove.
+`events tail` shows local lifecycle events already recorded in the SQLite
+ledger, including proposal creation, approval/rejection, writeback jobs, and
+writeback applied/conflict/failed receipts. Add `--follow` to keep polling a
+running local store.
+
+`events webhook` pushes the same local lifecycle events to a local/dev/staging
+HTTP endpoint, one event envelope per POST. Use it for a review UI, Slack bridge,
+or app-local notification path when polling is awkward. It is not a hosted
+central ledger and does not expose database credentials.
+
+`store prune` defaults to dry-run. `store reset` requires `--yes` and removes
+only the local SQLite ledger files. MCP server modes write a small active-store
+lease next to the SQLite file; destructive store operations refuse while that
+lease points at a live PID unless you pass `--force` after verifying the server
+is stopped or stale.
 
 ## Boundary
 

package/docs/mcp-audit.md

@@ -1,6 +1,6 @@
 # MCP database risk review
 
-`npx -y -p @synapsor/runner@alpha synapsor-runner audit <target>` performs a
+`npx -y -p @synapsor/runner synapsor-runner audit <target>` performs a
 static MCP database risk review over an exported tool manifest, a remote MCP
 `tools/list` endpoint, or a stdio MCP server. The `mcp audit` subcommand is also
 available for users who look for the command under the MCP namespace.
@@ -23,7 +23,7 @@ MCP annotations are treated as hints, not enforcement.
 Built-in database MCP risk example:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp
+npx -y -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp
 ```
 
 This bundled example does not require a source checkout or local examples file.
@@ -34,38 +34,38 @@ table/column inputs, and model-controlled tenant/principal fields.
 Human-readable output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit ./tools-list.json
+npx -y -p @synapsor/runner synapsor-runner audit ./tools-list.json
 ```
 
 Remote `tools/list` endpoint with a bearer token kept in the environment:
 
 ```bash
 SYNAPSOR_MCP_AUDIT_BEARER="..." \
-npx -y -p @synapsor/runner@alpha synapsor-runner audit https://mcp.example.com --format json
+npx -y -p @synapsor/runner synapsor-runner audit https://mcp.example.com --format json
 ```
 
 Remote endpoint with a custom bearer-token environment variable:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
+npx -y -p @synapsor/runner synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
 ```
 
 Stdio MCP server:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit 'stdio:node ./server.mjs' --timeout-ms 5000
+npx -y -p @synapsor/runner synapsor-runner audit 'stdio:node ./server.mjs' --timeout-ms 5000
 ```
 
 JSON output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit ./tools-list.json --format json
+npx -y -p @synapsor/runner synapsor-runner audit ./tools-list.json --format json
 ```
 
 Markdown output for issues, PRs, or security review notes:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp --format markdown
+npx -y -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp --format markdown
 ```
 
 During local development, the repo-local wrapper can run the same command:

package/docs/mcp-client-setup.md

@@ -6,10 +6,10 @@ The primary local proof path is still the one-command Docker demo:
 ./scripts/demo-docker.sh
 ```
 
-Use this page after that demo passes and you want to attach a local MCP client.
-The tested local-client contract here is stdio. HTTP MCP is available for
-app/server deployments where your agent connects to a long-running Runner
-service.
+Use this page after that demo passes and you want to attach a local MCP client
+or SDK. The simplest local-client contract is stdio. Standard HTTP MCP is
+available through Streamable HTTP when your agent connects to a long-running
+Runner service.
 
 Command examples use the published alpha package through `npx`. From a source
 checkout, use `./bin/synapsor-runner ...` only when you intentionally want the local
@@ -32,28 +32,53 @@ corepack pnpm test:mcp-client-configs
 | Mode | Use when | Command |
 | --- | --- | --- |
 | stdio | Claude Desktop, Cursor, VS Code, or another local MCP client can launch Synapsor Runner | `synapsor-runner mcp serve` |
-| HTTP | Your app/server, Python agent, Node service, or container connects to a long-running Runner service | `synapsor-runner mcp serve-http` |
+| Streamable HTTP MCP | Your app/server, Python agent, Node service, or container uses a standard HTTP MCP client | `synapsor-runner mcp serve-streamable-http` |
+| JSON-RPC bridge | Your app wants a small explicit wrapper around `tools/list`, `tools/call`, and `resources/read` | `synapsor-runner mcp serve-http` |
 
 Stdio keeps the MCP protocol on process stdin/stdout and is the simplest local
-developer path. HTTP uses JSON-RPC over an authenticated `/mcp` endpoint and is
-better for app/server deployments.
-
-Important alpha limitation: HTTP mode is not full MCP Streamable HTTP. It does
-not implement `initialize` or an SSE session handshake. Standard SDK HTTP MCP
-clients that require initialization may fail. Use stdio for those clients, or
-call Runner's HTTP JSON-RPC endpoint through a thin app/server wrapper.
+developer path. Streamable HTTP implements MCP initialize/session behavior over
+an authenticated `/mcp` endpoint. The JSON-RPC bridge is intentionally smaller
+and does not implement MCP initialize/session behavior.
 
 HTTP requires bearer auth by default:
 
 ```bash
 export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
 
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
+OpenAI Agents SDK rejects dotted function/tool names such as
+`billing.inspect_invoice`. For OpenAI-facing transports, ask Runner to expose
+OpenAI-safe aliases while keeping canonical Synapsor capability names in MCP
+metadata:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+The model sees names such as `billing__inspect_invoice`; `_meta` includes
+`synapsor.canonical_tool_name = billing.inspect_invoice`, and Runner routes the
+alias back to the canonical capability. Use `--alias-mode both` only when a
+migration needs canonical dotted names and OpenAI-safe aliases exposed at the
+same time.
+
+Preview the exact alias mapping before wiring a client:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
 Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
 [HTTP MCP](http-mcp.md).
 
@@ -62,7 +87,7 @@ Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
 Print a snippet without modifying any client files:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
@@ -75,18 +100,29 @@ generic
 claude-desktop
 cursor
 vscode
+openai-agents
+```
+
+For OpenAI Agents SDK, generate the Streamable HTTP start command and Python
+snippet:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner mcp client-config \
+  --client openai-agents \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
 ```
 
 The older form is still supported:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Write is opt-in and requires an explicit destination:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure \
+npx -y -p @synapsor/runner synapsor-runner mcp configure \
   --client cursor \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -105,22 +141,24 @@ database URLs or passwords into the client config.
 From the runner repository:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For the alpha package, keep the package tag explicit in client configuration.
 
-For app/server HTTP mode:
+For standard app/server HTTP MCP mode:
 
 ```bash
 export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
 
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./examples/mcp-postgres-billing/synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
+For the smaller JSON-RPC bridge, use `synapsor-runner mcp serve-http` instead.
+
 ## Generic stdio Client
 
 ```json
@@ -131,7 +169,7 @@ npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
       "args": [
         "-y",
         "-p",
-        "@synapsor/runner@alpha",
+        "@synapsor/runner",
         "synapsor-runner",
         "mcp",
         "serve",
@@ -174,7 +212,7 @@ small tool-call test.
 First confirm what Runner exposes:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner tools preview \
+npx -y -p @synapsor/runner synapsor-runner tools preview \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```

package/docs/openai-agents-sdk.md

@@ -0,0 +1,57 @@
+# OpenAI Agents SDK
+
+Use Synapsor Runner with the OpenAI Agents SDK through standard MCP Streamable
+HTTP. Runner exposes semantic database tools to the model and keeps approval,
+writeback, database URLs, and write credentials outside the model-facing tool
+surface.
+
+## Start Runner
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+`--alias-mode openai` is important because OpenAI function/tool names cannot
+contain dots. Runner exposes names such as `billing__inspect_invoice` to the
+model and maps calls back to canonical Synapsor capability names such as
+`billing.inspect_invoice`.
+
+## Generate The Snippet
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner mcp client-config \
+  --client openai-agents \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The generated output includes:
+
+- the Streamable HTTP server command;
+- the `/mcp` URL;
+- a Python `MCPServerStreamableHttp` snippet;
+- the OpenAI alias note.
+
+It does not include database URLs, passwords, write credentials, API keys, or
+bearer token values.
+
+## Sanity Check
+
+Before giving the agent a real task, ask it to inspect one known object and
+return the tool name it called plus the evidence handle. A healthy setup calls a
+semantic tool such as `billing__inspect_invoice`. It should not expose
+`execute_sql`, approval tools, commit/apply tools, database URLs, or write
+credentials.
+
+## Examples
+
+```text
+examples/openai-agents-http/
+examples/openai-agents-stdio/
+```