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

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- `result_format: 2` for a stable MCP result envelope with
+  `ok`, `summary`, `data`, `proposal`, `error`, `evidence`,
+  `source_database_changed`, and `_meta.canonical_capability`.
+- `--result-format v1|v2` for `mcp serve`, `mcp serve --transport
+  streamable-http`, `mcp serve-streamable-http`, and the legacy JSON-RPC bridge.
+- Capability config fields `description`, per-argument `description`, and
+  `returns_hint`; these are surfaced in MCP tool metadata.
+- `tools list` as a first-class alias for `tools preview`, including
+  `tools list --aliases`.
+- `mcp client-config --include-instructions` for Claude/Cursor/OpenAI-style
+  client snippets with propose-first agent guidance.
+- `schemas/synapsor.runner.schema.json` for editor validation.
+- `docs/capability-authoring.md` and `docs/result-envelope-v2.md`.
+- RFC source docs under `docs/rfcs/`.
+
+### Changed
+
+- OpenAI-safe aliases include the canonical Synapsor capability name in
+  descriptions/metadata so model-visible aliases can still be audited against
+  dotted capability names.
+- v2 MCP errors redact raw driver/infra strings and map failures to a small
+  safe error-code enum.
+
+### Compatibility
+
+- Result envelope v1 remains the default in this alpha. Opt in with
+  `result_format: 2` or `--result-format v2`.
+- The public command remains `synapsor-runner`.
+
+## 0.1.0-alpha.14
+
+### Changed
+
+- Clarified that `@synapsor/handler` is not published as a standalone npm
+  package yet. The TypeScript helper currently exists in the source monorepo
+  and as the bundled `synapsor-handler.mjs` shim used by the packaged
+  app-owned executor example.
+- Included `CHANGELOG.md` in the `@synapsor/runner` npm tarball so users can
+  inspect alpha changes without cloning the repository.
+
+## 0.1.0-alpha.13
+
+### Changed
+
+- Reworked the README opening around a five-line mental model: agent talks to
+  Runner, Runner exposes capabilities, proposals are saved but not applied, and
+  approval/writeback stay outside the model-facing tool surface.
+- Added plain definitions for capability, proposal, writeback, and executor near
+  the top of the README.
+- Added the direct-writeback versus app-owned-executor rule up front: guarded
+  one-row updates can use Runner direct writeback; richer business actions use
+  an app-owned executor.
+- Added a tiny readable own-database config example with one read capability and
+  one proposal capability so new users can picture what the guided wizard
+  creates.
+
+## 0.1.0-alpha.12
+
+### Added
+
+- `doctor --check-writeback` verifies direct SQL writer connectivity,
+  receipt-table readiness, and rollback-only access to configured proposal
+  target tables/columns without mutating business rows.
+- `docs/doctor.md` documents redacted setup checks, handler reachability,
+  direct SQL writeback probes, and receipt-table guidance.
+- `store reset --yes` removes only the local SQLite ledger files and refuses
+  active server leases unless `--force` is provided.
+
+### Changed
+
+- Doctor output now warns when direct SQL writeback has not been probed and
+  points to `--check-writeback`.
+- Packed/public verification scripts exercise `store reset` in addition to
+  stats/prune.
+
+## 0.1.0-alpha.11
+
+See [docs/release-notes.md](docs/release-notes.md) for the current published
+alpha notes.

package/README.md

@@ -7,31 +7,44 @@ 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.
 
-## Alpha Operational Notes
+## The Five-Line Model
 
-These are current alpha requirements, not hidden behavior:
+Your agent talks to Synapsor Runner, not directly to your database.
+It can look: scoped reads through reviewed tools.
+It can suggest: saved proposals with evidence and exact diffs.
+It cannot commit: approval and writeback happen outside the model-facing tool.
+After writeback, Runner keeps receipts and replay so you can inspect what happened.
 
-- 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.
+## Four Terms
+
+- Capability: a tool you define in config, such as `billing.inspect_invoice`
+  or `billing.propose_late_fee_waiver`. The agent only sees capabilities.
+- Proposal: the agent's suggested database-backed change. It is saved, not
+  applied.
+- Writeback: the moment an approved proposal actually changes the database.
+- Executor: your app's writeback handler for anything richer than a guarded
+  one-row update.
+
+## Who Does What
+
+You write the config: sources, trusted context, capabilities, visible fields,
+proposal fields, and guards. For rich writes, you also write a small handler.
+
+Synapsor Runner serves the MCP tools, stores evidence/proposals/receipts,
+enforces tenant, column, version, and idempotency guards, routes writeback, and
+keeps the replay log. You do not rebuild the safety loop yourself.
+
+## The Writeback Rule
+
+One-row update to an existing row: Runner can do guarded direct writeback.
+Anything else, such as inserting a row, touching two tables, or emitting an
+event: your app-owned executor does it after approval.
+
+## Deliberate Limits
+
+Runner does not expose raw SQL, write credentials, approval tools, or commit
+tools to the model. Direct Runner writeback does not do generic `INSERT`,
+`DELETE`, `UPSERT`, DDL, or multi-row SQL. Those are app-owned executor jobs.
 
 ```text
 AI agent or MCP client
@@ -115,6 +128,51 @@ MCP risk review        -> npx -y -p @synapsor/runner@alpha synapsor-runner audit
 `synapsor-runner` is the public command for this OSS runner. `synapsor` is
 reserved for the Synapsor Cloud CLI.
 
+Authoring reference:
+
+- [Capability Authoring](docs/capability-authoring.md): read/proposal tools,
+  model-facing descriptions, result envelope v2, trusted context, and writeback
+  guards.
+- [Result Envelope v2](docs/result-envelope-v2.md): stable
+  `ok`/`summary`/`data`/`proposal`/`error` MCP tool results.
+- [JSON Schema](schemas/synapsor.runner.schema.json): editor validation for
+  `synapsor.runner.json`.
+
+## Current Alpha Details
+
+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.
+- Run `synapsor-runner doctor --config synapsor.runner.json --check-writeback`
+  after reviewing receipt-table DDL/grants to verify writer connectivity,
+  receipt-table permissions, and rollback-only target-table access. The probe
+  never mutates business rows, but it can create the receipt table if the
+  writer has permission.
+- For app-owned `http_handler` executors, configure `signing_secret_env` to
+  have Runner sign writeback requests with `X-Synapsor-Signature`. Run
+  `synapsor-runner doctor --config synapsor.runner.json --check-handlers` to
+  check handler env vars and network reachability without applying a proposal.
+
 ## Connect Your Own Staging Database
 
 Put a read-only connection string in the environment:
@@ -147,6 +205,89 @@ 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 end-to-end shape is:
+
+```text
+1. Put your read-only DB URL in DATABASE_URL.
+2. Run start --from-env DATABASE_URL.
+3. Choose one table/view and the safe fields agents may see.
+4. Preview the generated capabilities.
+5. Serve them over MCP to Claude, Cursor, OpenAI Agents SDK, or your app.
+6. For writes, approve a proposal outside MCP before writeback.
+```
+
+The generated config is just the safety contract. A small reviewed version
+looks like this:
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "sources": {
+    "app_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL",
+      "write_url_env": "SYNAPSOR_DATABASE_WRITE_URL"
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "app_postgres",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": ["id", "status", "late_fee_cents", "updated_at"],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "app_postgres",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true },
+        "reason": { "type": "string", "required": true }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": ["id", "status", "late_fee_cents", "updated_at"],
+      "patch": {
+        "late_fee_cents": { "fixed": 0 },
+        "waiver_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["late_fee_cents", "waiver_reason"],
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    }
+  ]
+}
+```
+
+The agent sees `billing.inspect_invoice` and
+`billing.propose_late_fee_waiver`. It does not see the database URL, writer
+credential, raw SQL, approval command, or commit command.
+
 The wizard creates this local flow:
 
 ```text
@@ -421,6 +562,7 @@ Create a redacted local diagnostic report:
 
 ```bash
 synapsor-runner doctor --config synapsor.runner.json --report --redact --output synapsor-doctor.md
+synapsor-runner doctor --config synapsor.runner.json --check-writeback
 ```
 
 Inspect or compact the local ledger:
@@ -429,6 +571,7 @@ Inspect or compact the local ledger:
 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
+synapsor-runner store reset --store ./.synapsor/local.db --yes
 ```
 
 This is local indexed search for local/dev/staging usage. It is not external
@@ -442,6 +585,9 @@ 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`.
+The packaged app-owned billing example also includes a bundled
+`synapsor-handler.mjs` helper shim; `@synapsor/handler` is not published as a
+standalone npm package yet.
 You can also generate a starter handler directly:
 
 ```bash

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAqG,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAmB3P,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAC/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAoS3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1D;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,CA6OjB;AA4uDD,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAM/H"}