One-command local economic audit (experimental source workflow)

Use one command for a project or a previously collected real trace:

npx seenrelay audit . --json
npx seenrelay audit exported-traces.otlp.json --json
npx seenrelay audit exported-tool-observations.jsonl --json
npx seenrelay audit fleet-savings-ledger.json --overhead-usd 0.14 --json

The first-value meter in the human-readable audit output shows candidate files or observed repeated work immediately. Exported traces show gross potential only when the underlying cost is explicitly provided; a measured active savings ledger shows actual avoided executions and gross avoided cost, with net savings unknown until overhead is measured. It never attributes savings merely to installing SeenRelay. Use --json for the underlying evidence and exact claim boundaries.

The command selects the existing guided static prescreen, strict OpenTelemetry/trace/
Langfuse census, or savings-ledger reporter based on explicit input format. It runs locally and uploads nothing. It does not generate paid traffic, invent repetition, prove external customer savings, automatically enable reuse, or activate billing. For unknown formats it fails closed and asks you to use a specific command. A trace census reports possible work, not verified net savings. Always compare local/source/provider-native solutions first.

SeenRelay JavaScript / TypeScript client

Avoid redundant expensive validation.

Local-first, provider-independent client with zero third-party runtime dependencies. For eligible read-only work, reuse locally or privately first, use source-native checks when available, and keep the application's original validation as fallback.

Client 0.2.19 adds distributed shadow overlap measurement to the JavaScript / TypeScript fleet surface. Multiple workers can classify exact eligible calls that begin while the same coordinate already has an active shadow leader, while every authoritative operation still executes and no result is shared. The report records observed overlap and explicit caller cost provenance without labeling shadow cost as avoided savings. Active coordination and conservative savings receipts remain opt-in, fail-open, caller-scoped, and provider-native-control-first. Python remains behaviorally unchanged in 0.2.19. Shared evidence never authorizes reuse by itself.

Local zero-code prescreen

Before changing application code, run a local static prescreen:

npx seenrelay scan
# or machine-readable output
npx seenrelay scan . --json

# machine-readable adoption plan; never modifies code or enables reuse
npx seenrelay adopt-plan . --json

# combined prescreen + plan + next action for agents/operators
npx seenrelay guide . --json

The scanner reads supported text/source files locally, does not contact SeenRelay, does not upload source code, and does not modify the target project. It looks for metered or resource-intensive read-only work, recurring execution signals, stronger native/local controls, and supported integration boundaries.

Its states are deliberately pre-evidentiary: CANDIDATE_FOR_SHADOW_MEASUREMENT, NATIVE_CONTROL_FIRST, NEEDS_RUNTIME_EVIDENCE, or NO_ELIGIBLE_CANDIDATE_FOUND. Static analysis can never return a SeenRelay USE verdict or authorize reuse. A real USE / DO NOT USE / INSUFFICIENT EVIDENCE decision still requires natural-workload shadow measurement and comparison against the best measured non-shared path.

Local fleet trace census

If you already have caller-owned call traces, rank exact in-flight overlap before changing the workload:

npx seenrelay trace-census fleet-trace.jsonl
npx seenrelay trace-census fleet-trace.jsonl --json

The trace census is local-only and accepts sanitized events with opaque SHA-256 exact-coordinate hashes, start/end timestamps, worker identity, explicit shareability policy and optional caller-provenanced marginal cost. It rejects common raw prompt/argument/URL/result fields rather than retaining them.

The report separates observed overlap from successful-leader opportunities and leaves actual_avoided_executions / actual_net_savings_usd null. It is a way to find natural workloads worth instrumenting, not a shortcut around shadow evidence or native-control comparison. See docs/FLEET_TRACE_CENSUS.md and docs/FLEET_OVERLAP_GATE.md.

OpenTelemetry / OTLP substrate path

If the workload already emits OpenTelemetry traces, you can feed an OTLP/JSON export into the same conservative census without integrating SeenRelay with a specific agent framework:

npx seenrelay otel-trace-census traces.otlp.json
npx seenrelay otel-trace-census traces.otlp.json --json

The adapter does not infer safety from an HTTP/tool/CI span type. It admits only spans carrying an opaque seenrelay.coordinate_hash plus explicit SeenRelay policy attributes, and it does not copy raw tool arguments/results, prompts, URLs, headers or request bodies into the report. See docs/OTEL_TRACE_CENSUS.md.

Langfuse export census

If production traces already live in Langfuse, export TOOL observations and run a local candidate census before adding runtime coordination:

npx seenrelay langfuse-census observations.json --json

The command canonicalizes and hashes exact tool name + input locally, counts exact recurrence and in-flight overlap, and reports Langfuse-recorded TOOL cost when present. Raw tool input/output is not copied into the report.

This surface deliberately stops before a USE verdict: Langfuse recurrence does not prove read-only semantics, result compatibility, executor identity, freshness policy, or residual value after a native cache. See docs/LANGFUSE_CENSUS.md.

Shared CHECK assurance

seenrelay/assurance turns additive CHECK evidence into an explicit caller-side policy decision. The multi-signal preset requires at least two observer keys, two cryptographic continuity keys, and two reuse-independence buckets, plus matching value fingerprints and acceptable freshness.

import { createMultiSignalRetainedReusePolicy } from 'seenrelay/assurance';

const reuseRetained = createMultiSignalRetainedReusePolicy({
  maxAgeSeconds: 300
});

These signals reduce trivial poisoning risk; they do not establish truth or prove independent real-world actors. High-consequence validation should still require authoritative source confirmation under the application's own policy.

Deterministic coordinates

seenrelay/coordinates separates local call coordinates from shared source-backed fact descriptors. Do not guess semantic equivalence.

import {
  mcpToolCoordinate,
  openApiOperationCoordinate,
  jsonPointerFact
} from 'seenrelay/coordinates';

const localCall = mcpToolCoordinate({
  server: 'catalog-prod',
  name: 'catalog.read',
  arguments: { id: 42 }
});

const apiCall = openApiOperationCoordinate({
  service: 'catalog-api',
  operationId: 'getProduct',
  parameters: { id: 42 }
});

const fact = jsonPointerFact({
  subject: 'Product 42 stock',
  predicate: 'availability.current',
  source: 'https://api.example.com/products/42',
  jsonPointer: '/stock'
});

MCP/OpenAPI coordinates are local repetition keys only. Shared fact builders require a stable source-native locator and remain subject to SeenRelay's server-side fact identity contract.

Ambient MCP

Start in zero-behavior-change local shadow mode. The original tool call still runs; SeenRelay keeps only local fingerprints and aggregate counters. No shadow CHECK or OBSERVE is sent.

import { ambientMcpClient } from 'seenrelay/ambient';

const client = ambientMcpClient(rawMcpClient, { serverKey: 'docs' });
// use client.callTool(...) normally
console.log(client.seenRelayAmbient.getReport());

The report identifies exact repeated calls that are worth reviewing. It is an upper-bound diagnostic, not a savings claim. Native/source/provider validators and SeenRelay CHECK overhead have not yet been subtracted.

For OpenAI Agents JS:

import { ambientOpenAIAgentsMcpServer } from 'seenrelay/ambient';

const server = ambientOpenAIAgentsMcpServer(rawMcpServer);
// pass `server` to the Agent exactly as before

For AI SDK MCP tools:

import { ambientAiSdkMcpTools } from 'seenrelay/ambient';

const { tools, seenRelayAmbient } = ambientAiSdkMcpTools(await mcpClient.tools());

Active local-first protection is opt-in per exact MCP tool name. Unconfigured tools stay shadow-only:

const client = ambientMcpClient(rawMcpClient, {
  serverKey: 'docs',
  tools: {
    'document.read': { maxAgeMs: 30_000 }
  }
});

Do not enable active protection for mutating/destructive operations or for calls whose context/result equivalence has not been reviewed. Unknown call options fail closed from shadow equivalence measurement and preserve the authoritative call.

Install

npm install seenrelay

Local-first Zero-State

import { SeenRelayZeroState } from 'seenrelay/zero-state';

const edge = new SeenRelayZeroState({
  localMaxAgeMs: 30_000
});

const result = await edge.guard({
  coordinate: {
    tool: 'catalog.read',
    arguments: { id: 42 }
  },
  validate: async () => expensiveRead()
});

console.log(result.value);

Zero-State is useful without a populated public network:

• simultaneous identical calls are coalesced in-process;
• completed results are reused only inside an explicit freshness window;
• source-native ETag / Last-Modified validators can be retained for conditional confirmation;
• an optional caller-owned private L1 store can reuse encrypted entries across workers or restarts;
• shared SeenRelay CHECK is off by default and is only an optional accelerator;
• OBSERVE is never required to return the application's validated result.

The default completed-result freshness window is 0. SeenRelay does not invent a TTL for an arbitrary tool call.

Fleet-level exact in-flight coordination

Before enabling coordination, the same seenrelay/fleet surface can measure distributed exact in-flight overlap in shadow mode. The shadow meter uses caller-owned coordination metadata only: every authoritative operation still runs, no result is shared, and no CHECK or OBSERVE is sent.

import {
  SeenRelayFleetShadowMeter,
  createRedisRestFleetStore
} from 'seenrelay/fleet';

const store = createRedisRestFleetStore({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
  prefix: 'seenrelay:fleet:shadow:v0'
});

const meter = new SeenRelayFleetShadowMeter({
  store,
  scopeKey: process.env.SEENRELAY_FLEET_SCOPE
});

const result = await meter.measure({
  coordinate: {
    provider: 'openai',
    operation: 'responses.create',
    model,
    input
  },
  policy: {
    sideEffectClass: 'read_only',
    exactSingleAnswerShareable: true,
    independentSamplesRequired: false
  },
  execute: () => expensiveReadOnlyCall(),
  cost: {
    marginalCostUsd: 0.48,
    provenance: 'provider_list_price'
  }
});

console.log(meter.getReport());

callsWithIdenticalInflightPredecessor counts eligible calls that started while the same exact shadow coordinate already had an active leader lease. overlappedFollowerObservedCostUsd is cost that was actually incurred during shadow execution; it is not labeled as avoided savings. Mutations, independent sampling and a declared zero-cost provider-native exact response cache are excluded from overlap candidacy. Store failure leaves the authoritative operation untouched and marks that eligible call unclassified.

For a selected function whose semantics have already been reviewed, use the generic wrapper to remove coordinate/execute boilerplate:

import {
  wrapFleetShadowCall
} from 'seenrelay/fleet';

const measuredCall = wrapFleetShadowCall(
  meter,
  expensiveReadOnlyCall,
  {
    policy: {
      sideEffectClass: 'read_only',
      exactSingleAnswerShareable: true,
      independentSamplesRequired: false
    },
    cost: {
      marginalCostUsd: 0.48,
      provenance: 'provider_list_price'
    }
  }
);

await measuredCall(arg1, arg2);

By default, the exact argument list is the shadow coordinate. If the arguments are not safely JSON-canonicalizable, the call still executes and is reported as unclassified rather than being forced into a coordinate. Use coordinateFromArgs only when the application can define a stricter exact identity.

For expensive work repeated at the same time across separate workers, seenrelay/fleet can then coordinate one authoritative execution without turning the result into a sequential cache.

import {
  SeenRelayFleetCoordinator,
  createRedisRestFleetStore,
  fleetCodecFromPrivateCodec
} from 'seenrelay/fleet';
import { createAesGcmPrivateCodec } from 'seenrelay/zero-state';

const fleet = new SeenRelayFleetCoordinator({
  store: createRedisRestFleetStore({
    url: process.env.UPSTASH_REDIS_REST_URL,
    token: process.env.UPSTASH_REDIS_REST_TOKEN
  }),
  codec: fleetCodecFromPrivateCodec(
    createAesGcmPrivateCodec(Buffer.from(process.env.SEENRELAY_FLEET_KEY, 'base64'))
  ),
  scopeKey: process.env.SEENRELAY_FLEET_SCOPE
});

const result = await fleet.run({
  coordinate: {
    provider: 'openai',
    operation: 'responses.create',
    model: 'gpt-5.6-sol',
    input
  },
  policy: {
    sideEffectClass: 'read_only',
    exactSingleAnswerShareable: true,
    independentSamplesRequired: false
  },
  execute: () => expensiveReadOnlyCall()
});

Every result-affecting qualifier belongs in the coordinate. Different fleet scopes never coordinate. Mutations, independent sampling, underspecified policies, store failures, follower timeouts and codec failures preserve the application's authoritative path.

A Savings Report is measurement evidence, not an invoice, bill, charge or payment receipt. SeenRelay is currently free. Legacy API names such as onReceipt are retained for compatibility only.

To quantify value locally, attach a Savings Report ledger:

import { createFleetSavingsLedger } from 'seenrelay/fleet';

const savings = createFleetSavingsLedger();

await fleet.run({
  coordinate,
  policy: {
    sideEffectClass: 'read_only',
    exactSingleAnswerShareable: true,
    independentSamplesRequired: false
  },
  execute: expensiveReadOnlyTask,
  cost: {
    marginalCostUsd: 0.48,
    provenance: 'provider_list_price'
  },
  onReceipt: savings.record
});

console.log(savings.snapshot());
// avoidedExecutions counts only actual follower reuse.
// grossAvoidedCostUsd is null/absent from the savings record when cost is unknown.

You can turn the saved ledger or JSONL receipt stream into a conservative local Savings Report:

npx seenrelay savings-report fleet-savings-ledger.json --json
npx seenrelay savings-report fleet-receipts.jsonl --overhead-usd 0.14 --json

The command contacts nobody. It can confirm measured follower reuse and, when cost provenance exists, gross avoided cost. Net savings remain unknown unless measured SeenRelay overhead is supplied. Even a positive local net value does not emit a USE verdict or prove native/SOTA superiority, external customer adoption, customer ROI, or any payment obligation.

Cost metadata never authorizes coordination. If cost is unknown, SeenRelay reports avoided executions without inventing dollars. Receipt callback failures never change the application result.

If the provider already supplies a zero-cost exact response cache, declare that native control and SeenRelay steps aside.

This surface is deliberately narrower than semantic caching: it coordinates only an exact compatible operation that is already in flight.

Bind once around MCP tool calls

import { protectMcpClient } from 'seenrelay/mcp-auto';

const client = protectMcpClient(rawMcpClient, {
  serverKey: 'catalog-server',
  tools: {
    'catalog.read': {
      maxAgeMs: 30_000
    }
  }
});

const result = await client.callTool({
  name: 'catalog.read',
  arguments: { id: 42 }
});

Only exact tool names explicitly listed in tools are eligible. Unlisted tools pass through unchanged. A policy with no TTL still gains in-flight deduplication but does not reuse completed results sequentially.

The generic core does not infer that a tool is read-only from its name, description or an untrusted hint.

Generic dispatcher adapters

import { SeenRelayAuto, exactToolAdapter } from 'seenrelay/auto';

const auto = new SeenRelayAuto({
  adapters: [
    exactToolAdapter({
      toolNames: ['catalog.read'],
      maxAgeMs: 30_000
    })
  ]
});

const execute = auto.wrap(yourToolDispatcher);

Adapters are ordinary caller-side policy. Core modules do not depend on any particular scraping, browser, API or MCP provider.

Provider-specific integrations, when supplied, are optional subpath adapters. They cannot make their provider a runtime dependency of the core client. For example, the Firecrawl adapter lives under seenrelay/firecrawl; public relay evidence is opt-in in that adapter and intermediary provider-cache hits are not re-labeled as new independent observations.

Source-native conditional validation

For ordinary HTTP reads, source-native validators are preferable to guessing freshness:

import {
  SeenRelayZeroState,
  createConditionalFetchValidator
} from 'seenrelay/zero-state';

const edge = new SeenRelayZeroState();
const validate = createConditionalFetchValidator({
  url: 'https://api.example.com/item/42'
});

const result = await edge.guard({
  coordinate: { resource: 'https://api.example.com/item/42' },
  validate
});

When an earlier response carried a safe ETag or Last-Modified validator, a later validation can use If-None-Match or If-Modified-Since. A source 304 Not Modified confirms the retained value without requiring the public relay.

Optional private L1

A caller can supply both a private store and codec to reuse values across workers or restarts. SeenRelay ships an AES-256-GCM codec helper; the application owns the encryption key, storage and namespace.

import {
  SeenRelayZeroState,
  createAesGcmPrivateCodec
} from 'seenrelay/zero-state';

const edge = new SeenRelayZeroState({
  privateStore,
  privateCodec: createAesGcmPrivateCodec(keyBytes),
  privateMaxAgeMs: 30_000
});

Private values are not sent to the public SeenRelay service merely because L1 is enabled. Store/codec failures are fail-open to the application's normal validation path.

Classic shadow-first client

The original API remains available:

import { SeenRelayClient } from 'seenrelay';

const relay = new SeenRelayClient();

const value = await relay.guard({
  fact,
  knownValue,
  validate: ({ conditionalHeaders }) => expensiveValidation(conditionalHeaders)
});

Without an explicit reuse policy, the classic client never skips the original validation. It remains the conservative path for directly measuring public CHECK evidence.

Prove public-relay value before enabling classic reuse

import { SeenRelayClient } from 'seenrelay';
import { SeenRelayShadowProof } from 'seenrelay/shadow-proof';

const proof = new SeenRelayShadowProof(new SeenRelayClient());

const value = await proof.guard({
  fact,
  knownValue,
  validate: ({ conditionalHeaders }) => expensiveValidation(conditionalHeaders)
});

console.log(proof.report({
  avoidedValidationCost: 0.01
}));

Shadow Proof always keeps the original validation authoritative. For SAME_OBSERVED, it can compare the caller's known deterministic JSON value with the validation result and retain only aggregate agreement counters. Any observed mismatch fails safety evidence; an unavailable deterministic comparison leaves evidence incomplete. Compared raw values are not included in the snapshot or report. Safety-adjusted savings remain unavailable until the observed SAME_OBSERVED set passes strict agreement.

Potential economics still use caller-supplied costs and do not constitute a universal savings claim.

Collect natural-workload evidence for the hostile benchmark

JavaScript / TypeScript Shadow Proof can additionally retain a bounded local record for each naturally occurring protected validation. The record contains only CHECK outcome, simulated policy decision, agreement result, measured call timings and caller-supplied cost units. It does not retain the fact descriptor, source URL, known value, validated value or a per-call timestamp.

The simulated reuse policy runs only after the authoritative validation. It cannot suppress the validation or turn measurement into active reuse.

import {
  SeenRelayClient,
  reuseKnownOnSameObserved
} from 'seenrelay';
import { SeenRelayShadowProof } from 'seenrelay/shadow-proof';
import { evaluateHostileBenchmark } from 'seenrelay/economics';

const proof = new SeenRelayShadowProof(
  new SeenRelayClient(),
  { benchmarkRecordLimit: 10_000 }
);

await proof.guard({
  fact,
  knownValue,
  validate: ({ conditionalHeaders }) => expensiveValidation(conditionalHeaders),
  benchmark: {
    reuse: reuseKnownOnSameObserved,
    baselineCost: 5,
    checkCost: 0,
    observeCost: 0,
    observeAfterBaseline: true
  }
});

const benchmarkInput = proof.hostileBenchmarkInput({
  workloadId: 'opaque-run-id',
  controls: {
    local_cache: { available: true, measured: true },
    source_native_conditional: { available: true, measured: true },
    provider_native_cache: { available: true, measured: true }
  }
});

const evaluation = evaluateHostileBenchmark(benchmarkInput);

Use only a non-sensitive opaque workloadId. Every control marked available: true must actually have been measured against the same workload before the hostile evaluator accepts the evidence. CHECK failures remain in the sample as unavailable rather than disappearing. If a hypothetical reuse cannot be compared deterministically with the authoritative validation, safety evidence is incomplete; any observed mismatch fails it. Record overflow or an invalid simulated reuse policy invalidates export instead of silently truncating the sample.

The collector does not upload benchmark telemetry. Export is explicit and local. The evaluator reports evidence; automatic_reuse_enabled_by_evaluator is always false.

Firecrawl shadow economics

For an existing Firecrawl MCP client, seenrelay/firecrawl-shadow measures whether repeated public scrape work would benefit from shared CHECK without suppressing any Firecrawl call:

import { createFirecrawlShadowPilot } from 'seenrelay/firecrawl-shadow';

const measured = createFirecrawlShadowPilot(existingFirecrawlMcpClient);

await measured.callTool({
  name: 'firecrawl_scrape',
  arguments: {
    url: 'https://example.com/public-page',
    formats: ['markdown'],
    maxAge: 60_000
  }
});

await measured.seenRelayFirecrawlShadowPilot.flush();

const evaluation = measured.seenRelayFirecrawlShadowPilot.evaluate({
  workload_id: 'opaque-workload-id',
  local_cache: { available: false, measured: false },
  source_native_conditional: { available: false, measured: false }
});

The authoritative Firecrawl request always runs and returns before the counterfactual measurement needs to finish. A prior retained exact-result fingerprint is CHECKed only after the current provider result has completed and before the current result can contribute an OBSERVE. This keeps the experiment shadow-only and prevents a call from manufacturing its own hit.

Firecrawl provider-cache hits are retained as provider baseline evidence but are not re-labeled as independent OBSERVEs. If Firecrawl does not expose a usable creditsUsed value, cost evaluation remains incomplete unless the caller explicitly supplies a justified provider_credit_fallback_units in the same provider-credit unit. Local cache and source-native controls must be declared truthfully; an available but unmeasured control makes the hostile evaluator reject the evidence.

A favorable pilot result is evidence only for the measured workload. It does not enable reuse or establish a universal Firecrawl savings rate.

Direct Firecrawl JavaScript SDK shadow adapter

For applications that use the Firecrawl JavaScript SDK directly, the staged seenrelay/firecrawl-sdk-shadow subpath wraps current scrape(url, options) and legacy scrapeUrl(url, options) calls without changing provider behavior:

import { createFirecrawlSdkShadowPilot } from 'seenrelay/firecrawl-sdk-shadow';

const measured = createFirecrawlSdkShadowPilot(existingFirecrawlSdkClient, {
  // SeenRelay measurement horizon only. It is not added to the Firecrawl request.
  maxAgeMs: 60_000
});

const result = await measured.scrape('https://example.com/public-page', {
  formats: ['markdown']
});

await measured.seenRelayFirecrawlSdkShadowPilot.flush();

The original SDK method always runs with the exact argument list supplied by the application, and the exact raw provider result is returned. The adapter converts the successful result only inside the measurement bridge so it can reuse the existing Firecrawl shadow semantics. If that internal measurement serialization fails after Firecrawl succeeds, the provider result still returns successfully and shadow evidence for that call is simply unavailable.

Protocol boundary

The client does not add a third SeenRelay operation. The hosted service still exposes only CHECK and OBSERVE. SeenRelay reports source-backed observations; it does not browse, search, verify arbitrary facts on demand, act as a truth oracle or provide shared general-agent memory.

License

The client package is MIT licensed. The hosted SeenRelay service implementation remains governed by the repository root license.

Ambient framework integrations

Ambient integrations preserve the authoritative tool call and start in local-only shadow mode. They do not send CHECK or OBSERVE from shadow measurement and do not authorize reuse automatically.

import { ambientLangChainMcpHooks } from "seenrelay/ambient";
const hooks = ambientLangChainMcpHooks();
// pass hooks.beforeToolCall / hooks.afterToolCall to LangChain MCP adapters
console.log(hooks.seenRelayAmbient.getReport());

OpenAI Agents and AI SDK adapters remain available from the same seenrelay/ambient entry point.

Coding agents and integration tooling can inspect the installed package without network discovery:

import { getAmbientIntegrationCatalog } from "seenrelay/ambient";
console.log(getAmbientIntegrationCatalog());

The catalog is local metadata only. It adds no telemetry, hosted operation, or reuse authorization.