@synapsor/runner 1.5.0 → 1.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +134 -3
- package/README.md +108 -113
- package/dist/authoring.d.ts +23 -0
- package/dist/authoring.d.ts.map +1 -0
- package/dist/authoring.mjs +1318 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +4 -5
- package/dist/local-ui.d.ts +14 -0
- package/dist/local-ui.d.ts.map +1 -1
- package/dist/runner.mjs +12334 -5256
- package/dist/runtime.mjs +817 -149
- package/dist/shadow.d.ts +36 -0
- package/dist/shadow.d.ts.map +1 -0
- package/dist/shadow.mjs +5362 -0
- package/docs/README.md +25 -2
- package/docs/alternatives.md +122 -0
- package/docs/capability-authoring.md +49 -1
- package/docs/client-recipes.md +218 -0
- package/docs/cloud-mode.md +18 -0
- package/docs/contract-testing.md +9 -7
- package/docs/cursor-plugin.md +78 -0
- package/docs/database-enforced-scope.md +8 -0
- package/docs/dsl-reference.md +45 -4
- package/docs/effect-regression.md +39 -2
- package/docs/fresh-developer-usability.md +110 -0
- package/docs/getting-started-own-database.md +102 -5
- package/docs/guarded-crud-writeback.md +10 -1
- package/docs/host-compatibility.md +59 -0
- package/docs/http-mcp.md +222 -207
- package/docs/limitations.md +9 -2
- package/docs/local-mode.md +11 -7
- package/docs/mcp-audit.md +166 -2
- package/docs/mcp-client-setup.md +28 -11
- package/docs/mcp-clients.md +43 -8
- package/docs/openai-agents-sdk.md +16 -2
- package/docs/oss-vs-cloud.md +3 -0
- package/docs/production.md +72 -7
- package/docs/release-notes.md +131 -4
- package/docs/runner-bundles.md +7 -2
- package/docs/runner-config-reference.md +96 -6
- package/docs/running-a-runner-fleet.md +42 -13
- package/docs/security-boundary.md +58 -8
- package/docs/shadow-studies.md +47 -4
- package/docs/store-lifecycle.md +93 -5
- package/docs/troubleshooting-first-run.md +46 -0
- package/examples/openai-agents-http/README.md +10 -4
- package/examples/openai-agents-http/agent.py +2 -2
- package/examples/runner-fleet/Dockerfile +7 -2
- package/examples/runner-fleet/README.md +11 -7
- package/examples/runner-fleet/docker-compose.yml +4 -4
- package/examples/runner-fleet/mint-dev-token.mjs +1 -1
- package/examples/runner-fleet/start-tls-runner.sh +21 -0
- package/examples/runner-fleet/synapsor.runner.json +27 -1
- package/examples/support-billing-agent/README.md +18 -0
- package/examples/support-billing-agent/app/README.md +6 -0
- package/examples/support-billing-agent/app/contract.ts +28 -0
- package/examples/support-billing-agent/app/effect-adapter.mjs +23 -0
- package/examples/support-billing-agent/app/record-shadow-outcomes.mjs +44 -0
- package/examples/support-billing-agent/scripts/run-evaluation.sh +6 -5
- package/examples/support-plan-credit/README.md +54 -3
- package/examples/support-plan-credit/mcp-client-examples/README.md +23 -0
- package/examples/support-plan-credit/mcp-client-examples/claude-code.sh +34 -0
- package/examples/support-plan-credit/mcp-client-examples/codex.config.toml +24 -0
- package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs +35 -0
- package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.json +4 -1
- package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.mjs +31 -0
- package/examples/support-plan-credit/mcp-client-examples/google-adk.py +40 -0
- package/examples/support-plan-credit/mcp-client-examples/langchain.mjs +29 -0
- package/examples/support-plan-credit/mcp-client-examples/llamaindex.py +36 -0
- package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts +1 -1
- package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts +5 -1
- package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json +20 -0
- package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.contract-tests.generated.json +221 -0
- package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.ts +34 -0
- package/examples/support-plan-credit/synapsor.contract.json +0 -3
- package/fixtures/mcp-audit/README.md +14 -0
- package/fixtures/mcp-audit/cursor-bypass-config.json +38 -0
- package/fixtures/mcp-audit/dangerous-tools-list.json +33 -0
- package/fixtures/mcp-audit/reviewed-proposal-tools-list.json +60 -0
- package/package.json +18 -3
- package/schemas/mcp-audit-report.schema.json +100 -1
- package/schemas/synapsor.contract-tests.schema.json +1 -1
- package/schemas/synapsor.runner.schema.json +80 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,138 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## 1.5.
|
|
3
|
+
## 1.5.4 (prepared, not published)
|
|
4
|
+
|
|
5
|
+
### Networked MCP authentication hardening
|
|
6
|
+
|
|
7
|
+
- Defines explicit local-loopback, remote single-tenant, and shared multi-tenant
|
|
8
|
+
HTTP security profiles while preserving zero-configuration local stdio.
|
|
9
|
+
- Refuses non-loopback cleartext listeners before bind unless the operator
|
|
10
|
+
explicitly selects a trusted TLS proxy or authenticated break-glass posture.
|
|
11
|
+
Runner-owned TLS and optional mTLS remain supported.
|
|
12
|
+
- Hardens opaque endpoint tokens with environment-only provisioning, production
|
|
13
|
+
entropy checks, constant-time comparison, one bounded previous-token rotation
|
|
14
|
+
slot, and per-session credential pinning. Opaque tokens remain service access
|
|
15
|
+
credentials, not tenant or user identity.
|
|
16
|
+
- Requires verified signed identity for shared deployments. Runner validates
|
|
17
|
+
algorithm, signature, issuer, audience/resource, time, scope, tenant, and
|
|
18
|
+
principal on every request, including requests for existing MCP sessions.
|
|
19
|
+
- Adds RFC 9728 protected-resource metadata and standards-correct Bearer
|
|
20
|
+
challenges for external authorization servers. Runner remains a protected
|
|
21
|
+
resource and does not issue passwords, access tokens, or refresh tokens.
|
|
22
|
+
- Adds exact Origin and Host policy, bounded headers/bodies/connections/sessions,
|
|
23
|
+
TLS preflight, bounded public-only JWKS handling, and safe overload responses.
|
|
24
|
+
- Expands `doctor`, help, client generators, fleet examples, and deployment docs
|
|
25
|
+
so operators can distinguish TLS, Bearer presentation, opaque tokens, JWTs,
|
|
26
|
+
MCP session IDs, trusted context, database scope, and operator authority
|
|
27
|
+
without printing credential values.
|
|
28
|
+
- Adds read-only, no-ID-first `lifecycle` inspection across local SQLite and
|
|
29
|
+
shared PostgreSQL runtime stores. Latest, filtered business-object lookup, and
|
|
30
|
+
proposal/evidence/replay/job/intent/receipt/audit handles resolve one typed,
|
|
31
|
+
redacted proposal-to-receipt/replay timeline without creating jobs, leases,
|
|
32
|
+
source calls, or Cloud synchronization.
|
|
33
|
+
- Makes UPDATE conflict guarding exact by default in the SQL-like DSL.
|
|
34
|
+
Omitting `CONFLICT GUARD <column>` now fails. The explicit legacy
|
|
35
|
+
`CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` form is limited to ordinary
|
|
36
|
+
single-row source-DB UPDATE and warns that projection hashing can miss outside
|
|
37
|
+
changes.
|
|
38
|
+
- Preserves canonical `SESSION` for implementations with a real typed session
|
|
39
|
+
boundary while making Runner fail closed with
|
|
40
|
+
`SESSION_BINDING_UNSUPPORTED`. Runner-targeted DSL validation, contract load,
|
|
41
|
+
lint/explain, and runtime no longer allow an environment fallback.
|
|
42
|
+
- Prepares `@synapsor/runner@1.5.4` and `@synapsor/dsl@1.4.4`;
|
|
43
|
+
`@synapsor/spec@1.4.2` and the Cloud CLI remain unchanged.
|
|
44
|
+
|
|
45
|
+
## 1.5.3 (published 2026-07-21)
|
|
46
|
+
|
|
47
|
+
### Intent to Safe Action
|
|
48
|
+
|
|
49
|
+
- Adds one code-first Safe Action Composer from a reviewed read boundary to a
|
|
50
|
+
restricted TypeScript draft, canonical contract, plain-language explanation,
|
|
51
|
+
and deterministic allow/deny/effect tests. Runner statically parses the file
|
|
52
|
+
and never imports or executes adopter code while deciding authority.
|
|
53
|
+
- Keeps every generated action disabled until a human reviews a real staging
|
|
54
|
+
Data PR in the secured Workbench and explicitly activates the complete
|
|
55
|
+
digest. Editing, validating, or watching a draft cannot change active MCP
|
|
56
|
+
tools; proposals remain pinned to their active contract digest.
|
|
57
|
+
- Adds current Cursor project/plugin packaging, `/synapsor-protect`, live Safe
|
|
58
|
+
Action diagnostics, owned install/uninstall, and an honest host matrix.
|
|
59
|
+
Activation, approval, apply, credentials, and trusted identity stay outside
|
|
60
|
+
the model-facing surface.
|
|
61
|
+
- Extends MCP audit with evidence-labeled authority maps, explicitly consented
|
|
62
|
+
selected-server bypass checks, text/JSON/Markdown/SARIF output, fixtures, and
|
|
63
|
+
a non-mutating GitHub Actions workflow.
|
|
64
|
+
- Adds a checked-in Safe Action CI workflow plus verified proposal-only recipes
|
|
65
|
+
for Claude Code, Codex, VS Code, OpenAI Agents, LangChain/LangGraph, Google
|
|
66
|
+
ADK, LlamaIndex, and generic MCP clients.
|
|
67
|
+
- Reframes the README and website around one existing-application Data PR,
|
|
68
|
+
publishes an honest alternatives guide, and adds a deterministic 36-second
|
|
69
|
+
support-plan-credit cut backed by real PostgreSQL proposal, receipt, retry,
|
|
70
|
+
and stale-conflict evidence.
|
|
71
|
+
- Published only `@synapsor/runner@1.5.3`; `@synapsor/spec@1.4.2`,
|
|
72
|
+
`@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
|
|
73
|
+
|
|
74
|
+
## 1.5.2 (prepared, not published)
|
|
75
|
+
|
|
76
|
+
### First safe action in an existing application
|
|
77
|
+
|
|
78
|
+
- Establishes one canonical path from an existing application and staging
|
|
79
|
+
Postgres/MySQL database to a reviewed semantic action, scoped evidence, exact
|
|
80
|
+
proposal/Data PR, external human review, guarded apply, receipt, and replay.
|
|
81
|
+
Own-data failures stop honestly and never fall back to synthetic data.
|
|
82
|
+
- Generates a canonical contract and local Runner wiring from read-only schema
|
|
83
|
+
inspection while detecting Prisma, Drizzle, OpenAPI, known database
|
|
84
|
+
environment names, and existing Synapsor files without executing adopter
|
|
85
|
+
code. The happy path requires no hand-written JSON or DSL.
|
|
86
|
+
- Adds a focused localhost workbench for Project, Data source, Trust scope,
|
|
87
|
+
Action, Agent, Test, and Review. Configuration validation alone no longer
|
|
88
|
+
marks Test complete; a scoped read must create query-audit evidence first.
|
|
89
|
+
- Adds safe project-scoped Cursor install, status, and uninstall with preview,
|
|
90
|
+
merge, backup, ownership/integrity checks, exact-version launch, and
|
|
91
|
+
preservation of unrelated MCP entries. Approval, apply, revert, credentials,
|
|
92
|
+
and trusted identity remain outside the model-facing MCP surface.
|
|
93
|
+
- Adds local-only activation reports for proof, own-data onboarding, Cursor,
|
|
94
|
+
first read, and first proposal. Product timing explicitly excludes initial
|
|
95
|
+
package download; separately reported cold `npx` timing is environment-
|
|
96
|
+
specific. No activation telemetry or business identifiers are transmitted.
|
|
97
|
+
- Adds optional `@synapsor/runner/authoring` and
|
|
98
|
+
`@synapsor/runner/shadow` exports. TypeScript authoring emits the same
|
|
99
|
+
canonical public contract, while shadow progression and provider-neutral
|
|
100
|
+
effect regression remain non-activating and label deterministic versus
|
|
101
|
+
external-model evidence.
|
|
102
|
+
- Connects MCP audit candidates directly to the secured workbench and keeps
|
|
103
|
+
audit prominent in the README and docs. Adds an explicit host-compatibility
|
|
104
|
+
matrix and a packaged support/billing first-action reference workflow.
|
|
105
|
+
- Corrects the supported runtime floor to Node 22.13.0, where `node:sqlite` is
|
|
106
|
+
available without an experimental flag, and fails earlier runtimes before
|
|
107
|
+
loading the Runner bundle.
|
|
108
|
+
- Prepares only `@synapsor/runner@1.5.2`; `@synapsor/spec@1.4.2`,
|
|
109
|
+
`@synapsor/dsl@1.4.3`, and the Cloud CLI remain unchanged.
|
|
110
|
+
|
|
111
|
+
## 1.5.1 (prepared, not published)
|
|
112
|
+
|
|
113
|
+
### Safe ownership for disposable try state
|
|
114
|
+
|
|
115
|
+
- Stops `try` from recursively deleting a caller-provided `--state-dir`.
|
|
116
|
+
Custom paths are now unowned containers; Runner writes into a marked managed
|
|
117
|
+
child and removes only its known direct state files.
|
|
118
|
+
- Rejects filesystem roots, home/cwd/repository paths and their ancestors,
|
|
119
|
+
parent traversal, symlinked path components, unmarked lookalike directories,
|
|
120
|
+
and managed files replaced by links. Unrelated caller files are preserved.
|
|
121
|
+
- Adds an atomic per-state lease. Concurrent runs fail clearly, while a valid
|
|
122
|
+
lease left by a dead process can recover without broad cleanup.
|
|
123
|
+
- Keeps `demo inspect --state-dir` aligned with the managed-child layout and
|
|
124
|
+
safely adopts only the known legacy default `.synapsor/try` file set.
|
|
125
|
+
- Hardens explicit `--force` replacement for generated schema and MCP-audit
|
|
126
|
+
candidate directories against protected paths, symlinked ancestors, and
|
|
127
|
+
linked or invalid ownership markers.
|
|
128
|
+
- Consistently identifies the embedded `try` source as synthetic.
|
|
129
|
+
- Updates the packaged YAML parser to `2.8.3`, which includes the upstream
|
|
130
|
+
deeply nested collection denial-of-service fix.
|
|
131
|
+
- Corrects the repository's stale publication wording for the live `1.5.0`
|
|
132
|
+
release. Only `@synapsor/runner` is staged at `1.5.1`; Spec, DSL, and Cloud
|
|
133
|
+
CLI versions remain unchanged.
|
|
134
|
+
|
|
135
|
+
## 1.5.0 (2026-07-20)
|
|
4
136
|
|
|
5
137
|
### Complete guarded-action developer proof
|
|
6
138
|
|
|
@@ -31,9 +163,8 @@
|
|
|
31
163
|
- Rewrites the README around the complete `try --prove` outcome, keeps MCP
|
|
32
164
|
audit immediately second, names each isolation boundary precisely, and
|
|
33
165
|
reconciles release documentation with the live npm registry.
|
|
34
|
-
-
|
|
166
|
+
- Published only `@synapsor/runner@1.5.0`; `@synapsor/spec@1.4.2`,
|
|
35
167
|
`@synapsor/dsl@1.4.3`, and `@synapsor/cli@0.1.0-beta.1` remain unchanged.
|
|
36
|
-
Nothing is published by this change.
|
|
37
168
|
|
|
38
169
|
## 1.4.123 (2026-07-17)
|
|
39
170
|
|
package/README.md
CHANGED
|
@@ -4,23 +4,26 @@
|
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
[](https://github.com/Synapsor/Synapsor-Runner/actions/workflows/ci.yml?query=branch%3Amain)
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**Let AI agents change real application data without giving the model SQL.**
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
gives agents reviewed business actions instead of `execute_sql`, saves risky
|
|
11
|
-
changes as proposals, and keeps database credentials, approval, and writeback
|
|
12
|
-
outside the model-facing surface.
|
|
9
|
+
**MCP connects the agent. Synapsor controls the commit.**
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
Synapsor Runner is an open-source MCP runtime for Postgres and MySQL. It gives
|
|
12
|
+
agents reviewed business actions, records proposed changes as exact Data PRs,
|
|
13
|
+
and keeps credentials, activation, approval, and commit authority outside the
|
|
14
|
+
model-facing surface.
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
16
|
+
## Prove The Boundary In Four Seconds
|
|
17
|
+
|
|
18
|
+
No database, Docker, config, MCP client, LLM, or account is required:
|
|
18
19
|
|
|
19
20
|
```bash
|
|
20
21
|
npx -y @synapsor/runner try --prove
|
|
21
22
|
```
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
Timing begins after package resolution; cold `npx` download time varies.
|
|
25
|
+
|
|
26
|
+
The embedded synthetic source requests a $55 waiver and proves:
|
|
24
27
|
|
|
25
28
|
```text
|
|
26
29
|
Proposed effect: late_fee_cents: 5500 -> 0
|
|
@@ -30,11 +33,71 @@ Restart-safe retry: yes; duplicate mutations: 0
|
|
|
30
33
|
Stale apply refused: yes
|
|
31
34
|
```
|
|
32
35
|
|
|
33
|
-
Review happens outside
|
|
34
|
-
|
|
36
|
+
Review happens outside model-facing tools. State is stored under
|
|
37
|
+
`./.synapsor/try/`; this proves the boundary, not your database connection.
|
|
35
38
|
`demo --quick` remains a noninteractive compatibility alias.
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
## Protect One Action In Your Application
|
|
41
|
+
|
|
42
|
+
Start with a staging database and a read-only credential. Runner inspects
|
|
43
|
+
metadata, creates one reviewed read boundary, and opens the secured localhost
|
|
44
|
+
Workbench:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install -g @synapsor/runner
|
|
48
|
+
export DATABASE_URL="postgresql://runner_reader:REPLACE_ME@db.example.com:5432/app?sslmode=require"
|
|
49
|
+
synapsor-runner start --from-env DATABASE_URL --schema public
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Describe one business action. This creates an inert TypeScript draft; it does
|
|
53
|
+
not add a tool or change the active contract:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
synapsor-runner start \
|
|
57
|
+
--action plan_credit \
|
|
58
|
+
--description "Propose one reviewed customer plan credit" \
|
|
59
|
+
--based-on support.inspect_customer
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Add the reviewed tools to the current Cursor project:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
synapsor-runner mcp install cursor --project \
|
|
66
|
+
--config ./synapsor.runner.json \
|
|
67
|
+
--store ./.synapsor/local.db
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
In Cursor, use the Workbench's exact prompt. The checked-in project
|
|
71
|
+
instructions require the coding agent to draft and validate the action while
|
|
72
|
+
leaving effect review and activation to you. Once activated, a request such as
|
|
73
|
+
"give CUS-3001 a $25 plan credit" can only create a semantic proposal:
|
|
74
|
+
|
|
75
|
+
```text
|
|
76
|
+
Data PR wrp_...
|
|
77
|
+
Action support.propose_plan_credit on CUS-3001
|
|
78
|
+
Effect plan_credit_cents: 0 -> 2500
|
|
79
|
+
Source unchanged before approval: Yes
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Review the exact effect in the secured Workbench, select **Approve outside
|
|
83
|
+
MCP**, then run the displayed guarded apply command from a trusted terminal.
|
|
84
|
+
The agent has no approval or commit tool. Runner rechecks scope, policy, row
|
|
85
|
+
version, bounds, and idempotency before returning a receipt; a retry cannot
|
|
86
|
+
duplicate the mutation and a stale proposal conflicts.
|
|
87
|
+
|
|
88
|
+
Inspect the latest lifecycle without copying an id:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
synapsor-runner lifecycle --details --store ./.synapsor/local.db
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
See the [own-database guide](docs/getting-started-own-database.md),
|
|
95
|
+
[Cursor plugin guide](docs/cursor-plugin.md), and
|
|
96
|
+
[store lifecycle guide](docs/store-lifecycle.md) for the complete paths.
|
|
97
|
+
|
|
98
|
+
## Audit An Existing MCP Server
|
|
99
|
+
|
|
100
|
+
Audit a typical raw-SQL MCP server without launching or calling one:
|
|
38
101
|
|
|
39
102
|
```bash
|
|
40
103
|
npx -y @synapsor/runner audit --example dangerous-db-mcp
|
|
@@ -49,9 +112,10 @@ npx -y @synapsor/runner audit ./tools-list.json
|
|
|
49
112
|
It flags raw SQL, arbitrary identifiers, model-controlled authority,
|
|
50
113
|
model-facing approval/writeback, and missing conflict or idempotency signals.
|
|
51
114
|
It does not call business tools. See [MCP Database Risk
|
|
52
|
-
Review](docs/mcp-audit.md) for
|
|
53
|
-
|
|
54
|
-
|
|
115
|
+
Review](docs/mcp-audit.md) for local manifests, selected-server checks, CI,
|
|
116
|
+
SARIF, evidence labels, and limits. You may not need Runner: use the
|
|
117
|
+
[alternatives guide](docs/alternatives.md) to compare direct read-only access,
|
|
118
|
+
hand-built tools, and this reviewed boundary.
|
|
55
119
|
|
|
56
120
|
## Safety Model
|
|
57
121
|
|
|
@@ -96,81 +160,26 @@ not make raw SQL or prompt-injection-prone clients safe.
|
|
|
96
160
|
| `postgres_rls` | PostgreSQL also checks transaction-bound tenant/principal scope. Arbitrary trusted-context or credential control remains outside this guarantee. |
|
|
97
161
|
| `tenant_bound` | Authenticated context selects a restricted per-tenant credential or process. |
|
|
98
162
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
163
|
+
Use stdio; no socket opens. HTTP requires authentication; non-loopback
|
|
164
|
+
listeners require TLS or an explicit trusted TLS proxy. Shared services require
|
|
165
|
+
signed claims. Model-controlled input and MCP session IDs never establish
|
|
166
|
+
identity. See [HTTP MCP].
|
|
167
|
+
MySQL has no native RLS; use restricted views or tenant credentials. See
|
|
168
|
+
[Database scope] and the
|
|
103
169
|
[build-vs-adopt guide](docs/why-synapsor-vs-app-guardrails.md).
|
|
104
170
|
|
|
105
171
|
## Connect A Staging Database
|
|
106
172
|
|
|
107
|
-
|
|
108
|
-
|
|
173
|
+
The setup above stores environment-variable names, not connection strings, and
|
|
174
|
+
never falls back to synthetic data if inspection fails. Keep staging, database
|
|
175
|
+
permissions, restricted views, and RLS underneath Runner. Bind trusted tenant
|
|
176
|
+
and principal values in the launching process, then review the exact field and
|
|
177
|
+
tool surface before connecting Cursor.
|
|
109
178
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
The wizard inspects metadata, generates reviewed capabilities, previews MCP
|
|
117
|
-
tools, and prints smoke/serve commands. It stores environment-variable names,
|
|
118
|
-
not connection strings.
|
|
119
|
-
|
|
120
|
-
[Generate disabled review candidates from Prisma, Drizzle, or
|
|
121
|
-
OpenAPI.](docs/schema-api-candidates.md)
|
|
122
|
-
|
|
123
|
-
The generated capability is a tenant-scoped read with an explicit column
|
|
124
|
-
allowlist and required evidence. See the [own-database
|
|
125
|
-
guide](docs/getting-started-own-database.md) for the full configuration.
|
|
126
|
-
|
|
127
|
-
```json
|
|
128
|
-
{
|
|
129
|
-
"name": "billing.inspect_invoice",
|
|
130
|
-
"kind": "read",
|
|
131
|
-
"source": "app_postgres",
|
|
132
|
-
"target": {
|
|
133
|
-
"schema": "public",
|
|
134
|
-
"table": "invoices",
|
|
135
|
-
"primary_key": "id",
|
|
136
|
-
"tenant_key": "tenant_id"
|
|
137
|
-
},
|
|
138
|
-
"args": {
|
|
139
|
-
"invoice_id": { "type": "string", "required": true, "max_length": 128 }
|
|
140
|
-
},
|
|
141
|
-
"lookup": { "id_from_arg": "invoice_id" },
|
|
142
|
-
"visible_columns": ["id", "tenant_id", "status", "late_fee_cents", "updated_at"],
|
|
143
|
-
"evidence": "required",
|
|
144
|
-
"max_rows": 1
|
|
145
|
-
}
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Set the trusted values in the process that launches Runner, then validate and
|
|
149
|
-
preview the exact model-facing boundary before connecting an MCP client:
|
|
150
|
-
|
|
151
|
-
```bash
|
|
152
|
-
export SYNAPSOR_TENANT_ID="acme"
|
|
153
|
-
export SYNAPSOR_PRINCIPAL="local-developer"
|
|
154
|
-
synapsor-runner config validate --config ./synapsor.runner.json
|
|
155
|
-
synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
|
|
156
|
-
synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
For proposal capabilities and writes, follow the
|
|
160
|
-
[complete own-database guide](docs/getting-started-own-database.md). Reviewed
|
|
161
|
-
single-row INSERT, UPDATE, and DELETE can use Runner's guarded direct
|
|
162
|
-
writeback. Runner also supports tightly [bounded set
|
|
163
|
-
writes](docs/bounded-set-writeback.md): fixed-predicate UPDATE/DELETE and
|
|
164
|
-
exact-review batch INSERT, with human approval, a hard 100-row ceiling, atomic
|
|
165
|
-
apply, and exact receipts. Free-form predicates, unbounded or cross-table work,
|
|
166
|
-
and external effects go through an [app-owned
|
|
167
|
-
executor](docs/writeback-executors.md) after approval.
|
|
168
|
-
|
|
169
|
-
Direct writes can use [reviewed
|
|
170
|
-
compensation](docs/reversible-change-sets.md). Receipts capture a
|
|
171
|
-
bounded inverse; `synapsor-runner revert <proposal_id>` creates a separately
|
|
172
|
-
approved proposal. This is not rollback, time travel, or app-owned
|
|
173
|
-
compensation.
|
|
179
|
+
The [complete own-database guide](docs/getting-started-own-database.md) covers
|
|
180
|
+
validation, scoped reads, disabled Prisma/Drizzle/OpenAPI candidates, guarded
|
|
181
|
+
single-row writes, and app-owned executors. Use the [host compatibility
|
|
182
|
+
matrix](docs/host-compatibility.md) for accurately tested client behavior.
|
|
174
183
|
|
|
175
184
|
## Review And Prove Your Contract
|
|
176
185
|
|
|
@@ -202,18 +211,11 @@ trust boundaries, covered threats, non-goals, and required operator controls.
|
|
|
202
211
|
- MCP proposal, evidence, and replay handles are references rather than bearer
|
|
203
212
|
authority: resource reads re-check the owning tenant and principal against
|
|
204
213
|
the current trusted session.
|
|
205
|
-
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
`test:reversible` run disposable PostgreSQL/MySQL scenarios. They prove no
|
|
211
|
-
pre-approval mutation, guarded single-row CRUD, idempotent retry,
|
|
212
|
-
fail-closed conflicts, bounded atomic sets, exact receipts, and reviewed
|
|
213
|
-
compensation.
|
|
214
|
-
- The C++/Cloud round-trip verifier exports normalized contracts, validates
|
|
215
|
-
them with `@synapsor/spec`, and loads them in Runner. The shared contract and
|
|
216
|
-
verification commands are documented in [Conformance](docs/conformance.md).
|
|
214
|
+
- `test:principal-scope`, `test:live-apply`, `test:guarded-crud`,
|
|
215
|
+
`test:bounded-set`, and `test:reversible` prove cross-principal denial,
|
|
216
|
+
no pre-approval mutation, guarded writes, idempotent retry, conflicts,
|
|
217
|
+
bounded atomic sets, receipts, and reviewed compensation on disposable
|
|
218
|
+
PostgreSQL/MySQL fixtures.
|
|
217
219
|
|
|
218
220
|
Runner is a narrow agent/database safety boundary, not a replacement for
|
|
219
221
|
least-privilege database access, host security, or application authorization.
|
|
@@ -221,15 +223,13 @@ See [Security Boundary](docs/security-boundary.md) and
|
|
|
221
223
|
[Current Limitations](docs/limitations.md).
|
|
222
224
|
|
|
223
225
|
[Database scope]: docs/database-enforced-scope.md
|
|
226
|
+
[HTTP MCP]: docs/http-mcp.md
|
|
224
227
|
|
|
225
228
|
## Operate The Approval Loop
|
|
226
229
|
|
|
227
|
-
Policies combine per-proposal and
|
|
228
|
-
review.
|
|
229
|
-
|
|
230
|
-
claims, asymmetric JWT sessions, and a shared Postgres `runtime_store`.
|
|
231
|
-
`smoke call` follows that store and never falls back to SQLite. Use `/healthz`
|
|
232
|
-
for liveness and `/readyz` for dependency readiness. See
|
|
230
|
+
Policies can combine per-proposal and aggregate ceilings; exceeding one routes
|
|
231
|
+
to human review. Local SQLite is the default, while bounded fleets can use
|
|
232
|
+
verified HTTP claims and a shared Postgres runtime store. See
|
|
233
233
|
[Production](docs/production.md), [Runner Config](docs/runner-config-reference.md),
|
|
234
234
|
and [Small Runner Fleets](docs/running-a-runner-fleet.md).
|
|
235
235
|
|
|
@@ -242,16 +242,11 @@ and [Small Runner Fleets](docs/running-a-runner-fleet.md).
|
|
|
242
242
|
| `@synapsor/dsl` | SQL-like authoring that compiles contexts, capabilities, and workflow declarations into canonical contract JSON. |
|
|
243
243
|
| `@synapsor/cli` | Synapsor Cloud administration, contract governance, human review, Runner connections, and shared audit records. |
|
|
244
244
|
|
|
245
|
-
Runner
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
Use the [DSL Reference](docs/dsl-reference.md) for exact authoring grammar and
|
|
251
|
-
the [Runner Config Reference](docs/runner-config-reference.md) for every wiring
|
|
252
|
-
key, default, and path-resolution rule. The
|
|
253
|
-
[Store Lifecycle guide](docs/store-lifecycle.md) explains ledger sensitivity,
|
|
254
|
-
owner-only permissions, inspection commands, and retention.
|
|
245
|
+
Runner, JSON, `.synapsor.sql`, and the optional TypeScript
|
|
246
|
+
`@synapsor/runner/authoring` frontend all use the same canonical spec. The
|
|
247
|
+
`@synapsor/runner/shadow` helper records app-owned outcomes without granting
|
|
248
|
+
write authority. Start with [Capability Authoring](docs/capability-authoring.md)
|
|
249
|
+
and the [Runner Config Reference](docs/runner-config-reference.md).
|
|
255
250
|
|
|
256
251
|
## OSS And Cloud
|
|
257
252
|
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { type AgentContextSpec, type CapabilitySpec, type PolicySpec, type ResourceSpec, type SynapsorContract, type WorkflowSpec } from "@synapsor/spec";
|
|
2
|
+
export type SynapsorContractDefinition = Omit<SynapsorContract, "spec_version" | "kind">;
|
|
3
|
+
/** Preserve editor inference for a canonical resource definition. */
|
|
4
|
+
export declare function defineResource<const T extends ResourceSpec>(resource: T): T;
|
|
5
|
+
/** Preserve editor inference for trusted context bindings resolved outside model input. */
|
|
6
|
+
export declare function defineAgentContext<const T extends AgentContextSpec>(context: T): T;
|
|
7
|
+
/** Preserve editor inference for a canonical read, aggregate, proposal, or external capability. */
|
|
8
|
+
export declare function defineCapability<const T extends CapabilitySpec>(capability: T): T;
|
|
9
|
+
/** Preserve editor inference for a canonical workflow declaration. */
|
|
10
|
+
export declare function defineWorkflow<const T extends WorkflowSpec>(workflow: T): T;
|
|
11
|
+
/** Preserve editor inference for a canonical policy declaration. */
|
|
12
|
+
export declare function definePolicy<const T extends PolicySpec>(policy: T): T;
|
|
13
|
+
/**
|
|
14
|
+
* Build and validate the same language-neutral contract consumed by the JSON,
|
|
15
|
+
* SQL-like DSL, local Runner, and Cloud registry paths.
|
|
16
|
+
*/
|
|
17
|
+
export declare function defineContract<const T extends SynapsorContractDefinition>(definition: T): SynapsorContract & T;
|
|
18
|
+
/** Validate and normalize a code-first definition into canonical contract JSON shape. */
|
|
19
|
+
export declare function compileContract(definition: SynapsorContractDefinition | SynapsorContract): SynapsorContract;
|
|
20
|
+
/** Serialize normalized canonical JSON for review, version control, or Runner loading. */
|
|
21
|
+
export declare function contractJson(definition: SynapsorContractDefinition | SynapsorContract, indentation?: number): string;
|
|
22
|
+
export type { AgentContextSpec, CapabilitySpec, PolicySpec, ResourceSpec, SynapsorContract, WorkflowSpec, } from "@synapsor/spec";
|
|
23
|
+
//# sourceMappingURL=authoring.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,gBAAgB,EAAE,cAAc,GAAG,MAAM,CAAC,CAAC;AAEzF,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAE3E;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAElF;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,CAEjF;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAE3E;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,0BAA0B,EACvE,UAAU,EAAE,CAAC,GACZ,gBAAgB,GAAG,CAAC,CAQtB;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,UAAU,EAAE,0BAA0B,GAAG,gBAAgB,GAAG,gBAAgB,CAM3G;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAC1B,UAAU,EAAE,0BAA0B,GAAG,gBAAgB,EACzD,WAAW,SAAI,GACd,MAAM,CAKR;AAED,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC"}
|