@synapsor/runner 0.1.0-alpha.4 → 0.1.0-alpha.5

package/docs/README.md

@@ -1,56 +1,34 @@
 # Synapsor Runner Docs
 
-Start with the practical paths, not the internals.
-
-## Try The Local Trust Loop
-
-```bash
-./scripts/try-synapsor.sh
-```
-
-This runs disposable Postgres/MySQL fixtures and proves the core loop:
-
-```text
-MCP tool call
--> trusted context
--> scoped read
--> evidence
--> proposal diff
--> approval outside MCP
--> guarded commit or stale-row conflict
--> receipt/replay
-```
-
-Read: [First 10 Minutes](first-10-minutes.md).
-
-## Use Your Own Staging Postgres/MySQL
-
-```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-./scripts/use-your-db.sh
-```
-
-This inspects your schema, opens the guided setup, generates
-`synapsor.runner.json`, previews the semantic MCP tools, and prints the
-`mcp serve` and local UI commands.
-
-For disposable dev RDS databases with local CA issues:
-
-```bash
-./scripts/use-your-db.sh --allow-insecure-ssl
-```
-
-Use certificate verification with the database CA bundle for real staging or
-production-like databases.
-
-Read: [Connect Your Own Database](getting-started-own-database.md).
-
-## Important References
-
-- [Schema Inspection](schema-inspection.md)
-- [MCP Client Setup](mcp-client-setup.md)
-- [Capability Config](capability-config.md)
-- [Local UI](local-ui.md)
-- [Writeback Executors](writeback-executors.md)
-- [Security Boundary](security-boundary.md)
-- [Current Scope And Limitations](limitations.md)
+Start with the README. Use these docs only when you need the next level of
+detail.
+
+## First Setup
+
+- [Connect Your Own Database](getting-started-own-database.md): inspect a
+  staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
+  semantic tools, and serve them over MCP.
+- [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
+  another stdio MCP client.
+- [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
+  service for app/server agents.
+
+## Safety And Operations
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [Current Limitations](limitations.md): current alpha scope.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
+  failures and fixes.
+- [Local Mode](local-mode.md): local store, proposals, approval, replay, and
+  writeback flow.
+
+## Features
+
+- [MCP Audit](mcp-audit.md): static risk review for database MCP tools.
+- [Recipes](recipes.md): starter business-capability templates.
+- [Writeback Executors](writeback-executors.md): app-owned writeback handlers
+  for approved proposals.
+
+The public docs intentionally stay small. Historical implementation reports,
+release checklists, and internal planning notes are not part of the public
+getting-started path.

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

@@ -7,6 +7,11 @@ Do not start with your most sensitive production database. The current alpha
 runner is a local commit-safety runtime for reviewed single-row business
 actions, not a production certification.
 
+If you only ran `synapsor demo --quick`, you have tested the fixture-only
+teaching path and local ledger commands. This page is the real own-database
+path: it inspects your Postgres/MySQL metadata and generates reviewed semantic
+tools from your selections.
+
 ## Fast path
 
 Set one read-only database URL and run the wrapper from this repo:
@@ -128,10 +133,17 @@ In an interactive terminal, run the guided wizard:
 npx -y -p @synapsor/runner@alpha synapsor init --from-env DATABASE_URL --mode read_only --wizard
 ```
 
-The generated capabilities are based on your selections. Synapsor Runner does
-not force billing, support, order, or any other built-in domain. You choose the
-namespace, object name, lookup argument, visible fields, proposal fields, guards,
-and approval role.
+The generated context and capabilities are based on your selections. Synapsor
+Runner does not force billing, support, order, or any other built-in domain.
+The local shape is:
+
+```text
+trusted context -> capability -> MCP tool
+```
+
+You choose the source object, trusted tenant/principal bindings, namespace,
+object name, lookup argument, visible fields, proposal fields, guards, and
+approval role.
 
 Start with `read_only` to prove safe database reads first. Use `--mode review`
 when you are ready to create proposal tools and guarded writeback setup.
@@ -141,9 +153,10 @@ The wizard:
 - asks for the engine and read URL environment-variable name;
 - tests read connectivity through schema inspection;
 - lists discovered schemas and tables/views;
-- asks you to confirm primary key, tenant/scope column, conflict/version
-  column, visible columns, mode, semantic names, trusted context env vars, and
-  proposal patch mappings;
+- asks which source object backs the local context;
+- asks which tenant/scope column and backend session env vars are trusted;
+- asks you to confirm primary key, conflict/version column, visible columns,
+  mode, semantic capability names, and proposal patch mappings;
 - previews the MCP tools and what is not exposed;
 - writes the generated config, `.env.example`, and MCP client snippets only
   after final confirmation.
@@ -302,12 +315,31 @@ npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json -
 
 ## 8. Serve semantic MCP tools
 
+Use stdio when a local MCP client can launch Synapsor Runner:
+
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
 npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
+Use HTTP when an app/server agent connects to a long-running Runner process:
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+HTTP defaults to `127.0.0.1:8765` and requires bearer auth by default. Use
+private networking/TLS before exposing it beyond localhost. See
+[HTTP MCP](http-mcp.md).
+
 The model-facing MCP server exposes semantic tools such as:
 
 ```text
@@ -349,7 +381,7 @@ payload, not arbitrary model SQL:
 npx -y -p @synapsor/runner@alpha synapsor apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
-See `docs/writeback-executors.md`.
+See [Writeback Executors](writeback-executors.md).
 
 Replay afterward:
 

package/docs/http-mcp.md

@@ -0,0 +1,200 @@
+# 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.
+
+## Start The HTTP Server
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor 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
+```
+
+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:8765/healthz
+```
+
+The health endpoint is secret-free:
+
+```json
+{
+  "ok": true,
+  "transport": "http",
+  "tools": 1,
+  "mode": "read_only"
+}
+```
+
+## List Tools
+
+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
+
+```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
+
+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 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 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/
+```
+
+The stdio example uses the MCP client integration from the OpenAI Agents SDK
+when available. The HTTP example uses a minimal JSON-RPC client wrapped as an
+OpenAI function tool because native HTTP MCP client support can vary by SDK
+version. The boundary is the same: the agent calls a semantic Synapsor tool,
+not raw SQL.

package/docs/local-mode.md

@@ -9,6 +9,14 @@ Command model:
 - From a source checkout, use `./bin/synapsor <command>` if the global binary is
   not linked yet.
 
+`synapsor demo --quick` creates a fixture ledger for learning and CLI
+verification. In a terminal it walks through the safety model step by step; in
+CI or piped output it prints a short summary and exits without waiting for
+Enter. It does not read or write external Postgres/MySQL. Local mode with
+`synapsor mcp serve`, `synapsor demo`, or an own generated config is the real
+Postgres/MySQL path. Use `synapsor demo inspect` to print the follow-up
+commands for the quick-demo fixture.
+
 Current local-mode foundation:
 
 - strict JSON capability config validation in `packages/config`;
@@ -17,6 +25,7 @@ Current local-mode foundation:
 - local localhost proposal review UI through `synapsor ui`;
 - static MCP database risk review with `synapsor audit`;
 - local stdio MCP server with semantic read/proposal tools;
+- authenticated HTTP MCP server for app/server agents;
 - MCP resource reads for `synapsor://proposals/*`, `synapsor://evidence/*`, and `synapsor://replay/*`;
 - local approved proposal to `synapsor.writeback-job.v1` job generation;
 - guarded Postgres/MySQL writeback adapters for approved structured jobs.
@@ -29,10 +38,6 @@ engine requirement and the CLI exits early with a clear message on older Node
 versions. The Docker-backed demo remains the recommended path when you do not
 want to change your host Node version.
 
-Commands in this page that use local ledger search/export or `synapsor store`
-require this checkout or package version `0.1.0-alpha.4` or newer while npm
-`@alpha` still points to an older alpha.
-
 ## Initialize a config
 
 Create a starter config without putting credentials in the file:
@@ -65,6 +70,31 @@ npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
 read/write credential separation, metadata visibility for configured targets,
 and the semantic MCP tool boundary without printing credential values.
 
+## Stdio Vs HTTP MCP
+
+Use stdio for local MCP clients that launch Synapsor Runner:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Use HTTP when your app/server agent connects to a long-running Runner process:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+HTTP defaults to `127.0.0.1:8765`, requires bearer auth by default, and should
+run behind private networking/TLS before production-like exposure. Details:
+[HTTP MCP](http-mcp.md).
+
 ## Local safety modes
 
 The local runner modes are intentionally narrow:
@@ -191,6 +221,8 @@ npx -y -p @synapsor/runner@alpha synapsor replay export --proposal wrp_123 \
 ```
 
 Replay records include proposal metadata, before/after diff, events, writeback receipts, evidence summaries, and query audit rows currently stored for the proposal.
+Human output is concise by default. Use `--details` for reviewer metadata or
+`--json` for complete machine-readable records.
 
 ## Local evidence, query audit, and receipts
 
@@ -215,6 +247,10 @@ synapsor receipts list --proposal wrp_123 --store ./.synapsor/local.db
 synapsor receipts show <receipt_id> --store ./.synapsor/local.db
 ```
 
+Default inspection output is intentionally short. Add `--details` when you need
+target URIs, primary keys, proposal hash/version, conflict guards, query
+fingerprints, event timestamps, or receipt internals.
+
 Read-only MCP tools record evidence bundles and query-audit rows and return an
 evidence handle. Use `evidence show`, `evidence list`, and `query-audit list`
 to inspect those captured rows and fingerprints later without rerunning the

package/docs/mcp-audit.md

@@ -26,10 +26,6 @@ Built-in database MCP risk example:
 npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
 ```
 
-Markdown output requires this checkout or package version `0.1.0-alpha.4` or
-newer. Check `npm view @synapsor/runner@alpha version` before promoting npm
-snippets publicly.
-
 This bundled example does not require a source checkout or local examples file.
 It audits a deliberately risky database MCP shape with `execute_sql`,
 `run_query`, model-callable approval/update/delete tools, arbitrary

package/docs/mcp-client-setup.md

@@ -6,7 +6,10 @@ The primary local proof path is still the one-command Docker demo:
 ./scripts/demo-docker.sh
 ```
 
-Use this page after that demo passes and you want to attach a local MCP client. The tested integration contract here is stdio. Client-specific UIs change, so the checked-in examples verify config shape and `tools/list`, not every client screen.
+Use this page after that demo passes and you want to attach a local MCP client.
+The tested local-client contract here is stdio. HTTP MCP is available for
+app/server deployments where your agent connects to a long-running Runner
+service.
 
 Command examples use the published alpha package through `npx`. From a source
 checkout, use `./bin/synapsor ...` only when you intentionally want the local
@@ -24,6 +27,31 @@ Validate them with:
 corepack pnpm test:mcp-client-configs
 ```
 
+## Stdio Vs HTTP MCP
+
+| Mode | Use when | Command |
+| --- | --- | --- |
+| stdio | Claude Desktop, Cursor, VS Code, or another local MCP client can launch Synapsor Runner | `synapsor mcp serve` |
+| HTTP | Your app/server, Python agent, Node service, or container connects to a long-running Runner service | `synapsor mcp serve-http` |
+
+Stdio keeps the MCP protocol on process stdin/stdout and is the simplest local
+developer path. HTTP uses JSON-RPC over an authenticated `/mcp` endpoint and is
+better for app/server deployments.
+
+HTTP requires bearer auth by default:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
+[HTTP MCP](http-mcp.md).
+
 ## Generate A Client Snippet
 
 Print a snippet without modifying any client files:
@@ -77,6 +105,17 @@ npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./examples/mcp-post
 
 For the alpha package, keep the package tag explicit in client configuration.
 
+For app/server HTTP mode:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
 ## Generic stdio Client
 
 ```json

package/examples/openai-agents-http/README.md

@@ -0,0 +1,55 @@
+# OpenAI Agents SDK + Synapsor Runner over HTTP
+
+This example shows an OpenAI Agents SDK app calling a long-running Synapsor
+Runner HTTP MCP service.
+
+Use HTTP when your agent runs as an app/server and should connect to Runner
+over a local/private network endpoint instead of launching a stdio child
+process.
+
+Native HTTP MCP client support can vary by SDK version. This example is honest
+about that: it uses the OpenAI Agents SDK for the agent and wraps Synapsor's
+HTTP MCP JSON-RPC endpoint as an OpenAI function tool.
+
+The model still sees a semantic action. It does not receive raw SQL, database
+URLs, write credentials, approval tools, or commit tools.
+
+## Terminal 1: Start Synapsor Runner HTTP MCP
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="openai_agent_demo"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+
+npx -y -p @synapsor/runner@alpha synapsor mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+## Terminal 2: Run The Agent
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+
+export OPENAI_API_KEY="..."
+export SYNAPSOR_RUNNER_HTTP_URL="http://127.0.0.1:8765/mcp"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+export SYNAPSOR_INVOICE_ID="INV-3001"
+
+python agent.py
+```
+
+Expected behavior:
+
+- the agent calls `billing.inspect_invoice` through Synapsor HTTP MCP;
+- Synapsor applies trusted tenant/principal context from the server process;
+- the response includes scoped data and evidence handles;
+- no SQL/write/approval tool is exposed to the model;
+- evidence/query audit are saved in the local Runner store.
+
+For production-like deployment, keep HTTP MCP behind private networking/TLS,
+bearer auth, and rate limits. See [HTTP MCP](../../docs/http-mcp.md).

package/examples/openai-agents-http/agent.py

@@ -0,0 +1,90 @@
+import asyncio
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+try:
+    from agents import Agent, Runner, function_tool
+except ImportError as exc:
+    raise SystemExit(
+        "This example requires the OpenAI Agents SDK. "
+        "Install with: pip install -r requirements.txt"
+    ) from exc
+
+
+def call_synapsor_http_mcp(method: str, params: dict) -> dict:
+    url = os.environ.get("SYNAPSOR_RUNNER_HTTP_URL", "http://127.0.0.1:8765/mcp")
+    token = os.environ.get("SYNAPSOR_RUNNER_HTTP_TOKEN")
+    if not token:
+        raise RuntimeError("SYNAPSOR_RUNNER_HTTP_TOKEN is not set")
+
+    payload = json.dumps({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": method,
+        "params": params,
+    }).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "authorization": f"Bearer {token}",
+            "content-type": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8")
+        raise RuntimeError(f"Synapsor HTTP MCP returned HTTP {exc.code}: {body}") from exc
+
+    parsed = json.loads(body)
+    if "error" in parsed:
+        raise RuntimeError(f"Synapsor HTTP MCP error: {parsed['error']}")
+    return parsed["result"]
+
+
+@function_tool
+def billing_inspect_invoice(invoice_id: str) -> str:
+    """Inspect one scoped invoice through Synapsor Runner HTTP MCP."""
+    result = call_synapsor_http_mcp("tools/call", {
+        "name": "billing.inspect_invoice",
+        "arguments": {"invoice_id": invoice_id},
+    })
+    return json.dumps(result.get("structuredContent", result), indent=2)
+
+
+async def main() -> None:
+    required = ["OPENAI_API_KEY", "SYNAPSOR_RUNNER_HTTP_URL", "SYNAPSOR_RUNNER_HTTP_TOKEN"]
+    missing = [name for name in required if not os.environ.get(name)]
+    if missing:
+        raise SystemExit(f"Missing required environment variables: {', '.join(missing)}")
+
+    invoice_id = os.environ.get("SYNAPSOR_INVOICE_ID", "INV-3001")
+    agent = Agent(
+        name="Synapsor HTTP MCP demo agent",
+        instructions=(
+            "Use the billing_inspect_invoice tool to inspect scoped invoice data. "
+            "Do not claim that you can run SQL, approve proposals, or commit writes."
+        ),
+        tools=[billing_inspect_invoice],
+    )
+    result = await Runner.run(
+        agent,
+        (
+            f"Inspect invoice {invoice_id} using Synapsor. "
+            "Explain what you saw and whether you have write authority."
+        ),
+    )
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.exit(130)

package/examples/openai-agents-http/requirements.txt

@@ -0,0 +1 @@
+openai-agents>=0.1.0