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

package/README.md

@@ -1,38 +1,321 @@
 # Synapsor Runner
 
-Commit-safe MCP runner for Postgres and MySQL agents.
+Safe database tools for AI agents.
 
-Synapsor Runner lets an MCP agent request database-backed business actions
-without receiving raw SQL, write credentials, approval tools, or commit tools.
-It exposes semantic tools, creates proposals, records evidence, requires
-approval outside the model-facing tool surface, and applies approved writes
-through guarded execution.
+Turn Postgres/MySQL into reviewed MCP capabilities, not raw SQL. Synapsor
+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
+## Alpha Operational Notes
+
+These are current alpha requirements, not hidden behavior:
+
+- Writeback with `--config ./synapsor.runner.json` reads the trusted writer
+  connection from the source `write_url_env`, for example
+  `SYNAPSOR_DATABASE_WRITE_URL`. `SYNAPSOR_DATABASE_URL` is only the legacy
+  fallback when you run direct worker/apply flows without a local config.
+- `synapsor-runner mcp serve` is standard stdio MCP for local clients that can
+  launch Runner.
+- `synapsor-runner mcp serve-streamable-http` is standard MCP Streamable HTTP
+  with `initialize` and in-memory session behavior for SDK/client HTTP MCP
+  integrations.
+- OpenAI Agents SDK rejects dotted function/tool names. Use
+  `--alias-mode openai` or `--openai-tool-aliases` for OpenAI-facing MCP
+  transports. Runner exposes aliases such as `billing__inspect_invoice` and
+  keeps the canonical Synapsor capability name in tool metadata.
+- `synapsor-runner mcp serve-http` is a small authenticated JSON-RPC bridge for
+  `tools/list`, `tools/call`, and `resources/read`. Use it only when you want a
+  simple app/server wrapper instead of full HTTP MCP.
+- Direct SQL writeback creates or writes `synapsor_writeback_receipts` for
+  idempotency and replay. The trusted writer needs permission for that table,
+  or an administrator must pre-create it and grant access. Use an app-owned
+  `http_handler` or `command_handler` if Runner should not create receipt
+  tables in your application schema.
+
+```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-runner --help
+npx -y -p @synapsor/runner@alpha synapsor-runner demo --quick
 ```
 
-Use it with a local or staging database:
+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-runner 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-runner demo --quick --guided
+synapsor-runner demo --quick --no-interactive
+synapsor-runner demo --quick --details
+synapsor-runner demo inspect --npx
+```
+
+Then choose one path:
+
+```text
+Full disposable proof  -> npx -y -p @synapsor/runner@alpha synapsor-runner demo
+Your own staging DB    -> export DATABASE_URL=... then run the inspect command below
+MCP risk review        -> npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp
+```
+
+`synapsor-runner` is the public command for this OSS runner. `synapsor` is
+reserved for the Synapsor Cloud CLI.
+
+## 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"
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect --engine auto --from-env DATABASE_URL --schema public
-npx -y -p @synapsor/runner@alpha synapsor-runner init --wizard --engine auto --from-env DATABASE_URL --schema public
-npx -y -p @synapsor/runner@alpha synapsor-runner tools preview
-npx -y -p @synapsor/runner@alpha synapsor-runner 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.
+
+Run the guided own-database path:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner start \
+  --from-env DATABASE_URL \
+  --schema public
+```
+
+`start --from-env` is the low-friction alias for `onboard db --from-env`. That
+path inspects metadata, helps you choose one table/view, creates trusted
+context bindings, generates semantic MCP tools, validates the tool boundary,
+and prints the exact MCP/UI next commands. It does not require hand-authored
+JSON. If you provide an optional real object id during the wizard, it also
+writes `./.synapsor/smoke-input.json` so the first tool call can use an actual
+row instead of guessed sample data. When the read URL env var and trusted
+tenant/principal env vars are already set, onboarding also attempts that smoke
+call immediately and stores the evidence/query audit in the local ledger. If
+those env vars are missing, it prints the exact command to run after you set
+them from `.env.example`.
+
+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-runner 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-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+npx -y -p @synapsor/runner@alpha synapsor-runner smoke call \
+  <generated.inspect_tool_name> \
+  --input ./.synapsor/smoke-input.json \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+`smoke call` uses the same runtime as MCP, records evidence/query audit or a
+proposal in the local store, and prints the evidence/proposal/replay commands
+to inspect what happened. If you skipped the optional smoke input in the
+wizard, pass `--json '{"<lookup_arg>":"<real_id>"}'` instead.
+
+## 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-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+For OpenAI Agents SDK over stdio, add OpenAI-safe aliases:
+
+```bash
+synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
+App/server deployments:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor-runner mcp serve-streamable-http \
+  --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 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+Streamable HTTP defaults to `127.0.0.1:8766`, requires bearer auth by default,
+and should use private networking, TLS, and rate limits before being exposed
+beyond a local machine. With `--alias-mode openai`, tools are exposed to
+the model as OpenAI-safe aliases such as `billing__inspect_invoice`; `_meta`
+still includes `synapsor.canonical_tool_name = billing.inspect_invoice`, and
+Runner routes calls back to the canonical Synapsor capability. Use
+`--alias-mode both` during migrations if one client still expects canonical
+dotted names while another needs OpenAI-safe aliases.
+
+Bridge mode:
+
+```bash
+synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+Bridge HTTP defaults to `127.0.0.1:8765` and supports only JSON-RPC
+`tools/list`, `tools/call`, and `resources/read`. It does not implement MCP
+Streamable HTTP `initialize`/session behavior.
+
+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.
+
+## Sanity Check The Agent Connection
+
+Before asking an agent to solve a real task, confirm it can call a Runner tool:
+
+```bash
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For OpenAI-facing clients:
+
+```bash
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
+Then ask the agent:
+
+```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 agent calls a semantic tool, returns an evidence handle or
+local ledger reference, and says raw SQL/write/approval tools were not
+available. If it gives generic advice or unrelated prose without a tool call,
+Runner is not connected yet.
+
+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
@@ -48,11 +331,135 @@ 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-runner 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-runner activity search --tenant acme --object invoice:INV-3001
+synapsor-runner proposals list --tenant acme --object invoice:INV-3001 --status approved
+synapsor-runner evidence show ev_...
+synapsor-runner query-audit list --evidence ev_...
+synapsor-runner receipts list --proposal wrp_...
+synapsor-runner receipts show <receipt_id>
+synapsor-runner replay show --proposal wrp_...
+synapsor-runner 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-runner evidence export ev_... --format markdown --output evidence.md
+synapsor-runner replay export --proposal wrp_... --format json --output replay.json
+synapsor-runner replay export --proposal wrp_... --format markdown --output replay.md
+```
+
+Create a redacted local diagnostic report:
+
+```bash
+synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+```
+
+Inspect or compact the local ledger:
+
+```bash
+synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner store vacuum --store ./.synapsor/local.db
+synapsor-runner 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.
+Starter handlers are included under `examples/app-owned-writeback`.
+You can also generate a starter handler directly:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner handler template node-fastify \
+  --output ./synapsor-writeback-handler.mjs
+```
+
+For direct SQL writeback, set the writer env var named by the source
+`write_url_env`, for example `SYNAPSOR_DATABASE_WRITE_URL`. Runner also creates
+or writes `synapsor_writeback_receipts` for idempotency/replay, so the writer
+needs permission for that receipt table or an administrator must pre-create and
+grant it. Use app-owned handlers when you do not want Runner creating receipt
+tables in your application schema.
+
 ## Command Name
 
-This package installs the `synapsor-runner` binary. It intentionally does not
-install a `synapsor` binary because the hosted Synapsor SDK package already owns
-that command.
+This package installs `synapsor-runner` as the OSS runner binary. The `synapsor`
+command is reserved for the Synapsor Cloud CLI.
 
 ## Scope
 
@@ -61,4 +468,4 @@ Synapsor DBMS, not a physical branch engine for Postgres/MySQL, and not a
 general MCP security platform.
 
 See the full repository README and docs for Docker demos, MCP client setup,
-configuration recipes, and security boundaries.
+configuration recipes, security boundaries, and release notes.

package/TRADEMARKS.md

@@ -0,0 +1,23 @@
+# Trademark Policy
+
+Apache License 2.0 grants copyright and patent rights to the code in this
+repository. It does not grant trademark rights.
+
+The names "Synapsor" and "Synapsor Runner", Synapsor logos, and Synapsor brand
+assets may not be used to imply endorsement or to operate a confusingly similar
+hosted service.
+
+Forks may accurately describe themselves as:
+
+- "based on Synapsor Runner";
+- "built with Synapsor Runner";
+- "compatible with Synapsor Runner".
+
+Forks may not call themselves "Synapsor", use Synapsor branding as their own
+product branding, or imply that Synapsor sponsors, endorses, or operates the
+fork.
+
+Hosted or commercial services based on this code must use their own branding.
+
+For trademark permission requests, use the contact form at
+https://synapsor.ai/contact.

package/dist/cli.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { type DbRowReader } from "@synapsor-runner/mcp-server";
+import { type WritebackJob } from "@synapsor-runner/protocol";
 import { type SchemaInspection } from "@synapsor-runner/schema-inspector";
 export declare function main(argv: string[]): Promise<number>;
 type WizardAsk = (question: string, defaultValue?: string) => Promise<string>;
@@ -6,7 +8,9 @@ export declare function runInitWizard(args: string[], options?: {
     ask?: WizardAsk;
     env?: NodeJS.ProcessEnv;
     inspection?: SchemaInspection;
+    readRow?: DbRowReader;
     stdout?: Pick<NodeJS.WriteStream, "write">;
 }): Promise<number>;
+export declare function resolveSqlWriteDatabaseUrl(job: WritebackJob, configPath: string, env: NodeJS.ProcessEnv): Promise<string>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

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;AAiC3C,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":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAAwE,MAAM,6BAA6B,CAAC;AAkBxO,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAkS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiD1D;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,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2OjB;AAo9CD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}