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

package/README.md

@@ -7,46 +7,180 @@ 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
 ```
 
-The local-ledger quick fixture, audit `--format markdown`, local evidence
-search, and store maintenance commands are in this checkout and package version
-`0.1.0-alpha.4`. If
-`npm view @synapsor/runner@alpha version` still reports an older alpha, use
-`./bin/synapsor ...` from this checkout or wait for the next alpha publish
-before relying on those npm examples.
+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.
 
-`synapsor` is the public command. `synapsor-runner` remains available as a
-backward-compatible alias for earlier alpha commands.
+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.
 
-`synapsor demo --quick` is fixture-only, does not require Docker, and writes an
-inspectable local ledger fixture to `./.synapsor/quick-demo.db`. Use
-`synapsor demo` for the disposable local Postgres-backed demo.
+```bash
+npx -y -p @synapsor/runner@alpha synapsor demo inspect
+```
 
-Inspect the quick fixture:
+Human output is concise by default. Use `--details` for reviewer metadata or
+`--json` for complete machine-readable records.
+
+Useful quick-demo modes:
 
 ```bash
-synapsor proposals show latest --store ./.synapsor/quick-demo.db
-synapsor activity search --object invoice:INV-3001 --store ./.synapsor/quick-demo.db
-synapsor replay show latest --store ./.synapsor/quick-demo.db
+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
 ```
 
-Use it with a local or staging database:
+`synapsor` is the public command. `synapsor-runner` remains available as a
+backward-compatible alias.
+
+## Connect Your Own 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`
@@ -62,9 +196,10 @@ For a longer local session, you can install the alpha package explicitly:
 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
@@ -106,6 +241,35 @@ 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
@@ -125,6 +289,10 @@ 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

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8BA,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,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"}