{
  "markdown": "# SeenRelay\n\nSeenRelay is a reuse layer for repeated read-only validation.\n\nIt sits in front of validation work an AI agent or application already performs. For an exact eligible repeat, it can use caller-owned local/private reuse, source-native freshness confirmation, or optional shared CHECK evidence. If none of those paths is sufficient, the original validation runs normally.\n\n<!-- BEGIN GENERATED:PUBLIC-FACTS -->\n**Install:** `npm install seenrelay` · `pip install seenrelay` · client v0.2.9 · currently free · no account/API key.\n\n**Measured first-party smoke result:** Firecrawl JSON extraction, n=3: 3/3 eligible provider calls avoided, 15 credits avoided, median 1265.68 ms fresh / 1039.5 ms provider-cached → 617.78 ms SeenRelay bounded reuse. This is a small first-party benchmark, not a promised reuse rate.\n<!-- END GENERATED:PUBLIC-FACTS -->\n\n## First proof: measure without changing application behavior\n\nAmbient wraps an existing MCP-style client in local shadow mode. The authoritative call still runs; SeenRelay measures exact repetition and produces a local report.\n\nJavaScript / TypeScript:\n\n```bash\nnpm install seenrelay\n```\n\n```js\nimport { ambientMcpClient } from 'seenrelay/ambient';\n\nconst client = ambientMcpClient(rawMcpClient);\n// use client.callTool(...) normally\nconsole.log(client.seenRelayAmbient.getReport());\n```\n\nPython:\n\n```bash\npip install seenrelay\n```\n\n```python\nfrom seenrelay_ambient import ambient_mcp_client\n\nclient = ambient_mcp_client(raw_mcp_client)\n# await client.call_tool(...) normally\nprint(client.get_report())\n```\n\nFor a compatible coding agent, install the Agent Skill directly from the canonical domain:\n\n```bash\nnpx skills add https://seenrelay.com --skill seenrelay --yes\n```\n\nRun the existing workload and inspect the report before enabling any bounded reuse. Shared CHECK remains optional and off by default in Zero-State.\n\nSeenRelay has exactly two hosted domain operations: `CHECK` and `OBSERVE`. It reports recent observations, not universal truth.\n\nJavaScript/TypeScript and Python 0.2.9 add multi-signal shared-evidence assurance helpers and deterministic Fact Coordinate Kit v1. JavaScript/TypeScript keeps Zero-State local-first; Python remains shadow-first by default. Shared evidence is explicit caller policy, does not prove truth or independent real-world actors, and MCP/OpenAPI coordinates are local repetition keys unless a stable source-native locator supports a shared fact descriptor. Provider-specific adapters are optional.\n\n## What it can avoid\n\nEven with no shared observation:\n\n- simultaneous identical eligible calls can be coalesced in-process;\n- completed read-only results can be reused only inside an explicit caller-defined freshness window;\n- optional encrypted caller-owned L1 storage can reuse values across workers or restarts;\n- ETag / Last-Modified can support source-native conditional confirmation without a shared CHECK;\n- shared CHECK is optional in Zero-State and is not placed on the hot path merely because SeenRelay is installed;\n- after a genuinely fresh independent validation, OBSERVE can add evidence that may help later callers.\n\nAccess is **currently free** and requires no account or API key.\n\n## Start here\n\n- Public install: `npm install seenrelay` or `pip install seenrelay`\n- JavaScript / TypeScript Zero-State: [`clients/typescript/README.md`](clients/typescript/README.md)\n- Fleet economics and measured examples: `https://seenrelay.com/economics`\n- Client overview: [`clients/README.md`](clients/README.md)\n- Integration choices and MCP setup: [`docs/CLIENTS.md`](docs/CLIENTS.md)\n- Quickstart: [`docs/QUICKSTART.md`](docs/QUICKSTART.md)\n- Protocol contract: [`docs/PROTOCOL.md`](docs/PROTOCOL.md)\n- Web quickstart: `https://seenrelay.com/quickstart`\n- Web client integrations: `https://seenrelay.com/clients`\n- MCP endpoint: `https://seenrelay.com/mcp`\n- Official MCP Registry: `io.github.ovladon/seenrelay`\n- OpenAPI: `https://seenrelay.com/openapi.json`\n- Machine descriptor: `https://seenrelay.com/service.json`\n- Machine-oriented index: `https://seenrelay.com/llms.txt`\n\n## How it works\n\nFor eligible JavaScript/TypeScript Zero-State calls, the preferred order is:\n\n1. exact in-process reuse / coalescing when safe;\n2. optional caller-owned private reuse;\n3. source-native conditional confirmation when available;\n4. optional shared SeenRelay CHECK when configured and useful;\n5. the application's original validation as fallback;\n6. OBSERVE only after a fresh independent validation that is eligible for contribution.\n\nFor direct REST/MCP or the classic wrapper, CHECK and OBSERVE remain available exactly as before.\n\nPossible CHECK statuses are `SAME_OBSERVED`, `CHANGED_OBSERVED`, `CONTESTED`, `STALE`, and `UNKNOWN`.\n\n`SAME_OBSERVED` means the same value was recently observed for the same deterministic fact identity. It is not a truth verdict. The consuming agent decides whether the evidence is sufficient for its own policy.\n\n## JavaScript / TypeScript Zero-State\n\n```js\nimport { SeenRelayZeroState } from 'seenrelay/zero-state';\n\nconst edge = new SeenRelayZeroState({\n  localMaxAgeMs: 30_000\n});\n\nconst result = await edge.guard({\n  coordinate: {\n    tool: 'catalog.read',\n    arguments: { id: 42 }\n  },\n  validate: async () => expensiveRead()\n});\n\nconsole.log(result.value);\n```\n\nThe default completed-result freshness window is `0`. SeenRelay does not invent a TTL for arbitrary calls. Mutation/destructive operations must not be suppressed; generic core does not infer read-only safety from tool names, descriptions or untrusted annotations.\n\nFor MCP clients, `seenrelay/mcp-auto` can bind once around explicitly allowlisted `callTool()` operations. Unlisted tools pass through unchanged.\n\n## Classic shadow-first path\n\nThe original JavaScript/TypeScript and Python APIs remain available. Without an explicit reuse policy they CHECK, keep the original validation, and OBSERVE the independently obtained result best-effort.\n\n```js\nconst relay = new SeenRelayClient();\n\nconst validatePrice = relay.protectValidation({\n  fact,\n  validate: ({ conditionalHeaders }) => existingValidation(conditionalHeaders)\n});\n\nconst value = await validatePrice(knownValue);\n```\n\nPython exposes the equivalent `protect_validation(...)` path. Use Shadow Proof when you specifically want to measure public CHECK evidence before enabling classic bounded reuse.\n\n## Source-native revalidation\n\nSource-native validators are preferable to guessing freshness. When a retained response carries a safe ETag or Last-Modified validator, a later eligible validation can try `If-None-Match` or `If-Modified-Since`. A `304 Not Modified` response is confirmation from the source, not from SeenRelay.\n\nThe classic CHECK/OBSERVE path can also carry observer-supplied ETag / Last-Modified metadata as an explicitly unverified conditional-request hint. The caller still decides whether source confirmation is required.\n\n## Optional private L1\n\nJavaScript/TypeScript Zero-State can use a caller-supplied private store plus codec for reuse across workers or restarts. SeenRelay provides an AES-256-GCM codec helper; the caller owns the key, storage and namespace.\n\nPrivate values are not sent to the public SeenRelay service merely because private L1 is enabled. Store or codec failure fails open into the application's normal validation path.\n\n## Fact identity\n\nSeenRelay uses the versioned `seenrelay-fact-v3` identity contract. Identity precedence is:\n\n1. stable source-native locator (`json_pointer`, `element_id`, `source_key`);\n2. canonical machine predicate when no stable locator exists.\n\nHuman-readable `subject` text and mutable observed content do not enter the fact key. Source URLs are canonicalized deterministically without browsing. Credential- or signature-bearing source URLs are rejected before stateful admission.\n\nSee [`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the complete contract.\n\n## Observer provenance\n\n`OBSERVE` supports optional transport-independent `ed25519-v1` proof-of-possession. A valid proof establishes key possession, continuity, and payload integrity. It does not establish legal identity, independent real-world actor identity, or truth.\n\nAn intermediary provider-cache hit is not re-labeled as a new independent OBSERVE merely because a different caller received it.\n\n## Access and contribution\n\nSeenRelay issues signed ephemeral operational leases without account creation. `CHECK` and `OBSERVE` are currently free to use. Contribution credit is based on later qualifying reuse rather than raw submission volume.\n\nHive classes describe operational contribution only; they are not identity or truth scores.\n\n## Public interfaces\n\nThe canonical domain is `seenrelay.com`.\n\n- Browser `Accept: text/html` at `/` receives the public landing page.\n- Generic/API requests to `/` receive the machine descriptor.\n- `/service.json` exposes the explicit machine descriptor.\n- `/public-stats.json` exposes privacy-safe aggregate activity.\n- `/openapi.json` exposes the REST contract.\n- `/mcp` exposes MCP `2026-07-28`.\n- `/quickstart` and `/clients` provide integration instructions.\n\n## Product boundary\n\nSeenRelay itself does not browse or search fact sources, perform on-demand external verification, call an LLM to decide truth, or expose a shared general-agent memory. `UNKNOWN` simply means no sufficiently recent reusable shared observation is available.\n\nClient-side adapters can use source-native validation or integrate with existing providers, but provider adapters are optional and cannot become dependencies of the provider-independent core.\n\n## Architecture\n\n- Vercel managed deployment\n- Neon Postgres state store\n- Hono + TypeScript / Node 22\n- REST/OpenAPI\n- MCP `2026-07-28` through the official v2 server SDK\n- provider-independent JavaScript/TypeScript Zero-State client plus classic JavaScript/TypeScript and Python wrappers\n- authenticated human-only Control Room for runtime operations and incident controls\n\nA2A is monitored but is not advertised as an implemented product interface.\n\n## Verification\n\n`npm run check` performs TypeScript checks, product guardrails, production dependency auditing, structural tests, and runtime tests. Package Validation clean-installs built npm/PyPI artifacts. The Preview Release Gate additionally exercises REST, MCP, fact identity, security boundaries, runtime controls, and reuse accounting against the exact Preview deployment SHA before Production promotion.\n\nBuilds use the committed lockfile and `npm ci`.\n\n## Maintenance\n\nDependabot and Standards Watch prepare isolated maintenance work. Production changes remain subject to compatibility, security, CI, and Preview verification gates.\n\n## Bootstrap\n\n```bash\nnpm ci\nnpm run check\n# DATABASE_ADMIN_URL must be set only for this migration command\nnpm run db:migrate\n```\n\nDeployment details are in [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).\n",
  "bytes": 10878,
  "sha": "77c1d69d271b90df628fe9eea1b5ee8594564ec761793cf99445653547bb0e86",
  "repo_slug": "ovladon/seenrelay",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ovladon_seenrelay_45073e12/readme"
}