@synapsor/runner 1.5.0 → 1.5.4

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();
+}

package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.json

@@ -1,5 +1,8 @@
 {
   "name": "synapsor-runner",
   "transport": "streamable-http",
-  "url": "http://127.0.0.1:8766/mcp"
+  "url": "http://127.0.0.1:8766/mcp",
+  "headers_from_env": {
+    "Authorization": "Bearer $SYNAPSOR_RUNNER_HTTP_TOKEN"
+  }
 }

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

@@ -0,0 +1,31 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const token = process.env.SYNAPSOR_RUNNER_HTTP_TOKEN;
+if (!token) throw new Error("set SYNAPSOR_RUNNER_HTTP_TOKEN in the launching environment");
+
+const transport = new StreamableHTTPClientTransport(new URL("http://127.0.0.1:8766/mcp"), {
+  requestInit: { headers: { Authorization: `Bearer ${token}` } },
+});
+const client = new Client({ name: "synapsor-generic-http", 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();
+}

package/examples/support-plan-credit/mcp-client-examples/google-adk.py

@@ -0,0 +1,40 @@
+import os
+
+from google.adk.agents import LlmAgent
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
+from mcp import StdioServerParameters
+
+
+root_agent = LlmAgent(
+    model=os.environ["GOOGLE_ADK_MODEL"],
+    name="synapsor_support_agent",
+    instruction=(
+        "List your Synapsor tools. 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 the model-facing agent."
+    ),
+    tools=[
+        McpToolset(
+            connection_params=StdioConnectionParams(
+                server_params=StdioServerParameters(
+                    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",
+                    ],
+                )
+            ),
+            tool_filter=[
+                "support.inspect_customer",
+                "support.propose_plan_credit",
+            ],
+        )
+    ],
+)
+
+# Run root_agent with your normal ADK runner. Approval, apply, commit,
+# activation, and revert are intentionally not MCP tools.

package/examples/support-plan-credit/mcp-client-examples/langchain.mjs

@@ -0,0 +1,29 @@
+import { MultiServerMCPClient } from "@langchain/mcp-adapters";
+
+const client = new MultiServerMCPClient({
+  synapsor: {
+    transport: "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",
+    ],
+  },
+});
+
+const tools = await client.getTools();
+const names = 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 proposal = tools.find((tool) => tool.name === "support.propose_plan_credit");
+if (!proposal) throw new Error(`proposal tool missing; available: ${names.join(", ")}`);
+
+const result = await proposal.invoke({
+  customer_id: "CUS-3001",
+  credit_cents: 2500,
+  reason: "SLA outage ticket SUP-481",
+});
+console.log(result);
+console.error("Proposal only. Review and apply outside the model-facing LangChain/LangGraph agent.");

package/examples/support-plan-credit/mcp-client-examples/llamaindex.py

@@ -0,0 +1,36 @@
+import asyncio
+
+from llama_index.tools.mcp import BasicMCPClient
+
+
+async def main() -> None:
+    client = BasicMCPClient(
+        "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",
+        ],
+    )
+    tools = await client.list_tools()
+    names = [tool.name for tool in tools.tools]
+    forbidden = [name for name in names if any(part in name.lower() for part in (
+        "sql", "approve", "apply", "commit", "activate", "revert"
+    ))]
+    if forbidden:
+        raise RuntimeError(f"unsafe model-facing tools: {forbidden}")
+
+    result = await client.call_tool(
+        "support.propose_plan_credit",
+        {
+            "customer_id": "CUS-3001",
+            "credit_cents": 2500,
+            "reason": "SLA outage ticket SUP-481",
+        },
+    )
+    print(result)
+    print("Proposal only. Review and apply outside the model-facing LlamaIndex agent.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts

@@ -9,7 +9,7 @@ await synapsor.connect();
 try {
   const agent = new Agent({
     name: "Support operations agent",
-    instructions: "Use only Synapsor business tools. Inspect evidence before proposing a plan credit.",
+    instructions: "Use only the listed Synapsor business tools. Inspect evidence before proposing a plan credit. Never request approval or apply authority; stop for human review outside the agent.",
     mcpServers: [synapsor],
   });
   const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");

package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts

@@ -1,16 +1,20 @@
 import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";
 
 // Start Runner with --alias-mode openai so model-visible tool names are valid OpenAI function names.
+const token = process.env.SYNAPSOR_RUNNER_HTTP_TOKEN;
+if (!token) throw new Error("set SYNAPSOR_RUNNER_HTTP_TOKEN in the launching environment");
+
 const synapsor = new MCPServerStreamableHttp({
   name: "Synapsor Runner",
   url: "http://127.0.0.1:8766/mcp",
+  requestInit: { headers: { Authorization: `Bearer ${token}` } },
 });
 
 await synapsor.connect();
 try {
   const agent = new Agent({
     name: "Support operations agent",
-    instructions: "Use only Synapsor business tools. Inspect evidence before proposing a plan credit.",
+    instructions: "Use only the listed Synapsor business tools. Inspect evidence before proposing a plan credit. Never request approval or apply authority; stop for human review outside the agent.",
     mcpServers: [synapsor],
   });
   const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");

package/examples/support-plan-credit/mcp-client-examples/vscode.mcp.json

@@ -0,0 +1,20 @@
+{
+  "servers": {
+    "synapsor": {
+      "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"
+      ]
+    }
+  }
+}

package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.contract-tests.generated.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "https://schemas.synapsor.ai/synapsor.contract-tests.schema.json",
+  "version": 1,
+  "name": "support.propose_plan_credit generated contract boundary",
+  "tests": [
+    {
+      "id": "support.propose_plan_credit-operator-boundary",
+      "kind": "operator_boundary",
+      "capability": "support.propose_plan_credit"
+    },
+    {
+      "id": "support.propose_plan_credit-proposal-effect",
+      "kind": "proposal_effect",
+      "capability": "support.propose_plan_credit",
+      "expected": {
+        "action": "grant_plan_credit",
+        "operation": {
+          "kind": "update"
+        },
+        "allowed_fields": [
+          "plan_credit_cents",
+          "credit_reason"
+        ],
+        "patch": {
+          "plan_credit_cents": {
+            "from_arg": "credit_cents"
+          },
+          "credit_reason": {
+            "from_arg": "reason"
+          }
+        },
+        "numeric_bounds": {
+          "plan_credit_cents": {
+            "minimum": 1,
+            "maximum": 50000
+          }
+        },
+        "transition_guards": {},
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "approval": {
+          "mode": "policy",
+          "policy": "support_propose_plan_credit_auto_approval",
+          "required_role": "support_reviewer"
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        },
+        "max_rows": 1
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-kept-out-fields",
+      "kind": "hide_fields",
+      "capability": "support.propose_plan_credit",
+      "args": {
+        "customer_id": "replace-customer_id",
+        "credit_cents": 1,
+        "reason": "replace-reason"
+      },
+      "trusted_context": {
+        "tenant_id": "replace-with-test-tenant",
+        "principal": "contract_test"
+      },
+      "fields": [
+        "card_token",
+        "raw_payment_method",
+        "internal_risk_score",
+        "private_notes"
+      ]
+    },
+    {
+      "id": "support.propose_plan_credit-conflict-guard",
+      "kind": "conflict_guard",
+      "capability": "support.propose_plan_credit",
+      "expected": {
+        "column": "updated_at"
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-trusted-scope",
+      "kind": "trusted_scope",
+      "capability": "support.propose_plan_credit",
+      "expected": {
+        "context": "support_agent_context",
+        "tenant_key": "tenant_id",
+        "tenant_binding": "tenant_id",
+        "tenant_authority": {
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID",
+          "required": true
+        },
+        "principal_binding": "principal",
+        "principal_authority": {
+          "source": "environment",
+          "key": "SYNAPSOR_PRINCIPAL",
+          "required": true
+        }
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-evidence-required",
+      "kind": "evidence_requirement",
+      "capability": "support.propose_plan_credit",
+      "expected": {
+        "required": true,
+        "query_audit": true
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-approval-boundary",
+      "kind": "approval_boundary",
+      "capability": "support.propose_plan_credit",
+      "expected": {
+        "approval": {
+          "mode": "policy",
+          "policy": "support_propose_plan_credit_auto_approval",
+          "required_role": "support_reviewer"
+        },
+        "policy": {
+          "kind": "approval",
+          "limits": [
+            {
+              "kind": "count",
+              "max": 20,
+              "period": "day",
+              "scope": "tenant_policy"
+            },
+            {
+              "field": "plan_credit_cents",
+              "kind": "total",
+              "max": 100000,
+              "period": "day",
+              "scope": "tenant_policy"
+            }
+          ],
+          "mode": "green",
+          "name": "support_propose_plan_credit_auto_approval",
+          "rules": [
+            {
+              "field": "plan_credit_cents",
+              "max": 2500
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-allowed-effect",
+      "kind": "tool_allow",
+      "capability": "support.propose_plan_credit",
+      "args": {
+        "customer_id": "replace-customer_id",
+        "credit_cents": 1,
+        "reason": "replace-reason"
+      },
+      "trusted_context": {
+        "tenant_id": "replace-with-test-tenant",
+        "principal": "contract_test"
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-other-tenant-denied",
+      "kind": "tool_deny",
+      "capability": "support.propose_plan_credit",
+      "args": {
+        "customer_id": "replace-with-other-tenant-customer_id",
+        "credit_cents": 1,
+        "reason": "replace-reason"
+      },
+      "trusted_context": {
+        "tenant_id": "replace-with-test-tenant",
+        "principal": "contract_test"
+      },
+      "expected_code": "NOT_FOUND_IN_TENANT"
+    },
+    {
+      "id": "support.propose_plan_credit-source-unchanged",
+      "kind": "source_unchanged_before_approval",
+      "capability": "support.propose_plan_credit",
+      "args": {
+        "customer_id": "replace-customer_id",
+        "credit_cents": 1,
+        "reason": "replace-reason"
+      },
+      "trusted_context": {
+        "tenant_id": "replace-with-test-tenant",
+        "principal": "contract_test"
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-customer_id-constraints",
+      "kind": "argument_constraint",
+      "capability": "support.propose_plan_credit",
+      "argument": "customer_id",
+      "expected": {
+        "max_length": 128
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-credit_cents-constraints",
+      "kind": "argument_constraint",
+      "capability": "support.propose_plan_credit",
+      "argument": "credit_cents",
+      "expected": {
+        "minimum": 1,
+        "maximum": 50000
+      }
+    },
+    {
+      "id": "support.propose_plan_credit-reason-constraints",
+      "kind": "argument_constraint",
+      "capability": "support.propose_plan_credit",
+      "argument": "reason",
+      "expected": {
+        "max_length": 500
+      }
+    }
+  ]
+}

package/examples/support-plan-credit/synapsor/actions/support.propose_plan_credit.ts

@@ -0,0 +1,34 @@
+import { defineCapability } from "@synapsor/runner/authoring";
+
+// Disabled authoring source. Editing this file never changes active Runner tools.
+export default defineCapability({
+  name: "support.propose_plan_credit",
+  description: "Propose one bounded support plan credit after reviewing customer evidence.",
+  kind: "proposal",
+  context: "support_agent_context",
+  source: "local_postgres",
+  subject: {
+    schema: "public", table: "customers", primary_key: "id",
+    tenant_key: "tenant_id", conflict_key: "updated_at",
+  },
+  args: {
+    customer_id: { type: "string", required: true, max_length: 128 },
+    credit_cents: { type: "number", required: true, minimum: 1, maximum: 50000 },
+    reason: { type: "string", required: true, max_length: 500 },
+  },
+  lookup: { id_from_arg: "customer_id" },
+  visible_fields: ["id", "tenant_id", "customer_id", "plan", "invoice_status", "support_ticket_reason", "plan_credit_cents", "credit_reason", "updated_at"],
+  kept_out_fields: ["card_token", "raw_payment_method", "internal_risk_score", "private_notes"],
+  evidence: { required: true, query_audit: true },
+  max_rows: 1,
+  proposal: {
+    action: "grant_plan_credit",
+    operation: { kind: "update" },
+    allowed_fields: ["plan_credit_cents", "credit_reason"],
+    patch: { plan_credit_cents: { from_arg: "credit_cents" }, credit_reason: { from_arg: "reason" } },
+    numeric_bounds: { plan_credit_cents: { minimum: 1, maximum: 50000 } },
+    conflict_guard: { column: "updated_at" },
+    approval: { mode: "policy", policy: "support_propose_plan_credit_auto_approval", required_role: "support_reviewer" },
+    writeback: { mode: "direct_sql" },
+  },
+});

package/examples/support-plan-credit/synapsor.contract.json

@@ -182,9 +182,6 @@
           "mode": "human",
           "required_role": "support_reviewer"
         },
-        "conflict_guard": {
-          "weak_guard_ack": true
-        },
         "numeric_bounds": {
           "amount_cents": {
             "maximum": 50000,

package/fixtures/mcp-audit/README.md

@@ -0,0 +1,14 @@
+# MCP audit fixtures
+
+These deterministic fixtures exercise the public `synapsor-runner audit`
+contract without a database, account, telemetry, or business-tool call.
+
+- `dangerous-tools-list.json` contains raw SQL and model-callable commit
+  authority.
+- `reviewed-proposal-tools-list.json` contains a semantic read and an exact
+  proposal boundary.
+- `cursor-bypass-config.json` proves that a reviewed Synapsor server does not
+  govern a second model-visible server that still exposes `execute_sql`.
+
+Static config auditing never launches either command in the Cursor fixture.
+Live inspection requires one exact `--live-server` name and explicit `--yes`.

package/fixtures/mcp-audit/cursor-bypass-config.json

@@ -0,0 +1,38 @@
+{
+  "mcpServers": {
+    "synapsor": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner@1.5.3",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "${workspaceFolder}/synapsor.runner.json",
+        "--store",
+        "${workspaceFolder}/.synapsor/local.db"
+      ]
+    },
+    "legacy-database": {
+      "type": "stdio",
+      "command": "legacy-database-mcp",
+      "args": [],
+      "tools": [
+        {
+          "name": "execute_sql",
+          "description": "Execute arbitrary SQL.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "sql": { "type": "string" }
+            },
+            "required": ["sql"]
+          }
+        }
+      ]
+    }
+  }
+}