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

package/docs/mcp-audit.md

@@ -0,0 +1,152 @@
+# MCP database risk review
+
+`npx -y -p @synapsor/runner@alpha 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.
+
+From a source checkout, use `./bin/synapsor-runner ...` if the global binary is not
+linked yet.
+
+It does not call business tools. It only inspects names, descriptions, input schemas, output schemas, annotations, and examples when those are present.
+
+Every report includes this disclaimer:
+
+```text
+This is a static risk review, not proof that an MCP server is secure.
+```
+
+MCP annotations are treated as hints, not enforcement.
+
+## Usage
+
+Built-in database MCP risk example:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp
+```
+
+This bundled example does not require a source checkout or local examples file.
+It audits a deliberately risky database MCP shape with `execute_sql`,
+`run_query`, model-callable approval/update/delete tools, arbitrary
+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
+```
+
+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
+```
+
+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
+```
+
+Stdio MCP server:
+
+```bash
+npx -y -p @synapsor/runner@alpha 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
+```
+
+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
+```
+
+During local development, the repo-local wrapper can run the same command:
+
+```bash
+./bin/synapsor-runner audit ./tools-list.json
+./bin/synapsor-runner audit ./tools-list.json --format json
+```
+
+## Supported inputs
+
+The audit accepts common exported shapes:
+
+```json
+{ "tools": [] }
+```
+
+```json
+{ "result": { "tools": [] } }
+```
+
+```json
+{ "data": { "tools": [] } }
+```
+
+It also scans nested `adapter`, `mcpServers`, and `servers` blocks when they include tool metadata.
+
+For live targets, the audit calls only JSON-RPC `tools/list`. It does not call business tools, approval tools, commit tools, or writeback tools.
+
+## Findings
+
+The audit flags database-commit risks such as:
+
+- generic `execute_sql`, `run_query`, or raw SQL tools;
+- tools accepting arbitrary SQL, schema, table, or column identifiers;
+- tools accepting `tenant_id`, `principal`, source ids, allowed columns, row versions, or approval identity as model input;
+- model-callable approval, commit, apply, settle, merge, or writeback tools;
+- write-like tools with no visible proposal, approval, or guarded-writeback boundary;
+- missing structured output schemas;
+- missing idempotency/request-key metadata for direct write-like tools;
+- missing row-version/conflict-guard metadata for direct write-like tools;
+- ambiguous read/write tool boundaries;
+- missing business descriptions, annotations, or fixture examples.
+
+## Recommended target shape
+
+A safer model-facing database MCP tool should look like a reviewed semantic proposal capability:
+
+```json
+{
+  "name": "billing.propose_late_fee_waiver",
+  "description": "Create an evidence-backed proposal for support lead approval before trusted writeback.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "invoice_id": { "type": "string" },
+      "reason": { "type": "string" }
+    },
+    "required": ["invoice_id", "reason"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "status": { "type": "string" },
+      "proposal_id": { "type": "string" },
+      "evidence_bundle_id": { "type": "string" },
+      "source_database_changed": { "type": "boolean" }
+    },
+    "required": ["status", "proposal_id", "source_database_changed"]
+  },
+  "annotations": {
+    "readOnlyHint": false,
+    "destructiveHint": false
+  },
+  "examples": [
+    {
+      "invoice_id": "INV-3001",
+      "reason": "customer requested review"
+    }
+  ]
+}
+```
+
+Trusted values such as tenant, principal, source, allowed columns, approval identity, row-version guard, and database credentials must come from Synapsor/runner context, not from model-facing arguments.

package/docs/mcp-client-setup.md

@@ -0,0 +1,231 @@
+# 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
+```
+
+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
+```
+
+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/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,129 @@
+# 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.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.10
+```

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.