@synapsor/runner 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/http-mcp.md

@@ -0,0 +1,276 @@
+# HTTP MCP
+
+Use HTTP MCP when an app, server-side agent, container, or Python/Node process
+needs to connect to a long-running Synapsor Runner service.
+
+Use stdio MCP when a local MCP client such as Claude Desktop, Cursor, or a
+local agent tool can launch Synapsor Runner directly.
+
+Synapsor Runner has two HTTP modes:
+
+- `mcp serve-streamable-http`: spec-compatible MCP Streamable HTTP. Use this
+  when an MCP SDK/client expects `initialize`, session IDs, POST/GET/DELETE, and
+  standard HTTP MCP behavior.
+- `mcp serve-http`: a lightweight authenticated JSON-RPC bridge for
+  `tools/list`, `tools/call`, and `resources/read`. Use this when your app wants
+  simple POST calls or an explicit wrapper around Runner tools.
+
+## Start Standard Streamable HTTP MCP
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor-runner mcp serve-streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+For OpenAI Agents SDK, expose OpenAI-safe aliases because OpenAI function names
+cannot contain dots:
+
+```bash
+synapsor-runner mcp serve-streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+Equivalent unified command:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
+```
+
+The model sees aliases such as `billing__inspect_invoice`. MCP tool metadata
+still includes `synapsor.canonical_tool_name`, and Runner maps calls back to
+the canonical Synapsor capability such as `billing.inspect_invoice`. Use
+`--alias-mode both` only during migrations where some clients still need
+canonical dotted names.
+
+Defaults:
+
+```text
+host: 127.0.0.1
+port: 8766
+auth: bearer token required
+cors: disabled
+sessions: in-memory
+```
+
+Use `/mcp` as the MCP endpoint. Health is available at `/healthz`.
+
+## Start The JSON-RPC Bridge
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor-runner mcp serve-http \
+  --host 127.0.0.1 \
+  --port 8765 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+Defaults:
+
+```text
+host: 127.0.0.1
+port: 8765
+auth: bearer token required
+cors: disabled
+```
+
+Bridge scope: `serve-http` does not implement MCP Streamable HTTP
+`initialize`/session behavior. Standard SDK HTTP MCP clients should use
+`serve-streamable-http` instead.
+
+Startup output prints the URL, config path, store path, and token environment
+variable name. It does not print token values or database URLs.
+
+## Health Check
+
+```bash
+curl -i http://127.0.0.1:8766/healthz
+curl -i http://127.0.0.1:8765/healthz
+```
+
+The health endpoint is secret-free:
+
+```json
+{
+  "ok": true,
+  "transport": "streamable-http",
+  "tools": 1,
+  "mode": "read_only"
+}
+```
+
+## List Tools Through The JSON-RPC Bridge
+
+Unauthorized requests fail:
+
+```bash
+curl -i \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  http://127.0.0.1:8765/mcp
+```
+
+Authorized requests include the bearer token:
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  http://127.0.0.1:8765/mcp
+```
+
+The tool catalog should contain semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+```
+
+It should not contain:
+
+```text
+execute_sql
+raw_sql
+approval tools
+commit/apply tools
+database URLs
+write credentials
+model-controlled tenant authority
+arbitrary table or column names
+```
+
+## Call A Tool Through The JSON-RPC Bridge
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "billing.inspect_invoice",
+      "arguments": { "invoice_id": "INV-3001" }
+    }
+  }' \
+  http://127.0.0.1:8765/mcp
+```
+
+The response includes scoped data, trusted context, evidence handles, and
+`source_database_mutated: false`. The agent still does not receive SQL,
+database credentials, or approval/commit authority.
+
+## Read Evidence Or Replay Resources Through The JSON-RPC Bridge
+
+Use `resources/read` with a `synapsor://...` handle returned by a tool call:
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "resources/read",
+    "params": { "uri": "synapsor://evidence/ev_..." }
+  }' \
+  http://127.0.0.1:8765/mcp
+```
+
+## CORS
+
+CORS is disabled by default. If a local browser app needs access during
+development, allow one explicit origin:
+
+```bash
+synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --cors-origin http://localhost:3000
+```
+
+Do not use wildcard CORS for a model-facing database tool service.
+
+## Network Exposure
+
+Synapsor Runner binds to `127.0.0.1` by default.
+
+If you explicitly bind to all interfaces:
+
+```bash
+synapsor-runner mcp serve-http --host 0.0.0.0
+```
+
+the CLI prints a warning. Treat this as a production-like service:
+
+- keep bearer auth enabled;
+- use TLS or a trusted reverse proxy;
+- prefer private networking;
+- add rate limits and request-size limits at the edge;
+- do not log request bodies by default;
+- rotate the bearer token if it is exposed.
+
+`--dev-no-auth` is accepted only on `localhost` or `127.0.0.1`. It fails closed
+with `--host 0.0.0.0`.
+
+## Trusted Context
+
+Tenant and principal values must come from trusted configuration such as
+environment variables or a server-side session. HTTP request arguments cannot
+override trusted fields such as:
+
+```text
+tenant_id
+principal
+principal_id
+project_id
+source_id
+allowed_columns
+approval_identity
+```
+
+Use `read_only` mode first. Proposal/review mode should use a separate trusted
+write path and a separate write credential. The model-facing HTTP MCP endpoint
+must not receive write credentials.
+
+## OpenAI Agents SDK
+
+See:
+
+```text
+examples/openai-agents-http/
+examples/openai-agents-stdio/
+```
+
+Both examples use the MCP client integration from the OpenAI Agents SDK when it
+is available. The stdio example launches Runner as a child process. The HTTP
+example connects to `synapsor-runner mcp serve-streamable-http` through
+`MCPServerStreamableHttp`. Use the JSON-RPC bridge only when you intentionally
+want a small app-owned wrapper instead of standard HTTP MCP.
+
+The boundary is the same in both modes: the agent calls a semantic Synapsor
+tool, not raw SQL. OpenAI-facing examples use `--alias-mode openai` so
+the model sees OpenAI-valid aliases while Runner preserves canonical Synapsor
+tool names in metadata.

package/docs/licensing.md

@@ -0,0 +1,36 @@
+# Licensing
+
+Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
+
+This page is a plain-English summary, not legal advice. If this summary
+conflicts with `../LICENSE`, the `LICENSE` file controls.
+
+Apache-2.0 applies to the code in this runner repository. It grants copyright
+and patent rights under the license terms.
+
+Apache-2.0 does not grant trademark rights. The Synapsor name, Synapsor Runner
+name, logos, hosted Cloud service, and proprietary Synapsor platform features
+remain separate. See `../TRADEMARKS.md`.
+
+This license applies only to `synapsor-runner`. It does not open source:
+
+- Synapsor Cloud;
+- the hosted control plane;
+- hosted capability registry;
+- advanced policy/capability compiler;
+- team approvals, RBAC, or SSO;
+- hosted audit/evidence ledger;
+- managed runners;
+- production writeback orchestration;
+- workflow builder;
+- native Synapsor engine;
+- C++/DBMS internals;
+- branching, time travel, or settlement;
+- compliance exports or production support/SLA.
+
+Synapsor Cloud is a separate hosted commercial service. Use Cloud when your team
+needs shared approvals, RBAC, hosted evidence/replay search, runner fleet
+status, leases, retention, audit visibility, enterprise controls, and support.
+
+Before public release, license and trademark text should be reviewed by the
+release owner or qualified counsel.

package/docs/limitations.md

@@ -0,0 +1,95 @@
+# Limitations
+
+Synapsor Runner is intentionally narrow in the current alpha.
+
+## Supported
+
+- Stdio MCP server for semantic database capabilities.
+- Local read and proposal tools.
+- Local SQLite evidence/proposal/query-audit/replay store.
+- Human approval through CLI commands.
+- Public protocol objects:
+  - `synapsor.change-set.v1`
+  - `synapsor.writeback-job.v1`
+  - `synapsor.execution-receipt.v1`
+  - `synapsor.runner-registration.v1`
+- Guarded single-row `UPDATE` for Postgres and MySQL.
+- App/API handler writeback through approved `http_handler` executors.
+- Local script writeback through approved `command_handler` executors.
+- Primary-key guard.
+- Tenant guard.
+- Allowed-column validation.
+- Version-column or explicit weak row-hash conflict guard.
+- Idempotency receipts.
+- Named local trusted contexts for capability configs.
+- Capability recipes that generate reviewed starter configs.
+- Shadow-mode proposal-vs-human-action comparison.
+- Static MCP database risk review.
+- Local indexed search for proposals, evidence bundles, query audit, writeback
+  receipts, and proposal replay.
+
+## Runtime Contract
+
+Local capabilities are config-defined, not built into the server. The runtime
+does not special-case billing, support, orders, refunds, invoices, or tickets.
+Those domains appear only in demos, smoke tests, and optional recipe JSON files.
+When you connect your own database, `synapsor.runner.json` is the source of
+truth for the model-facing tools.
+
+## Not Supported
+
+- Arbitrary SQL.
+- Model-generated SQL.
+- DDL.
+- INSERT.
+- DELETE.
+- UPSERT.
+- Multi-row UPDATE.
+- Stored procedures.
+- Cross-database transactions.
+- Physical branching of Postgres/MySQL.
+- Full Synapsor workflow/DAG execution.
+- `CREATE AGENT WORKFLOW` or hosted Synapsor SQL generation.
+- Auto-merge or settlement policy semantics.
+- Automatic rollback of external database writes.
+- Model-callable approval or commit tools.
+- Generic MCP firewall behavior.
+- Prompt-injection prevention.
+- High availability, SLA, compliance certification, or production support guarantee.
+
+## Important External Database Semantics
+
+External Postgres/MySQL databases are not branched or merged by Synapsor Runner.
+
+The proposal, evidence, replay, and approval state live in Synapsor Runner locally or in Synapsor Cloud. The external source database changes only when a trusted runner applies an approved writeback job.
+
+Local replay means replay of records captured by the runner:
+
+- trusted context values used by the capability;
+- captured/projected source-row excerpts;
+- query audit fingerprints and redacted parameter metadata;
+- proposal before/proposed diffs;
+- approval/rejection events;
+- guarded writeback jobs;
+- applied/conflict/failed receipts.
+
+It does not mean external Postgres/MySQL time travel. Runner cannot reconstruct
+arbitrary historical rows that were never captured as evidence, and it does not
+provide `AS OF` queries over an external source.
+
+Local search is single-node SQLite search over the local runner store. It is
+useful for local/dev/staging usage. It is not a hosted central evidence ledger,
+not cross-runner aggregation, not RBAC/SSO, and not compliance retention.
+
+Use this wording:
+
+```text
+External DB = Synapsor review state + trusted writeback
+Synapsor-native = real branch + merge
+```
+
+Do not describe external approval as merge.
+
+## Weak Conflict Guards
+
+A version/timestamp column is the preferred conflict guard. A weak row-hash guard can be acknowledged for local/dev use, but it should not be presented as equivalent to a durable version column.