@retinue/agentkit 0.1.0

package/dist/loadtest/runbooks.js

@@ -0,0 +1,159 @@
+/**
+ * The runbooks — AC-5: "runbooks exist for every failure mode observed in testing".
+ *
+ * Kept as data next to the failure matrix, so a test can assert the two agree. A runbook in a wiki is a runbook
+ * that drifts from the code silently, and the drift is discovered during the incident it was written for.
+ *
+ * Each one is written for someone woken at 3am: what they will see, what to check first, what to do, and — the
+ * part usually missing — **what not to do**. Most of the damage in an incident comes from a well-intentioned
+ * action that fights the recovery mechanism, and "do not restart the workers, the reaper is already handling it"
+ * is the sentence that saves the night.
+ */
+import { FAILURE_MODES } from "./injection.js";
+export const RUNBOOKS = {
+    "provider-timeout": {
+        mode: "provider-timeout",
+        symptoms: [
+            "agentkit_model_latency_ms p99 pinned at the provider timeout",
+            "agentkit_retries_total climbing",
+            "agentkit_run_duration_ms following, with throughput falling",
+        ],
+        confirm: [
+            "model.failed log lines with errorCode=timeout, not rate-limited — the two need different responses",
+            "agentkit_model_calls_total{outcome=error} rising while tool metrics stay flat, which locates it at the provider",
+        ],
+        action: [
+            "Nothing, first: retries are bounded and runs will fail cleanly rather than hang.",
+            "If it persists beyond the provider's own status page, fail over the model configuration to a second provider.",
+            "Runs that failed are safe to re-drive — the checkpoint means a resumed run does not repeat a completed tool call.",
+        ],
+        doNot: [
+            "Do not raise the retry count to ride it out. Retries hold a worker slot, so more retries against a dead provider converts a provider outage into a queue backlog.",
+            "Do not raise the provider timeout. A longer timeout holds the same slot for longer and reaches the same place more slowly.",
+        ],
+        expectedRecovery: "Immediate once the provider answers; in-flight runs fail after their retry budget and can be re-driven.",
+    },
+    "provider-rate-limit": {
+        mode: "provider-rate-limit",
+        symptoms: [
+            "agentkit_retries_total with reason=rate-limited",
+            "throughput drops while error rate stays near zero — the shape of working backoff",
+        ],
+        confirm: ["run.retry-scheduled log lines", "the provider's own quota dashboard"],
+        action: [
+            "Reduce worker concurrency. Fewer parallel calls means fewer rejections and, counter-intuitively, more completed work.",
+            "If sustained, raise the provider quota or spread across provider accounts.",
+        ],
+        doNot: [
+            "Do not add workers. More workers means more concurrent calls against the same quota, so throughput falls as the rejection rate rises.",
+            "Do not disable the retry. A rate limit is the one failure that genuinely does resolve by waiting.",
+        ],
+        expectedRecovery: "Throughput returns as the provider's window rolls; no run is lost.",
+    },
+    "redis-unavailable": {
+        mode: "redis-unavailable",
+        symptoms: [
+            "enqueue errors with code=unavailable, immediately rather than after a hang",
+            "queue depth unreadable; no new claims",
+            "runs already claimed continue to completion",
+        ],
+        confirm: [
+            "run.enqueue-failed log lines with errorCode=unavailable",
+            "in-flight runs still reaching terminal states, which distinguishes this from a database problem",
+        ],
+        action: [
+            "Restore Redis. The reaper re-enqueues anything whose lease expired while it was down.",
+            "Callers that received the typed error may retry; the job id is derived from tenant and run, so a repeat enqueue collapses into one job.",
+        ],
+        doNot: [
+            "Do not re-drive runs by hand while Redis is down; there is nowhere for the job to go and the attempt fails.",
+            "Do not clear the queue to 'start clean'. Those jobs are the record of admitted work.",
+        ],
+        expectedRecovery: "Claims resume immediately; expired leases are re-enqueued within one reap interval.",
+    },
+    "database-unavailable": {
+        mode: "database-unavailable",
+        symptoms: [
+            "claims stop entirely; runs fail with code=unavailable",
+            "queue depth rises because nothing can be claimed",
+            "connection errors in the worker logs",
+        ],
+        confirm: ["run.failed with errorCode=unavailable across every worker at once, which is what separates this from one bad worker"],
+        action: [
+            "Restore the database. Runs resume from their last checkpoint, so a multi-step run does not restart from the beginning.",
+            "Expect a burst of reaper activity as leases that expired during the outage are collected.",
+        ],
+        doNot: [
+            "Do not truncate or reset anything to clear the errors. The run rows and checkpoints are what makes resumption possible.",
+            "Do not restart workers repeatedly; a worker with no database cannot claim, and restarting only loses its in-memory state.",
+        ],
+        expectedRecovery: "Claims resume immediately; checkpointed runs continue from their last committed step.",
+    },
+    "database-failover": {
+        mode: "database-failover",
+        symptoms: ["a burst of connection errors, then recovery", "a spike in reaped runs shortly after"],
+        confirm: ["the failover event in the database provider's own log, correlated with the error burst"],
+        action: [
+            "Wait. The compare-and-set claim and the per-step checkpoint mean a half-applied step is never observable, so recovery is automatic.",
+            "Check that the connection pool reconnected — a pool holding dead connections looks exactly like a database still being down.",
+        ],
+        doNot: [
+            "Do not re-drive runs during the failover window. They are still claimed until their leases expire, and a manual re-drive races the reaper.",
+        ],
+        expectedRecovery: "Seconds to the provider's failover time, plus one lease interval for runs that were mid-step.",
+    },
+    "worker-kill": {
+        mode: "worker-kill",
+        symptoms: [
+            "one worker disappears; its runs sit in 'running' with no progress",
+            "claim latency p99 rises by roughly one lease interval",
+        ],
+        confirm: ["run.reaped log lines naming the runs, one lease interval after the worker went", "the killed worker's workerId absent from recent run.claimed lines"],
+        action: [
+            "Nothing. The lease expires, the reaper re-enqueues, another worker resumes from the checkpoint.",
+            "If the worker was killed by the OOM killer, reduce concurrency before bringing it back or it will be killed again.",
+        ],
+        doNot: [
+            "Do not re-drive the runs by hand before the lease expires. The claim is still held, so the manual attempt is rejected — and if it were not, it would be the duplicate-external-action bug this platform is built to prevent.",
+            "Do not shorten the lease to speed recovery. A lease shorter than a slow step causes a *live* worker to lose its claim mid-run, which is a much worse failure.",
+        ],
+        expectedRecovery: "One lease interval plus one reap interval.",
+    },
+    "slow-consumer": {
+        mode: "slow-consumer",
+        symptoms: ["a subscriber falling behind its run's event sequence", "no producer-side memory growth"],
+        confirm: ["the subscriber's last acknowledged sequence lagging the run's current sequence"],
+        action: [
+            "Nothing on the platform side: the durable event log means a slow reader holds no producer buffer and resumes from its own sequence.",
+            "Investigate the client. A consistently slow subscriber is usually rendering every event rather than batching.",
+        ],
+        doNot: [
+            "Do not raise a buffer size to 'give it room'. A producer-side buffer is precisely what turns one slow client into the platform's memory problem.",
+        ],
+        expectedRecovery: "The subscriber catches up at its own pace; nothing is lost while it is behind.",
+    },
+    overload: {
+        mode: "overload",
+        symptoms: [
+            "queue depth at its bound",
+            "admissions refused with code=resource-exhausted",
+            "RSS flat — which is the point",
+        ],
+        confirm: [
+            "run.refused-quota or a resource-exhausted rate rising while error rate stays low",
+            "flat memory alongside the refusals; memory growth instead means the bound is not being enforced",
+        ],
+        action: [
+            "Add workers if the database can take the extra connections; otherwise raise capacity upstream.",
+            "Refusals are the correct behaviour. Communicate them as capacity, not as errors.",
+        ],
+        doNot: [
+            "Do not raise maxQueueDepth to stop the refusals. That converts an honest 'no' into an unbounded backlog, and the queue then fails by exhausting memory instead of by saying no.",
+            "Do not disable admission checks to 'let the work through'. A refused run holds no slot and no job; an admitted one it cannot serve holds both.",
+        ],
+        expectedRecovery: "Immediate once offered load falls below capacity; the backlog drains at the sustainable rate.",
+    },
+};
+/** Every mode has a runbook. Asserted, so a new injector cannot ship undocumented. */
+export const modesWithoutRunbook = () => FAILURE_MODES.filter((mode) => RUNBOOKS[mode] === undefined);
+//# sourceMappingURL=runbooks.js.map

package/dist/loadtest/scenario.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The traffic mix and the synthetic engine — the load the harness actually offers.
+ *
+ * **Why the engine is synthetic, and why that is not a compromise.** A load test cannot drive a real model
+ * provider: it would cost money proportional to the load, the provider's own rate limits would become the thing
+ * under test, and a provider outage would look like a platform bug. Nobody load-tests through a paid third
+ * party. What *is* under test is the platform — the claim, the lease, the checkpoint, the queue, the event log,
+ * the idempotency of external effects — and every one of those is real here.
+ *
+ * The engine's job is therefore to be a *believable* source of latency and failure, and its knobs are exactly
+ * the failure modes #144 lists: a timeout, a rate limit, a tool that performs an external effect, and an
+ * approval that suspends the run.
+ *
+ * The one thing it must get right is the **external effect**: it performs a side effect under an idempotency
+ * key, so "no duplicated external action" becomes a count of effects against a count of distinct keys rather
+ * than a reading of logs.
+ */
+import type { AgentEngine } from "../runtime/worker.js";
+export type TrafficShape = {
+    /** Steps a run takes before completing. More steps means more checkpoints and more to lose on a kill. */
+    readonly steps: number;
+    /** Simulated model latency per step. */
+    readonly modelLatencyMs: number;
+    /** Fraction of runs that call a tool with an external effect. */
+    readonly externalActionRate: number;
+    /** Fraction of runs that pause for an approval. */
+    readonly approvalRate: number;
+    /** Fraction of steps where the provider times out before eventually succeeding. */
+    readonly providerTimeoutRate: number;
+    /** Fraction of steps the provider rate-limits. */
+    readonly rateLimitRate: number;
+};
+/**
+ * The default mix.
+ *
+ * Chosen to look like the product rather than to look good: most runs are a few steps of model output, a
+ * meaningful minority calls a tool that touches the outside world, and a smaller minority stops for a human. A
+ * mix with no approvals would miss the longest-lived state the platform has, and a mix with no external actions
+ * would make the one assertion that matters untestable.
+ */
+export declare const DEFAULT_TRAFFIC: TrafficShape;
+/** Where the synthetic external effects are counted. Shared by the engine and the assertions. */
+export type EffectLedger = {
+    /** Every effect performed, in order, with the key it was performed under. */
+    readonly performed: {
+        readonly key: string;
+        readonly atMs: number;
+    }[];
+    perform(key: string, atMs: number): void;
+    /** Distinct keys. Compared against `performed.length` — equality is "no duplicate". */
+    distinctKeys(): number;
+};
+export declare const createEffectLedger: () => EffectLedger;
+/**
+ * Deterministic pseudo-randomness.
+ *
+ * A seeded generator, so a run that found a failure can be replayed exactly. `Math.random()` would make the
+ * interesting runs — the ones that broke — unrepeatable, which is the opposite of what a load test is for.
+ */
+export declare const seededRandom: (seed: number) => (() => number);
+/**
+ * Two stable, well-distributed fractions from a run id.
+ *
+ * Stable because a resumed run must draw the same fate as its first attempt — `Math.random()` and a shared
+ * generator both fail at that, and a scenario that changes under a resume can make no claim about resumption.
+ *
+ * Well-distributed because the first version was not, and it mattered. Plain FNV-1a with two different offset
+ * bases, taken as a raw fraction, gave 0.03 external-action rate for one id prefix and 0.50 for another against a
+ * configured 0.30 — the low bits are poorly mixed and two bases correlate. So: FNV-1a over a *salted* string,
+ * then murmur3's `fmix32` avalanche. A biased traffic mix is a load test that measures a different workload than
+ * the one it reports, and nothing in the output would have said so.
+ */
+export declare const runFate: (runId: string) => {
+    readonly a: number;
+    readonly b: number;
+};
+export type SyntheticEngineDeps = {
+    readonly traffic: TrafficShape;
+    readonly effects: EffectLedger;
+    readonly random: () => number;
+    readonly now?: () => number;
+    /** Injected so a test does not actually wait. Real runs pass a real sleep. */
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/** A rate-limit failure shaped like a provider's, so the retry path treats it the way it would in production. */
+export declare class SyntheticRateLimit extends Error {
+    readonly code = "rate-limited";
+    readonly retryable = true;
+    constructor();
+}
+export declare class SyntheticTimeout extends Error {
+    readonly code = "timeout";
+    readonly retryable = true;
+    constructor();
+}
+/**
+ * The engine.
+ *
+ * Resumable, because the whole point of the worker-kill case is that a restarted run must not redo work. It
+ * reads `resume` and skips the steps already in the checkpoint — and the external effect is keyed on the run and
+ * the step, so a step that *is* redone reuses its key and the duplicate is detectable rather than invisible.
+ */
+export declare const createSyntheticEngine: (deps: SyntheticEngineDeps) => AgentEngine;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/loadtest/scenario.js

@@ -0,0 +1,208 @@
+/**
+ * The traffic mix and the synthetic engine — the load the harness actually offers.
+ *
+ * **Why the engine is synthetic, and why that is not a compromise.** A load test cannot drive a real model
+ * provider: it would cost money proportional to the load, the provider's own rate limits would become the thing
+ * under test, and a provider outage would look like a platform bug. Nobody load-tests through a paid third
+ * party. What *is* under test is the platform — the claim, the lease, the checkpoint, the queue, the event log,
+ * the idempotency of external effects — and every one of those is real here.
+ *
+ * The engine's job is therefore to be a *believable* source of latency and failure, and its knobs are exactly
+ * the failure modes #144 lists: a timeout, a rate limit, a tool that performs an external effect, and an
+ * approval that suspends the run.
+ *
+ * The one thing it must get right is the **external effect**: it performs a side effect under an idempotency
+ * key, so "no duplicated external action" becomes a count of effects against a count of distinct keys rather
+ * than a reading of logs.
+ */
+import { asId } from "../core/ids.js";
+/**
+ * The default mix.
+ *
+ * Chosen to look like the product rather than to look good: most runs are a few steps of model output, a
+ * meaningful minority calls a tool that touches the outside world, and a smaller minority stops for a human. A
+ * mix with no approvals would miss the longest-lived state the platform has, and a mix with no external actions
+ * would make the one assertion that matters untestable.
+ */
+export const DEFAULT_TRAFFIC = {
+    steps: 3,
+    modelLatencyMs: 40,
+    externalActionRate: 0.3,
+    approvalRate: 0.1,
+    providerTimeoutRate: 0,
+    rateLimitRate: 0,
+};
+export const createEffectLedger = () => {
+    const performed = [];
+    return {
+        performed,
+        perform(key, atMs) {
+            // Deliberately **not** deduplicated here. The platform's idempotency is what is under test, so a ledger
+            // that refused a repeat would be answering the question on the platform's behalf and every run would pass.
+            performed.push({ key, atMs });
+        },
+        distinctKeys: () => new Set(performed.map((p) => p.key)).size,
+    };
+};
+/**
+ * Deterministic pseudo-randomness.
+ *
+ * A seeded generator, so a run that found a failure can be replayed exactly. `Math.random()` would make the
+ * interesting runs — the ones that broke — unrepeatable, which is the opposite of what a load test is for.
+ */
+export const seededRandom = (seed) => {
+    let state = seed >>> 0 || 1;
+    return () => {
+        // xorshift32. Small, fast, and good enough to pick a branch; it is choosing traffic, not generating keys.
+        state ^= state << 13;
+        state ^= state >>> 17;
+        state ^= state << 5;
+        return ((state >>> 0) % 1_000_000) / 1_000_000;
+    };
+};
+/**
+ * Two stable, well-distributed fractions from a run id.
+ *
+ * Stable because a resumed run must draw the same fate as its first attempt — `Math.random()` and a shared
+ * generator both fail at that, and a scenario that changes under a resume can make no claim about resumption.
+ *
+ * Well-distributed because the first version was not, and it mattered. Plain FNV-1a with two different offset
+ * bases, taken as a raw fraction, gave 0.03 external-action rate for one id prefix and 0.50 for another against a
+ * configured 0.30 — the low bits are poorly mixed and two bases correlate. So: FNV-1a over a *salted* string,
+ * then murmur3's `fmix32` avalanche. A biased traffic mix is a load test that measures a different workload than
+ * the one it reports, and nothing in the output would have said so.
+ */
+export const runFate = (runId) => {
+    const fnv = (text) => {
+        let h = 0x811c9dc5;
+        for (let i = 0; i < text.length; i += 1) {
+            h ^= text.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        return h >>> 0;
+    };
+    // murmur3 fmix32. Without it the low bits stay correlated with the input and sequential ids cluster.
+    const mix = (h0) => {
+        let h = h0 >>> 0;
+        h ^= h >>> 16;
+        h = Math.imul(h, 0x85ebca6b) >>> 0;
+        h ^= h >>> 13;
+        h = Math.imul(h, 0xc2b2ae35) >>> 0;
+        h ^= h >>> 16;
+        return (h >>> 0) / 0x1_0000_0000;
+    };
+    // Two different *strings*, not two different bases: salting the input decorrelates the pair, changing the
+    // basis does not.
+    return { a: mix(fnv(`effect:${runId}`)), b: mix(fnv(`approval:${runId}`)) };
+};
+/** A rate-limit failure shaped like a provider's, so the retry path treats it the way it would in production. */
+export class SyntheticRateLimit extends Error {
+    code = "rate-limited";
+    retryable = true;
+    constructor() {
+        super("synthetic rate limit");
+        this.name = "SyntheticRateLimit";
+    }
+}
+export class SyntheticTimeout extends Error {
+    code = "timeout";
+    retryable = true;
+    constructor() {
+        super("synthetic provider timeout");
+        this.name = "SyntheticTimeout";
+    }
+}
+/**
+ * The engine.
+ *
+ * Resumable, because the whole point of the worker-kill case is that a restarted run must not redo work. It
+ * reads `resume` and skips the steps already in the checkpoint — and the external effect is keyed on the run and
+ * the step, so a step that *is* redone reuses its key and the duplicate is detectable rather than invisible.
+ */
+export const createSyntheticEngine = (deps) => {
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    return {
+        async *run(input) {
+            const { traffic } = deps;
+            /**
+             * How far a previous attempt got — counted from the engine's **own** step parts.
+             *
+             * Not `parts.length`, and not `resume.step`. `parts.length` was the first version and it was wrong: the
+             * approval marker is a part too, so a run that paused for approval came back with `alreadyDone` already
+             * equal to `steps`, skipped the loop entirely, never yielded `run.completed`, and sat in
+             * `waiting-for-approval` forever. Sixty-five of a hundred and sixty runs did exactly that, and the
+             * staircase reported it as an error rate rather than as a resume bug — which is what a `stuckByStatus`
+             * breakdown was worth adding for.
+             *
+             * `resume.step` is no good either: the runtime derives it from *tool-call* parts, and this engine emits
+             * none. It would be zero forever and every resumed run would redo all its work — including its external
+             * action, which is precisely the duplicate this whole exercise exists to detect.
+             */
+            const stepPart = new RegExp(`^${input.run.id}-p\\d+$`);
+            const alreadyDone = (input.resume?.parts ?? []).filter((part) => stepPart.test(part.id)).length;
+            // Derived from the **run id**, not from the shared generator.
+            //
+            // A real bug the first time: `deps.random()` advances global state, so a resumed run drew *different*
+            // values than its first attempt — a run that had performed its external action could come back deciding it
+            // never does one, and a run that paused for approval could resume deciding to pause again, forever. A load
+            // test whose scenario is not stable across a resume cannot make any claim about resumption at all.
+            const fate = runFate(input.run.id);
+            const doesExternalAction = fate.a < traffic.externalActionRate;
+            const pausesForApproval = fate.b < traffic.approvalRate;
+            for (let step = alreadyDone; step < traffic.steps; step += 1) {
+                if (input.signal.isCancelled())
+                    return;
+                if (deps.random() < traffic.rateLimitRate)
+                    throw new SyntheticRateLimit();
+                if (deps.random() < traffic.providerTimeoutRate)
+                    throw new SyntheticTimeout();
+                await sleep(traffic.modelLatencyMs);
+                yield {
+                    type: "part.added",
+                    part: {
+                        id: `${input.run.id}-p${step}`,
+                        type: "text",
+                        schemaVersion: 1,
+                        createdAt: new Date(now()).toISOString(),
+                        text: `step ${step}`,
+                    },
+                };
+                // The external effect on the *last* step, so a kill mid-run lands before it and recovery has to decide
+                // whether to redo it. Placing it on the first step would make the interesting case unreachable.
+                if (doesExternalAction && step === traffic.steps - 1) {
+                    // Keyed on run and step, which is what the platform's own idempotency key would be derived from. A key
+                    // including an attempt number would make every retry unique and the duplicate check vacuous.
+                    deps.effects.perform(`${input.run.id}:${step}`, now());
+                }
+                // The approval is requested once, on the step *after* it is recorded, so `alreadyDone` on resume is past
+                // it. Without the marker part the resumed run reaches the same step, requests approval again, and pauses
+                // forever — which looks exactly like a platform that cannot resume.
+                if (pausesForApproval && step === Math.floor(traffic.steps / 2)) {
+                    yield {
+                        type: "part.added",
+                        part: {
+                            id: `${input.run.id}-approval-mark`,
+                            type: "text",
+                            schemaVersion: 1,
+                            createdAt: new Date(now()).toISOString(),
+                            text: "approval requested",
+                        },
+                    };
+                    yield {
+                        type: "approval.requested",
+                        interactionId: asId(`${input.run.id}-a`),
+                        toolName: "publish_post",
+                        summary: "publish",
+                        riskCategory: "external-write",
+                    };
+                    // Suspend. The harness decides the approval, which is what makes approval wait time measurable and
+                    // what exercises the longest-lived state the platform holds.
+                    return;
+                }
+            }
+            yield { type: "run.completed" };
+        },
+    };
+};
+//# sourceMappingURL=scenario.js.map

package/dist/mcp/egress.d.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP egress policy — `docs/10-mcp-integration.md` → Egress and trust.
+ *
+ * A tenant's MCP endpoint is validated *before any handshake*, at registration and again at connect.
+ * HTTP endpoints are checked against scheme/host rules and blocked from reaching private/loopback
+ * addresses (SSRF defense); stdio commands are checked against an explicit allow-list. Anything not
+ * allowed is rejected — the safe default is deny.
+ */
+import type { McpTransport } from "./index.js";
+export type EgressPolicy = {
+    /** If set, only these HTTP hosts are permitted (allow-list). */
+    readonly allowedHttpHosts?: readonly string[];
+    /** Permitted URL schemes for HTTP transports. Defaults to `["https"]`. */
+    readonly allowedSchemes?: readonly string[];
+    /** Explicit allow-list of stdio commands. Stdio is denied unless a command matches. */
+    readonly allowedStdioCommands?: readonly string[];
+    /** Allow private/loopback addresses (dev only). Defaults to false. */
+    readonly allowPrivateNetworks?: boolean;
+};
+/** Normalize a host for policy checks: lowercase, strip IPv6 brackets and a trailing dot (`a.` ≡ `a`). */
+export declare const normalizeHost: (host: string) => string;
+/**
+ * Private/loopback/link-local detection for a host (name or IP literal). Blocks the obvious private
+ * ranges, and — importantly — every IPv6 literal by default: an IPv4-mapped form like
+ * `::ffff:169.254.169.254` otherwise slips a metadata address past a naive v4-only check. A specific
+ * public IPv6 endpoint must instead be permitted explicitly via `allowedHttpHosts`.
+ */
+export declare const isPrivateHost: (host: string) => boolean;
+/**
+ * Validate an endpoint against the policy. Throws `forbidden` when disallowed. For stdio the endpoint
+ * is the command; for HTTP transports it is a URL.
+ */
+export declare const validateEndpoint: (policy: EgressPolicy, transport: McpTransport, endpoint: string) => void;
+/**
+ * The HTTP half of the policy, on its own — #176.
+ *
+ * Extracted because the check is about **HTTP egress**, not about MCP: an agent tool that fetches a URL needs
+ * exactly these rules, and the alternatives were both bad. Calling `validateEndpoint(policy, "streamable-http",
+ * url)` would be passing a transport the caller does not have, and writing the checks again in the tool would be
+ * a second SSRF defence that drifts from the first — and the one that drifts is the one nobody re-reads.
+ *
+ * Everything here was already load-bearing for MCP. Stated again because it is now reachable from a tool the
+ * *model* chooses the argument for, which is a materially more hostile position than an operator-configured
+ * endpoint:
+ *
+ * - Credentials in userinfo are **refused**, not stripped.
+ * - Every IPv6 literal is denied by default, because `::ffff:169.254.169.254` slips a cloud metadata address
+ *   past any v4-only check.
+ * - An explicit host allow-list is authoritative, so an operator can permit something they trust.
+ * - Absent an allow-list, private, loopback, link-local and `.internal`/`.local` targets are blocked.
+ */
+export declare const validateHttpEgress: (policy: EgressPolicy, endpoint: string) => URL;
+//# sourceMappingURL=egress.d.ts.map

package/dist/mcp/egress.js

@@ -0,0 +1,115 @@
+/**
+ * MCP egress policy — `docs/10-mcp-integration.md` → Egress and trust.
+ *
+ * A tenant's MCP endpoint is validated *before any handshake*, at registration and again at connect.
+ * HTTP endpoints are checked against scheme/host rules and blocked from reaching private/loopback
+ * addresses (SSRF defense); stdio commands are checked against an explicit allow-list. Anything not
+ * allowed is rejected — the safe default is deny.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+const forbidden = (message) => new AgentPlatformError({ code: "forbidden", message, retryable: false });
+const PRIVATE_HOSTNAMES = new Set(["localhost", "ip6-localhost", "metadata.google.internal"]);
+/** Normalize a host for policy checks: lowercase, strip IPv6 brackets and a trailing dot (`a.` ≡ `a`). */
+export const normalizeHost = (host) => host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.+$/, "");
+const isPrivateV4 = (h) => {
+    const v4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!v4)
+        return false;
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    if (a === 10 || a === 127 || a === 0)
+        return true;
+    if (a === 169 && b === 254)
+        return true; // link-local incl. cloud metadata 169.254.169.254
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+};
+/**
+ * Private/loopback/link-local detection for a host (name or IP literal). Blocks the obvious private
+ * ranges, and — importantly — every IPv6 literal by default: an IPv4-mapped form like
+ * `::ffff:169.254.169.254` otherwise slips a metadata address past a naive v4-only check. A specific
+ * public IPv6 endpoint must instead be permitted explicitly via `allowedHttpHosts`.
+ */
+export const isPrivateHost = (host) => {
+    const h = normalizeHost(host);
+    if (h.length === 0)
+        return true;
+    if (h === "localhost" || PRIVATE_HOSTNAMES.has(h) || h.endsWith(".local") || h.endsWith(".internal"))
+        return true;
+    if (h.includes(":"))
+        return true; // any IPv6 literal (incl. ::, ::1, ::ffff:… mapped) — deny by default
+    return isPrivateV4(h);
+};
+/**
+ * Validate an endpoint against the policy. Throws `forbidden` when disallowed. For stdio the endpoint
+ * is the command; for HTTP transports it is a URL.
+ */
+export const validateEndpoint = (policy, transport, endpoint) => {
+    if (transport === "stdio") {
+        const allowed = policy.allowedStdioCommands ?? [];
+        const command = endpoint.trim().split(/\s+/)[0] ?? "";
+        if (!allowed.includes(command))
+            throw forbidden(`stdio command "${command}" is not on the egress allow-list`);
+        return;
+    }
+    validateHttpEgress(policy, endpoint);
+};
+/**
+ * The HTTP half of the policy, on its own — #176.
+ *
+ * Extracted because the check is about **HTTP egress**, not about MCP: an agent tool that fetches a URL needs
+ * exactly these rules, and the alternatives were both bad. Calling `validateEndpoint(policy, "streamable-http",
+ * url)` would be passing a transport the caller does not have, and writing the checks again in the tool would be
+ * a second SSRF defence that drifts from the first — and the one that drifts is the one nobody re-reads.
+ *
+ * Everything here was already load-bearing for MCP. Stated again because it is now reachable from a tool the
+ * *model* chooses the argument for, which is a materially more hostile position than an operator-configured
+ * endpoint:
+ *
+ * - Credentials in userinfo are **refused**, not stripped.
+ * - Every IPv6 literal is denied by default, because `::ffff:169.254.169.254` slips a cloud metadata address
+ *   past any v4-only check.
+ * - An explicit host allow-list is authoritative, so an operator can permit something they trust.
+ * - Absent an allow-list, private, loopback, link-local and `.internal`/`.local` targets are blocked.
+ */
+export const validateHttpEgress = (policy, endpoint) => {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw forbidden(`Invalid URL`);
+    }
+    /**
+     * A URL carrying userinfo is a **credential**, and it is refused (#145).
+     *
+     * `https://user:sk-live-abc@allowed.host` passed every check here: the scheme is permitted, the host is on the
+     * allow-list, and the endpoint was then stored verbatim in `mcp_connections.endpoint`. A secret in a database
+     * column — and in every log line, error message and support ticket that ever quotes the endpoint.
+     *
+     * The whole point of `McpAuth.credentialRef` is that a secret is *referenced*, never inlined. A URL is a second,
+     * unguarded way to inline one, which is why this is a refusal and not a strip: silently removing the userinfo
+     * would connect without the credential the operator believed they had configured, and the failure would look
+     * like the remote server rejecting them.
+     */
+    if (url.username !== "" || url.password !== "")
+        throw forbidden("MCP endpoint URL must not contain credentials in its userinfo; use McpAuth.credentialRef instead");
+    const schemes = policy.allowedSchemes ?? ["https"];
+    const scheme = url.protocol.replace(/:$/, "");
+    if (!schemes.includes(scheme))
+        throw forbidden(`scheme "${scheme}" is not permitted for MCP egress`);
+    const host = normalizeHost(url.hostname);
+    // An explicit host allow-list is authoritative — it lets an operator permit a specific internal or
+    // IPv6-literal host they trust. Without one, private/loopback/metadata targets are blocked.
+    if (policy.allowedHttpHosts) {
+        if (!policy.allowedHttpHosts.map(normalizeHost).includes(host))
+            throw forbidden(`host "${url.hostname}" is not on the egress allow-list`);
+        return url;
+    }
+    if (!policy.allowPrivateNetworks && isPrivateHost(url.hostname))
+        throw forbidden(`endpoint host "${url.hostname}" resolves to a private/loopback address`);
+    return url;
+};
+//# sourceMappingURL=egress.js.map