mythos-sentinel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thewaltero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+<div align="center">
+  <img src="assets/banner.png" alt="Mythos Sentinel banner" width="864" />
+</div>
+
+# Mythos Sentinel
+
+**Local-first runtime firewall for wallet-enabled AI agents, MCP tools, and x402/Base payments.**
+
+Agents are starting to discover paid APIs and pay over HTTP. Sentinel sits before those payments and answers the question raw wallets and discovery layers do not fully answer:
+
+> Should this agent be allowed to spend this amount on this endpoint right now?
+
+```text
+Agent / MCP client / wallet-enabled workflow
+        ↓
+Mythos Sentinel
+        ↓
+policy · budget · unknown-domain rules · RouteScore signal
+        ↓
+allow · approval_required · block · receipt
+```
+
+## Why Sentinel?
+
+| Tool type | What it does | What Sentinel adds |
+| --- | --- | --- |
+| Agent frameworks | Run tasks and call tools | Spend/control layer before risky actions |
+| MCP clients | Connect agents to tools | Runtime proxy and policy enforcement |
+| x402 APIs | Let agents pay services | Budget, trust, receipts, and fallback routing |
+| Wallet permissions | Limit raw spend | Context-aware allow / approval / block decisions |
+| API marketplaces | Help agents discover services | Local reliability scoring and routing decisions |
+
+## Why this exists
+
+x402/Bazaar-style discovery makes it easier for agents to find and pay APIs. That creates a new problem: agents can spend quickly, but they still need budgets, trust signals, logs, and approval rules.
+
+Sentinel is the local control layer around that behavior:
+
+- Can this agent spend on this domain?
+- Is this amount safe for an unknown API?
+- Does RouteScore say this endpoint is reliable enough?
+- Did the action produce an audit trail?
+- Should the human approve before payment?
+
+## Core features
+
+| Feature | What it does |
+| --- | --- |
+| Adaptive x402/Base spend guard | Enforces trusted, known, unknown, denied, budget, and RouteScore-based decisions. |
+| RouteScore catalog + routing | Scores seed, custom, and Bazaar-imported paid agent APIs, then recommends selected services and fallback routes. |
+| Fallback routing primitives | Plans and executes fallback attempts through caller-provided executors so agents can retry safer alternatives when a provider fails. |
+| x402 receipt ingestion | Normalizes sanitized x402 payment receipts, tracks settlement status, and summarizes observed spend without storing prompts or responses. |
+| Opt-in local telemetry | Stores sanitized local endpoint events only after the user enables it. No prompts, responses, secrets, private files, or wallet balances. |
+| Passive reliability scoring | Uses proxied-call success/failure, latency, schema, and price-match signals to improve RouteScore locally. |
+| Runtime MCP proxy | Puts Sentinel in front of upstream MCP tools so risky calls cannot bypass policy. |
+| Scanner and guards | Finds risky instructions and checks command, file, network, and payment actions before execution. |
+| Receipts | Captures before/after workspace hashes and verifies agent work. |
+| Local dashboard | A premium local control room for policy, RouteScore, telemetry, receipts, and guard tests. |
+| GitHub Action | Runs Sentinel in CI without model keys, wallet keys, or hosted accounts. |
+
+## Install
+
+```bash
+npm install -g mythos-sentinel
+```
+
+Or run directly:
+
+```bash
+npx mythos-sentinel help
+```
+
+Node.js 20+ is required. Sentinel does **not** require OpenAI, Anthropic, Coinbase, wallet, or private-key access.
+
+## Runtime MCP proxy
+
+Direct MCP mode gives agents Sentinel tools to ask for permission. Runtime proxy mode puts Sentinel in front of upstream MCP servers so risky calls cannot bypass policy.
+
+```bash
+mythos-sentinel proxy
+```
+
+Flow:
+
+```txt
+Agent -> Mythos Sentinel Proxy -> upstream MCP tools / x402 APIs
+```
+
+Use this mode for wallet-enabled agents, paid x402 APIs, shell tools, file tools, browser tools, and demos that need real enforcement. See `docs/RUNTIME_MCP_PROXY.md`.
+
+## Quick start
+
+Inside the project you want to protect:
+
+```bash
+mythos-sentinel init --base
+mythos-sentinel scan .
+mythos-sentinel ui
+```
+
+Check actions before an agent does them:
+
+```bash
+mythos-sentinel check-command -- "npm install unknown-package"
+mythos-sentinel check-file --path .env --operation read
+mythos-sentinel check-network --domain api.github.com
+mythos-sentinel check-payment --domain api.exa.ai --amount 0.01
+mythos-sentinel check-payment --domain fresh-api.example --amount 0.01
+mythos-sentinel check-payment --domain fresh-api.example --amount 0.10
+```
+
+List, import, recommend, and route x402 services:
+
+```bash
+mythos-sentinel routescore categories
+mythos-sentinel routescore list
+mythos-sentinel routescore import services.yml
+mythos-sentinel routescore sync-bazaar --query web_search --limit 20
+mythos-sentinel routescore recommend --category web_search --max-price 0.05
+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
+```
+
+Enable local telemetry and inspect receipt summaries:
+
+```bash
+mythos-sentinel telemetry enable
+mythos-sentinel telemetry status
+mythos-sentinel telemetry summary
+mythos-sentinel x402-receipt summary
+```
+
+## Adaptive payment policy
+
+Default behavior is balanced: agents can explore, but not with unlimited wallet freedom.
+
+```json
+{
+  "payments": {
+    "x402": {
+      "enabled": true,
+      "strategy": "balanced",
+      "maxPerRequestUSDC": 0.25,
+      "maxDailyUSDC": 5,
+      "requireApprovalAboveUSDC": 0.25,
+      "trustedDomains": ["api.coinbase.com", "api.developer.coinbase.com", "api.exa.ai"],
+      "deniedDomains": [],
+      "unknown": {
+        "allowTrial": true,
+        "maxPerRequestUSDC": 0.02,
+        "maxDailyUSDC": 0.25,
+        "requireApprovalAboveUSDC": 0.02
+      },
+      "routeScore": {
+        "autoAllowMinScore": 80,
+        "requireApprovalBelowScore": 60,
+        "blockBelowScore": 35
+      }
+    }
+  }
+}
+```
+
+Decision model:
+
+```text
+trusted domain + under budget         -> allow
+known service + high RouteScore       -> allow
+unknown domain + tiny amount          -> allow trial
+unknown domain + larger amount        -> approval_required
+low RouteScore / denied / over budget -> block
+```
+
+This avoids the bad tradeoff of either blocking every new API or letting agents freely spend on anything.
+
+## RouteScore and fallback routing
+
+RouteScore 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** — starter category/domain/endpoint/rough-price metadata.
+2. **Custom local services** — user-imported `services.yml` / JSON.
+3. **Optional Bazaar metadata** — live public discovery metadata synced into local storage.
+4. **Local telemetry** — opt-in success/failure/latency/price-match observations.
+5. **x402 receipts** — sanitized local payment/settlement records.
+
+Commands:
+
+```bash
+mythos-sentinel routescore categories
+mythos-sentinel routescore list --json
+mythos-sentinel routescore import services.yml
+mythos-sentinel routescore sync-bazaar --query content_extraction --limit 20
+mythos-sentinel routescore recommend --category content_extraction --max-price 0.05 --json
+mythos-sentinel routescore route --category content_extraction --max-price 0.05 --json
+mythos-sentinel routescore fallback --category content_extraction --max-price 0.05 --simulate-fail primary
+```
+
+Custom service catalog example:
+
+```yaml
+services:
+  - name: Custom Search API
+    category: web_search
+    domain: api.example.com
+    endpoint: https://api.example.com/search
+    priceUSDC: 0.01
+    network: base
+```
+
+See `docs/ROUTESCORE.md`, `docs/FALLBACK_ROUTING.md`, and `docs/BAZAAR_ADAPTER.md`.
+
+## Opt-in telemetry and x402 receipts
+
+Telemetry is disabled until the user enables it. It stores sanitized endpoint metadata only and never stores prompts, responses, secrets, private files, private keys, or wallet balances.
+
+```bash
+mythos-sentinel telemetry enable
+mythos-sentinel telemetry status
+mythos-sentinel telemetry summary
+mythos-sentinel telemetry events --json
+```
+
+x402 receipt ingestion stores sanitized payment proof locally and can feed RouteScore telemetry when telemetry is enabled.
+
+```bash
+mythos-sentinel x402-receipt ingest --file receipt.json
+mythos-sentinel x402-receipt summary
+mythos-sentinel x402-receipt list --json
+```
+
+See `docs/TELEMETRY.md`, `docs/PASSIVE_SCORING.md`, and `docs/X402_RECEIPTS.md`.
+
+## Local dashboard
+
+Run:
+
+```bash
+mythos-sentinel ui
+```
+
+For GitHub Codespaces demos:
+
+```bash
+mythos-sentinel ui --host 0.0.0.0 --port 4317 --demo
+```
+
+The dashboard is local-first. It does not upload repos, secrets, wallet keys, prompts, responses, telemetry, or reports to a hosted Mythos service.
+
+## MCP usage
+
+Run the MCP-style server:
+
+```bash
+mythos-sentinel mcp
+```
+
+Example Cursor/Claude MCP config:
+
+```json
+{
+  "mcpServers": {
+    "mythos-sentinel": {
+      "command": "npx",
+      "args": ["mythos-sentinel", "mcp"]
+    }
+  }
+}
+```
+
+Exposed tools:
+
+- `sentinel_scan_path`
+- `sentinel_check_x402_payment`
+- `sentinel_recommend_x402_service`
+- `sentinel_route_x402_service`
+- `sentinel_list_service_categories`
+- `sentinel_parse_x402_receipt`
+- `sentinel_score_x402_domain`
+- `sentinel_check_command`
+- `sentinel_check_file`
+- `sentinel_check_network`
+- `sentinel_snapshot`
+
+## Scanner demo
+
+Sentinel detects secrets, risky shell installers, sensitive files, network calls, and policy violations before agent work is trusted.
+
+## Receipts
+
+Create an agent work receipt:
+
+```bash
+mythos-sentinel snapshot . --out .mythos/snapshots/before.json
+# Let Codex/Cursor/Claude/your agent work here.
+mythos-sentinel scan . --out .mythos/reports/sentinel-report.json
+mythos-sentinel receipt \
+  --before .mythos/snapshots/before.json \
+  --summary "Implemented feature safely" \
+  --agent codex \
+  --provider openai \
+  --tool codex-cli \
+  --out mythos-receipt.json
+mythos-sentinel verify --receipt mythos-receipt.json
+```
+
+## CLI commands
+
+```text
+mythos-sentinel init [--base] [--force]
+mythos-sentinel scan [path] [--json] [--sarif] [--out report.json] [--fail-on high|critical|none]
+mythos-sentinel check-payment --domain api.example.com --amount 0.05 [--daily-spent 1.2] [--route-score 91]
+mythos-sentinel check-command -- "shell command"
+mythos-sentinel check-file --path .env --operation read|write
+mythos-sentinel check-network --domain api.example.com
+mythos-sentinel routescore list|categories|recommend|route|fallback [--category web_search] [--max-price 0.05]
+mythos-sentinel routescore import services.yml
+mythos-sentinel routescore sync-bazaar [--query web_search] [--limit 20]
+mythos-sentinel routescore search-bazaar --query browser --limit 10
+mythos-sentinel telemetry status|enable|disable|summary|events
+mythos-sentinel x402-receipt ingest --file receipt.json
+mythos-sentinel x402-receipt summary
+mythos-sentinel x402-receipt list
+mythos-sentinel snapshot [path] --out before.json
+mythos-sentinel receipt --before before.json --summary "task" --agent codex
+mythos-sentinel verify --receipt mythos-receipt.json
+mythos-sentinel mcp
+mythos-sentinel proxy [--policy mythos.policy.json] [--config proxy.json]
+mythos-sentinel ui [--host 127.0.0.1] [--port 4317] [--open] [--demo]
+mythos-sentinel doctor
+```
+
+## Security model
+
+Sentinel is a policy decision engine and scanner. It is **not** a sandbox, wallet, transaction signer, or guarantee of API quality. It works when agents route risky actions through Sentinel before execution/payment.
+
+For real funds, use least-privilege agent wallets, low spend permissions, testnet rehearsals, separate API credentials, hardware wallets for high-value assets, and human approval for large payments.
+
+## Roadmap
+
+- [x] Static agent/skill/MCP/repo scanner
+- [x] command, file, network, and x402/Base guards
+- [x] adaptive unknown-domain trial policy
+- [x] RouteScore seed catalog and recommendation API
+- [x] MCP RouteScore tools
+- [x] premium local dashboard
+- [x] GitHub Action and optional SARIF workflow
+- [x] snapshot and agent work receipts
+- [x] runtime MCP proxy mode
+- [x] opt-in local telemetry store
+- [x] passive routed-call reliability scoring
+- [x] live Bazaar catalog adapter
+- [x] fallback route planning and execution primitives
+- [x] expanded service categories
+- [x] x402 payment receipt ingestion
+- [ ] signed provider badges
+- [ ] optional shared reliability network
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,43 @@
+name: Mythos Sentinel
+
+description: Scan agent skills, MCP tools, repo instructions, and x402/Base payment code.
+
+author: thewaltero
+
+inputs:
+  path:
+    description: Path to scan
+    required: false
+    default: .
+  policy:
+    description: Path to mythos.policy.json
+    required: false
+    default: mythos.policy.json
+  format:
+    description: text, json, or sarif
+    required: false
+    default: text
+  out:
+    description: Optional output file
+    required: false
+    default: ''
+  fail-on:
+    description: Severity threshold to fail on. Use none to never fail.
+    required: false
+    default: high
+
+runs:
+  using: composite
+  steps:
+    - name: Run Mythos Sentinel
+      shell: bash
+      run: |
+        FLAGS=""
+        if [ "${{ inputs.format }}" = "json" ]; then FLAGS="$FLAGS --json"; fi
+        if [ "${{ inputs.format }}" = "sarif" ]; then FLAGS="$FLAGS --sarif"; fi
+        if [ -n "${{ inputs.out }}" ]; then FLAGS="$FLAGS --out ${{ inputs.out }}"; fi
+        node "${{ github.action_path }}/bin/mythos-sentinel.js" scan "${{ inputs.path }}" --policy "${{ inputs.policy }}" --fail-on "${{ inputs.fail-on }}" $FLAGS
+
+branding:
+  icon: shield
+  color: purple

package/bin/mythos-sentinel-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runMcpServer } from '../src/mcp/server.js';
+
+runMcpServer().catch((error) => {
+  console.error(JSON.stringify({ level: 'error', message: error?.message || String(error) }));
+  process.exit(1);
+});

package/bin/mythos-sentinel.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(`\nmythos-sentinel failed: ${error?.message || error}`);
+  if (process.env.MYTHOS_DEBUG) console.error(error?.stack || error);
+  process.exit(1);
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+Mythos Sentinel is intentionally dependency-light, local-first, and CLI/MCP-first.
+
+## Layers
+
+```text
+CLI / MCP tools / Runtime MCP proxy / GitHub Action / Dashboard
+        ↓
+policy engine
+        ↓
+scanner · guards · RouteScore · telemetry · x402 receipts · snapshots
+        ↓
+JSON reports · SARIF · local receipts · local reliability signals
+```
+
+## Modules
+
+- `src/cli.js` — command surface for scan, guard checks, RouteScore, telemetry, x402 receipts, MCP, proxy, and dashboard.
+- `src/scanner` — static rules for agent skills, MCP configs, repo instructions, CI files, wallet/payment code, and unsafe commands.
+- `src/core/policy.js` — policy loading and command/file/network/payment guard decisions.
+- `src/core/routescore.js` — seed/custom/Bazaar service catalog, scoring, category aliases, route plans, and fallback execution primitives.
+- `src/core/telemetry.js` — opt-in local telemetry store and passive reliability summaries.
+- `src/core/x402-receipts.js` — sanitized x402 receipt ingestion, local receipt store, and spend summaries.
+- `src/core/snapshot.js` — file hash snapshots and diffs.
+- `src/core/receipt.js` — task receipts and drift verification.
+- `src/mcp/server.js` — local JSON-RPC/MCP-style tool surface.
+- `src/mcp/proxy.js` — runtime proxy that gates upstream MCP tools before forwarding calls.
+- `src/ui/server.js` and `src/ui/static` — local dashboard and API endpoints.
+- `src/report` — human, JSON, and SARIF outputs.
+
+## Local storage
+
+Runtime state is stored under `.mythos/`:
+
+```text
+.mythos/routescore/services.json   # imported/synced service catalog
+.mythos/telemetry/events.jsonl     # opt-in local endpoint telemetry
+.mythos/x402/receipts.jsonl        # sanitized x402 receipt records
+.mythos/reports/                   # generated scan reports
+.mythos/snapshots/                 # generated file snapshots
+```
+
+Generated runtime files should not be committed unless intentionally shared.
+
+## Non-goals
+
+- Not a sandbox.
+- Not a wallet or transaction signer.
+- Not a formal verifier.
+- Not a remote SaaS scanner.
+- Not a guarantee of endpoint quality or settlement success.
+- Not another coding agent.
+
+Sentinel should stay a small, auditable permission, routing, and spend-control layer around agents.

package/docs/BASE_X402.md

@@ -0,0 +1,33 @@
+# Base / x402 Positioning
+
+Mythos Sentinel is built for agents that can discover paid services and pay over x402/Base.
+
+The product should be positioned as:
+
+> Adaptive spend firewall and RouteScore reliability layer for wallet-enabled agents.
+
+Not as:
+
+- a wallet
+- a transaction signer
+- a generic MCP scanner only
+- a fake API marketplace
+- a guarantee of endpoint quality
+
+## Correct flow
+
+```text
+Agent discovers paid API
+        ↓
+RouteScore recommends/checks reliability
+        ↓
+Sentinel checks policy, budget, trust, and score
+        ↓
+allow / approval_required / block
+        ↓
+payment tool or wallet executes only if allowed
+```
+
+## Why this is useful
+
+x402 reduces friction for paid APIs. That makes the next problem obvious: agents need spend limits, endpoint trust, routing context, and receipts. Sentinel focuses on that runtime gap.

package/docs/BAZAAR_ADAPTER.md

@@ -0,0 +1,41 @@
+# Bazaar Adapter
+
+Mythos Sentinel v0.10 can import x402 service metadata from CDP Bazaar discovery endpoints into the local RouteScore catalog.
+
+## Why it exists
+
+The seed RouteScore catalog is intentionally small. The Bazaar adapter lets Sentinel expand from a few seed services into a live/local catalog without manually hardcoding every endpoint.
+
+## Commands
+
+```bash
+mythos-sentinel routescore sync-bazaar --limit 100
+mythos-sentinel routescore sync-bazaar --query web_search --limit 20
+mythos-sentinel routescore search-bazaar --query browser --limit 10
+```
+
+Synced services are normalized and stored in:
+
+```text
+.mythos/routescore/services.json
+```
+
+## What is normalized
+
+- `resource` / endpoint URL
+- domain
+- inferred category
+- network
+- rough USDC price when payment metadata exposes an amount
+- metadata description
+- input/output schema presence
+- payment metadata presence
+- last updated timestamp
+
+## Privacy
+
+The adapter fetches public catalog metadata only. It does not send prompts, responses, wallet keys, private files, or telemetry to Mythos.
+
+## Reliability model
+
+Bazaar metadata expands discovery. Passive telemetry and RouteScore scoring still decide whether a service is preferred, limited, trial-only, or avoided.

package/docs/DASHBOARD.md

@@ -0,0 +1,22 @@
+# Dashboard
+
+Run:
+
+```bash
+mythos-sentinel ui
+```
+
+The dashboard is a local control room for:
+
+- adaptive x402/Base spend policy;
+- trusted and unknown-domain payment rules;
+- RouteScore seed/custom/Bazaar-imported catalog data;
+- fallback route plans;
+- opt-in local telemetry and passive samples;
+- x402 receipt summaries;
+- payment, command, file, and scan checks;
+- MCP and agent setup snippets.
+
+The visual direction is intentionally dark, minimal, and developer-infra focused: graphite background, restrained amber accents, compact metrics, and clear guard decisions.
+
+No hosted account is required. The dashboard does not upload prompts, responses, repos, secrets, wallet keys, telemetry, receipts, or reports to a hosted Mythos service.

package/docs/FALLBACK_ROUTING.md

@@ -0,0 +1,37 @@
+# Fallback routing
+
+RouteScore can now produce and execute ordered fallback plans. This prevents an agent from depending on a single paid API when multiple acceptable services exist.
+
+## CLI route plan
+
+```bash
+mythos-sentinel routescore route --category web_search --max-price 0.05
+```
+
+The plan includes:
+
+1. selected service
+2. fallback services
+3. RouteScore and price
+4. Sentinel payment-policy decisions
+
+## CLI fallback simulation
+
+```bash
+mythos-sentinel routescore fallback --category web_search --max-price 0.05 --simulate-fail primary
+```
+
+This does not call paid APIs. It demonstrates the attempt order and fallback behavior using a simulated executor.
+
+## SDK primitive
+
+`executeFallbackRoute` accepts a route plan and a caller-provided executor:
+
+```js
+const result = await executeFallbackRoute({
+  plan,
+  executor: async (service) => callProvider(service.endpoint)
+});
+```
+
+Sentinel does not hide spending logic inside fallback routing. Integrations remain responsible for payment/signing flows, while Sentinel supplies route order, policy checks, and telemetry hooks.