@synapsor/runner 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -7,39 +7,199 @@ Runner lets an MCP agent inspect scoped data and request database-backed
 business actions without receiving raw SQL, write credentials, approval tools,
 or commit tools.
 
-## Run The Alpha
+```text
+AI agent or MCP client
+(Claude, Cursor, OpenAI Agents SDK, LangGraph)
+        |
+        | calls reviewed MCP tool
+        v
++--------------------------------+
+| Synapsor Runner MCP            |
+| semantic capabilities only     |
+| trusted tenant/principal ctx   |
+| evidence + query audit         |
++--------------------------------+
+        |
+        | scoped read / guarded proposal
+        v
++--------------------------------+
+| Your Postgres or MySQL         |
+| source of truth                |
++--------------------------------+
+
+Local Runner store:
+evidence · query audit · proposals · receipts · replay
+```
+
+Your database stays the source of truth. Synapsor Runner owns the
+model-facing boundary: what the agent can read, what it can propose, what
+evidence is saved, and what can later be reviewed or replayed.
+
+## What Runner Does
+
+When an agent uses Runner:
+
+- the model gets reviewed capabilities, not raw database authority;
+- reads produce evidence handles and query audit;
+- writes become proposals, not direct mutations;
+- approval and writeback happen outside the model-facing MCP surface;
+- replay shows what the agent saw, proposed, and what was applied or blocked.
+
+## Start Here
+
+Run the guided quick demo first. It does not require Docker, a database, a
+config file, an MCP client, or a Synapsor Cloud account.
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor --help
 npx -y -p @synapsor/runner@alpha synapsor demo --quick
-npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
+```
+
+In a terminal, it walks through the safety model step by step. In CI, piped
+output, or other non-interactive mode, it prints a short summary and exits
+without waiting for Enter.
+
+That command creates a local ledger fixture at `./.synapsor/quick-demo.db`.
+It does not prove database connectivity. It shows the proposal, evidence, and
+replay flow without giving the runner a database URL.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor demo inspect
+```
+
+Human output is concise by default. Use `--details` for reviewer metadata or
+`--json` for complete machine-readable records.
+
+Useful quick-demo modes:
+
+```bash
+synapsor demo --quick --guided
+synapsor demo --quick --no-interactive
+synapsor demo --quick --details
+synapsor demo inspect --npx
+```
+
+Then choose one path:
+
+```text
+Full disposable proof  -> npx -y -p @synapsor/runner@alpha synapsor demo
+Your own staging DB    -> export DATABASE_URL=... then run the inspect command below
+MCP risk review        -> npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
 ```
 
 `synapsor` is the public command. `synapsor-runner` remains available as a
-backward-compatible alias for earlier alpha commands.
+backward-compatible alias.
 
-`synapsor demo --quick` is fixture-only and does not require Docker. Use
-`synapsor demo` for the disposable local Postgres-backed demo.
+## Connect Your Own Staging Database
 
-Use it with a local or staging database:
+Put a read-only connection string in the environment:
 
 ```bash
 export DATABASE_URL="postgresql://readonly_user:password@localhost:5432/app"
-synapsor inspect --engine auto --from-env DATABASE_URL --schema public
-synapsor init --wizard --engine auto --from-env DATABASE_URL --schema public
-synapsor tools preview
-synapsor mcp serve
 ```
 
+For disposable dev RDS fixtures only, use `sslmode=no-verify` if your local
+Node/Postgres TLS stack cannot verify the test certificate chain. For real
+staging or production-like databases, keep certificate verification enabled.
+
+Inspect metadata:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor inspect \
+  --engine auto \
+  --from-env DATABASE_URL \
+  --schema public
+```
+
+Generate a reviewed read-only config first. The wizard creates this local
+flow:
+
+```text
+trusted context -> capability -> MCP tool
+```
+
+It asks which table/view backs the context, which tenant/scope column and
+backend session env vars are trusted, which fields are visible, and what
+semantic capability name to expose.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor init \
+  --wizard \
+  --engine auto \
+  --from-env DATABASE_URL \
+  --schema public \
+  --mode read_only
+```
+
+Preview and serve the semantic tools:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+## Two Ways To Run MCP
+
+Use stdio when the MCP client runs locally and can launch Synapsor Runner. Use
+HTTP when your agent service runs as an app/server and connects to a
+long-running Runner process.
+
+Local MCP clients:
+
+```bash
+synapsor mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+App/server deployments:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor mcp serve-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
+use private networking, TLS, and rate limits before being exposed beyond a
+local machine.
+
+OpenAI Agents SDK examples:
+
+```text
+examples/openai-agents-stdio/
+examples/openai-agents-http/
+```
+
+Use `--mode review` only when you are ready to create proposal tools and test
+guarded writeback with a separate trusted write credential.
+
+The disposable reference app includes proposal-first write examples for:
+
+- `billing.propose_late_fee_waiver`
+- `support.propose_plan_credit`
+- `orders.propose_status_change`
+
+Each tool creates evidence, a before/after diff, and a proposal. The source
+database remains unchanged until approval outside MCP and guarded writeback.
+
 For a longer local session, you can install the alpha package explicitly:
 
 ```bash
 npm install -g @synapsor/runner@alpha
 ```
 
-## What It Does
+## Runtime Flow
 
-The local runner implements a small Synapsor-style trust loop:
+The local runner keeps the model-facing tool call separate from approval and
+writeback:
 
 ```text
 MCP tool call
@@ -55,6 +215,117 @@ MCP tool call
 Your Postgres/MySQL database remains the source of truth. The runner stores
 local proposals, evidence, receipts, and replay data in a local SQLite store.
 
+## Why Not Just Use A Read-Only Database User?
+
+You should use one.
+
+Synapsor Runner is not a replacement for least-privilege database permissions.
+Start with a read-only user, restricted views, row-level security, and staging
+data where appropriate.
+
+The difference is that database permissions protect the connection. Synapsor
+Runner shapes the model-facing interface.
+
+Instead of exposing `execute_sql`, `query_database`, table names, or
+model-controlled tenant filters, Synapsor exposes reviewed business
+capabilities such as `billing.inspect_invoice` and
+`billing.propose_late_fee_waiver`.
+
+For read-only use cases, Runner provides scoped semantic tools, trusted context
+binding, evidence handles, query audit, and local inspection. Proposal
+workflows add full replay across evidence, approval, writeback receipts, and
+events.
+
+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.
+
+## Fixture Benchmark
+
+Run the included MCP efficiency fixture:
+
+```bash
+synapsor benchmark mcp-efficiency
+```
+
+Current fixture result for the late-fee-waiver workflow:
+
+```text
+Generic database MCP reference:
+  exposed tools: 4
+  scripted tool calls: 5
+  raw SQL exposed: yes
+  approval separated: no
+  stale-row conflict checked: no
+
+Synapsor Runner semantic path:
+  exposed tools: 2
+  scripted tool calls: 2
+  raw SQL exposed: no
+  approval separated: yes
+  stale-row conflict checked: yes
+```
+
+The fixture tokenizer is deterministic and repeatable for this package. It is
+not a model billing tokenizer and not a universal token-savings claim.
+
+## Find Evidence And Replay
+
+The commands in this section require this checkout or an alpha package that
+includes the local-ledger CLI surface.
+
+The runner stores a local SQLite evidence/replay ledger. Search it without
+relying on `latest`:
+
+```bash
+synapsor activity search --tenant acme --object invoice:INV-3001
+synapsor proposals list --tenant acme --object invoice:INV-3001 --status approved
+synapsor evidence show ev_...
+synapsor query-audit list --evidence ev_...
+synapsor receipts list --proposal wrp_...
+synapsor receipts show <receipt_id>
+synapsor replay show --proposal wrp_...
+synapsor replay show --replay replay_wrp_...
+```
+
+Default inspection output is meant for first-run clarity. Add `--details` for
+target URIs, primary keys, proposal hash/version, conflict guards, query
+fingerprints, event timestamps, and receipt internals.
+
+Export captured evidence or proposal replay:
+
+```bash
+synapsor evidence export ev_... --format markdown --output evidence.md
+synapsor replay export --proposal wrp_... --format json --output replay.json
+synapsor replay export --proposal wrp_... --format markdown --output replay.md
+```
+
+Create a redacted local diagnostic report:
+
+```bash
+synapsor doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+```
+
+Inspect or compact the local ledger:
+
+```bash
+synapsor store stats --store ./.synapsor/local.db
+synapsor store vacuum --store ./.synapsor/local.db
+synapsor store prune --store ./.synapsor/local.db --older-than 30d --dry-run
+```
+
+This is local indexed search for local/dev/staging usage. It is not external
+database time travel, not cross-runner search, and not hosted compliance
+retention.
+
+## App-Owned Writeback
+
+Use direct guarded DB writeback for simple local/staging single-row updates. If
+your application service already owns business writes, configure an
+`http_handler` or `command_handler` executor. Approval still happens outside
+MCP, and the handler returns an applied/conflict/failed receipt for replay.
+
 ## Command Name
 
 This package installs `synapsor` as the primary binary and `synapsor-runner` as

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiBA,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA0H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqC1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA0KjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA+BA,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA4H3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8C1D;AA0DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CAiLjB"}

package/dist/cli.js

@@ -6,6 +6,11 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const invoked = basename(process.argv[1] || 'synapsor');
 const commandName = invoked === 'synapsor-runner' ? 'synapsor-runner' : 'synapsor';
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (!(major > 22 || (major === 22 && minor >= 5))) {
+  console.error(`Synapsor Runner requires Node >= 22.5.0 because the local ledger uses Node's node:sqlite runtime. Current Node: ${process.versions.node}. Upgrade Node or use the Docker demo from a source checkout.`);
+  process.exit(1);
+}
 const result = spawnSync(process.execPath, ['--no-warnings', join(__dirname, 'runner.mjs'), ...process.argv.slice(2)], {
   stdio: 'inherit',
   env: { ...process.env, NODE_NO_WARNINGS: '1', SYNAPSOR_RUNNER_COMMAND_NAME: commandName },