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

package/docs/mcp-client-setup.md

@@ -0,0 +1,270 @@
+# MCP Client Setup
+
+The primary local proof path is still the one-command Docker demo:
+
+```bash
+./scripts/demo-docker.sh
+```
+
+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
+source wrapper.
+
+Checked examples live in:
+
+```text
+examples/mcp-client-configs/
+```
+
+Validate them with:
+
+```bash
+corepack pnpm test:mcp-client-configs
+```
+
+## Stdio Vs HTTP MCP
+
+| Mode | Use when | Command |
+| --- | --- | --- |
+| stdio | Claude Desktop, Cursor, VS Code, or another local MCP client can launch Synapsor Runner | `synapsor-runner mcp serve` |
+| 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. 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-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@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).
+
+## Generate A Client Snippet
+
+Print a snippet without modifying any client files:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Supported client names:
+
+```text
+generic-stdio
+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:
+
+```bash
+npx -y -p @synapsor/runner@alpha 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 \
+  --client cursor \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --write \
+  --destination ./cursor-mcp.json
+```
+
+When the destination already exists, Synapsor Runner creates a timestamped
+backup before writing. Noninteractive scripts must add `--yes`.
+
+The command writes only the local stdio MCP command and args. It does not write
+database URLs or passwords into the client config.
+
+## Start Command
+
+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
+```
+
+For the alpha package, keep the package tag explicit in client configuration.
+
+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-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
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner@alpha",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "./examples/mcp-postgres-billing/synapsor.runner.json",
+        "--store",
+        "./.synapsor/local.db"
+      ],
+      "env": {
+        "BILLING_POSTGRES_READ_URL": "postgresql://synapsor_reader:...@localhost:55433/synapsor_runner_mcp_billing",
+        "SYNAPSOR_TENANT_ID": "acme",
+        "SYNAPSOR_PRINCIPAL": "local_billing_agent"
+      }
+    }
+  }
+}
+```
+
+The MCP server should list semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+```
+
+It should not list:
+
+```text
+execute_sql
+run_query
+approve_proposal
+commit_proposal
+```
+
+## Sanity Check The Agent Connection
+
+After installing the MCP client snippet, restart the client and run a deliberately
+small tool-call test.
+
+First confirm what Runner exposes:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Then ask the MCP client:
+
+```text
+Use the Synapsor Runner MCP tool to inspect invoice INV-3001.
+Do not answer from memory.
+Return the tool name called, the evidence handle, and whether raw SQL was available.
+```
+
+Expected result:
+
+- the client calls a tool such as `billing.inspect_invoice`;
+- the response includes an evidence handle or local ledger reference;
+- the model reports that raw SQL, write credentials, approval tools, and commit
+  tools were not available.
+
+If the answer is generic prose or unrelated task planning with no tool call and
+no evidence handle, Synapsor Runner is not connected to that agent session yet.
+Check the MCP config path, restart the client, set trusted context env vars, and
+run `tools/list` or `synapsor-runner tools preview` again.
+
+## Claude Desktop / Cursor / VS Code
+
+Use the matching checked-in example as the starting point:
+
+```text
+examples/mcp-client-configs/claude-desktop.json
+examples/mcp-client-configs/cursor.json
+examples/mcp-client-configs/vscode.json
+```
+
+Each example uses the same stdio command/args/env structure. Replace the placeholder environment variables in your client settings or shell environment.
+
+Do not add a write database URL to the MCP server environment unless you are intentionally running a local review/writeback demo. For normal read/proposal tool calls, use the read URL and trusted context values only.
+
+Before documenting a client UI as officially tested, verify:
+
+1. the server starts;
+2. `tools/list` returns semantic tools;
+3. read tools return evidence handles;
+4. proposal tools return exact diffs and `source_database_changed: false`;
+5. no approval or commit tool is model-callable;
+6. resource reads work for proposal/evidence/replay handles.
+
+## Troubleshooting
+
+- Server not listed: check the command path, working directory, and config path.
+- Tool schema mismatch: run `synapsor-runner audit <exported-tools.json>`.
+- Missing trusted context: set `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`, or use the environment variables configured in `trusted_context.values`.
+- Database unavailable: verify the read credential and host access.
+- Proposal waiting review: approve outside the model with `synapsor-runner proposals approve`.
+- Stale-row conflict: inspect replay; the source row changed after the proposal was created, so the guarded worker refused to commit.

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/recipes.md

@@ -0,0 +1,61 @@
+# Capability Recipes
+
+Recipes are reviewed starter contracts for common database-backed agent actions.
+
+They do not introspect and silently guess write authority. They generate a
+starter config that you must map to your actual staging table names, columns,
+tenant key, conflict column, and business limits.
+
+List recipes:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
+```
+
+Inspect one:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
+```
+
+Initialize a starter config:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+```
+
+Built-in recipes are JSON files under `recipes/`. They are starter data, not
+runtime hardcoding. You can copy one, edit table/column/tool names for your
+domain, and initialize from your file:
+
+```bash
+cp recipes/billing.late_fee_waiver.json my-recipe.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show ./my-recipe.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init ./my-recipe.json --output synapsor.runner.json
+```
+
+Available recipes:
+
+- `billing.late_fee_waiver`
+- `support.ticket_resolution`
+- `orders.refund_review`
+- `accounts.trial_extension`
+- `credits.account_credit`
+
+Each recipe includes:
+
+- expected table type;
+- required columns;
+- recommended primary key;
+- recommended tenant key;
+- recommended conflict/version column;
+- visible columns;
+- allowed write columns;
+- patch mapping;
+- numeric/status bounds where relevant;
+- semantic MCP tool names;
+- staging-first notes.
+
+Start with staging or a disposable database. Keep production write credentials
+out of the MCP client.

package/docs/release-notes.md

@@ -0,0 +1,158 @@
+# Release Notes
+
+These notes track public Synapsor Runner alpha behavior. While the runner is in
+alpha, install with the explicit alpha tag or an exact version. Do not rely on
+the untagged `latest` dist-tag until a stable release is published.
+
+```bash
+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
+
+- `synapsor-runner start --from-env DATABASE_URL` is the shortest own-database
+  onboarding command. It is an alias for the guided `onboard db --from-env`
+  flow, not the legacy cloud worker.
+- The wizard inspects database metadata, creates trusted context bindings,
+  generates semantic capabilities, writes `.env.example`, previews MCP tools,
+  and prints exact smoke-call, MCP, and UI commands.
+- If you provide a real object id and the required environment variables are
+  set, onboarding attempts the first smoke tool call and stores local evidence
+  and query audit. If not, it prints the exact `smoke call` command to run
+  after setting the values.
+- `synapsor-runner ui --open` opens the local review UI and is the preferred
+  way to inspect proposals, evidence, receipts, and replay after a demo or
+  smoke call.
+
+### MCP Transport
+
+- `synapsor-runner mcp serve` is standard stdio MCP for local MCP clients that
+  can launch Runner, such as Claude Desktop, Cursor, and similar clients.
+- `synapsor-runner mcp serve-streamable-http` is the standard Streamable HTTP
+  MCP path for app/server agents and SDK clients. It implements MCP
+  initialize/session behavior on the `/mcp` endpoint.
+- `synapsor-runner mcp serve-http` is an authenticated JSON-RPC bridge for
+  simple `tools/list`, `tools/call`, and `resources/read` wrappers. It is not
+  the standard Streamable HTTP MCP transport.
+- The OpenAI Agents SDK HTTP example uses the Streamable HTTP MCP path. Use the
+  JSON-RPC bridge only when you intentionally want a thin app-owned wrapper.
+
+### Writeback
+
+- Direct SQL writeback is intentionally narrow: guarded single-row `UPDATE`
+  only. It does not support arbitrary SQL, DDL, `INSERT`, `DELETE`, `UPSERT`,
+  stored procedures, or multi-row writes.
+- Direct SQL writeback reads the trusted writer connection from the source
+  `write_url_env` in `synapsor.runner.json`, such as
+  `SYNAPSOR_DATABASE_WRITE_URL`.
+- `SYNAPSOR_DATABASE_URL` is accepted only as a legacy fallback for older
+  direct worker/apply flows without a local config.
+- Direct SQL writeback creates or writes `synapsor_writeback_receipts` for
+  idempotency and replay. The trusted writer needs permission for that receipt
+  table, or an administrator must pre-create the table and grant access.
+- Use `synapsor-runner writeback doctor`, `writeback migration`, and
+  `writeback grants` to inspect and prepare the direct writeback path.
+- Use app-owned `http_handler` or `command_handler` executors for rich writes
+  such as inserting credit rows, opening tickets, deleting records through app
+  policy, or updating multiple related rows.
+- `synapsor-runner handler template` writes starter Node/Fastify,
+  Python/FastAPI, or command-handler files so rich writes can start from an
+  app-owned transaction boundary instead of hand-writing a handler from
+  scratch.
+
+### Evidence And Replay
+
+- Read-only capabilities produce scoped semantic tools, trusted context
+  binding, evidence handles, query audit, and local inspection records.
+- Proposal workflows add full local replay across evidence, approval,
+  writeback jobs, execution receipts, and events.
+- External Postgres/MySQL databases are not physically branched by Runner.
+  Replay covers records captured by Runner; it is not external database
+  time travel.
+
+### Known Limitations
+
+- This is an alpha local runner, not Synapsor Cloud, not the Synapsor DBMS, and
+  not a generic MCP security platform.
+- Runner does not expose model-callable approval, commit, apply, or raw SQL
+  tools.
+- Runner does not implement Synapsor Cloud workflow DAGs, native branches,
+  auto-merge, settlement policies, hosted RBAC/SSO, hosted evidence retention,
+  CDC, managed runner fleets, compliance exports, production SLA, or C++ DBMS
+  internals.
+- The local store is single-node SQLite for local/dev/staging usage.
+- Node >= 22.5.0 is required because the local ledger uses Node's
+  `node:sqlite` runtime. Use a supported Node runtime or the Docker-backed
+  source demo path.
+
+### Upgrade Notes From Earlier Alphas
+
+- Public command examples now use `synapsor-runner`, not `synapsor`.
+- Standard HTTP MCP examples now use `mcp serve-streamable-http`; `mcp
+  serve-http` is documented as the JSON-RPC bridge.
+- Direct SQL writeback docs now use `write_url_env` for writer credentials and
+  document `SYNAPSOR_DATABASE_URL` only as a legacy fallback.
+- Receipt-table permissions are now a documented writeback requirement.
+- The quick demo is guided in interactive terminals, concise in noninteractive
+  mode, and keeps the longer explanation behind `--details`.
+
+## Stable Release Policy
+
+Stay on `@synapsor/runner@alpha` or an exact alpha version while first-run
+onboarding, MCP transport behavior, and writeback documentation are still
+changing. A stable `0.1.0` release should only be tagged after:
+
+- the README's npm commands match the published package;
+- a clean temporary directory can run the quick demo, own-database onboarding,
+  MCP config generation, smoke call, UI, and replay commands;
+- stdio MCP and Streamable HTTP MCP are covered by tests and examples;
+- direct and app-owned writeback requirements are documented and verified; and
+- known limitations are still accurate.
+
+For the local tarball before publish, run:
+
+```bash
+./scripts/verify-packed-runner.sh
+./scripts/verify-packed-own-db.sh
+```
+
+After publishing an alpha, verify the public package from a clean temporary
+directory:
+
+```bash
+./scripts/verify-published-alpha.sh 0.1.0-alpha.11
+```

package/docs/security-boundary.md

@@ -0,0 +1,94 @@
+# Security Boundary
+
+Synapsor Runner controls a narrow database path for MCP agents. It does not make
+MCP generally secure and it does not solve prompt injection.
+
+## Least-privilege database access
+
+Use a read-only database user, restricted views, row-level security, and staging
+data where appropriate. Synapsor Runner is not a replacement for database
+permissions.
+
+Database permissions protect the connection. Synapsor Runner shapes the
+model-facing interface: reviewed semantic capabilities, trusted context
+binding, evidence handles, query audit, local inspection, and proposal-first
+writes instead of model-facing commit authority.
+
+If all you need is restricted reads, database permissions are a good start.
+Use Synapsor Runner when you also want the agent-facing layer: semantic tools,
+trusted context, evidence handles, query audit, local inspection, and
+proposal-first writes. Proposal workflows add full replay across evidence,
+approval, writeback receipts, and events.
+
+The model-facing MCP server exposes reviewed semantic tools such as
+`billing.inspect_invoice` and `billing.propose_late_fee_waiver`.
+
+The model does not receive:
+
+- raw SQL;
+- a generic `execute_sql` tool;
+- arbitrary table, schema, or column names;
+- database URLs or credentials;
+- approval tools;
+- commit/writeback tools;
+- trusted tenant or principal authority as ordinary model arguments.
+
+Trusted context comes from local configuration, environment bindings, or Cloud
+session context in Cloud mode. Tenant, principal, and authorization scope must
+not be accepted from the model as authority.
+
+Proposal tools read the current row through the read credential, store evidence
+and an exact before/after diff, and leave the source database unchanged.
+
+The local proposal store rejects obvious credential material before persistence:
+database URLs, bearer tokens, Synapsor runner tokens, private-key blocks, and
+secret-like fields such as password, token, API key, private key, cookie,
+credential, connection string, read URL, or write URL. If a selected table
+contains one of those fields, remove it from the reviewed visible/evidence
+projection before creating proposals.
+
+Writeback is separate. A trusted local runner/apply path uses a write credential
+outside the model-facing MCP server and verifies:
+
+- local reviewed config;
+- source and capability identity;
+- fixed safe schema, table, and column identifiers;
+- local approval state;
+- proposal and job digests;
+- target schema/table;
+- primary-key and tenant guards;
+- allowed mutable columns;
+- conflict/version guard;
+- idempotency key;
+- job expiry;
+- exactly one affected row.
+
+If any authority check cannot be verified, the write fails closed.
+
+For direct SQL writeback, the writer connection is the env var named by the
+source `write_url_env` in `synapsor.runner.json`. Direct SQL writeback also
+creates or writes `synapsor_writeback_receipts` for idempotency and replay, so
+the writer needs permission for that receipt table or an administrator must
+pre-create and grant it. If your database policy forbids Runner-managed receipt
+tables, use an app-owned `http_handler` or `command_handler` executor instead.
+
+When a capability uses an `http_handler` or `command_handler` executor, the
+same approval boundary applies. The runner sends a structured proposal/job
+payload to the configured handler after approval. Handler URLs, commands, bearer
+tokens, database URLs, and write credentials come from environment variables and
+are not exposed to MCP tools.
+
+Writeback jobs and change sets also reject path-traversal or SQL-fragment-like
+database identifiers such as `../private`, `id/../../tenant_id`, or
+`status; DROP TABLE tickets` before adapter execution. Local CLI file paths
+remain explicit user-provided paths; they are not model-facing authority.
+
+Local review can happen through the CLI or `synapsor-runner ui`. The UI is a localhost
+review surface with a per-run session token and CSRF protection for
+approve/reject actions. It does not expose raw SQL, database URLs, write
+credentials, approval tools, commit tools, or controls that widen reviewed
+tables/columns.
+
+Synapsor Runner supports reviewed single-row business actions only in the
+current alpha. It does not support arbitrary SQL, DDL, `INSERT`, `DELETE`,
+`UPSERT`, or multi-row updates.