mythos-sentinel 0.1.0

package/docs/MCP.md

@@ -0,0 +1,70 @@
+# MCP usage
+
+Mythos Sentinel exposes a local JSON-RPC/MCP-style server so agent clients can ask for policy decisions before using risky capabilities.
+
+Run:
+
+```bash
+mythos-sentinel mcp
+```
+
+Example config:
+
+```json
+{
+  "mcpServers": {
+    "mythos-sentinel": {
+      "command": "npx",
+      "args": ["mythos-sentinel", "mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `sentinel_scan_path` — scan a folder, skill, MCP server, or repository.
+- `sentinel_check_command` — decide whether a shell command is allowed, blocked, or needs approval.
+- `sentinel_check_file` — decide whether a file read/write is allowed.
+- `sentinel_check_network` — decide whether a domain is allowed.
+- `sentinel_check_x402_payment` — decide whether an x402/Base payment is allowed.
+- `sentinel_recommend_x402_service` — recommend a paid API by category and price.
+- `sentinel_route_x402_service` — return a selected service plus fallback route plan.
+- `sentinel_list_service_categories` — list normalized service categories and aliases.
+- `sentinel_parse_x402_receipt` — normalize a receipt-like payload without storing it.
+- `sentinel_score_x402_domain` — return a RouteScore signal for a known payment domain.
+- `sentinel_snapshot` — create a file hash snapshot before agent work.
+
+## Runtime proxy mode
+
+Direct MCP mode gives agents Sentinel tools to ask for permission. Runtime proxy mode places Sentinel in front of upstream MCP servers so risky calls cannot bypass policy.
+
+```bash
+mythos-sentinel proxy --config proxy.json
+```
+
+Example proxy config:
+
+```json
+{
+  "upstreams": [
+    {
+      "name": "filesystem-tools",
+      "command": "npx",
+      "args": ["some-filesystem-mcp-server"]
+    }
+  ]
+}
+```
+
+Flow:
+
+```text
+Agent / MCP client -> Mythos Sentinel Proxy -> upstream MCP server
+```
+
+Sentinel classifies tool calls, checks policy, blocks or gates risky calls, forwards allowed calls, and can record opt-in local telemetry for paid API calls.
+
+## Design note
+
+This is intentionally local and keyless. Sentinel does not need model API keys or wallet keys. For production, keep MCP clients scoped to the project directory and do not expose the server over a network socket.

package/docs/PASSIVE_SCORING.md

@@ -0,0 +1,33 @@
+# Passive Routed-Call Reliability Scoring
+
+Passive scoring lets RouteScore improve from actual proxy traffic instead of requiring Mythos to spend money probing every endpoint.
+
+## Flow
+
+```text
+1. Agent calls a tool through Mythos Sentinel Proxy.
+2. Sentinel classifies the call as payment/network/shell/file.
+3. If allowed, Sentinel forwards it to the upstream MCP server.
+4. Sentinel records sanitized local metadata about success/failure and latency.
+5. RouteScore uses the telemetry summary when ranking services.
+```
+
+## What improves the score
+
+- high success rate
+- valid schema signal
+- low median latency
+- price matching the quote
+- more passive samples
+
+## What lowers the score
+
+- upstream failures
+- repeated recent failures
+- price mismatch
+- poor schema match
+- high latency
+
+## No paid probes required
+
+The first implementation does not require Sentinel to pay for APIs. It uses the user or agent's own routed calls. Active paid probes can be added later for important endpoints, but they are not required for the public MVP.

package/docs/ROUTESCORE.md

@@ -0,0 +1,101 @@
+# RouteScore
+
+RouteScore is the reliability, recommendation, and fallback-routing layer inside Mythos Sentinel.
+
+It is not a fake global oracle. It starts with a seed catalog, can import live/custom services, and becomes more valuable when agents route calls through Sentinel and opt into local telemetry.
+
+## Data layers
+
+1. **Seed metadata**: category, domain, endpoint, rough price, network, notes.
+2. **Custom local services**: user-provided JSON/YAML catalogs stored in `.mythos/routescore/services.json`.
+3. **Bazaar discovery**: optional sync from CDP Bazaar discovery endpoints.
+4. **Free checks**: domain alive, x402 quote/402 response, price metadata, schema shape, quote latency.
+5. **Passive routed-call telemetry**: local success/failure, latency, schema match, price mismatch from proxied calls.
+6. **x402 receipts**: optional local payment/settlement proof ingestion.
+7. **Fallback routing**: selected route plus ordered fallback candidates.
+8. **Small paid probes**: optional checks for important endpoints later.
+
+Sentinel must never collect prompts, full responses, secrets, private keys, wallet balances, or user files as RouteScore telemetry. The current implementation is local-only and disabled by default.
+
+## CLI
+
+```bash
+mythos-sentinel routescore list
+mythos-sentinel routescore recommend --category web_search --max-price 0.05
+mythos-sentinel routescore categories
+mythos-sentinel routescore route --category web_search --max-price 0.05
+mythos-sentinel routescore fallback --category web_search --max-price 0.05 --simulate-fail primary
+```
+
+## Import custom services
+
+Create `services.yml`:
+
+```yaml
+services:
+  - name: Custom Search API
+    category: web_search
+    domain: api.example.com
+    endpoint: https://api.example.com/search
+    priceUSDC: 0.01
+    network: base
+    tags:
+      - search
+      - custom
+```
+
+Import it:
+
+```bash
+mythos-sentinel routescore import services.yml
+mythos-sentinel routescore list
+```
+
+Custom services are stored locally in `.mythos/routescore/services.json`.
+
+## Sync Bazaar discovery
+
+```bash
+# Browse the paginated x402 catalog and save normalized services locally.
+mythos-sentinel routescore sync-bazaar --limit 100
+
+# Search the catalog and save only matching services.
+mythos-sentinel routescore sync-bazaar --query web_search --limit 20
+
+# Search without saving.
+mythos-sentinel routescore search-bazaar --query browser --limit 10
+```
+
+Network calls are only made when you run `sync-bazaar` or `search-bazaar`. Normal RouteScore operations stay local.
+
+## MCP tools
+
+- `sentinel_recommend_x402_service`
+- `sentinel_route_x402_service`
+- `sentinel_score_x402_domain`
+
+## Why routing matters
+
+Agents should not need to manually choose between dozens of paid APIs. RouteScore can give an agent a route plan:
+
+1. selected service
+2. fallback services
+3. price and score
+4. Sentinel payment-policy decision
+
+The route plan is not a guarantee of output quality. It is a pre-spend reliability and policy signal.
+
+## Telemetry commands
+
+```bash
+mythos-sentinel telemetry enable
+mythos-sentinel telemetry status
+mythos-sentinel telemetry summary
+```
+
+See `docs/TELEMETRY.md` and `docs/PASSIVE_SCORING.md`.
+
+## Related docs
+
+- `docs/FALLBACK_ROUTING.md`
+- `docs/X402_RECEIPTS.md`

package/docs/RUNTIME_MCP_PROXY.md

@@ -0,0 +1,90 @@
+# Runtime MCP Proxy
+
+Runtime proxy mode turns Mythos Sentinel from a permission-checking MCP server into an enforcement layer.
+
+```txt
+Agent / Claude / Cursor / custom runtime
+  -> mythos-sentinel proxy
+  -> upstream MCP servers and x402 tools
+```
+
+The agent still sees normal MCP tools. Sentinel mirrors upstream tools, checks each `tools/call`, and only forwards allowed calls.
+
+## Why it matters
+
+Direct guardrail mode depends on the agent remembering to ask Sentinel before risky actions. Proxy mode removes that weak point: every proxied tool call is preflighted before the upstream server receives it.
+
+Sentinel checks:
+
+- x402/Base payment domain, amount, daily spend, unknown-domain trial rules, and RouteScore signal
+- shell commands against blocked and approval-required patterns
+- file reads/writes against deny and allow rules
+- network domains against deny/allow rules
+
+`block` and `approval_required` decisions are not forwarded to upstream tools.
+
+## Run
+
+```bash
+mythos-sentinel proxy
+```
+
+or with an explicit policy/config:
+
+```bash
+mythos-sentinel proxy --policy mythos.policy.json
+mythos-sentinel proxy --config proxy.json
+```
+
+## Claude/Cursor config
+
+```json
+{
+  "mcpServers": {
+    "mythos-sentinel-proxy": {
+      "command": "npx",
+      "args": ["mythos-sentinel", "proxy"]
+    }
+  }
+}
+```
+
+## Configure upstream tools
+
+Add upstream MCP servers in `mythos.policy.json`:
+
+```json
+{
+  "mcpProxy": {
+    "enabled": true,
+    "mode": "enforce",
+    "approvalMode": "return_error",
+    "toolNameStrategy": "preserve_unless_collision",
+    "upstreams": [
+      {
+        "id": "search",
+        "command": "npx",
+        "args": ["-y", "your-search-mcp-server"]
+      },
+      {
+        "id": "browser",
+        "command": "npx",
+        "args": ["-y", "your-browser-mcp-server"]
+      }
+    ]
+  }
+}
+```
+
+If two upstreams expose the same tool name, Sentinel automatically prefixes the collision as `upstreamId__toolName`.
+
+## Decision behavior
+
+- `allow`: forward to upstream and attach `_sentinel` metadata to `structuredContent`
+- `approval_required`: return an MCP tool error before upstream execution
+- `block`: return an MCP tool error before upstream execution
+- `upstream_error`: upstream failed after Sentinel allowed the call
+
+## Positioning
+
+Use direct MCP mode for lightweight projects where the agent voluntarily asks Sentinel. Use proxy mode for wallet-enabled agents, paid x402 tools, shell/file access, or demos where enforcement must be visible.

package/docs/SPEND_FIREWALL.md

@@ -0,0 +1,50 @@
+# Adaptive Spend Firewall
+
+Mythos Sentinel protects wallet-enabled agents before they pay x402/Base endpoints.
+
+The important design choice is **risk-based freedom**. A strict allowlist is safe but makes agents weak. A fully open wallet is flexible but dangerous. Sentinel uses tiers:
+
+| Tier | Default action |
+| --- | --- |
+| Trusted domain | Allow within budget. |
+| Known service with high RouteScore | Allow within budget. |
+| Unknown domain | Allow tiny trial spend only. |
+| Expensive unknown domain | Require human approval. |
+| Denied / very low RouteScore / over budget | Block. |
+
+## Policy fields
+
+```json
+{
+  "payments": {
+    "x402": {
+      "strategy": "balanced",
+      "maxPerRequestUSDC": 0.25,
+      "maxDailyUSDC": 5,
+      "requireApprovalAboveUSDC": 0.25,
+      "trustedDomains": ["api.exa.ai"],
+      "unknown": {
+        "allowTrial": true,
+        "maxPerRequestUSDC": 0.02,
+        "maxDailyUSDC": 0.25,
+        "requireApprovalAboveUSDC": 0.02
+      },
+      "routeScore": {
+        "autoAllowMinScore": 80,
+        "requireApprovalBelowScore": 60,
+        "blockBelowScore": 35
+      }
+    }
+  }
+}
+```
+
+## Strategies
+
+- `balanced`: recommended default. Unknown APIs get tiny trial freedom.
+- `strict`: unknown APIs require approval.
+- `explorer`: for demos and experiments; keep budgets low.
+
+## What Sentinel does not do
+
+Sentinel does not sign transactions or claw back payments. It must sit before the wallet/payment tool. If an agent bypasses Sentinel and spends directly, Sentinel cannot protect that flow.

package/docs/TELEMETRY.md

@@ -0,0 +1,74 @@
+# Opt-in Local Telemetry
+
+Mythos Sentinel can store a small local telemetry log so RouteScore can learn from real routed calls without Mythos paying for every API probe.
+
+Telemetry is **disabled by default**.
+
+Enable it:
+
+```bash
+mythos-sentinel telemetry enable
+```
+
+Disable it:
+
+```bash
+mythos-sentinel telemetry disable
+```
+
+View status and summary:
+
+```bash
+mythos-sentinel telemetry status
+mythos-sentinel telemetry summary
+mythos-sentinel telemetry events --json
+```
+
+## What is stored
+
+Events are written locally to:
+
+```text
+.mythos/telemetry/events.jsonl
+```
+
+Each event contains only sanitized reliability metadata:
+
+- endpoint domain
+- service id when matched to the RouteScore catalog
+- decision: allow, block, approval_required, upstream_error
+- amount in USDC when present
+- latency in milliseconds
+- success/failure status
+- schema/price-match flags when known
+- timestamp
+- upstream/tool names
+
+## What is never stored
+
+Sentinel does not store:
+
+- prompts
+- model responses
+- secrets
+- private file contents
+- wallet balances
+- seed phrases or private keys
+
+## Passive routed-call reliability scoring
+
+When telemetry is enabled and an agent uses `mythos-sentinel proxy`, Sentinel observes whether forwarded paid/network API calls succeeded or failed. Those events feed RouteScore automatically:
+
+```text
+Agent -> Sentinel Proxy -> x402/API tool
+              ↓
+     local telemetry event
+              ↓
+     RouteScore success rate / latency / failure count
+```
+
+This means users or agents pay for their own API calls, while Sentinel learns from the result locally.
+
+## Local-first by design
+
+The current implementation is local-only. It does not upload telemetry to a hosted Mythos service. A future shared reliability network should stay explicit opt-in and anonymous.

package/docs/THREAT_MODEL.md

@@ -0,0 +1,28 @@
+# Threat model
+
+Mythos Sentinel focuses on risks created when AI agents can install tools, read files, run commands, call APIs, and spend money.
+
+## In scope
+
+- malicious or compromised agent skills
+- prompt injection inside skill instructions
+- MCP tool poisoning or unsafe tool descriptions
+- local secret exposure
+- wallet/private-key exposure
+- unauthorized x402/Base spending
+- dangerous shell commands
+- CI permission escalation
+- auditability of AI-generated work
+
+## Out of scope for v0.1
+
+- full OS sandboxing
+- malware reverse engineering
+- formal verification
+- blockchain transaction settlement
+- real-time network proxying
+- guaranteed prompt-injection prevention
+
+## Security stance
+
+Sentinel should fail closed in CI for high/critical findings. For local agent development, start in monitor mode and move to enforce mode when the policy is tuned.

package/docs/X402_RECEIPTS.md

@@ -0,0 +1,54 @@
+# x402 receipt ingestion
+
+Sentinel can ingest sanitized x402 payment receipts and settlement responses so agent payment events become auditable without storing prompts, responses, private request bodies, secrets, private keys, or wallet balances.
+
+## Commands
+
+```bash
+mythos-sentinel x402-receipt ingest --file receipt.json
+mythos-sentinel x402-receipt summary
+mythos-sentinel x402-receipt list --json
+```
+
+Receipts are stored locally at:
+
+```txt
+.mythos/x402/receipts.jsonl
+```
+
+This path is ignored by Git by default.
+
+## Accepted input shapes
+
+The ingester accepts common receipt/settlement shapes and tries to normalize them:
+
+```json
+{
+  "endpoint": "https://api.exa.ai/search",
+  "amount": "5000",
+  "asset": "USDC",
+  "network": "eip155:8453",
+  "status": "settled",
+  "txHash": "0x..."
+}
+```
+
+It also accepts payment-response header style values through keys like `x-payment-response`, `x-payment`, `x402-receipt`, or `x402-payment-response` when provided as JSON/base64 JSON.
+
+## Stored fields
+
+Sentinel stores only sanitized payment metadata:
+
+- domain and endpoint
+- amount, asset, network
+- payer/payTo when present
+- transaction hash when present
+- settlement status
+- facilitator when present
+- observed timestamp
+
+It does not store prompts, responses, private request bodies, secrets, private files, private keys, or wallet balances.
+
+## Telemetry integration
+
+When opt-in telemetry is enabled, ingested receipts also produce sanitized local telemetry events. Settled receipts count as successful payment observations; failed receipts count as failures.

package/examples/base/mythos.policy.json

@@ -0,0 +1,142 @@
+{
+  "version": "0.8",
+  "mode": "enforce",
+  "project": "base-agent-project",
+  "filesystem": {
+    "deny": [
+      ".env",
+      ".env.*",
+      "**/.env",
+      "**/.env.*",
+      "**/id_rsa",
+      "**/id_ed25519",
+      "**/*.pem",
+      "**/*.key",
+      "**/*.p12",
+      "**/*.pfx"
+    ],
+    "allowRead": [
+      "**/*"
+    ],
+    "allowWrite": [
+      "src/**",
+      "test/**",
+      "docs/**",
+      "examples/**",
+      ".github/workflows/**",
+      "README.md",
+      "package.json",
+      "package-lock.json",
+      "mythos.policy.json"
+    ]
+  },
+  "commands": {
+    "blockedPatterns": [
+      "curl\\s+[^|]+\\|\\s*(sudo\\s+)?(bash|sh|zsh)",
+      "wget\\s+[^|]+\\|\\s*(sudo\\s+)?(bash|sh|zsh)",
+      "Invoke-WebRequest[^|]+\\|\\s*iex",
+      "iwr\\s+[^|]+\\s*\\|\\s*iex",
+      "rm\\s+-rf\\s+(/|~|\\$HOME|\\.\\./)",
+      "chmod\\s+777",
+      "base64\\s+-d\\s+[^|]+\\|\\s*(bash|sh|zsh)",
+      "powershell\\s+.*-enc(odedcommand)?"
+    ],
+    "approvalPatterns": [
+      "npm\\s+install",
+      "pnpm\\s+install",
+      "yarn\\s+add",
+      "pip\\s+install",
+      "docker\\s+run",
+      "git\\s+push"
+    ]
+  },
+  "network": {
+    "blockUnknown": true,
+    "allowedDomains": [
+      "api.coinbase.com",
+      "api.developer.coinbase.com",
+      "api.exa.ai",
+      "mainnet.base.org",
+      "base.org",
+      "api.github.com"
+    ],
+    "deniedDomains": []
+  },
+  "payments": {
+    "x402": {
+      "enabled": true,
+      "strategy": "balanced",
+      "enforceAllowlist": false,
+      "maxPerRequestUSDC": 0.25,
+      "maxDailyUSDC": 5,
+      "requireApprovalAboveUSDC": 0.25,
+      "trustedDomains": [
+        "api.coinbase.com",
+        "api.developer.coinbase.com",
+        "api.exa.ai",
+        "www.x402.org",
+        "x402.org"
+      ],
+      "allowedDomains": [],
+      "deniedDomains": [],
+      "unknown": {
+        "allowTrial": true,
+        "maxPerRequestUSDC": 0.02,
+        "maxDailyUSDC": 0.25,
+        "requireApprovalAboveUSDC": 0.02
+      },
+      "routeScore": {
+        "autoAllowMinScore": 80,
+        "requireApprovalBelowScore": 60,
+        "blockBelowScore": 35
+      }
+    }
+  },
+  "routeScore": {
+    "enabled": true,
+    "catalogMode": "seed",
+    "telemetry": {
+      "anonymous": true,
+      "collectPrompts": false,
+      "collectResponses": false,
+      "collectWalletBalances": false,
+      "enabled": false,
+      "localOnly": true,
+      "storePath": ".mythos/telemetry/events.jsonl"
+    },
+    "seedCategories": [
+      "web_search",
+      "content_extraction",
+      "inference",
+      "web3_data",
+      "wallet_intel"
+    ]
+  },
+  "findings": {
+    "failOn": [
+      "critical",
+      "high"
+    ],
+    "warnOn": [
+      "medium"
+    ]
+  },
+  "scanner": {
+    "ignore": [
+      "mythos.policy.json"
+    ],
+    "useMythosIgnore": true
+  },
+  "receipts": {
+    "require": true,
+    "includeFileHashes": true
+  },
+  "mcpProxy": {
+    "enabled": true,
+    "mode": "enforce",
+    "approvalMode": "return_error",
+    "toolNameStrategy": "preserve_unless_collision",
+    "exposeSentinelTools": false,
+    "upstreams": []
+  }
+}

package/examples/claude_desktop/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mythos-sentinel-proxy": {
+      "command": "npx",
+      "args": ["mythos-sentinel", "proxy"]
+    }
+  }
+}

package/examples/codex/AGENTS.md

@@ -0,0 +1,31 @@
+# Mythos Sentinel rules for Codex
+
+Codex may edit project files, but all agent work must pass Mythos Sentinel policy checks.
+
+## Required workflow
+
+1. Before editing, run:
+   `mythos-sentinel snapshot . --out .mythos/snapshots/before.json`
+2. Before risky actions, ask Sentinel:
+   - command: `mythos-sentinel check-command -- "<command>"`
+   - file write: `mythos-sentinel check-file --path <path> --operation write`
+   - network: `mythos-sentinel check-network --domain <domain>`
+   - RouteScore: `mythos-sentinel routescore recommend --category <category> --max-price <usdc>`
+   - x402/Base spend: `mythos-sentinel check-payment --domain <domain> --amount <usdc> [--route-score <score>]`
+3. Make the requested changes.
+4. Run tests/lint for the project.
+5. Run:
+   `mythos-sentinel scan . --out .mythos/reports/sentinel-report.json`
+6. Create a receipt:
+   `mythos-sentinel receipt --before .mythos/snapshots/before.json --summary "<task>" --agent codex --provider openai --tool codex-cli --out mythos-receipt.json`
+
+## Never do this
+
+- Never read `.env`, private keys, wallet secrets, SSH keys, browser profiles, or unrelated home-directory files.
+- Never make x402/Base/USDC payments unless Sentinel returns `allow`. Unknown domains may only use tiny trial payments under policy; larger payments require human approval.
+- Never install unknown agent skills or MCP servers without scanning them first.
+- Never run destructive shell commands.
+
+## Hard stop
+
+Stop and ask for approval if Sentinel returns `block` or `approval_required`.

package/examples/cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mythos-sentinel-proxy": {
+      "command": "npx",
+      "args": ["mythos-sentinel", "proxy"]
+    }
+  }
+}