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

package/docs/README.md

@@ -8,17 +8,27 @@ detail.
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
   staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
   semantic tools, and serve them over MCP.
+- [Use Your Own Database](use-your-own-database.md): short entry point that
+  links to the canonical own-database guide.
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
 - [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
   service for app/server agents.
+- [OpenAI Agents SDK](openai-agents-sdk.md): use Streamable HTTP MCP with
+  OpenAI-safe tool aliases.
 
 ## Safety And Operations
 
 - [Security Boundary](security-boundary.md): what the model can and cannot see.
 - [Current Limitations](limitations.md): current alpha scope.
+- [Current Scope](current-scope.md): compact alpha scope summary.
+- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
 - [Release Notes](release-notes.md): alpha behavior, breaking changes, and the
   stable release policy.
+- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
+  not included in this runner repo.
+- [Dependency License Inventory](dependency-license-inventory.md): current
+  dependency license summary for release review.
 - [Troubleshooting First Run](troubleshooting-first-run.md): common setup
   failures and fixes.
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
@@ -30,6 +40,13 @@ detail.
 - [Recipes](recipes.md): starter business-capability templates.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
+- [App-Owned Executors](app-owned-executors.md): short entry point for rich
+  business transactions handled by your app.
+
+Useful examples:
+
+- `examples/mcp-postgres-billing-app-handler/`: disposable Postgres app showing
+  guarded SQL writeback and app-owned account-credit execution side by side.
 
 The public docs intentionally stay small. Historical implementation reports,
 release checklists, and internal planning notes are not part of the public

package/docs/app-owned-executors.md

@@ -0,0 +1,21 @@
+# App-Owned Executors
+
+The canonical guide is [Writeback Executors](writeback-executors.md).
+
+Use app-owned executors when an approved proposal needs a real business
+transaction instead of Runner-managed single-row SQL.
+
+Examples:
+
+- create a credit row;
+- open a ticket;
+- call Stripe or Zendesk;
+- write ledger/event rows;
+- update multiple tables in one application transaction.
+
+The model-facing MCP tool only creates a proposal. Approval happens outside MCP.
+After approval, Runner calls your `http_handler` or `command_handler`, records
+the receipt, and includes the result in replay.
+
+Do not use generic SQL for rich business transactions. Let the model propose,
+let Synapsor Runner approve/replay, and let your app execute the transaction.

package/docs/cloud-mode.md

@@ -0,0 +1,24 @@
+# Cloud Mode
+
+Synapsor Runner is local-first. It does not require Synapsor Cloud for the local
+demo, own-database onboarding, MCP serving, proposal creation, local approval,
+guarded writeback, or replay.
+
+Cloud-linked mode is for teams that need a shared control plane:
+
+- team approvals and RBAC;
+- hosted evidence/replay search;
+- runner registration and heartbeat;
+- job leases;
+- receipt reporting;
+- retention and audit visibility.
+
+The local runner still keeps database credentials in your environment. MCP
+client config snippets should contain command paths and runner arguments, not
+database URLs or write credentials.
+
+Run the local smoke for this mode with:
+
+```bash
+corepack pnpm test:mcp-cloud-linked
+```

package/docs/current-scope.md

@@ -0,0 +1,24 @@
+# Current Scope
+
+The canonical scope page is [Current Limitations](limitations.md).
+
+Current alpha scope:
+
+- local semantic MCP tools for Postgres/MySQL-backed business actions;
+- schema inspection and guided config generation;
+- trusted context from environment/session values;
+- evidence handles, query audit, proposals, receipts, and local replay;
+- guarded single-row `UPDATE` writeback for simple edits;
+- app-owned `http_handler` and `command_handler` executors for richer approved
+  business transactions;
+- stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
+
+Out of scope:
+
+- raw `execute_sql`;
+- model-generated SQL;
+- generic INSERT/DELETE/UPSERT/DDL;
+- generic multi-row SQL writeback;
+- physical branching of external Postgres/MySQL;
+- self-hosted Synapsor Cloud;
+- production SLA or compliance certification.

package/docs/dependency-license-inventory.md

@@ -0,0 +1,35 @@
+# Dependency License Inventory
+
+Generated from the current lockfile/install with:
+
+```bash
+corepack pnpm licenses list --json
+```
+
+Summary from the current dependency set:
+
+| License | Package entries |
+| --- | ---: |
+| MIT | 149 |
+| Apache-2.0 | 4 |
+| BSD-3-Clause | 3 |
+| BSD-2-Clause | 1 |
+| ISC | 11 |
+
+Apache-2.0 dependency entries reported by pnpm:
+
+- `denque@2.1.0`
+- `expect-type@1.3.0`
+- `long@5.3.2`
+- `typescript@5.9.3`
+
+This file is an inventory summary, not a replacement for dependency license
+review. Third-party dependency licenses and notices are not changed by the
+first-party Synapsor Runner Apache-2.0 license.
+
+Before public release:
+
+- regenerate this inventory from a clean install;
+- review dependency notices with the release owner or qualified counsel;
+- keep third-party notices separate from the first-party Synapsor Runner
+  license.

package/docs/http-mcp.md

@@ -28,6 +28,38 @@ synapsor-runner mcp serve-streamable-http \
   --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
@@ -239,4 +271,6 @@ example connects to `synapsor-runner mcp serve-streamable-http` through
 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.
+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/mcp-client-setup.md

@@ -51,6 +51,34 @@ npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
   --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@alpha 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@alpha 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).
 
@@ -72,6 +100,17 @@ 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@alpha synapsor-runner mcp client-config \
+  --client openai-agents \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
 ```
 
 The older form is still supported:

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@alpha 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@alpha 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/
+```

package/docs/release-notes.md

@@ -11,6 +11,35 @@ npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.0-alpha.11
+
+### OpenAI MCP Aliases
+
+- `synapsor-runner mcp serve` and `synapsor-runner mcp serve-streamable-http`
+  now accept `--alias-mode openai` and `--openai-tool-aliases`.
+- `synapsor-runner mcp serve --transport streamable-http` is available as a
+  unified command form for the standard HTTP MCP server.
+- `synapsor-runner mcp client-config --client openai-agents` prints a
+  Streamable HTTP start command and OpenAI Agents SDK snippet.
+- `synapsor-runner tools preview --alias-mode openai` shows model-visible alias
+  names and the canonical Synapsor capability each alias maps to.
+- `examples/mcp-postgres-billing-app-handler/` adds a disposable Postgres proof
+  for the app-owned executor path: proposal first, approval outside MCP,
+  account-credit row inserted by the app handler, idempotent retry, and replay.
+- `--alias-mode both` exposes canonical dotted names and OpenAI-safe aliases
+  together for migration/debugging.
+- OpenAI alias mode exposes MCP tool names such as
+  `billing__inspect_invoice` instead of canonical dotted names such as
+  `billing.inspect_invoice`.
+- Tool metadata includes `synapsor.canonical_tool_name`,
+  `synapsor.exposed_tool_name`, and `synapsor.tool_name_style`, so reviewers
+  can still see the canonical Synapsor capability.
+- Runner routes alias calls back to the canonical capability. This removes the
+  need for user-written OpenAI wrapper code whose only job is replacing dots in
+  tool names.
+- The OpenAI Agents SDK stdio and Streamable HTTP examples now document the
+  built-in alias mode.
+
 ## 0.1.0-alpha.10
 
 ### First-Run Flow
@@ -125,5 +154,5 @@ After publishing an alpha, verify the public package from a clean temporary
 directory:
 
 ```bash
-./scripts/verify-published-alpha.sh 0.1.0-alpha.10
+./scripts/verify-published-alpha.sh 0.1.0-alpha.11
 ```

package/docs/use-your-own-database.md

@@ -0,0 +1,18 @@
+# Use Your Own Database
+
+The canonical guide is [Connect Your Own Database](getting-started-own-database.md).
+
+Use it when you want to point Synapsor Runner at a staging Postgres/MySQL
+database, inspect schemas/tables, generate one reviewed context/capability, and
+serve semantic MCP tools without exposing raw SQL or write credentials to the
+model.
+
+Short path:
+
+```bash
+export DATABASE_URL="postgresql://readonly_user:password@host:5432/app?sslmode=require"
+npx -y -p @synapsor/runner@alpha synapsor-runner start --from-env DATABASE_URL --schema public
+```
+
+Runner stores environment-variable names in `synapsor.runner.json`, not database
+URLs. Keep credentials in your shell, process manager, or secret manager.

package/docs/writeback-executors.md

@@ -159,6 +159,17 @@ Concrete business-action examples are in:
 examples/app-owned-writeback/business-actions.md
 ```
 
+The full disposable Postgres account-credit demo is in:
+
+```text
+examples/mcp-postgres-billing-app-handler/
+```
+
+It proves the rich-write path end to end: the model creates a proposal, the
+source DB is unchanged before approval, the app-owned handler inserts an
+`account_credits` row after approval, retry is idempotent, and replay stores the
+handler receipt.
+
 Or generate one into your app:
 
 ```bash

package/examples/mcp-postgres-billing-app-handler/README.md

@@ -0,0 +1,82 @@
+# Postgres Billing App Handler
+
+This example shows the two Synapsor Runner commit paths against one disposable
+Postgres billing database.
+
+Direct guarded SQL writeback:
+
+- `billing.propose_late_fee_waiver`
+- one-row `UPDATE`;
+- tenant guard, allowed-column guard, conflict guard, idempotency receipt.
+
+App-owned rich writeback:
+
+- `billing.propose_account_credit`
+- model-facing MCP only creates a proposal;
+- approval happens outside MCP;
+- Runner calls `billing_app_handler`;
+- the app inserts an `account_credits` row and updates the invoice inside its
+  own transaction;
+- Runner records the handler receipt and replay.
+
+The model never receives `execute_sql`, approval tools, commit/apply tools,
+database URLs, or write credentials.
+
+## Run
+
+From the repository root:
+
+```bash
+examples/mcp-postgres-billing-app-handler/scripts/run-demo.sh
+```
+
+Expected ending:
+
+```text
+App-owned billing handler demo passed.
+Verified: proposal first, source unchanged before approval, account credit inserted by app handler, idempotent retry, replay.
+```
+
+## Manual Start
+
+```bash
+docker compose -f examples/mcp-postgres-billing-app-handler/docker-compose.yml up -d
+
+export BILLING_APP_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55437/synapsor_billing_app_handler"
+export BILLING_APP_HANDLER_URL="http://127.0.0.1:8787/synapsor/writeback"
+export BILLING_APP_HANDLER_TOKEN="dev-handler-token"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_operator"
+
+node examples/mcp-postgres-billing-app-handler/app-handler.mjs
+```
+
+Then, in another terminal:
+
+```bash
+synapsor-runner tools preview \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+
+synapsor-runner propose billing.propose_account_credit \
+  --json '{"invoice_id":"INV-3001","amount_cents":2500,"reason":"support-approved credit"}' \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+
+synapsor-runner proposals approve latest --yes --store ./tmp/billing-app-handler/local.db
+synapsor-runner apply latest \
+  --config examples/mcp-postgres-billing-app-handler/synapsor.runner.json \
+  --store ./tmp/billing-app-handler/local.db
+synapsor-runner replay show latest --store ./tmp/billing-app-handler/local.db
+```
+
+## Why This Exists
+
+Direct Runner SQL writeback should stay intentionally narrow. It is good for
+simple, bounded, single-row updates.
+
+For richer business transactions such as creating credits, refund reviews,
+ledger rows, tickets, events, or multi-row updates, keep execution in your
+application service. Synapsor Runner still owns proposal creation, evidence,
+approval boundary, idempotency, receipt storage, and replay.