@synapsor/runner 1.4.123 → 1.5.3

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.
Files changed (98) hide show
  1. package/CHANGELOG.md +144 -19
  2. package/README.md +132 -135
  3. package/dist/authoring.d.ts +23 -0
  4. package/dist/authoring.d.ts.map +1 -0
  5. package/dist/authoring.mjs +1318 -0
  6. package/dist/cli.d.ts.map +1 -1
  7. package/dist/cli.js +4 -5
  8. package/dist/local-ui.d.ts +14 -0
  9. package/dist/local-ui.d.ts.map +1 -1
  10. package/dist/runner.mjs +18427 -7084
  11. package/dist/runtime.d.ts +50 -0
  12. package/dist/runtime.d.ts.map +1 -0
  13. package/dist/runtime.mjs +15094 -0
  14. package/dist/shadow.d.ts +36 -0
  15. package/dist/shadow.d.ts.map +1 -0
  16. package/dist/shadow.mjs +5262 -0
  17. package/docs/README.md +44 -5
  18. package/docs/alternatives.md +122 -0
  19. package/docs/capability-authoring.md +44 -1
  20. package/docs/client-recipes.md +218 -0
  21. package/docs/contract-testing.md +9 -7
  22. package/docs/cursor-plugin.md +78 -0
  23. package/docs/database-enforced-scope.md +273 -0
  24. package/docs/dependency-license-inventory.md +6 -2
  25. package/docs/doctor.md +17 -0
  26. package/docs/effect-regression.md +179 -0
  27. package/docs/fresh-developer-usability.md +110 -0
  28. package/docs/getting-started-own-database.md +103 -2
  29. package/docs/host-compatibility.md +59 -0
  30. package/docs/local-mode.md +12 -7
  31. package/docs/mcp-apps.md +188 -0
  32. package/docs/mcp-audit.md +220 -2
  33. package/docs/mcp-client-setup.md +20 -4
  34. package/docs/mcp-clients.md +41 -4
  35. package/docs/oss-vs-cloud.md +3 -0
  36. package/docs/production.md +8 -0
  37. package/docs/release-notes.md +138 -14
  38. package/docs/release-policy.md +9 -5
  39. package/docs/runner-config-reference.md +25 -0
  40. package/docs/schema-api-candidates.md +68 -0
  41. package/docs/security-boundary.md +30 -5
  42. package/docs/shadow-studies.md +241 -0
  43. package/docs/troubleshooting-first-run.md +46 -0
  44. package/examples/mcp-postgres-billing-app-handler/app-handler.mjs +9 -1
  45. package/examples/mcp-postgres-billing-app-handler/schema.sql +11 -0
  46. package/examples/mcp-postgres-billing-app-handler/synapsor-handler.mjs +3 -0
  47. package/examples/raw-sql-vs-synapsor/Makefile +2 -2
  48. package/examples/raw-sql-vs-synapsor/README.md +6 -4
  49. package/examples/support-billing-agent/Makefile +5 -1
  50. package/examples/support-billing-agent/README.md +57 -5
  51. package/examples/support-billing-agent/app/README.md +6 -0
  52. package/examples/support-billing-agent/app/contract.ts +28 -0
  53. package/examples/support-billing-agent/app/effect-adapter.mjs +23 -0
  54. package/examples/support-billing-agent/app/record-shadow-outcomes.mjs +44 -0
  55. package/examples/support-billing-agent/db/schema.sql +88 -1
  56. package/examples/support-billing-agent/db/seed.sql +15 -15
  57. package/examples/support-billing-agent/scripts/run-demo.sh +4 -0
  58. package/examples/support-billing-agent/scripts/run-evaluation.sh +63 -0
  59. package/examples/support-billing-agent/shadow-study/cases.jsonl +6 -0
  60. package/examples/support-billing-agent/shadow-study/outcomes.jsonl +2 -0
  61. package/examples/support-billing-agent/synapsor.runner.json +17 -5
  62. package/examples/support-plan-credit/README.md +48 -2
  63. package/examples/support-plan-credit/mcp-client-examples/README.md +23 -0
  64. package/examples/support-plan-credit/mcp-client-examples/claude-code.sh +34 -0
  65. package/examples/support-plan-credit/mcp-client-examples/codex.config.toml +24 -0
  66. package/examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs +35 -0
  67. package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.mjs +31 -0
  68. package/examples/support-plan-credit/mcp-client-examples/google-adk.py +40 -0
  69. package/examples/support-plan-credit/mcp-client-examples/langchain.mjs +29 -0
  70. package/examples/support-plan-credit/mcp-client-examples/llamaindex.py +36 -0
  71. package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts +1 -1
  72. package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts +1 -1
  73. package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json +20 -0
  74. package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.contract-tests.generated.json +221 -0
  75. package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.ts +34 -0
  76. package/fixtures/effects/changed/eff_support_late_fee_v1.result.json +58 -0
  77. package/fixtures/effects/dataset.json +8 -0
  78. package/fixtures/effects/results/eff_support_late_fee_v1.result.json +59 -0
  79. package/fixtures/effects/support-late-fee.effect.json +71 -0
  80. package/fixtures/generators/drizzle/malicious.ts +11 -0
  81. package/fixtures/generators/drizzle/schema.ts +12 -0
  82. package/fixtures/generators/openapi/external-ref.yaml +15 -0
  83. package/fixtures/generators/openapi/openapi.yaml +81 -0
  84. package/fixtures/generators/prisma/schema.prisma +34 -0
  85. package/fixtures/mcp-audit/README.md +14 -0
  86. package/fixtures/mcp-audit/cursor-bypass-config.json +38 -0
  87. package/fixtures/mcp-audit/dangerous-tools-list.json +33 -0
  88. package/fixtures/mcp-audit/reviewed-proposal-tools-list.json +60 -0
  89. package/package.json +29 -3
  90. package/schemas/effect-dataset.schema.json +19 -0
  91. package/schemas/effect-fixture.schema.json +191 -0
  92. package/schemas/effect-result.schema.json +52 -0
  93. package/schemas/mcp-audit-candidates.schema.json +41 -0
  94. package/schemas/mcp-audit-report.schema.json +203 -0
  95. package/schemas/schema-candidate-review.schema.json +167 -0
  96. package/schemas/schema-candidates.schema.json +49 -0
  97. package/schemas/synapsor.contract-tests.schema.json +1 -1
  98. package/schemas/synapsor.runner.schema.json +51 -0
@@ -0,0 +1,52 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://synapsor.ai/schemas/effect-result.schema.json",
4
+ "title": "Synapsor imported effect result",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schema_version",
9
+ "fixture_id",
10
+ "capability_calls",
11
+ "trusted_context",
12
+ "proposal",
13
+ "observed_fields",
14
+ "evidence",
15
+ "source_database_changed"
16
+ ],
17
+ "properties": {
18
+ "$schema": { "type": "string" },
19
+ "schema_version": { "const": "synapsor.effect-result.v1" },
20
+ "fixture_id": { "type": "string", "minLength": 1, "maxLength": 256 },
21
+ "capability_calls": {
22
+ "type": "array",
23
+ "maxItems": 100,
24
+ "items": {
25
+ "type": "object",
26
+ "additionalProperties": false,
27
+ "required": ["name"],
28
+ "properties": {
29
+ "name": { "type": "string", "minLength": 1, "maxLength": 256 },
30
+ "args": { "type": "object" }
31
+ }
32
+ }
33
+ },
34
+ "trusted_context": { "$ref": "effect-fixture.schema.json#/$defs/trusted_context" },
35
+ "proposal": { "$ref": "effect-fixture.schema.json#/$defs/proposal" },
36
+ "observed_fields": {
37
+ "type": "array",
38
+ "maxItems": 1000,
39
+ "items": { "type": "string", "minLength": 1, "maxLength": 256 }
40
+ },
41
+ "evidence": {
42
+ "type": "object",
43
+ "additionalProperties": false,
44
+ "required": ["mode", "new_source_reads"],
45
+ "properties": {
46
+ "mode": { "enum": ["fixture", "live"] },
47
+ "new_source_reads": { "type": "boolean" }
48
+ }
49
+ },
50
+ "source_database_changed": { "type": "boolean" }
51
+ }
52
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://synapsor.ai/schemas/mcp-audit-candidates.schema.json",
4
+ "title": "Synapsor MCP Audit Candidate Directory Marker",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schema_version",
9
+ "owner",
10
+ "source_digest",
11
+ "activation",
12
+ "deterministic",
13
+ "files"
14
+ ],
15
+ "properties": {
16
+ "schema_version": {
17
+ "const": "synapsor.audit-candidates.v1"
18
+ },
19
+ "owner": {
20
+ "const": "@synapsor/runner"
21
+ },
22
+ "source_digest": {
23
+ "type": "string",
24
+ "pattern": "^sha256:[a-f0-9]{64}$"
25
+ },
26
+ "activation": {
27
+ "const": "blocked_unreviewed"
28
+ },
29
+ "deterministic": {
30
+ "const": true
31
+ },
32
+ "files": {
33
+ "type": "array",
34
+ "minItems": 1,
35
+ "uniqueItems": true,
36
+ "items": {
37
+ "type": "string"
38
+ }
39
+ }
40
+ }
41
+ }
@@ -0,0 +1,203 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://synapsor.ai/schemas/mcp-audit-report.schema.json",
4
+ "title": "Synapsor MCP Audit Report",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schema_version",
9
+ "target",
10
+ "disclaimer",
11
+ "generated_at",
12
+ "summary",
13
+ "authority_map",
14
+ "findings"
15
+ ],
16
+ "properties": {
17
+ "schema_version": {
18
+ "const": "synapsor.mcp-audit.v1"
19
+ },
20
+ "target": {
21
+ "type": "string"
22
+ },
23
+ "disclaimer": {
24
+ "const": "This is a static risk review, not proof that an MCP server is secure."
25
+ },
26
+ "generated_at": {
27
+ "type": "string",
28
+ "format": "date-time"
29
+ },
30
+ "summary": {
31
+ "type": "object",
32
+ "additionalProperties": false,
33
+ "required": [
34
+ "tools_inspected",
35
+ "high",
36
+ "medium",
37
+ "low",
38
+ "total_findings"
39
+ ],
40
+ "properties": {
41
+ "tools_inspected": {
42
+ "type": "integer",
43
+ "minimum": 0
44
+ },
45
+ "high": {
46
+ "type": "integer",
47
+ "minimum": 0
48
+ },
49
+ "medium": {
50
+ "type": "integer",
51
+ "minimum": 0
52
+ },
53
+ "low": {
54
+ "type": "integer",
55
+ "minimum": 0
56
+ },
57
+ "total_findings": {
58
+ "type": "integer",
59
+ "minimum": 0
60
+ }
61
+ }
62
+ },
63
+ "authority_map": {
64
+ "type": "object",
65
+ "additionalProperties": false,
66
+ "required": [
67
+ "items",
68
+ "visibility_limit"
69
+ ],
70
+ "properties": {
71
+ "items": {
72
+ "type": "array",
73
+ "items": {
74
+ "type": "object",
75
+ "additionalProperties": false,
76
+ "required": [
77
+ "authority",
78
+ "label",
79
+ "status",
80
+ "tools",
81
+ "evidence"
82
+ ],
83
+ "properties": {
84
+ "authority": { "type": "string" },
85
+ "label": { "type": "string" },
86
+ "status": {
87
+ "enum": [
88
+ "observed",
89
+ "not_observed",
90
+ "requires_operator_verification",
91
+ "outside_static_audit_visibility"
92
+ ]
93
+ },
94
+ "tools": {
95
+ "type": "array",
96
+ "items": { "type": "string" }
97
+ },
98
+ "evidence": { "type": "string" }
99
+ }
100
+ }
101
+ },
102
+ "visibility_limit": { "type": "string" }
103
+ }
104
+ },
105
+ "bypass_check": {
106
+ "type": "object",
107
+ "additionalProperties": false,
108
+ "required": [
109
+ "mode",
110
+ "servers",
111
+ "direct_bypass_observed",
112
+ "unverified_servers",
113
+ "warning"
114
+ ],
115
+ "properties": {
116
+ "mode": {
117
+ "enum": ["static_config", "selected_live_tools_list"]
118
+ },
119
+ "servers": {
120
+ "type": "array",
121
+ "items": {
122
+ "type": "object",
123
+ "additionalProperties": false,
124
+ "required": [
125
+ "server",
126
+ "status",
127
+ "transport",
128
+ "tools_observed",
129
+ "evidence",
130
+ "remediation"
131
+ ],
132
+ "properties": {
133
+ "server": { "type": "string" },
134
+ "status": {
135
+ "enum": [
136
+ "observed_direct_authority",
137
+ "no_direct_authority_observed",
138
+ "requires_operator_verification"
139
+ ]
140
+ },
141
+ "transport": { "enum": ["stdio", "remote", "unknown"] },
142
+ "tools_observed": {
143
+ "type": "array",
144
+ "items": { "type": "string" }
145
+ },
146
+ "evidence": { "type": "string" },
147
+ "remediation": { "type": "string" }
148
+ }
149
+ }
150
+ },
151
+ "direct_bypass_observed": { "type": "boolean" },
152
+ "unverified_servers": { "type": "integer", "minimum": 0 },
153
+ "warning": { "type": "string" }
154
+ }
155
+ },
156
+ "findings": {
157
+ "type": "array",
158
+ "items": {
159
+ "type": "object",
160
+ "additionalProperties": false,
161
+ "required": [
162
+ "severity",
163
+ "code",
164
+ "message",
165
+ "evidence",
166
+ "recommendation",
167
+ "remediation_url"
168
+ ],
169
+ "properties": {
170
+ "severity": {
171
+ "enum": [
172
+ "HIGH",
173
+ "MEDIUM",
174
+ "LOW"
175
+ ]
176
+ },
177
+ "code": {
178
+ "type": "string"
179
+ },
180
+ "tool": {
181
+ "type": "string"
182
+ },
183
+ "message": {
184
+ "type": "string"
185
+ },
186
+ "evidence": {
187
+ "type": "array",
188
+ "items": {
189
+ "type": "string"
190
+ }
191
+ },
192
+ "recommendation": {
193
+ "type": "string"
194
+ },
195
+ "remediation_url": {
196
+ "type": "string",
197
+ "format": "uri"
198
+ }
199
+ }
200
+ }
201
+ }
202
+ }
203
+ }
@@ -0,0 +1,167 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://synapsor.ai/schemas/schema-candidate-review.schema.json",
4
+ "title": "Synapsor Schema/API Candidate Review",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schema_version",
9
+ "format",
10
+ "source_digest",
11
+ "activation",
12
+ "summary",
13
+ "warnings",
14
+ "objects"
15
+ ],
16
+ "properties": {
17
+ "schema_version": {
18
+ "const": "synapsor.schema-candidates.v1"
19
+ },
20
+ "format": {
21
+ "enum": [
22
+ "prisma",
23
+ "drizzle",
24
+ "openapi"
25
+ ]
26
+ },
27
+ "source_digest": {
28
+ "type": "string",
29
+ "pattern": "^sha256:[a-f0-9]{64}$"
30
+ },
31
+ "activation": {
32
+ "const": "blocked_unreviewed"
33
+ },
34
+ "summary": {
35
+ "type": "object",
36
+ "additionalProperties": false,
37
+ "required": [
38
+ "objects",
39
+ "fields",
40
+ "capabilities",
41
+ "write_candidates"
42
+ ],
43
+ "properties": {
44
+ "objects": {
45
+ "type": "integer",
46
+ "minimum": 0
47
+ },
48
+ "fields": {
49
+ "type": "integer",
50
+ "minimum": 0
51
+ },
52
+ "capabilities": {
53
+ "type": "integer",
54
+ "minimum": 0
55
+ },
56
+ "write_candidates": {
57
+ "type": "integer",
58
+ "minimum": 0
59
+ }
60
+ }
61
+ },
62
+ "warnings": {
63
+ "type": "array",
64
+ "items": {
65
+ "type": "string"
66
+ }
67
+ },
68
+ "objects": {
69
+ "type": "array",
70
+ "items": {
71
+ "type": "object",
72
+ "additionalProperties": false,
73
+ "required": [
74
+ "name",
75
+ "table",
76
+ "structural_primary_key_candidates",
77
+ "potential_tenant_fields",
78
+ "potential_principal_fields",
79
+ "potential_conflict_fields",
80
+ "potentially_sensitive_fields",
81
+ "suggested_kept_out_fields",
82
+ "suggested_visible_fields",
83
+ "possible_actions",
84
+ "uncertain_assumptions",
85
+ "unsupported_or_dynamic"
86
+ ],
87
+ "properties": {
88
+ "name": {
89
+ "type": "string"
90
+ },
91
+ "table": {
92
+ "type": "string"
93
+ },
94
+ "structural_primary_key_candidates": {
95
+ "$ref": "#/$defs/stringArray"
96
+ },
97
+ "potential_tenant_fields": {
98
+ "$ref": "#/$defs/stringArray"
99
+ },
100
+ "potential_principal_fields": {
101
+ "$ref": "#/$defs/stringArray"
102
+ },
103
+ "potential_conflict_fields": {
104
+ "$ref": "#/$defs/stringArray"
105
+ },
106
+ "potentially_sensitive_fields": {
107
+ "$ref": "#/$defs/stringArray"
108
+ },
109
+ "suggested_kept_out_fields": {
110
+ "$ref": "#/$defs/stringArray"
111
+ },
112
+ "suggested_visible_fields": {
113
+ "$ref": "#/$defs/stringArray"
114
+ },
115
+ "possible_actions": {
116
+ "type": "array",
117
+ "items": {
118
+ "type": "object",
119
+ "additionalProperties": false,
120
+ "required": [
121
+ "name",
122
+ "kind",
123
+ "allowed_field_candidates",
124
+ "requires_business_logic",
125
+ "requires_app_owned_handler"
126
+ ],
127
+ "properties": {
128
+ "name": {
129
+ "type": "string"
130
+ },
131
+ "kind": {
132
+ "enum": [
133
+ "read",
134
+ "proposal"
135
+ ]
136
+ },
137
+ "allowed_field_candidates": {
138
+ "$ref": "#/$defs/stringArray"
139
+ },
140
+ "requires_business_logic": {
141
+ "type": "boolean"
142
+ },
143
+ "requires_app_owned_handler": {
144
+ "type": "boolean"
145
+ }
146
+ }
147
+ }
148
+ },
149
+ "uncertain_assumptions": {
150
+ "$ref": "#/$defs/stringArray"
151
+ },
152
+ "unsupported_or_dynamic": {
153
+ "$ref": "#/$defs/stringArray"
154
+ }
155
+ }
156
+ }
157
+ }
158
+ },
159
+ "$defs": {
160
+ "stringArray": {
161
+ "type": "array",
162
+ "items": {
163
+ "type": "string"
164
+ }
165
+ }
166
+ }
167
+ }
@@ -0,0 +1,49 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://synapsor.ai/schemas/schema-candidates.schema.json",
4
+ "title": "Synapsor Schema/API Candidate Directory Marker",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schema_version",
9
+ "owner",
10
+ "format",
11
+ "source_digest",
12
+ "activation",
13
+ "deterministic",
14
+ "files"
15
+ ],
16
+ "properties": {
17
+ "schema_version": {
18
+ "const": "synapsor.schema-candidates.v1"
19
+ },
20
+ "owner": {
21
+ "const": "@synapsor/runner"
22
+ },
23
+ "format": {
24
+ "enum": [
25
+ "prisma",
26
+ "drizzle",
27
+ "openapi"
28
+ ]
29
+ },
30
+ "source_digest": {
31
+ "type": "string",
32
+ "pattern": "^sha256:[a-f0-9]{64}$"
33
+ },
34
+ "activation": {
35
+ "const": "blocked_unreviewed"
36
+ },
37
+ "deterministic": {
38
+ "const": true
39
+ },
40
+ "files": {
41
+ "type": "array",
42
+ "minItems": 1,
43
+ "uniqueItems": true,
44
+ "items": {
45
+ "type": "string"
46
+ }
47
+ }
48
+ }
49
+ }
@@ -19,7 +19,7 @@
19
19
  "properties": {
20
20
  "id": { "type": "string", "minLength": 1 },
21
21
  "kind": {
22
- "enum": ["tool_allow", "tool_deny", "cross_principal_deny", "hide_fields", "argument_constraint", "transition_guard", "set_cap", "source_unchanged_before_approval", "operator_boundary"]
22
+ "enum": ["tool_allow", "tool_deny", "cross_principal_deny", "hide_fields", "argument_constraint", "transition_guard", "set_cap", "proposal_effect", "conflict_guard", "trusted_scope", "evidence_requirement", "approval_boundary", "source_unchanged_before_approval", "operator_boundary"]
23
23
  },
24
24
  "capability": { "type": "string", "minLength": 1 },
25
25
  "args": { "type": "object" },
@@ -394,6 +394,57 @@
394
394
  "queue_limit": { "type": "integer", "minimum": 0, "maximum": 100000 }
395
395
  }
396
396
  },
397
+ "database_scope": {
398
+ "description": "Database-side scope enforcement. application uses Runner predicates; postgres_rls also binds trusted context into transaction-local PostgreSQL settings and requires verified RLS policies.",
399
+ "oneOf": [
400
+ {
401
+ "type": "object",
402
+ "additionalProperties": false,
403
+ "required": ["mode"],
404
+ "properties": {
405
+ "mode": { "const": "application" }
406
+ }
407
+ },
408
+ {
409
+ "type": "object",
410
+ "additionalProperties": false,
411
+ "required": ["mode", "tenant_setting", "principal_setting"],
412
+ "properties": {
413
+ "mode": { "const": "postgres_rls" },
414
+ "tenant_setting": {
415
+ "type": "string",
416
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"
417
+ },
418
+ "principal_setting": {
419
+ "type": "string",
420
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)+$"
421
+ }
422
+ }
423
+ }
424
+ ]
425
+ },
426
+ "credential_scope": {
427
+ "description": "Connection authority. tenant_resolver names an application-supplied resolver; it never embeds credentials.",
428
+ "oneOf": [
429
+ {
430
+ "type": "object",
431
+ "additionalProperties": false,
432
+ "required": ["mode"],
433
+ "properties": {
434
+ "mode": { "const": "shared" }
435
+ }
436
+ },
437
+ {
438
+ "type": "object",
439
+ "additionalProperties": false,
440
+ "required": ["mode", "resolver"],
441
+ "properties": {
442
+ "mode": { "const": "tenant_resolver" },
443
+ "resolver": { "$ref": "#/$defs/identifier" }
444
+ }
445
+ }
446
+ ]
447
+ },
397
448
  "receipts": {
398
449
  "type": "object",
399
450
  "additionalProperties": false,