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

package/docs/README.md

@@ -0,0 +1,53 @@
+# Synapsor Runner Docs
+
+Start with the README. Use these docs only when you need the next level of
+detail.
+
+## First Setup
+
+- [Connect Your Own Database](getting-started-own-database.md): inspect a
+  staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
+  semantic tools, and serve them over MCP.
+- [Use Your Own Database](use-your-own-database.md): short entry point that
+  links to the canonical own-database guide.
+- [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
+  another stdio MCP client.
+- [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
+  service for app/server agents.
+- [OpenAI Agents SDK](openai-agents-sdk.md): use Streamable HTTP MCP with
+  OpenAI-safe tool aliases.
+
+## Safety And Operations
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [Current Limitations](limitations.md): current alpha scope.
+- [Current Scope](current-scope.md): compact alpha scope summary.
+- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [Release Notes](release-notes.md): alpha behavior, breaking changes, and the
+  stable release policy.
+- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
+  not included in this runner repo.
+- [Dependency License Inventory](dependency-license-inventory.md): current
+  dependency license summary for release review.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
+  failures and fixes.
+- [Local Mode](local-mode.md): local store, proposals, approval, replay, and
+  writeback flow.
+
+## Features
+
+- [MCP Audit](mcp-audit.md): static risk review for database MCP tools.
+- [Recipes](recipes.md): starter business-capability templates.
+- [Writeback Executors](writeback-executors.md): app-owned writeback handlers
+  for approved proposals.
+- [App-Owned Executors](app-owned-executors.md): short entry point for rich
+  business transactions handled by your app.
+
+Useful examples:
+
+- `examples/mcp-postgres-billing-app-handler/`: disposable Postgres app showing
+  guarded SQL writeback and app-owned account-credit execution side by side.
+
+The public docs intentionally stay small. Historical implementation reports,
+release checklists, and internal planning notes are not part of the public
+getting-started path.

package/docs/app-owned-executors.md

@@ -0,0 +1,21 @@
+# App-Owned Executors
+
+The canonical guide is [Writeback Executors](writeback-executors.md).
+
+Use app-owned executors when an approved proposal needs a real business
+transaction instead of Runner-managed single-row SQL.
+
+Examples:
+
+- create a credit row;
+- open a ticket;
+- call Stripe or Zendesk;
+- write ledger/event rows;
+- update multiple tables in one application transaction.
+
+The model-facing MCP tool only creates a proposal. Approval happens outside MCP.
+After approval, Runner calls your `http_handler` or `command_handler`, records
+the receipt, and includes the result in replay.
+
+Do not use generic SQL for rich business transactions. Let the model propose,
+let Synapsor Runner approve/replay, and let your app execute the transaction.

package/docs/cloud-mode.md

@@ -0,0 +1,24 @@
+# Cloud Mode
+
+Synapsor Runner is local-first. It does not require Synapsor Cloud for the local
+demo, own-database onboarding, MCP serving, proposal creation, local approval,
+guarded writeback, or replay.
+
+Cloud-linked mode is for teams that need a shared control plane:
+
+- team approvals and RBAC;
+- hosted evidence/replay search;
+- runner registration and heartbeat;
+- job leases;
+- receipt reporting;
+- retention and audit visibility.
+
+The local runner still keeps database credentials in your environment. MCP
+client config snippets should contain command paths and runner arguments, not
+database URLs or write credentials.
+
+Run the local smoke for this mode with:
+
+```bash
+corepack pnpm test:mcp-cloud-linked
+```

package/docs/current-scope.md

@@ -0,0 +1,24 @@
+# Current Scope
+
+The canonical scope page is [Current Limitations](limitations.md).
+
+Current alpha scope:
+
+- local semantic MCP tools for Postgres/MySQL-backed business actions;
+- schema inspection and guided config generation;
+- trusted context from environment/session values;
+- evidence handles, query audit, proposals, receipts, and local replay;
+- guarded single-row `UPDATE` writeback for simple edits;
+- app-owned `http_handler` and `command_handler` executors for richer approved
+  business transactions;
+- stdio MCP, Streamable HTTP MCP, and a small JSON-RPC bridge.
+
+Out of scope:
+
+- raw `execute_sql`;
+- model-generated SQL;
+- generic INSERT/DELETE/UPSERT/DDL;
+- generic multi-row SQL writeback;
+- physical branching of external Postgres/MySQL;
+- self-hosted Synapsor Cloud;
+- production SLA or compliance certification.

package/docs/dependency-license-inventory.md

@@ -0,0 +1,35 @@
+# Dependency License Inventory
+
+Generated from the current lockfile/install with:
+
+```bash
+corepack pnpm licenses list --json
+```
+
+Summary from the current dependency set:
+
+| License | Package entries |
+| --- | ---: |
+| MIT | 149 |
+| Apache-2.0 | 4 |
+| BSD-3-Clause | 3 |
+| BSD-2-Clause | 1 |
+| ISC | 11 |
+
+Apache-2.0 dependency entries reported by pnpm:
+
+- `denque@2.1.0`
+- `expect-type@1.3.0`
+- `long@5.3.2`
+- `typescript@5.9.3`
+
+This file is an inventory summary, not a replacement for dependency license
+review. Third-party dependency licenses and notices are not changed by the
+first-party Synapsor Runner Apache-2.0 license.
+
+Before public release:
+
+- regenerate this inventory from a clean install;
+- review dependency notices with the release owner or qualified counsel;
+- keep third-party notices separate from the first-party Synapsor Runner
+  license.

package/docs/getting-started-own-database.md

@@ -0,0 +1,460 @@
+# Connect Your Own Database
+
+Use this path after the Docker demo passes and you want to try Synapsor Runner
+against a staging or disposable Postgres/MySQL database.
+
+Do not start with your most sensitive production database. The current alpha
+runner is a local commit-safety runtime for reviewed single-row business
+actions, not a production certification.
+
+If you only ran `synapsor-runner demo --quick`, you have tested the fixture-only
+teaching path and local ledger commands. This page is the real own-database
+path: it inspects your Postgres/MySQL metadata and generates reviewed semantic
+tools from your selections.
+
+## Fast path
+
+Set one read-only database URL and run the public guided path:
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+npx -y -p @synapsor/runner@alpha synapsor-runner start --from-env DATABASE_URL
+```
+
+That command does the useful local mini-Synapsor path:
+
+```text
+inspect your schema
+-> choose one table/view
+-> choose trusted scope and visible fields
+-> optionally choose proposal/writeback rules
+-> generate synapsor.runner.json
+-> preview MCP tools exposed to the model
+-> run a local smoke check of the tool boundary
+-> optionally write .synapsor/smoke-input.json for one real row
+-> print mcp serve and local UI commands
+```
+
+It does not print your database URL, put the URL in MCP client config, expose
+`execute_sql`, expose approval/commit tools, or give the model write
+credentials.
+
+`start --from-env` is the shortest public command for first-run onboarding.
+`onboard db --from-env DATABASE_URL` is the same explicit path if you prefer the
+older command name in scripts.
+
+During the wizard, provide the optional sample object id if you know one safe
+row in the selected table. Runner writes `./.synapsor/smoke-input.json` with
+that id and prints the exact `smoke call` command. If you skip it, use
+`--json '{"<lookup_arg>":"<real_id>"}'` when you are ready to test one real
+row.
+
+The rest of this page shows the same flow step by step using the public
+`synapsor-runner ...` CLI. From a source checkout, use `./bin/synapsor-runner ...` if the
+global binary is not linked yet.
+
+From a source checkout, `./scripts/use-your-db.sh` runs the same kind of
+guided flow plus local repository checks.
+
+## 1. Put the read URL in an environment variable
+
+Do not pass connection strings on the command line.
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+```
+
+Use a read-only credential for inspection and model-facing read/proposal tools.
+
+### TLS notes for AWS RDS and other managed databases
+
+If you see an error like:
+
+```text
+self-signed certificate in certificate chain
+```
+
+that is not a Postgres permission issue. It means the client reached the
+database, but your local Node/Postgres TLS stack could not verify the server's
+certificate chain.
+
+For disposable dev RDS fixtures, you can allow an insecure retry:
+
+```bash
+./scripts/use-your-db.sh --allow-insecure-ssl
+```
+
+or put `sslmode=no-verify` in the disposable test URL.
+
+For real staging or production-like testing, do not disable verification.
+Install/use the AWS RDS CA bundle and keep certificate verification enabled.
+For example, download the AWS RDS global bundle and configure your Postgres URL
+or client environment so the Node Postgres client trusts that CA. The exact
+mechanism depends on your deployment environment and should be treated like any
+other trusted database TLS setup.
+
+## 2. Inspect metadata
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine auto \
+  --from-env DATABASE_URL \
+  --schema public
+```
+
+For a disposable staging URL, this also works:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+```
+
+For automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+  --engine postgres \
+  --from-env DATABASE_URL \
+  --schema public \
+  --json > schema-inspection.json
+```
+
+Inspection reads metadata only by default. It does not sample business rows.
+
+## 3. Start from a recipe when one matches
+
+Recipes give you a reviewed starter contract for a common business action. They
+do not silently infer write authority from your schema; you still map the recipe
+to your staging table, primary key, tenant key, conflict column, visible fields,
+allowed write fields, and business limits.
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+```
+
+Use a recipe when the shape is close. Use the guided wizard or explicit flags
+when your action is custom.
+
+Built-in recipes are JSON files under `recipes/`. You can copy one and pass the
+edited file path to `recipes show` or `recipes init`; the runtime still serves
+only the capabilities in your generated `synapsor.runner.json`.
+
+## 4. Generate from reviewed selections
+
+In an interactive terminal, run the guided wizard:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
+```
+
+The generated context and capabilities are based on your selections. Synapsor
+Runner does not force billing, support, order, or any other built-in domain.
+The local shape is:
+
+```text
+trusted context -> capability -> MCP tool
+```
+
+You choose the source object, trusted tenant/principal bindings, namespace,
+object name, lookup argument, visible fields, proposal fields, guards, and
+approval role. You can also provide an optional real object id so Runner writes
+`./.synapsor/smoke-input.json` for the first local tool call. If the read URL
+env var and trusted tenant/principal env vars are already set, the wizard also
+attempts that smoke call immediately and stores the evidence/query audit in the
+local ledger. If not, it prints the exact smoke command to run after you set
+the env vars from `.env.example`.
+
+Start with `read_only` to prove safe database reads first. Use `--mode review`
+when you are ready to create proposal tools and guarded writeback setup.
+
+The wizard:
+
+- asks for the engine and read URL environment-variable name;
+- tests read connectivity through schema inspection;
+- lists discovered schemas and tables/views;
+- asks which source object backs the local context;
+- asks which tenant/scope column and backend session env vars are trusted;
+- asks you to confirm primary key, conflict/version column, visible columns,
+  mode, semantic capability names, and proposal patch mappings;
+- asks review-mode users to choose direct guarded SQL writeback, an app-owned
+  HTTP handler, or an app-owned command handler;
+- previews the MCP tools and what is not exposed;
+- attempts a first smoke call when you supplied a real object id and the
+  required trusted env vars are present;
+- writes the generated config, `.env.example`, and MCP client snippets only
+  after final confirmation.
+
+For proposal modes, the current runner supports explicit field-update mappings such as:
+
+```text
+late_fee_cents=fixed:0,waiver_reason=arg:reason
+```
+
+Use `--starter` only when you intentionally want the old starter skeleton
+instead of the reviewed wizard.
+
+If you already know the reviewed table/action, generate config directly from
+metadata and explicit flags:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --from-env DATABASE_URL \
+  --engine postgres \
+  --schema public \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --visible-columns id,tenant_id,late_fee_cents,waiver_reason,updated_at \
+  --allowed-columns late_fee_cents,waiver_reason \
+  --patch-fixed late_fee_cents=0 \
+  --patch-from-arg waiver_reason=reason \
+  --numeric-bound late_fee_cents=0:5500 \
+  --write-url-env SYNAPSOR_DATABASE_WRITE_URL
+```
+
+For app-owned writeback, replace the direct writer env with a handler executor:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --from-env DATABASE_URL \
+  --engine postgres \
+  --schema public \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --patch-fixed late_fee_cents=0 \
+  --patch-from-arg waiver_reason=reason \
+  --writeback http_handler \
+  --handler-url-env APP_WRITEBACK_URL \
+  --handler-token-env APP_WRITEBACK_TOKEN
+```
+
+Use `--writeback command_handler --handler-command-env APP_WRITEBACK_COMMAND`
+when your app-owned writer is a local command/script instead of HTTP.
+
+Or generate from a saved inspection snapshot without reconnecting:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --inspection-json schema-inspection.json \
+  --table invoices \
+  --namespace billing \
+  --object-name invoice \
+  --mode review \
+  --patch-fixed late_fee_cents=0 \
+  --patch-from-arg waiver_reason=reason
+```
+
+The command uses inspected metadata for primary-key, tenant-key, conflict-column,
+and default-visible-column suggestions. If a suggestion is ambiguous or missing,
+pass explicit flags such as `--primary-key`, `--tenant-key`, and
+`--conflict-column`.
+
+Review mode requires at least one explicit `--patch-fixed` or
+`--patch-from-arg` mapping. Use `--mode read_only` if you only want an inspect
+tool.
+
+For bounded business actions, add reviewed value guards:
+
+```bash
+--numeric-bound credit_cents=0:10000
+--transition-guard status=open:pending_review
+```
+
+`--numeric-bound` keeps a proposed numeric column inside a fixed range before a
+proposal is created. `--transition-guard` keeps a status-like column on an
+approved state path such as `open -> pending_review`. For multiple states, use
+semicolon-separated paths, for example
+`status=open:pending_review;pending_review:resolved`.
+
+## 5. Or create a reviewed selection spec
+
+Create `onboarding-selection.json` from one table and one safe business action.
+
+```json
+{
+  "version": 1,
+  "engine": "postgres",
+  "mode": "review",
+  "read_url_env": "SYNAPSOR_DATABASE_READ_URL",
+  "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL",
+  "schema": "public",
+  "table": "invoices",
+  "primary_key": "id",
+  "tenant_key": "tenant_id",
+  "conflict_column": "updated_at",
+  "namespace": "billing",
+  "object_name": "invoice",
+  "visible_columns": ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  "allowed_columns": ["late_fee_cents", "waiver_reason"],
+  "patch": {
+    "late_fee_cents": { "fixed": 0 },
+    "waiver_reason": { "from_arg": "reason" }
+  },
+  "numeric_bounds": {
+    "late_fee_cents": { "minimum": 0, "maximum": 5500 }
+  }
+}
+```
+
+The selection file contains reviewed metadata selections only. It must not
+contain database URLs or passwords.
+
+## 6. Generate runner files
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
+  --spec onboarding-selection.json \
+  --non-interactive
+```
+
+This creates:
+
+- `synapsor.runner.json`
+- `.env.example`
+- `.synapsor/mcp/generic-stdio.json`
+- `.synapsor/mcp/claude-desktop.json`
+- `.synapsor/mcp/cursor.json`
+- `.synapsor/mcp/vscode.json`
+
+Use `--force` only if you intentionally want to overwrite existing generated
+files.
+
+Generate or refresh MCP client snippets later with:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Call one generated tool locally before wiring an MCP client:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+`smoke call` uses the same runtime as the MCP server. It records evidence and
+query audit for read tools, or creates a proposal for proposal tools, then
+prints the commands to inspect evidence/proposals/replay from the local store.
+
+The snippets contain the local command and args. They must not contain database
+URLs, passwords, approval tools, commit tools, or write credentials.
+
+## 7. Validate the config
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config show --config synapsor.runner.json --redacted
+```
+
+The config stores environment-variable names, not connection-string values.
+
+Run doctor after setting the referenced environment variables:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
+```
+
+Doctor validates config shape, trusted context env vars, source env vars,
+read/write credential separation, table/column metadata when the read URL is
+available, and the semantic MCP tool boundary. Use JSON for automation:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json --json
+```
+
+## 8. Serve semantic MCP tools
+
+Use stdio when a local MCP client can launch Synapsor Runner:
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Use Streamable HTTP when an app/server agent connects through a standard HTTP
+MCP client:
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+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
+```
+
+Streamable HTTP defaults to `127.0.0.1:8766` and requires bearer auth by
+default. Use private networking/TLS before exposing it beyond localhost. See
+[HTTP MCP](http-mcp.md). If you want the smaller JSON-RPC bridge instead, use
+`synapsor-runner mcp serve-http`.
+
+The model-facing MCP server exposes semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_invoice_update
+```
+
+Those names come from the example namespace/object. A custom setup might expose
+`clinic.inspect_appointment` and `clinic.propose_appointment_update`, or any
+other reviewed names you generated. It does not expose `execute_sql`, approval
+tools, commit tools, database URLs, write credentials, or tenant authority.
+
+## 9. Review and apply outside MCP
+
+Proposal tools leave the source database unchanged. Review locally:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+```
+
+Apply through the trusted worker path with a separate writer credential:
+
+```bash
+export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
+SYNAPSOR_ENGINE=postgres \
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For `apply --job ... --config ...`, Runner reads the write credential 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 direct worker flows that do not pass a local config.
+
+If your application/API should own the business write, use an `http_handler`
+executor instead of direct SQL writeback. Handler URLs and bearer tokens come
+from environment variables, and the handler receives a structured proposal/job
+payload, not arbitrary model SQL:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+```
+
+See [Writeback Executors](writeback-executors.md).
+
+Replay afterward:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+```
+
+## Boundary
+
+MCP tool call equals request/proposal authority. Trusted runner equals
+execution authority.
+
+If tenant scope, primary key, allowed columns, expected version, approval state,
+or local config cannot be verified, do not apply the write.