@synapsor/runner 1.5.0 → 1.5.3

package/docs/release-notes.md

@@ -10,7 +10,93 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
-## 1.5.0 (prepared, not published)
+## 1.5.3 (prepared, not published)
+
+### Intent to Safe Action
+
+- `start --action <name> --description <intent>` creates one inert TypeScript
+  Safe Action scaffold from an existing reviewed read boundary. Project-scoped
+  instructions let a coding agent complete and validate only the draft.
+- `action validate` statically parses the restricted object and emits a
+  digest-addressed disabled canonical draft, explanation, and deterministic
+  allow/deny/effect tests. It does not import adopter code, activate the action,
+  or alter the active MCP tool catalog.
+- The secured Workbench runs one real source-unchanged staging Data PR before
+  activation and requires `ACTIVATE` plus the complete digest. Cloud-linked
+  projects use governed Cloud activation. Existing proposals remain bound to
+  the exact active contract digest they were created under.
+- The package includes a current-format Cursor plugin with
+  `/synapsor-protect`, diagnostics, deterministic package verification, and
+  project-safe MCP wiring. Cursor host claims remain evidence-labeled; a stable
+  UI pass and Marketplace submission are owner gates.
+- MCP audit now renders a model-authority map and opt-in bypass evidence as
+  text, JSON, Markdown, or SARIF. A checked-in GitHub Actions workflow and Safe
+  Action team CI are deterministic and non-mutating.
+- Proposal-only integration recipes cover Claude Code, Codex, VS Code, OpenAI
+  Agents, LangChain/LangGraph, Google ADK, LlamaIndex, and generic MCP clients.
+- The first two README screens, public website, article, discovery routes, and
+  36-second evidence-backed demo now lead with the own-project Data PR path.
+
+Prepared package version: `@synapsor/runner@1.5.3`. Spec, DSL, and Cloud CLI
+packages are unchanged. Nothing has been published by this repository change.
+
+## 1.5.2 (prepared, not published)
+
+### First safe action in an existing application
+
+- `start --from-env DATABASE_URL` and
+  `try --prove --from-env DATABASE_URL` now converge on one own-data
+  onboarding path. It inspects a staging database read-only, asks the developer
+  to choose trusted scope and one reviewed action, emits canonical files, and
+  never substitutes synthetic data after an own-data failure.
+- The localhost workbench presents Project, Data source, Trust scope, Action,
+  Agent, Test, and Review plus an exact proposal Data PR. Test is complete only
+  after a scoped tool call records query audit, not after config validation.
+- Project-scoped Cursor install/status/uninstall previews and owns only its MCP
+  entry, preserves other entries, and launches the exact Runner version.
+  Approval, apply, revert, credentials, and trusted identity stay outside MCP.
+- Local activation reports measure proof, onboarding, Cursor, first read, and
+  first proposal without telemetry or business identifiers. Product time
+  excludes initial package download; cold `npx` time is reported separately
+  as an observed environment-specific measurement.
+- Optional TypeScript authoring emits the same canonical Spec contract. Shadow
+  trust progression and provider-neutral effect regression remain
+  non-activating and preserve deterministic/external-model provenance.
+- MCP audit candidates can open directly in the secured workbench, and the
+  release includes the host-compatibility matrix and support/billing reference
+  workflow.
+- The package now requires Node 22.13.0 or newer, the first Node 22 release
+  where Runner's `node:sqlite` dependency is available without an experimental
+  runtime flag. Older Node versions fail immediately with an actionable error.
+
+Prepared package version: `@synapsor/runner@1.5.2`. Spec, DSL, and Cloud CLI
+packages are unchanged. Nothing has been published by this repository change.
+
+## 1.5.1 (prepared, not published)
+
+### Safe disposable state ownership
+
+- `try --state-dir` no longer treats the supplied directory as disposable.
+  The supplied path is a caller-owned container and Runner uses a marked
+  managed child beneath it.
+- Cleanup removes only known direct try-state files. Unrelated files remain in
+  place, and roots, home/cwd/repository paths, traversal, symlink escapes,
+  unmarked lookalikes, and linked managed files fail closed.
+- An atomic state lease prevents concurrent runs from corrupting each other and
+  permits recovery from a valid lease whose process is no longer alive.
+- `demo inspect --state-dir` resolves the same managed child. The default
+  `.synapsor/try` path safely adopts only the recognized legacy file layout.
+- Explicit `--force` replacement of generated schema and MCP-audit candidate
+  directories now rejects protected paths, symlinked ancestors, and linked or
+  invalid ownership markers.
+- The embedded `try` data source is consistently identified as synthetic.
+- The packaged YAML parser is updated to `2.8.3` to include the upstream fix
+  for deeply nested collection denial of service.
+
+Prepared package version: `@synapsor/runner@1.5.1`. Spec, DSL, and Cloud CLI
+packages are unchanged. Nothing has been published by this repository change.
+
+## 1.5.0 (published 2026-07-20)
 
 ### Complete guarded-action developer proof
 
@@ -45,8 +131,8 @@ for the Synapsor Cloud CLI.
   immediately second, and distinguishes application scope, PostgreSQL RLS, and
   tenant-bound isolation without overstating any of them.
 
-Prepared package version: `@synapsor/runner@1.5.0`. Spec, DSL, and Cloud CLI
-packages are unchanged. Nothing has been published by this repository change.
+Published package version: `@synapsor/runner@1.5.0`. Spec, DSL, and Cloud CLI
+packages were unchanged.
 
 ## 1.4.123 (2026-07-17)
 
@@ -744,7 +830,7 @@ not change and must not be republished for this release.
   CDC, managed runner fleets, compliance exports, production SLA, or C++ DBMS
   internals.
 - The local store is single-node SQLite for local/dev/staging usage.
-- Node >= 22.5.0 is required because the local ledger uses Node's
+- Node >= 22.13.0 is required because the local ledger uses Node's unflagged
   `node:sqlite` runtime. Use a supported Node runtime or the Docker-backed
   source demo path.
 

package/docs/security-boundary.md

@@ -36,6 +36,7 @@ The model does not receive:
 - a generic `execute_sql` tool;
 - arbitrary table, schema, or column names;
 - database URLs or credentials;
+- contract activation tools;
 - approval tools;
 - commit/writeback tools;
 - trusted tenant or principal authority as ordinary model arguments.
@@ -84,6 +85,18 @@ explicit host-level administrative boundary.
 Proposal tools read the current row through the read credential, store evidence
 and an exact before/after diff, and leave the source database unchanged.
 
+Code-first Safe Actions do not create authority when a file is edited. Runner
+parses the restricted TypeScript object without importing or executing it,
+compiles it into a digest-addressed disabled canonical draft, and keeps the
+active contract pointer unchanged. Activation is available only in the
+session-token/CSRF-protected localhost Workbench after a matching real staging
+proposal proves `source_database_changed:false`; the operator must confirm the
+complete digest. A proposal remains pinned to the active contract digest it was
+created under, so later activation cannot reinterpret an old approval. Cloud-
+linked projects route activation through Cloud governance instead of the local
+control. No model-facing MCP tool can validate-and-activate, approve, apply, or
+revert.
+
 The local proposal store rejects obvious credential material before persistence:
 database URLs, bearer tokens, Synapsor runner tokens, private-key blocks, and
 secret-like fields such as password, token, API key, private key, cookie,
@@ -145,11 +158,13 @@ database identifiers such as `../private`, `id/../../tenant_id`, or
 `status; DROP TABLE tickets` before adapter execution. Local CLI file paths
 remain explicit user-provided paths; they are not model-facing authority.
 
-Local review can happen through the CLI or `synapsor-runner ui`. The UI is a localhost
-review surface with a per-run session token and CSRF protection for
-approve/reject actions. It does not expose raw SQL, database URLs, write
-credentials, approval tools, commit tools, or controls that widen reviewed
-tables/columns.
+Local review can happen through the CLI or `synapsor-runner ui`. The UI is a
+localhost review surface with a per-run session token and CSRF protection for
+approve/reject and Safe Action draft controls. Activation additionally requires
+a matching source-unchanged preview plus the complete digest. These operator
+controls are not MCP tools. The UI does not expose raw SQL, database URLs, or
+write credentials, and it does not let a model widen reviewed tables, columns,
+scope, policy, or executor authority.
 
 Contract lint and tests are review aids rather than a proof of complete
 security. Capability breadth can still drift as narrow tools accumulate;

package/docs/shadow-studies.md

@@ -142,6 +142,41 @@ synapsor-runner shadow outcome import \
   --store ./.synapsor/local.db
 ```
 
+For the normal application path, record the trusted outcome directly instead
+of assembling JSONL. `@synapsor/runner/shadow` writes through the same scope,
+effect-shape, and secret checks as the import command:
+
+```js
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const recorder = createShadowOutcomeRecorder({
+  storePath: "./.synapsor/local.db",
+  studyId: "sst_support_pilot",
+  actor: "support_application",
+  source: "support-audit-log",
+});
+
+try {
+  recorder.record({
+    requestId: "request_123",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500 },
+      after: { late_fee_cents: 0 },
+      patch: { late_fee_cents: 0 },
+    },
+  });
+} finally {
+  recorder.close();
+}
+```
+
+The application owns the truth of this outcome. The helper does not read or
+mutate the source database and cannot approve a shadow proposal.
+
 ## Review The Report
 
 ```bash
@@ -161,6 +196,16 @@ denial, unable-to-propose, stale/conflict, unmatched, and unsafe-scope cases.
 It also includes amount distributions, capability/reason breakdowns, and
 risk-ranked disagreements.
 
+The report also shows the explicit trust progression:
+
+```text
+Observe -> Compare -> Manual review -> Suggested bounded policy
+```
+
+It reports an insufficient sample size until the minimum comparable evidence
+exists. A suggested policy remains an inactive review artifact; the report
+never widens or activates the contract.
+
 Close a completed study:
 
 ```bash
@@ -187,10 +232,8 @@ synapsor-runner shadow case import \
   --input ./examples/support-billing-agent/shadow-study/cases.jsonl \
   --store ./.synapsor/shadow-reference.db
 
-synapsor-runner shadow outcome import \
-  --study sst_support_reference \
-  --input ./examples/support-billing-agent/shadow-study/outcomes.jsonl \
-  --store ./.synapsor/shadow-reference.db
+node ./examples/support-billing-agent/app/record-shadow-outcomes.mjs \
+  ./.synapsor/shadow-reference.db sst_support_reference
 
 synapsor-runner shadow report \
   --study sst_support_reference \

package/docs/troubleshooting-first-run.md

@@ -12,6 +12,52 @@ Use JSON for automation:
 npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
 ```
 
+## Safe Action Draft Does Not Appear As A Tool
+
+This is expected before activation. `start --action`, agent edits, `action
+validate`, and `action watch` can create or refresh only a disabled draft. They
+must not alter the active model-facing tools.
+
+Check status without exposing credentials:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Open the secured Workbench, run the real source-unchanged staging Data PR
+preview, review the complete digest, and activate it there. There is
+intentionally no activation CLI command to hand to a coding agent.
+
+## Activated Tool Does Not Appear In Cursor
+
+Some MCP hosts do not refresh `tools/list` for a running stdio session. First
+confirm that Runner's active tool surface changed:
+
+```bash
+synapsor-runner action status --json
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Then reconnect or restart the project MCP server as directed by the Workbench.
+Do not work around a stale host session by adding approval, apply, activation,
+credentials, tenant values, or raw SQL to the Cursor configuration.
+
+## Safe Action Validation Reports Review Placeholders
+
+The composer fails closed while any `__REVIEW_*__` authority placeholder or
+dynamic TypeScript expression remains. Review the reported field and source,
+then make the authority explicit in the restricted `defineCapability({...})`
+object. Runner will not infer trusted tenant/principal bindings, hidden fields,
+write columns, bounds, conflict guards, approval, or executor authority from
+application code.
+
+Use the generated explanation and test manifest after validation. Do not edit
+digest-addressed files under `.synapsor/drafts/` or `.synapsor/active/`; edit
+the TypeScript source and validate again.
+
 ## Smoke Proposal Missing From Another Runner
 
 What happened:

package/examples/support-billing-agent/README.md

@@ -63,6 +63,21 @@ The demo proves:
 - the shadow report compares cases with authoritative human outcomes before the
   effect fixture checks the expected business change.
 
+The app-owned integration files make those two evaluation paths reusable:
+
+- `app/contract.ts` is the code-first TypeScript form of the reviewed late-fee
+  action and compiles to the same canonical spec as JSON/DSL;
+- `app/record-shadow-outcomes.mjs` records authoritative app outcomes through
+  `@synapsor/runner/shadow` without approval or source mutation;
+- `app/effect-adapter.mjs` emits one deterministic, propose-only result through
+  the provider-neutral command adapter;
+- `.github/workflows/effect-regression.yml` runs the effect check and uploads
+  JUnit output for relevant pull requests.
+
+This repository result is deterministic application evidence, not an external
+model benchmark. Use `--result-origin external-model` only when your adapter
+actually invokes a model.
+
 RLS is defense in depth, not a claim that a fully compromised Runner process is
 contained. A process that can choose arbitrary trusted context or replace the
 database credential remains outside this guarantee. Production deployments
@@ -107,6 +122,9 @@ Relevant files:
 - `scripts/run-demo.sh`
 - `scripts/run-evaluation.sh`
 - `app/README.md`
+- `app/contract.ts`
+- `app/record-shadow-outcomes.mjs`
+- `app/effect-adapter.mjs`
 - `shadow-study/cases.jsonl` and `shadow-study/outcomes.jsonl`: deterministic
   true-shadow reference data for agent-versus-authoritative-outcome reports.
 

package/examples/support-billing-agent/app/README.md

@@ -11,3 +11,9 @@ writeback with tenant, primary-key, allowed-column, idempotency, and
 For richer app actions, such as inserting a credit ledger row and emitting an
 event, use the app-owned handler examples in `../app-owned-writeback/` and
 `../mcp-postgres-billing-app-handler/`.
+
+`contract.ts` demonstrates the optional typed authoring frontend without
+changing the canonical contract. `record-shadow-outcomes.mjs` is the normal-app
+bridge for authoritative human outcomes. `effect-adapter.mjs` is a deterministic
+propose-only CI adapter; it receives a bounded fixture path and emits one
+canonical result. Neither helper approves, applies, or mutates the source.

package/examples/support-billing-agent/app/contract.ts

@@ -0,0 +1,28 @@
+import { defineCapability } from "@synapsor/runner/authoring";
+
+export const waiveLateFee = defineCapability({
+  name: "billing.propose_late_fee_waiver",
+  kind: "proposal",
+  context: "local_operator",
+  source: "app_postgres",
+  subject: { resource: "billing.invoice", primary_key: "id", tenant_key: "tenant_id" },
+  args: {
+    invoice_id: { type: "string", required: true, max_length: 128 },
+    reason: { type: "string", required: true, max_length: 500 },
+  },
+  lookup: { id_from_arg: "invoice_id" },
+  visible_fields: ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  kept_out_fields: ["card_token", "internal_risk_note"],
+  evidence: { required: true, query_audit: true },
+  max_rows: 1,
+  proposal: {
+    action: "waive_late_fee",
+    operation: { kind: "update" },
+    allowed_fields: ["late_fee_cents", "waiver_reason"],
+    patch: { late_fee_cents: { fixed: 0 }, waiver_reason: { from_arg: "reason" } },
+    numeric_bounds: { late_fee_cents: { minimum: 0, maximum: 10000 } },
+    conflict_guard: { column: "updated_at" },
+    approval: { mode: "human", required_role: "billing_lead" },
+    writeback: { mode: "direct_sql" },
+  },
+});

package/examples/support-billing-agent/app/effect-adapter.mjs

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+
+if (process.env.SYNAPSOR_EFFECT_MODE !== "propose_only") {
+  throw new Error("reference effect adapter requires SYNAPSOR_EFFECT_MODE=propose_only");
+}
+if (process.env.DATABASE_URL || process.env.SYNAPSOR_DATABASE_WRITE_URL) {
+  throw new Error("reference effect adapter must not receive database credentials");
+}
+const fixturePath = process.env.SYNAPSOR_EFFECT_FIXTURE_PATH;
+if (!fixturePath) throw new Error("SYNAPSOR_EFFECT_FIXTURE_PATH is required");
+const fixture = JSON.parse(fs.readFileSync(fixturePath, "utf8"));
+const expected = fixture.expected;
+
+process.stdout.write(`${JSON.stringify({
+  schema_version: "synapsor.effect-result.v1",
+  fixture_id: fixture.fixture_id,
+  capability_calls: expected.capability_calls.map((name) => ({ name })),
+  trusted_context: expected.trusted_context,
+  proposal: expected.proposal,
+  observed_fields: Object.keys(expected.proposal.diff ?? {}).sort(),
+  evidence: { mode: "fixture", new_source_reads: false },
+  source_database_changed: false,
+})}\n`);

package/examples/support-billing-agent/app/record-shadow-outcomes.mjs

@@ -0,0 +1,44 @@
+import { createShadowOutcomeRecorder } from "@synapsor/runner/shadow";
+
+const [storePath, studyId] = process.argv.slice(2);
+if (!storePath || !studyId) {
+  throw new Error("usage: node record-shadow-outcomes.mjs <store-path> <study-id>");
+}
+
+const recorder = createShadowOutcomeRecorder({
+  storePath,
+  studyId,
+  actor: "support_reference_app",
+  source: "support-app-audit",
+});
+try {
+  recorder.record({
+    requestId: "req-waiver-exact",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-3001",
+    disposition: "applied",
+    actualEffect: {
+      before: { late_fee_cents: 5500, waiver_reason: null },
+      after: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+      patch: { late_fee_cents: 0, waiver_reason: "courtesy waiver" },
+    },
+    occurredAt: "2026-07-19T11:00:00.000Z",
+    reference: "ticket:SUP-184",
+    reason: "customer qualified",
+  });
+  recorder.record({
+    requestId: "req-waiver-rejected",
+    tenantId: "acme",
+    businessObject: "invoice",
+    objectId: "INV-REJECTED",
+    disposition: "rejected_no_action",
+    occurredAt: "2026-07-19T11:01:00.000Z",
+    reference: "ticket:SUP-REJECTED",
+    reason: "customer already received a courtesy waiver",
+  });
+} finally {
+  recorder.close();
+}
+
+process.stdout.write("Recorded 2 authoritative outcomes through @synapsor/runner/shadow.\n");

package/examples/support-billing-agent/scripts/run-evaluation.sh

@@ -23,10 +23,9 @@ corepack pnpm runner shadow case import \
   --input "$ROOT_DIR/examples/support-billing-agent/shadow-study/cases.jsonl" \
   --store "$STORE_PATH" >/dev/null
 
-corepack pnpm runner shadow outcome import \
-  --study sst_support_reference \
-  --input "$ROOT_DIR/examples/support-billing-agent/shadow-study/outcomes.jsonl" \
-  --store "$STORE_PATH" >/dev/null
+corepack pnpm build:runner-package >/dev/null
+node "$ROOT_DIR/examples/support-billing-agent/app/record-shadow-outcomes.mjs" \
+  "$STORE_PATH" sst_support_reference >/dev/null
 
 corepack pnpm runner shadow report \
   --study sst_support_reference \
@@ -54,7 +53,9 @@ NODE
 
 corepack pnpm runner effect run \
   --dataset "$ROOT_DIR/fixtures/effects/dataset.json" \
-  --results-dir "$ROOT_DIR/fixtures/effects/results" \
+  --adapter node \
+  --adapter-arg "$ROOT_DIR/examples/support-billing-agent/app/effect-adapter.mjs" \
+  --result-origin deterministic-application \
   --format json \
   --out "$EFFECT_PATH" >/dev/null
 

package/examples/support-plan-credit/README.md

@@ -15,7 +15,7 @@ policy-tier demonstration.
 ## Prerequisites
 
 - Docker
-- Node 22.5+
+- Node 22.13+
 - Port `55438` available
 
 Install the stable CLI once for the commands below:
@@ -50,6 +50,42 @@ network connection or connecting to a database. From a source checkout,
 `corepack pnpm verify:adoption` runs this boundary check plus the no-database
 quick demo and MCP config validation.
 
+## Clone And Validate The Same Safe Action
+
+The checked-in code-first action is
+[`synapsor/actions/support.propose_plan_credit.ts`](synapsor/actions/support.propose_plan_credit.ts).
+It is a reviewable frontend for the same canonical JSON contract, not another
+runtime format. Editing it cannot change active tools.
+
+After cloning the repository and installing dependencies, another developer can
+run the deterministic team gate without a database or Cloud account:
+
+```bash
+corepack pnpm install --frozen-lockfile
+corepack pnpm verify:safe-action-team
+```
+
+The verifier copies this example to a disposable directory, compiles the action
+only as a disabled draft, compares the regenerated boundary tests with the
+checked-in file, proves the config and active contract are unchanged, and emits
+text, JSON, and JUnit reports under `tmp/safe-action-team-ci/`. Its static gate
+covers the exact proposal effect, trusted scope, evidence requirement, approval
+policy, operator separation, kept-out fields, argument bounds, and conflict
+guard. It performs no approval, activation, source read, or source mutation.
+
+The same gate runs in
+[`safe-action-ci.yml`](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/safe-action-ci.yml).
+CI adds a disposable PostgreSQL service and runs the generated allowed-effect,
+cross-tenant-denial, and source-unchanged assertions. It uses an amount above
+the auto-approval threshold, performs no approval or apply, and requires source
+rows and source receipt state to remain equivalent before and after the live
+suite.
+For a real staging preview, each developer supplies their own
+`PLAN_CREDIT_POSTGRES_READ_URL`, `PLAN_CREDIT_POSTGRES_WRITE_URL`,
+`SYNAPSOR_TENANT_ID`, and `SYNAPSOR_PRINCIPAL` outside Git, then follows the
+Quick Start below. Cursor receives the same proposal-only tools; activation,
+approval, and apply remain outside the agent.
+
 ## Quick Start
 
 ```bash
@@ -199,9 +235,19 @@ shape without guessing which state should change.
 Copy the matching template from [`mcp-client-examples/`](mcp-client-examples/):
 
 - Claude Desktop: `claude-desktop.json`
+- Claude Code: `claude-code.sh`
+- Codex: `codex.config.toml`
 - Cursor project/global: `cursor-project.mcp.json`, `cursor-global.mcp.json`
+- VS Code: `vscode.mcp.json`
 - OpenAI Agents SDK: stdio and Streamable HTTP TypeScript examples
-- generic MCP: stdio and Streamable HTTP JSON examples
+- LangChain/LangGraph: `langchain.mjs`
+- Google ADK: `google-adk.py`
+- LlamaIndex: `llamaindex.py`
+- generic MCP: stdio and Streamable HTTP JSON and JavaScript examples
+
+See [Client And Framework Recipes](../../docs/client-recipes.md) for current
+official references, exact proposal input, evidence labels, and the mechanical
+verification gate.
 
 For Streamable HTTP, run:
 

package/examples/support-plan-credit/mcp-client-examples/README.md

@@ -0,0 +1,23 @@
+# Support Plan Credit MCP Recipes
+
+These files connect different MCP hosts and frameworks to the same reviewed
+Runner tools:
+
+- `support.inspect_customer`
+- `support.propose_plan_credit`
+
+Every proposal example uses:
+
+```json
+{
+  "customer_id": "CUS-3001",
+  "credit_cents": 2500,
+  "reason": "SLA outage ticket SUP-481"
+}
+```
+
+The expected call result has `source_database_changed: false`. Human review,
+approval, and apply stay outside every model-facing recipe.
+
+See [Client And Framework Recipes](../../../docs/client-recipes.md) for setup,
+evidence labels, official references, and verification commands.

package/examples/support-plan-credit/mcp-client-examples/claude-code.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run from the repository root. Credentials and trusted scope are inherited
+# from the shell that starts Claude Code; they are not written to .mcp.json.
+claude mcp add-json --scope project synapsor "$(cat <<'JSON'
+{
+  "type": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "-p",
+    "@synapsor/runner",
+    "synapsor-runner",
+    "mcp",
+    "serve",
+    "--config",
+    "./examples/support-plan-credit/synapsor.runner.json",
+    "--store",
+    "./tmp/support-plan-credit/local.db"
+  ]
+}
+JSON
+)"
+
+claude mcp get synapsor
+
+cat <<'PROMPT'
+List the Synapsor MCP tools. Confirm there is no SQL, approval, apply, commit,
+activation, or revert tool. Then call support.propose_plan_credit with
+customer_id CUS-3001, credit_cents 2500, and reason "SLA outage ticket
+SUP-481". Show the exact proposal effect and confirm source_database_changed is
+false. Stop for human review outside Claude Code.
+PROMPT

package/examples/support-plan-credit/mcp-client-examples/codex.config.toml

@@ -0,0 +1,24 @@
+# Merge this table into a trusted project's .codex/config.toml and start Codex
+# from the repository root. Credentials and trusted scope remain inherited
+# environment variables; do not add their values here.
+[mcp_servers.synapsor]
+command = "npx"
+args = [
+  "-y",
+  "-p",
+  "@synapsor/runner",
+  "synapsor-runner",
+  "mcp",
+  "serve",
+  "--config",
+  "./examples/support-plan-credit/synapsor.runner.json",
+  "--store",
+  "./tmp/support-plan-credit/local.db",
+]
+
+# Prompt:
+# List the Synapsor tools, then call support.propose_plan_credit with
+# customer_id CUS-3001, credit_cents 2500, and reason "SLA outage ticket
+# SUP-481". Confirm source_database_changed is false and stop for human review
+# outside Codex. Never request an approval, apply, commit, activation, or revert
+# MCP tool.

package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs

@@ -0,0 +1,35 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: [
+    "-y", "-p", "@synapsor/runner", "synapsor-runner", "mcp", "serve",
+    "--config", "./examples/support-plan-credit/synapsor.runner.json",
+    "--store", "./tmp/support-plan-credit/local.db",
+  ],
+  env: process.env,
+  stderr: "inherit",
+});
+const client = new Client({ name: "synapsor-generic-stdio", version: "1.0.0" });
+
+await client.connect(transport);
+try {
+  const listed = await client.listTools();
+  const names = listed.tools.map((tool) => tool.name);
+  const forbidden = names.filter((name) => /sql|approve|apply|commit|activate|revert/i.test(name));
+  if (forbidden.length) throw new Error(`unsafe model-facing tools: ${forbidden.join(", ")}`);
+
+  const result = await client.callTool({
+    name: "support.propose_plan_credit",
+    arguments: {
+      customer_id: "CUS-3001",
+      credit_cents: 2500,
+      reason: "SLA outage ticket SUP-481",
+    },
+  });
+  console.log(JSON.stringify(result, null, 2));
+  console.error("Proposal only. Review and apply outside the model-facing MCP client.");
+} finally {
+  await client.close();
+}