@synapsor/runner 0.1.9 → 0.1.11

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

@@ -0,0 +1,59 @@
+CREATE AGENT CONTEXT support_agent_context
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY support.inspect_customer
+  DESCRIPTION 'Inspect one support customer in the trusted tenant before proposing a plan credit.'
+  RETURNS HINT 'Returns reviewed customer fields plus evidence/query-audit handles.'
+  USING CONTEXT support_agent_context
+  SOURCE local_postgres
+  ON public.customers
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP customer_id BY id
+  ARG customer_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Customer id such as CUS-3001.'
+  ALLOW READ id, tenant_id, customer_id, plan, invoice_status, support_ticket_reason, plan_credit_cents, credit_reason, updated_at
+  KEEP OUT card_token, raw_payment_method, internal_risk_score, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY support.propose_plan_credit
+  DESCRIPTION 'Propose a bounded support plan credit after inspecting customer and ticket evidence.'
+  RETURNS HINT 'Returns a proposal id, exact diff, evidence handle, and source_database_changed:false. Policy may approve small credits, but writeback is still separate.'
+  USING CONTEXT support_agent_context
+  SOURCE local_postgres
+  ON public.customers
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP customer_id BY id
+  ARG customer_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Customer id such as CUS-3001.'
+  ARG credit_cents NUMBER REQUIRED MIN 1 DESCRIPTION 'Requested plan credit in cents.'
+  ARG reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason tied to support evidence.'
+  ALLOW READ id, tenant_id, customer_id, plan, invoice_status, support_ticket_reason, plan_credit_cents, credit_reason, updated_at
+  KEEP OUT card_token, raw_payment_method, internal_risk_score, private_notes
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION grant_plan_credit
+  ALLOW WRITE plan_credit_cents, credit_reason
+  PATCH plan_credit_cents = ARG credit_cents
+  PATCH credit_reason = ARG reason
+  BOUND plan_credit_cents 1..50000
+  APPROVAL ROLE support_reviewer
+  AUTO APPROVE WHEN plan_credit_cents <= 2500
+  WRITEBACK DIRECT SQL
+END
+
+CREATE AGENT WORKFLOW support.plan_credit_request
+  USING CONTEXT support_agent_context
+  ALLOW CAPABILITY support.inspect_customer
+  ALLOW CAPABILITY support.propose_plan_credit
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE support_reviewer
+  CHECKPOINT PROPOSAL ONLY
+END

package/examples/support-plan-credit/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: synapsor_runner_plan_credit
+    environment:
+      POSTGRES_DB: synapsor_runner_plan_credit
+      POSTGRES_USER: synapsor_admin
+      POSTGRES_PASSWORD: synapsor_admin_password
+    ports:
+      - "55438:5432"
+    volumes:
+      - ./seed:/docker-entrypoint-initdb.d:ro

package/examples/support-plan-credit/expected-output/cloud-push-response.json

@@ -0,0 +1,9 @@
+{
+  "ok": true,
+  "contract_id": "act_support_plan_credit_example",
+  "contract_version_id": "act_support_plan_credit_example_v1",
+  "version_number": 1,
+  "status": "draft",
+  "digest": "sha256:<server-computed-digest>",
+  "registry_url": "/workspace/contracts?contract=<contract_id>"
+}

package/examples/support-plan-credit/expected-output/proposal-created.json

@@ -0,0 +1,23 @@
+{
+  "proposal_id": "wrp_example_low_risk_credit",
+  "capability": "support.propose_plan_credit",
+  "status": "approved",
+  "approval_actor": "policy:support_propose_plan_credit_auto_approval",
+  "target": {
+    "table": "customers",
+    "id": "CUS-3001",
+    "tenant_id": "acme"
+  },
+  "change_set": {
+    "plan_credit_cents": {
+      "before": 0,
+      "after": 2500
+    },
+    "credit_reason": {
+      "before": null,
+      "after": "SLA outage ticket SUP-481"
+    }
+  },
+  "source_database_changed": false,
+  "evidence_handle": "evidence://local/example-plan-credit"
+}

package/examples/support-plan-credit/expected-output/receipt.json

@@ -0,0 +1,13 @@
+{
+  "receipt_id": "rct_example_plan_credit",
+  "proposal_id": "wrp_example_low_risk_credit",
+  "status": "applied",
+  "rows_affected": 1,
+  "guards": {
+    "tenant": "passed",
+    "primary_key": "passed",
+    "allowed_columns": "passed",
+    "expected_version": "passed",
+    "idempotency": "passed"
+  }
+}

package/examples/support-plan-credit/expected-output/replay-summary.json

@@ -0,0 +1,13 @@
+{
+  "proposal_id": "wrp_example_low_risk_credit",
+  "events": [
+    "scoped_read",
+    "evidence_saved",
+    "proposal_created",
+    "policy_approved",
+    "guarded_writeback_applied",
+    "receipt_recorded"
+  ],
+  "source_database_changed_before_approval": false,
+  "final_status": "applied"
+}

package/examples/support-plan-credit/expected-output/tools-preview.txt

@@ -0,0 +1,15 @@
+Synapsor tools preview: ok
+
+Exposed to MCP:
+  - support.inspect_customer
+  - support.propose_plan_credit
+
+Not exposed to MCP:
+  - execute_sql / raw query tools
+  - approval tools
+  - commit/apply tools
+  - database URLs
+  - write credentials
+  - model-controlled tenant authority
+
+auto-approval: enabled

package/examples/support-plan-credit/mcp-client-examples/claude-desktop.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "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"
+      ],
+      "cwd": "<absolute-path-to-Synapsor-Runner>"
+    }
+  }
+}

package/examples/support-plan-credit/mcp-client-examples/cursor-global.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "<absolute-path-to-Synapsor-Runner>/examples/support-plan-credit/synapsor.runner.json",
+        "--store",
+        "<absolute-path-to-Synapsor-Runner>/tmp/support-plan-credit/local.db"
+      ]
+    }
+  }
+}

package/examples/support-plan-credit/mcp-client-examples/cursor-project.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "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/mcp-client-examples/generic-stdio.json

@@ -0,0 +1,17 @@
+{
+  "name": "synapsor-runner",
+  "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"
+  ]
+}

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

@@ -0,0 +1,5 @@
+{
+  "name": "synapsor-runner",
+  "transport": "streamable-http",
+  "url": "http://127.0.0.1:8766/mcp"
+}

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

@@ -0,0 +1,19 @@
+import { Agent, MCPServerStdio, run } from "@openai/agents";
+
+const synapsor = new MCPServerStdio({
+  name: "Synapsor Runner",
+  fullCommand: "npx -y -p @synapsor/runner synapsor-runner mcp serve --config examples/support-plan-credit/synapsor.runner.json --store ./tmp/support-plan-credit/local.db --alias-mode openai",
+});
+
+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.",
+    mcpServers: [synapsor],
+  });
+  const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");
+  console.log(result.finalOutput);
+} finally {
+  await synapsor.close();
+}

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

@@ -0,0 +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 synapsor = new MCPServerStreamableHttp({
+  name: "Synapsor Runner",
+  url: "http://127.0.0.1:8766/mcp",
+});
+
+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.",
+    mcpServers: [synapsor],
+  });
+  const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");
+  console.log(result.finalOutput);
+} finally {
+  await synapsor.close();
+}

package/examples/support-plan-credit/seed/001_seed.sql

@@ -0,0 +1,92 @@
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL,
+  customer_id text NOT NULL,
+  plan text NOT NULL,
+  invoice_status text NOT NULL,
+  support_ticket_reason text NOT NULL,
+  plan_credit_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  card_token text,
+  raw_payment_method text,
+  internal_risk_score integer,
+  private_notes text
+);
+
+INSERT INTO public.customers (
+  id,
+  tenant_id,
+  customer_id,
+  plan,
+  invoice_status,
+  support_ticket_reason,
+  plan_credit_cents,
+  credit_reason,
+  updated_at,
+  card_token,
+  raw_payment_method,
+  internal_risk_score,
+  private_notes
+)
+VALUES
+  (
+    'CUS-3001',
+    'acme',
+    'CUS-3001',
+    'enterprise',
+    'open_dispute',
+    'SLA outage ticket SUP-481 confirmed by support lead',
+    0,
+    NULL,
+    '2026-06-20T14:31:08Z',
+    'tok_fake_acme_3001',
+    'fake_visa_4242',
+    12,
+    'fake internal note: do not expose'
+  ),
+  (
+    'CUS-9001',
+    'otherco',
+    'CUS-9001',
+    'starter',
+    'paid',
+    'OtherCo tenant row for spoof checks',
+    0,
+    NULL,
+    '2026-06-20T14:31:08Z',
+    'tok_fake_otherco_9001',
+    'fake_mastercard_4444',
+    77,
+    'fake other tenant note'
+  )
+ON CONFLICT (id) DO UPDATE SET
+  tenant_id = EXCLUDED.tenant_id,
+  customer_id = EXCLUDED.customer_id,
+  plan = EXCLUDED.plan,
+  invoice_status = EXCLUDED.invoice_status,
+  support_ticket_reason = EXCLUDED.support_ticket_reason,
+  plan_credit_cents = EXCLUDED.plan_credit_cents,
+  credit_reason = EXCLUDED.credit_reason,
+  updated_at = EXCLUDED.updated_at,
+  card_token = EXCLUDED.card_token,
+  raw_payment_method = EXCLUDED.raw_payment_method,
+  internal_risk_score = EXCLUDED.internal_risk_score,
+  private_notes = EXCLUDED.private_notes;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
+    CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_writer') THEN
+    CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  END IF;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_runner_plan_credit TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT CREATE ON SCHEMA public TO synapsor_writer;
+GRANT SELECT ON public.customers TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;

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

@@ -0,0 +1,198 @@
+{
+  "capabilities": [
+    {
+      "args": {
+        "customer_id": {
+          "description": "Customer id such as CUS-3001.",
+          "max_length": 128,
+          "required": true,
+          "type": "string"
+        }
+      },
+      "context": "support_agent_context",
+      "description": "Inspect one support customer in the trusted tenant before proposing a plan credit.",
+      "evidence": {
+        "query_audit": true,
+        "required": true
+      },
+      "kept_out_fields": [
+        "card_token",
+        "raw_payment_method",
+        "internal_risk_score",
+        "private_notes"
+      ],
+      "kind": "read",
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "max_rows": 1,
+      "name": "support.inspect_customer",
+      "returns_hint": "Returns reviewed customer fields plus evidence/query-audit handles.",
+      "source": "local_postgres",
+      "subject": {
+        "conflict_key": "updated_at",
+        "primary_key": "id",
+        "schema": "public",
+        "table": "customers",
+        "tenant_key": "tenant_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "plan",
+        "invoice_status",
+        "support_ticket_reason",
+        "plan_credit_cents",
+        "credit_reason",
+        "updated_at"
+      ]
+    },
+    {
+      "args": {
+        "credit_cents": {
+          "description": "Requested plan credit in cents.",
+          "minimum": 1,
+          "required": true,
+          "type": "number"
+        },
+        "customer_id": {
+          "description": "Customer id such as CUS-3001.",
+          "max_length": 128,
+          "required": true,
+          "type": "string"
+        },
+        "reason": {
+          "description": "Business reason tied to support evidence.",
+          "max_length": 500,
+          "required": true,
+          "type": "string"
+        }
+      },
+      "context": "support_agent_context",
+      "description": "Propose a bounded support plan credit after inspecting customer and ticket evidence.",
+      "evidence": {
+        "query_audit": true,
+        "required": true
+      },
+      "kept_out_fields": [
+        "card_token",
+        "raw_payment_method",
+        "internal_risk_score",
+        "private_notes"
+      ],
+      "kind": "proposal",
+      "lookup": {
+        "id_from_arg": "customer_id"
+      },
+      "max_rows": 1,
+      "name": "support.propose_plan_credit",
+      "proposal": {
+        "action": "grant_plan_credit",
+        "allowed_fields": [
+          "plan_credit_cents",
+          "credit_reason"
+        ],
+        "approval": {
+          "mode": "policy",
+          "policy": "support_propose_plan_credit_auto_approval",
+          "required_role": "support_reviewer"
+        },
+        "conflict_guard": {
+          "column": "updated_at"
+        },
+        "numeric_bounds": {
+          "plan_credit_cents": {
+            "maximum": 50000,
+            "minimum": 1
+          }
+        },
+        "patch": {
+          "credit_reason": {
+            "from_arg": "reason"
+          },
+          "plan_credit_cents": {
+            "from_arg": "credit_cents"
+          }
+        },
+        "writeback": {
+          "mode": "direct_sql"
+        }
+      },
+      "returns_hint": "Returns a proposal id, exact diff, evidence handle, and source_database_changed:false. Policy may approve small credits, but writeback is still separate.",
+      "source": "local_postgres",
+      "subject": {
+        "conflict_key": "updated_at",
+        "primary_key": "id",
+        "schema": "public",
+        "table": "customers",
+        "tenant_key": "tenant_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "plan",
+        "invoice_status",
+        "support_ticket_reason",
+        "plan_credit_cents",
+        "credit_reason",
+        "updated_at"
+      ]
+    }
+  ],
+  "contexts": [
+    {
+      "bindings": [
+        {
+          "key": "SYNAPSOR_TENANT_ID",
+          "name": "tenant_id",
+          "required": true,
+          "source": "environment"
+        },
+        {
+          "key": "SYNAPSOR_PRINCIPAL",
+          "name": "principal",
+          "required": true,
+          "source": "environment"
+        }
+      ],
+      "name": "support_agent_context",
+      "principal_binding": "principal",
+      "tenant_binding": "tenant_id"
+    }
+  ],
+  "kind": "SynapsorContract",
+  "policies": [
+    {
+      "kind": "approval",
+      "mode": "green",
+      "name": "support_propose_plan_credit_auto_approval",
+      "rules": [
+        {
+          "field": "plan_credit_cents",
+          "max": 2500
+        }
+      ]
+    }
+  ],
+  "spec_version": "0.1",
+  "workflows": [
+    {
+      "allowed_capabilities": [
+        "support.inspect_customer",
+        "support.propose_plan_credit"
+      ],
+      "approval": {
+        "required": true,
+        "role": "support_reviewer"
+      },
+      "context": "support_agent_context",
+      "name": "support.plan_credit_request",
+      "replay": {
+        "checkpoint": "proposal_only"
+      },
+      "required_evidence": true
+    }
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/support-plan-credit/local.db"
+  },
+  "contracts": [
+    "./synapsor.contract.json"
+  ],
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "PLAN_CREDIT_POSTGRES_READ_URL",
+      "write_url_env": "PLAN_CREDIT_POSTGRES_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",
@@ -25,6 +25,7 @@
     "examples/openai-agents-stdio/**",
     "examples/raw-sql-vs-synapsor/**",
     "examples/reference-support-billing-app/**",
+    "examples/support-plan-credit/**",
     "examples/support-billing-agent/**",
     "fixtures/**",
     "schemas/**",