@synapsor/runner 1.4.123 → 1.5.3

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

@@ -28,11 +28,11 @@ inspect your schema
 -> choose one table/view
 -> choose trusted scope and visible fields
 -> optionally choose proposal/writeback rules
--> generate synapsor.runner.json
+-> generate synapsor.runner.json + canonical synapsor.contract.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
+-> open the secured localhost first-action workbench in an interactive terminal
 ```
 
 It does not print your database URL, put the URL in MCP client config, expose
@@ -43,6 +43,11 @@ credentials.
 `onboard db --from-env DATABASE_URL` is the same explicit path if you prefer the
 older command name in scripts.
 
+Interactive `start` opens the focused local workbench after config validation
+and an MCP boundary handshake. Use `--no-open` for CI or scripts. That handshake
+proves the reviewed tool surface; the workbench's **Test** step remains pending
+until a real scoped read is recorded in the local ledger.
+
 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
@@ -66,6 +71,13 @@ export DATABASE_URL="<postgres-or-mysql-read-url>"
 
 Use a read-only credential for inspection and model-facing read/proposal tools.
 
+The generated compatibility setup uses application-level trusted-scope
+predicates. Before production-like multi-tenant use, choose and document one of
+the modes in [Database-Enforced Tenant And Principal
+Scope](database-enforced-scope.md): shared application scope, PostgreSQL RLS
+plus Runner checks, or tenant-bound credentials/deployments. MySQL has no
+native RLS equivalent.
+
 ### TLS notes for AWS RDS and other managed databases
 
 If you see an error like:
@@ -179,6 +191,95 @@ The wizard:
 - writes the generated config, `.env.example`, and MCP client snippets only
   after final confirmation.
 
+The generated action is explicit about its activation state. Read-only and
+shadow actions cannot commit. Review/writeback generation requires final
+confirmation (`--yes` in a noninteractive command) and still gives the model no
+approval or apply tool.
+
+### Draft another Safe Action with a coding agent
+
+After a reviewed read capability exists, describe one business action instead
+of hand-authoring a complete contract:
+
+```bash
+synapsor-runner start \
+  --action plan_credit \
+  --description "Propose one reviewed customer plan credit" \
+  --based-on support.inspect_customer
+```
+
+Runner writes `synapsor/actions/support.propose_plan_credit.ts` and scoped
+agent instructions. The file is an inert scaffold. It contains explicit
+authority questions for trusted scope, visible and kept-out fields, allowed
+effect, conflict guard, bounds, approval, and executor. Creating or editing it
+does not change the active contract or MCP tool list.
+
+Give the exact prompt printed by the command to Cursor or another coding
+agent. The agent may inspect project/schema evidence, complete the restricted
+TypeScript object, and run deterministic validation:
+
+```bash
+synapsor-runner action validate \
+  ./synapsor/actions/support.propose_plan_credit.ts
+```
+
+Runner statically parses rather than imports the file. A successful validation
+writes a digest-addressed **disabled draft**, a plain-language explanation,
+and exact static allow/deny/effect tests under `.synapsor/drafts/`. It cannot
+activate a tool.
+
+In the secured Workbench, run **Preview exact staging Data PR**. The preview
+may perform the reviewed scoped read and write proposal evidence to the local
+ledger, but it cannot mutate the source. Review the exact effect, type
+`ACTIVATE` plus the complete displayed digest, and confirm activation yourself.
+There is intentionally no CLI or MCP command a coding agent can use to
+activate the draft. If the host does not refresh `tools/list`, reconnect the
+MCP server after activation as the Workbench instructs.
+
+## 5. Add the reviewed tools to Cursor
+
+After setting trusted environment values, preview and install a project-scoped
+entry without hand-editing `.cursor/mcp.json`:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp install cursor --project --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Runner merges rather than replaces existing MCP servers, creates a backup,
+records an integrity marker, and is idempotent. The entry uses an exact Runner
+version and contains no database URL, trusted tenant/principal value, approval,
+apply, or revert authority. Remove only the Runner-owned entry with:
+
+```bash
+synapsor-runner mcp uninstall cursor --project --yes
+```
+
+See the [host compatibility matrix](host-compatibility.md) for the precise
+Cursor evidence and MCP Apps limitation.
+
+## 6. Inspect local activation evidence
+
+Runner records bounded timing milestones locally. It does not transmit them:
+
+```bash
+synapsor-runner activation show \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner activation export \
+  --out ./.synapsor/activation-report.json
+```
+
+Product activation time begins after package installation; initial npm
+resolution/download/cache time is measured separately when evaluating cold
+`npx` behavior. The report contains milestone timing/status only, not source
+rows, object IDs, tenant IDs, credentials, or project paths.
+
 For proposal modes, the current runner supports explicit field-update mappings such as:
 
 ```text

package/docs/host-compatibility.md

@@ -0,0 +1,59 @@
+# MCP Host Compatibility
+
+This matrix separates host evidence from protocol evidence. It was last
+reviewed on 2026-07-20. A working MCP SDK handshake is not presented as proof
+that a specific editor renders an extension or protects app-only controls.
+
+| Host/surface | Status | Evidence and boundary |
+| --- | --- | --- |
+| Cursor project `.cursor/mcp.json` lifecycle | Tested | Runner install/status/uninstall tests cover preview, merge, backup, idempotency, ownership, tamper refusal, paths with spaces, and exact-version `npx` wiring. Local Cursor version observed: 3.7.21 (`517f696d8ab6c53eb04fbfdaae705cd146bf3460`, x64). |
+| Cursor stdio Runner launch and `tools/list` | Protocol-tested | `mcp status cursor --project --check-launch` executes the generated command and checks the exact reviewed tools through the official MCP client transport. A final manual Cursor UI pass is still required for a release claim tied to that host version. |
+| Cursor MCP Apps inline proposal card | Unknown | Runner advertises the standard display-only resource metadata, but current stable Cursor rendering and app-only authority guarantees have not been reproduced. Use the secured localhost workbench or operator CLI. |
+| Cursor approval/apply/revert through MCP | Unsupported | Intentionally absent. Cursor may auto-run model-facing tools; commit authority therefore stays outside MCP regardless of host settings. |
+| Generic Add to Cursor deep link | Unsupported | Runner does not generate a link because no current documented generic server payload has been verified end to end. Project install is the supported path. |
+| Generic stdio MCP client | Protocol-tested | Official MCP SDK initialization, tool listing, calls, resources, and display-only Apps metadata are covered in the suite. |
+| Generic Streamable HTTP MCP client | Protocol-tested | Official MCP SDK sessions, signed context, secret rotation, JWKS, mTLS, aliases, and session isolation are covered. |
+| Claude Desktop | Protocol-tested | Packaged stdio configuration and MCP transport are tested; manual host UI behavior varies by version and remains a release checklist item. |
+| Claude Code | Configuration-tested and protocol-tested | Claude Code 2.1.216 accepted the secret-free stdio configuration through `mcp add-json`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
+| Codex | Configuration-tested and protocol-tested | Codex CLI 0.144.6 accepted the secret-free stdio configuration through `codex mcp add`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
+| VS Code | Protocol-tested | The checked `.vscode/mcp.json` shape is parsed and the same stdio command completes MCP `tools/list`; manual editor UI behavior is not claimed. |
+| OpenAI Agents SDK | Recipe-checked and protocol-tested | Packaged stdio/Streamable HTTP examples are syntax/safety checked and OpenAI-safe aliases are protocol-tested. The exact SDK agent call remains protocol-only until run with an owner-supplied API key. |
+| LangChain/LangGraph | Recipe-checked, protocol-only | The current `@langchain/mcp-adapters` recipe lists tools, rejects unsafe authority, and calls the proposal tool. The framework runtime has not been executed in this release environment. |
+| Google ADK | Recipe-checked, protocol-only | The current `McpToolset`/`StdioConnectionParams` recipe exposes only the two reviewed tools. The framework runtime has not been executed in this release environment. |
+| LlamaIndex | Recipe-checked, protocol-only | The current `BasicMCPClient` recipe lists tools and calls the proposal tool. The framework runtime has not been executed in this release environment. |
+
+## Cursor Project Setup
+
+Current Cursor documentation supports project MCP configuration in
+`.cursor/mcp.json`. Runner manages only its `synapsor` entry:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run
+synapsor-runner mcp install cursor --project --yes
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+The generated entry contains command paths only. Database credentials and
+trusted tenant/principal values must come from the environment that launches
+Runner. Other Cursor MCP servers and settings are preserved.
+
+Primary references:
+
+- [Cursor MCP documentation](https://cursor.com/docs/context/mcp)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
+
+All adjacent-host source links, runnable snippets, shared proposal input, and
+verification commands are in [Client And Framework Recipes](client-recipes.md).
+
+## Authority Fallback
+
+Hosts without a verified app-only human-control boundary receive the same
+structured/text proposal result and can open the secured loopback workbench.
+Approval, rejection, apply, compensation, policy activation, trusted identity,
+and credentials never enter model-visible `tools/list`. Runner does not infer
+host safety from a product name or user-agent string.
+
+Runner currently exposes tools, not MCP prompts or an elicitation-based
+approval flow. First-run setup and approval do not depend on optional host
+prompt/elicitation support.

package/docs/local-mode.md

@@ -30,13 +30,14 @@ Current local-mode foundation:
 - local approved proposal to `synapsor.writeback-job.v1` job generation;
 - guarded Postgres/MySQL writeback adapters for approved structured jobs.
 
-Still pending:
+Runtime requirement:
 
-The alpha package requires Node >= 22.5.0 because the local evidence/replay
-ledger uses Node's `node:sqlite` runtime. The published package declares that
-engine requirement and the CLI exits early with a clear message on older Node
-versions. The Docker-backed demo remains the recommended path when you do not
-want to change your host Node version.
+The stable package requires Node >= 22.13.0 because the local evidence/replay
+ledger uses Node's unflagged `node:sqlite` runtime. Earlier Node 22 releases
+require an experimental flag and are not supported. The published package
+declares that engine requirement and the CLI exits early with a clear message
+on older Node versions. The Docker-backed demo remains the recommended path
+when you do not want to change your host Node version.
 
 ## Initialize a config
 
@@ -184,7 +185,11 @@ npx -y -p @synapsor/runner synapsor-runner proposals reject wrp_123 \
 
 Approval records the approver against the exact proposal hash/version. The proposal patch is immutable after creation.
 
-Shadow-mode proposals are inspectable through `proposals show` and `replay show`, but `proposals approve` and `proposals writeback-job` reject them. Shadow mode never mutates Postgres/MySQL.
+Shadow-mode proposals are inspectable through `proposals show` and `replay
+show`, but `proposals approve` and `proposals writeback-job` reject them.
+Shadow mode never mutates Postgres/MySQL or invokes an app-owned handler. To
+compare agent behavior with explicit application/operator outcomes across a
+pilot, use [Shadow Studies](shadow-studies.md).
 
 ## Browser review UI
 

package/docs/mcp-apps.md

@@ -0,0 +1,188 @@
+# Inline Proposal Review With MCP Apps
+
+Synapsor Runner proposal tools advertise a display-only MCP App. A compatible
+host can render the proposed business effect inline after the tool call. Hosts
+without MCP Apps support continue to receive the same JSON and text result.
+
+The app is a presentation surface, not an approval boundary:
+
+- it shows the requested action, semantic capability, trusted tenant/principal
+  provenance, evidence summary, kept-out-field status, exact diff, expected
+  source version, policy state, receipt state, and reversibility state;
+- it contains no database URL, write credential, approval token, review
+  challenge, or reusable operator authority;
+- it cannot call approve, apply, commit, or raw SQL tools because Runner does
+  not expose those tools through MCP;
+- approval and apply remain explicit operator actions in the standalone local
+  UI or terminal.
+
+## Protocol And SDK Baseline
+
+The implementation is pinned to:
+
+| Component | Version |
+| --- | --- |
+| MCP Apps specification | `2026-01-26` stable |
+| `@modelcontextprotocol/ext-apps` | `1.7.4` |
+| `@modelcontextprotocol/sdk` | `1.29.0` |
+
+Proposal tools declare the standard `ui://synapsor/proposal-review.html`
+resource through `_meta.ui.resourceUri`. Runner serves the resource as
+`text/html;profile=mcp-app` and uses the standard `ui/initialize`,
+`ui/notifications/initialized`, and `ui/notifications/tool-result` messages.
+The official registration helper also supplies the compatibility
+`ui/resourceUri` metadata key.
+
+Repository tests use the official MCP SDK client and linked in-memory
+transport. They verify tool discovery, resource discovery/read, Apps message
+schemas, structured and text fallback results, and the absence of
+model-callable approval/apply tools or embedded authority.
+
+The upstream Apps SDK currently lists ChatGPT, Claude, VS Code, Goose, Postman,
+and MCPJam as supported clients. Synapsor's repository CI does not exercise
+those product hosts, so this project does not claim host-specific compatibility
+beyond the official protocol tests. Host support varies by product version and
+deployment.
+
+Specification:
+[MCP Apps 2026-01-26](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
+
+## Connect A Client
+
+Generate a client-native MCP snippet:
+
+```bash
+synapsor-runner mcp config claude-desktop \
+  --absolute-paths \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Runner does not require an Apps-specific switch. A supporting host discovers
+the app from proposal-tool metadata and fetches the declared resource. A
+non-supporting host renders or exposes the normal text/structured tool result.
+
+Preview the model-facing boundary before connecting:
+
+```bash
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+The tool list may include inspect and proposal capabilities. It must not
+include `execute_sql`, `approve`, `apply`, or `commit` tools.
+
+## Optional MCPB Installation
+
+The repository can build an MCP Bundle for hosts that install `.mcpb`
+artifacts:
+
+```bash
+corepack pnpm build:mcpb
+corepack pnpm verify:mcpb
+```
+
+The pinned build uses `@anthropic-ai/mcpb@2.1.2`, validates the `0.4`
+manifest, packs it, unpacks it again, scans its paths/placeholders, and writes
+an archive plus `SHA256SUMS` and `BUILD-INFO.json` under `dist/mcpb/`.
+The verification command launches the unpacked artifact with the official MCP
+client, checks semantic tool/resource discovery, reads the App resource, and
+confirms that no model-facing approval/apply tool is present.
+
+This profile is intentionally narrow:
+
+- it runs the standard `synapsor-runner contract bundle` environment names;
+- the installer asks for the Runner config, state directory, read/write URLs,
+  tenant, and principal;
+- sensitive values are installer configuration and are not embedded in the
+  archive;
+- contracts with custom environment names should use `mcp config` instead.
+
+The generated archive is **unsigned** and reports `signed: false`. Signing is
+a release-owner operation:
+
+```bash
+corepack pnpm exec mcpb sign \
+  --cert /secure/release-cert.pem \
+  --key /secure/release-key.pem \
+  ./dist/mcpb/synapsor-runner-<version>-unsigned.mcpb
+
+corepack pnpm exec mcpb verify \
+  ./dist/mcpb/synapsor-runner-<version>-unsigned.mcpb
+```
+
+Do not use `--self-signed` and present the result as an official release.
+The build inputs and manifest generation are repeatable, but the pinned packer
+records archive timestamps, so byte-for-byte archive hashes may differ between
+builds. The digest applies to the exact artifact that was built and reviewed.
+
+## Complete Human Review
+
+The inline card intentionally does not carry approval authority. Open the
+standalone operator UI:
+
+```bash
+synapsor-runner ui \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Or review from a trusted terminal:
+
+```bash
+synapsor-runner proposals show <proposal_id> \
+  --store ./.synapsor/local.db
+
+synapsor-runner proposals approve <proposal_id> \
+  --store ./.synapsor/local.db
+
+synapsor-runner apply <proposal_id> \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Operator identity, approval state, proposal identity, source version, trusted
+scope, and writeback guards are rechecked by Runner. Seeing a card never grants
+authority and never implies that the source database changed.
+
+## Why The Handoff Is Display-Only
+
+The selected stable Apps SDK provides standardized presentation metadata and
+app/host messaging, but it does not document a channel that Synapsor can prove
+is hidden from model-visible tool content, transcripts, and ordinary logs
+while carrying privileged review authority. Runner therefore does not embed a
+signed review challenge in the app resource, resource URI, result, or query
+string.
+
+If a future standard defines and tests a model-hidden authority channel, an
+inline approval flow would still need a one-time short-lived challenge bound
+to the exact proposal, operator session, purpose, and expiry. Until then, the
+standalone operator path is the security boundary.
+
+## Fallback Behavior
+
+| Client behavior | Result |
+| --- | --- |
+| Supports MCP Apps | Inline display-only proposal card |
+| Supports MCP but not Apps | JSON/text proposal result |
+| No graphical host | Terminal proposal commands |
+| Human wants a browser review surface | Standalone loopback local UI |
+
+All four paths use the same proposal review view model. Kept-out values remain
+absent; the card only states that the reviewed allowlist excluded them.
+
+## Security Checklist
+
+- Keep MCP and the local UI on loopback unless you follow the authenticated
+  production deployment guide.
+- Treat proposal/evidence handles as scoped audit data.
+- Never place database credentials or operator tokens in MCP client JSON.
+- Verify trusted tenant/principal provenance for shared HTTP deployments.
+- Keep least-privilege database roles and database-enforced isolation where
+  appropriate.
+- Treat `source_database_changed: false` as unchanged even when a proposal was
+  created successfully.
+
+See [MCP Client Configs](mcp-clients.md), [MCP Client Setup](mcp-client-setup.md),
+[Local Mode](local-mode.md), and [Security Boundary](security-boundary.md).