@synapsor/runner 0.1.0-alpha.10 → 0.1.0-alpha.13

package/README.md

@@ -7,27 +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.
-- `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
@@ -111,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:
@@ -143,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
@@ -199,6 +344,15 @@ synapsor-runner mcp serve \
   --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
@@ -207,12 +361,29 @@ 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
+  --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.
+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:
 
@@ -245,6 +416,15 @@ Before asking an agent to solve a real task, confirm it can call a Runner tool:
 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
@@ -382,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:
@@ -390,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

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAkF,KAAK,WAAW,EAAoD,MAAM,6BAA6B,CAAC;AAkBjM,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"}