@pyric/cli 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/register/net-guard.js

@@ -0,0 +1,462 @@
+/**
+ * The runtime network guard: the enforcement half of the production-leak
+ * invariant.
+ *
+ * A sandboxed app's Firebase traffic all routes to the local `/__pyric/*`
+ * namespace. So a pyric-launched process that opens a connection to a real
+ * Google/Firebase endpoint has escaped the sandbox: it is reading or writing
+ * live production data with the developer believing otherwise. This module
+ * detects that egress and, depending on one knob, warns about it or fails it.
+ *
+ * Where it hooks, and why exactly there
+ * -------------------------------------
+ * 1. `Symbol.for('undici.globalDispatcher.1')`, the undici global dispatcher.
+ *    Measured against Next 15.5 / Node 24 / undici 7, this one seam covers
+ *    Node route handlers, edge route handlers and middleware, under both the
+ *    webpack and turbopack dev servers. Patching `globalThis.fetch` does not:
+ *    the edge sandbox bundles its own undici, and that copy's
+ *    `getGlobalDispatcher()` reads the host realm's symbol, which is precisely
+ *    why hooking the dispatcher reaches it and hooking `fetch` does not.
+ *
+ *    Three mechanics the seam depends on:
+ *      - undici installs the property `configurable: false, writable: true`, so
+ *        we install by plain assignment. A `defineProperty` with
+ *        `configurable: true` throws a TypeError and takes the dev server down
+ *        with it. Accessor traps are useless anyway, because
+ *        `setGlobalDispatcher` uses `defineProperty`, which bypasses setters.
+ *      - The property does not exist until undici is first touched, and undici
+ *        only installs a default agent when it finds the slot empty. So we
+ *        materialize it first with `new Headers()` (loads undici, zero
+ *        network) and wrap whatever real Agent that produces.
+ *      - The `handler` argument of `dispatch(opts, handler)` must pass through
+ *        opaque and by identity. Edge hands a v6-shaped handler to the host's
+ *        v7 Agent and that cross-version handoff only survives untouched. We
+ *        read `opts.origin` and nothing else.
+ *
+ * 2. `net.connect` / `net.createConnection` / `tls.connect`, plus the
+ *    `createConnection` on the `http.Agent` and `https.Agent` prototypes: the
+ *    backstop for traffic that never goes through undici, such as
+ *    `http.request`, gRPC, database drivers, anything holding a raw socket.
+ *    Same catalog, same policy. (undici itself connects through `net.connect`,
+ *    so a warn-mode fetch would report twice; the once-per-host dedupe below
+ *    collapses that.)
+ *
+ *    The Agent prototypes need their own patch because
+ *    `http.Agent.prototype.createConnection` is a copied reference to
+ *    `net.createConnection`, taken when `_http_agent` first loaded. If anything
+ *    loaded `node:http` before this module ran, that copy is the unpatched
+ *    function and every plain `http.request` would sail past the backstop,
+ *    including a request to the metadata server. It is also why the socket
+ *    patches are installed BEFORE the dispatcher is materialized: materializing
+ *    loads undici, which loads `_http_agent`.
+ *
+ * Policy
+ * ------
+ * One knob, `PYRIC_GUARD=warn|block|off`, default `warn`:
+ *   warn   report the egress, let it through
+ *   block  report it and fail the request
+ *   off    no hooks at all, one notice line at install time
+ * The GCE metadata IP (`169.254.169.254`, `alwaysBlock` in the catalog) is
+ * refused in warn mode and cannot be allowlisted, since its only use from a
+ * dev process is credential theft. `off` is genuinely off, metadata IP
+ * included; the off notice says so out loud.
+ *
+ * A blocked fetch surfaces to app code as a bare `TypeError: fetch failed`
+ * (the reason is buried on `error.cause`), so the guard must log its own
+ * denial: the app's error will never explain itself.
+ *
+ * The allowlist seam
+ * ------------------
+ * `PYRIC_GUARD_ALLOW` is a comma/whitespace separated list of hosts or URLs,
+ * matched on label boundaries, permitting an otherwise-flagged catalog host
+ * (an allowlisted hit is still reported once). Env is the seam by design:
+ *   - the AI engine baseUrls live in the user's Vite config
+ *     (`PyricAiOptions.engine.baseUrl`, `serve/vite-ai-config.ts`), which is
+ *     read by the Vite plugin inside the serve host, a different process from
+ *     the one this module loads into, and not parsed by the CLI at all;
+ *   - `pyric.json` is read asynchronously by `runServe` (`cli/pyric-config.ts`)
+ *     and this module runs on the `--import` hot path of every child, where a
+ *     synchronous config-file read has no business being.
+ * `cli/sandbox-runner.ts:buildChildEnv` spreads the parent env into the child,
+ * so anything the pyric process exports reaches every descendant for free
+ * (`NODE_OPTIONS` already propagates the register import the same way). To
+ * wire a `pyric.json` `guardAllow` through, the whole change is: add the field
+ * to `PyricConfig`, and have `buildChildEnv` set `PYRIC_GUARD_ALLOW` from it
+ * at the `cli/serve.ts` call site, where `pyricConfig` is already in scope.
+ *
+ * Bun and Deno are out of scope: neither evaluates Node loader hooks (the
+ * register module never loads there) and neither routes `fetch` through
+ * undici's global dispatcher. `installNetGuard` degrades to the socket
+ * backstop instead of throwing.
+ */
+import { createRequire } from 'node:module';
+import { lookupGoogleEndpoint, matchesHostSuffix, normalizeHostname, } from '../google-endpoints.js';
+/** undici's global-dispatcher slot. Version-suffixed by undici itself. */
+const UNDICI_GLOBAL_DISPATCHER = Symbol.for('undici.globalDispatcher.1');
+/** Marks a rejection as the guard's, so callers can tell it from a DNS/TLS
+ *  failure. A blocked `fetch` only exposes it as `error.cause.code`. */
+export const GUARD_BLOCKED_CODE = 'PYRIC_GUARD_BLOCKED';
+const LOG_PREFIX = '@pyric/cli/register: net-guard';
+/** How often to check that nobody replaced the global dispatcher under us. */
+const REASSERT_INTERVAL_MS = 5_000;
+/** `PYRIC_GUARD` → mode. Unset, empty or unrecognised all mean the safe
+ *  default: report, do not break the developer's app. */
+export function parseGuardMode(raw) {
+    const value = (raw ?? '').trim().toLowerCase();
+    if (value === 'block')
+        return 'block';
+    if (value === 'off')
+        return 'off';
+    return 'warn';
+}
+/** `PYRIC_GUARD_ALLOW` → hostnames. Accepts bare hosts and full URLs, because
+ *  the values it carries are configured as URLs (AI engine baseUrls). */
+export function parseAllowHosts(raw) {
+    if (!raw)
+        return [];
+    const out = [];
+    for (const token of raw.split(/[\s,]+/)) {
+        const entry = token.trim();
+        if (entry.length === 0)
+            continue;
+        out.push(hostnameOf(entry));
+    }
+    return out;
+}
+/** Only a trailing `:port` is stripped; a bare IPv6 address is left alone. */
+const HOST_WITH_PORT = /^(.+):\d+$/;
+/**
+ * Best-effort hostname from a host, `host:port`, or full URL. Normalization
+ * and suffix matching are the catalog's, so the guard and the catalog can
+ * never disagree about what a hostname is.
+ */
+function hostnameOf(value) {
+    const trimmed = value.trim();
+    if (trimmed.includes('://')) {
+        try {
+            return normalizeHostname(new URL(trimmed).hostname).replace(/^\[|\]$/g, '');
+        }
+        catch {
+            // Not a parseable URL: fall through to the textual forms.
+        }
+    }
+    const withoutPath = trimmed.split('/')[0] ?? trimmed;
+    const portMatch = HOST_WITH_PORT.exec(withoutPath);
+    let hostPart;
+    if (portMatch === null) {
+        hostPart = withoutPath;
+    }
+    else {
+        hostPart = portMatch[1];
+    }
+    return normalizeHostname(hostPart);
+}
+/**
+ * The whole verdict, pure: catalog lookup, then `alwaysBlock`, then the
+ * allowlist, then the mode. `null` means nothing to say: either not a
+ * production endpoint, or the guard is off.
+ */
+export function evaluateEgress(hostname, policy) {
+    if (policy.mode === 'off')
+        return null;
+    const host = hostnameOf(hostname);
+    if (host.length === 0)
+        return null;
+    const entry = lookupGoogleEndpoint(host);
+    if (entry === undefined)
+        return null;
+    // `alwaysBlock` outranks both the mode and the allowlist: the metadata
+    // server is never a legitimate destination for a sandboxed dev process, so
+    // there is no configuration that should be able to permit it.
+    if (entry.alwaysBlock === true) {
+        return {
+            verdict: 'block',
+            permitted: false,
+            host,
+            endpoint: entry.host,
+            service: entry.service,
+            alwaysBlock: true,
+        };
+    }
+    if (policy.allow.some((allowed) => matchesHostSuffix(host, allowed))) {
+        return { verdict: 'allow', permitted: true, host, endpoint: entry.host, service: entry.service };
+    }
+    if (policy.mode === 'block') {
+        return {
+            verdict: 'block',
+            permitted: false,
+            host,
+            endpoint: entry.host,
+            service: entry.service,
+        };
+    }
+    return { verdict: 'warn', permitted: true, host, endpoint: entry.host, service: entry.service };
+}
+/** One stderr line per verdict: structured (fixed leading fields, so it is
+ *  greppable) and attributable (service + transport + initiating command).
+ *  The request PATH is deliberately never logged: it carries ids and tokens. */
+export function formatGuardLine(verdict, transport, context) {
+    let where = `via ${transport}`;
+    if (context !== undefined && context.length > 0)
+        where = `${where} from ${context}`;
+    const head = `${LOG_PREFIX} ${verdict.verdict.toUpperCase()} ${verdict.host} (${verdict.service}) ${where}:`;
+    const tail = 'Further attempts to this host are not logged.';
+    if (verdict.verdict === 'allow') {
+        return `${head} live production egress permitted by PYRIC_GUARD_ALLOW. ${tail}\n`;
+    }
+    if (verdict.verdict === 'warn') {
+        return (`${head} LIVE production egress. A sandboxed app routes Firebase traffic to /__pyric/*, ` +
+            `so this is reaching real data. Set PYRIC_GUARD=block to fail these requests instead. ${tail}\n`);
+    }
+    let why;
+    if (verdict.alwaysBlock === true) {
+        why = 'the credential metadata server is refused in every mode except PYRIC_GUARD=off';
+    }
+    else {
+        why = 'live production egress refused (PYRIC_GUARD=block)';
+    }
+    // What the app actually observes differs by seam: undici swallows our throw
+    // into the opaque `TypeError: fetch failed`, while a raw socket caller gets
+    // the error itself. Say which, or the developer cannot connect the two.
+    let surfaces;
+    if (transport === 'fetch') {
+        surfaces = `the caller sees \`TypeError: fetch failed\` with cause ${GUARD_BLOCKED_CODE}`;
+    }
+    else {
+        surfaces = `the caller sees an error with code ${GUARD_BLOCKED_CODE}`;
+    }
+    return `${head} ${why}; ${surfaces}. ${tail}\n`;
+}
+function blockedError(verdict, transport) {
+    return Object.assign(new Error(`pyric net-guard blocked ${transport} egress to ${verdict.host} (${verdict.service}): ` +
+        `this is LIVE production, not the pyric sandbox. ` +
+        `Set PYRIC_GUARD=warn to allow it, or PYRIC_GUARD_ALLOW to permit this host.`), { code: GUARD_BLOCKED_CODE, host: verdict.host, service: verdict.service });
+}
+function createReporter(options) {
+    const write = options.write ?? ((line) => void process.stderr.write(line));
+    const policy = { mode: options.mode, allow: options.allow };
+    const reported = options.reported ?? new Set();
+    return {
+        check(hostname, transport) {
+            if (hostname === undefined)
+                return;
+            const verdict = evaluateEgress(hostname, policy);
+            if (verdict === null)
+                return;
+            // A dev server retries relentlessly; one line per host is the signal,
+            // and it also collapses the undici-over-net.connect double report.
+            const key = `${verdict.verdict}:${verdict.host}`;
+            if (!reported.has(key)) {
+                reported.add(key);
+                write(formatGuardLine(verdict, transport, options.context));
+            }
+            if (!verdict.permitted)
+                throw blockedError(verdict, transport);
+        },
+    };
+}
+/** `opts.origin` is a URL or an origin string; anything else means "no idea",
+ *  and an unrecognisable origin is passed through rather than guessed at. */
+function originHost(opts) {
+    const origin = opts?.origin;
+    if (origin === undefined || origin === null)
+        return undefined;
+    if (typeof origin === 'object' && 'hostname' in origin) {
+        const hostname = origin.hostname;
+        return typeof hostname === 'string' ? hostname.toLowerCase() : undefined;
+    }
+    if (typeof origin !== 'string')
+        return undefined;
+    try {
+        return new URL(origin).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Wrap a dispatcher so `dispatch` is guarded and every other member still
+ * belongs to the real instance.
+ *
+ * A `Proxy` rather than a subclass or a copy: undici's Agent keeps state in
+ * private fields and internal symbols, and every forwarded call must run with
+ * `this` bound to the REAL instance (hence `Reflect.get(target, prop, target)`
+ * and the bind) or those fields are not there. `instanceof` keeps working.
+ */
+export function wrapDispatcher(real, options) {
+    const reporter = createReporter(options);
+    const guardedDispatch = (opts, handler) => {
+        reporter.check(originHost(opts), 'fetch');
+        // Both arguments cross UNTOUCHED. Edge hands a v6 handler to the host's
+        // v7 Agent, and that handoff only survives by identity.
+        return real.dispatch(opts, handler);
+    };
+    return new Proxy(real, {
+        get(target, prop) {
+            if (prop === 'dispatch')
+                return guardedDispatch;
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+/** `basename(argv[1])`, the cheapest honest attribution available. */
+function contextFrom(argv) {
+    const entry = argv?.[1];
+    if (typeof entry !== 'string' || entry.length === 0)
+        return undefined;
+    const parts = entry.split(/[\\/]/);
+    return parts[parts.length - 1] || undefined;
+}
+/**
+ * Materialize undici's lazy global dispatcher without touching the network.
+ * `new Headers()` loads Node's undici, whose module body installs a default
+ * Agent into the symbol only if the slot is still empty, so this must run
+ * before we put anything there. It also loads `_http_agent`, which is why the
+ * socket patches go in first.
+ */
+function materializeGlobalDispatcher() {
+    try {
+        new Headers();
+    }
+    catch {
+        // No WHATWG Headers, or a runtime that never had undici. The socket
+        // backstop still applies.
+    }
+}
+/**
+ * The `http.Agent` and `https.Agent` prototypes, or an empty list on a runtime
+ * without them. Each carries its own `createConnection`: `http`'s is a copied
+ * reference to `net.createConnection` snapshotted at `_http_agent` load time,
+ * so patching `net` alone leaves it unguarded whenever `node:http` loaded
+ * first.
+ */
+function nodeAgentPrototypes() {
+    const require = createRequire(import.meta.url);
+    const prototypes = [];
+    for (const id of ['node:http', 'node:https']) {
+        try {
+            const mod = require(id);
+            const prototype = mod.Agent?.prototype;
+            if (typeof prototype === 'object' && prototype !== null) {
+                prototypes.push(prototype);
+            }
+        }
+        catch {
+            // Runtime without that module: the other seams still apply.
+        }
+    }
+    return prototypes;
+}
+/**
+ * Install the guard. Gated on `PYRIC_SANDBOX` exactly like the rest of the
+ * register module: without the activator this is a no-op, so the module stays
+ * safe to import anywhere. Returns `null` when nothing was installed.
+ */
+export function installNetGuard(hooks = {}) {
+    const env = hooks.env ?? process.env;
+    if (!env.PYRIC_SANDBOX)
+        return null;
+    const write = hooks.write ?? ((line) => void process.stderr.write(line));
+    const mode = parseGuardMode(env.PYRIC_GUARD);
+    if (mode === 'off') {
+        write(`${LOG_PREFIX} disabled (PYRIC_GUARD=off): egress from this process to live ` +
+            `Google/Firebase endpoints is neither reported nor blocked, not even the GCE ` +
+            `metadata server (169.254.169.254).\n`);
+        return null;
+    }
+    const allow = parseAllowHosts(env.PYRIC_GUARD_ALLOW);
+    const context = contextFrom(hooks.argv ?? process.argv);
+    const reporterOptions = { mode, allow, write, context, reported: new Set() };
+    const scope = hooks.scope ?? globalThis;
+    // ── socket backstop: http.request, gRPC, DB drivers, raw sockets ──
+    //
+    // This runs FIRST, before the dispatcher is materialized. Materializing
+    // loads undici, which loads `_http_agent`, which snapshots
+    // `net.createConnection` onto `http.Agent.prototype.createConnection`. With
+    // the order reversed, that snapshot is the unpatched function and every
+    // plain `http.request` escapes the guard, the metadata server included.
+    const require = createRequire(import.meta.url);
+    const netModule = hooks.net ?? require('node:net');
+    const tlsModule = hooks.tls ?? require('node:tls');
+    const reporter = createReporter(reporterOptions);
+    const guardConnect = (target, name) => {
+        const original = target[name];
+        if (typeof original !== 'function')
+            return;
+        const wrapped = function (...args) {
+            reporter.check(connectHost(args), 'socket');
+            return original.apply(this, args);
+        };
+        target[name] = wrapped;
+    };
+    guardConnect(netModule, 'connect');
+    guardConnect(netModule, 'createConnection');
+    guardConnect(tlsModule, 'connect');
+    // And the Agent prototypes, so a `node:http` that loaded before this module
+    // is still covered. `https.Agent` also reaches the patched `tls.connect`, so
+    // its own patch is a second check on the same egress; the once-per-host
+    // dedupe keeps that from printing twice.
+    for (const prototype of hooks.agentPrototypes ?? nodeAgentPrototypes()) {
+        guardConnect(prototype, 'createConnection');
+    }
+    let installed;
+    const wrapGlobalDispatcher = () => {
+        const current = scope[UNDICI_GLOBAL_DISPATCHER];
+        if (current === undefined || current === null)
+            return;
+        if (current === installed)
+            return;
+        if (typeof current.dispatch !== 'function')
+            return;
+        // PLAIN ASSIGNMENT. undici's own property is
+        // `configurable: false, writable: true`; a `defineProperty` that tries to
+        // make it configurable throws and takes the process down.
+        installed = wrapDispatcher(current, reporterOptions);
+        scope[UNDICI_GLOBAL_DISPATCHER] = installed;
+    };
+    if (hooks.scope === undefined)
+        materializeGlobalDispatcher();
+    wrapGlobalDispatcher();
+    let timer;
+    if (hooks.scope === undefined) {
+        timer = setInterval(wrapGlobalDispatcher, REASSERT_INTERVAL_MS);
+        // Never hold the event loop open: a guarded child must still exit.
+        timer.unref?.();
+    }
+    return {
+        mode,
+        allow,
+        reassert: wrapGlobalDispatcher,
+        stop() {
+            if (timer !== undefined)
+                clearInterval(timer);
+        },
+    };
+}
+/**
+ * Extract the destination host from `net.connect` / `tls.connect` arguments,
+ * across all of their overloads: `(options[, cb])`, `(port[, host][, cb])`,
+ * `(path[, cb])`. An IPC path or a portless local socket has no host, which is
+ * exactly the "nothing to say" answer.
+ */
+function connectHost(args) {
+    const first = args[0];
+    if (typeof first === 'object' && first !== null) {
+        const host = first.host ??
+            first.hostname;
+        return typeof host === 'string' ? host : undefined;
+    }
+    if (typeof first === 'number' || (typeof first === 'string' && /^\d+$/.test(first))) {
+        // (port, host?, ...): the host, when given, is the next string argument.
+        const second = args[1];
+        if (typeof second === 'string')
+            return second;
+        if (typeof second === 'object' && second !== null) {
+            const host = second.host;
+            return typeof host === 'string' ? host : undefined;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=net-guard.js.map

package/dist/register/net-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-guard.js","sourceRoot":"","sources":["../../src/register/net-guard.ts"],"names":[],"mappings":"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"}

package/dist/serve/ai-diagnostics-relay.d.ts

@@ -0,0 +1,63 @@
+import type { SandboxEvent } from 'pyric/sandbox';
+/**
+ * AI diagnostics relay: headless dev visibility for the three things the
+ * broker does that no app-level signal reports.
+ *
+ * The broker lands `service_mutation` events (`service: 'ai'`) on the
+ * sandbox's unified stream. That stream is browser-side: the worker host fans
+ * it out over the port for Studio, and it never reaches the dev server. An
+ * agent driving `pyric dev` headlessly therefore saw NOTHING.
+ *
+ *   - `request_rejected`: a bad role, empty `contents`, a missing thought
+ *     signature, or an engine that answered an error envelope.
+ *   - `response_blocked`: the SILENT refusal. A safety / recitation /
+ *     blocklist filter answers HTTP 200 with an empty candidate, so nothing
+ *     throws anywhere and the app simply renders nothing.
+ *   - `model_substituted`: not a refusal at all. The answer arrives, from a
+ *     model the developer never asked for (an openai `modelMap` entry or
+ *     catch-all `model`, a gemini experimental alias). Same shape of problem:
+ *     the sandbox quietly did something other than what the code said, and
+ *     only the terminal can say so.
+ *
+ * One record per kind in {@link AI_DIAGNOSTIC_RELAYS} pairs the sandbox `op`
+ * with the narrower that turns it into a wire payload. The terminal formatter
+ * and throttle key for each kind live in `ai-terminal-blocks.ts`, keyed by the
+ * same {@link AiDiagnosticKind} union, so the compiler flags a kind that is
+ * relayed but never rendered.
+ *
+ * This is the AI twin of the Firebase Activity Guard reporter next door
+ * (`activity-guard.ts`): a browser-safe subscriber shared by the SharedWorker
+ * and in-page planes, which fire-and-forget POSTs to the dev server. It rides
+ * the DENIAL relay's existing channel (`POST /__pyric/denials`, see the denial
+ * relay section of `namespace.ts`) rather than opening a new one: a broker
+ * refusal is the same category of thing as a rules denial, it wants the same
+ * terminal treatment, and it wants that endpoint's per-(target, reason)
+ * throttle, because an agent retry loop re-sends the same request over and
+ * over.
+ *
+ * Best-effort, exactly like the activity reporter and the denial relay: never
+ * throws, never awaited into app flow, and a relay failure (dev server gone,
+ * no `fetch`, non-pyric host) is swallowed. Diagnostics, not a correctness
+ * path.
+ */
+/** The slice of the sandbox this relay needs. Live events only: replaying
+ *  `history()` on boot would re-announce refusals the terminal already
+ *  printed (and the activity feed's reason for taking history does not apply,
+ *  since nothing here correlates across events). */
+export interface AiDiagnosticsFeed {
+    subscribe(listener: (event: SandboxEvent) => void): unknown;
+}
+/** The `kind` discriminator on every payload this relay POSTs. It is also the
+ *  key of the formatter table in `ai-terminal-blocks.ts`. */
+export type AiDiagnosticKind = 'ai-rejection' | 'ai-blocked' | 'ai-model-substituted';
+/**
+ * Subscribe to the sandbox event stream and relay every broker refusal,
+ * rejected request or blocked response, plus every silent model substitution,
+ * to the dev server for terminal visibility.
+ *
+ * Browser-safe (shared by the SharedWorker host and the in-page runtime);
+ * returns nothing to unsubscribe with, mirroring the guard next door, since
+ * the subscription is observational and lives for the plane's lifetime.
+ */
+export declare function setupAiDiagnosticsRelay(feed: AiDiagnosticsFeed, fetchFn: typeof fetch): void;
+//# sourceMappingURL=ai-diagnostics-relay.d.ts.map

package/dist/serve/ai-diagnostics-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-diagnostics-relay.d.ts","sourceRoot":"","sources":["../../src/serve/ai-diagnostics-relay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;oDAGoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC;CAC7D;AAED;6DAC6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,YAAY,GAAG,sBAAsB,CAAC;AA8JtF;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,KAAK,GAAG,IAAI,CAoB5F"}

package/dist/serve/ai-diagnostics-relay.js

@@ -0,0 +1,125 @@
+import { capTerminalText } from './ai-terminal-text.js';
+/**
+ * A string field off the event's free-form `detail` record, or `undefined`
+ * when the emitter did not set it. `detail` is a public contract anyone can
+ * post onto, so every field is re-checked, and every value is length-capped
+ * here rather than on the far side: a model server that answers with a
+ * megabyte in its `finishMessage` must not push a megabyte through the
+ * fire-and-forget POST just to have the terminal cut it.
+ */
+function detailText(detail, field) {
+    const value = detail[field];
+    if (typeof value !== 'string')
+        return undefined;
+    return capTerminalText(value);
+}
+/** The event's `path` when it names a model, or `undefined`. */
+function eventModel(event) {
+    if (typeof event.path !== 'string' || event.path === '')
+        return undefined;
+    return capTerminalText(event.path);
+}
+function detailOf(event) {
+    return (event.detail ?? {});
+}
+/** Narrow a `request_rejected` event to its relay payload. */
+function toRejectionPayload(event) {
+    const detail = detailOf(event);
+    const payload = {
+        kind: 'ai-rejection',
+        message: detailText(detail, 'message') ?? 'request rejected',
+    };
+    payload.model = eventModel(event);
+    payload.engine = detailText(detail, 'engine');
+    payload.status = detailText(detail, 'status');
+    if (typeof detail.code === 'number')
+        payload.code = detail.code;
+    return payload;
+}
+/** Narrow a `response_blocked` event to its relay payload. */
+function toBlockedPayload(event) {
+    const detail = detailOf(event);
+    const payload = { kind: 'ai-blocked' };
+    payload.model = eventModel(event);
+    payload.engine = detailText(detail, 'engine');
+    payload.finishReason = detailText(detail, 'finishReason');
+    payload.finishMessage = detailText(detail, 'finishMessage');
+    payload.blockReason = detailText(detail, 'blockReason');
+    return payload;
+}
+/**
+ * Narrow a `model_substituted` event to its relay payload, and enforce the
+ * invariant the terminal line depends on: an effective model equal to the
+ * requested one is NOT a substitution and never relays. The broker already
+ * compares before emitting; this re-checks because the event stream is a
+ * public contract anyone can post onto.
+ */
+function toModelSubstitutionPayload(event) {
+    const detail = detailOf(event);
+    const requestedModel = detailText(detail, 'requestedModel') ?? eventModel(event) ?? '';
+    const effectiveModel = detailText(detail, 'effectiveModel') ?? '';
+    if (requestedModel === '' || effectiveModel === '')
+        return null;
+    let requestedBare = requestedModel;
+    if (requestedModel.startsWith('models/'))
+        requestedBare = requestedModel.slice('models/'.length);
+    if (effectiveModel === requestedBare || effectiveModel === requestedModel)
+        return null;
+    const payload = {
+        kind: 'ai-model-substituted',
+        requestedModel,
+        effectiveModel,
+    };
+    payload.engine = detailText(detail, 'engine');
+    payload.reason = detailText(detail, 'reason');
+    return payload;
+}
+const AI_DIAGNOSTIC_RELAYS = {
+    'ai-rejection': { op: 'request_rejected', fromEvent: toRejectionPayload },
+    'ai-blocked': { op: 'response_blocked', fromEvent: toBlockedPayload },
+    'ai-model-substituted': { op: 'model_substituted', fromEvent: toModelSubstitutionPayload },
+};
+/** The relay record for a sandbox `op`, or `null` for an op nothing relays. */
+function relayForOp(op) {
+    for (const relay of Object.values(AI_DIAGNOSTIC_RELAYS)) {
+        if (relay.op === op)
+            return relay;
+    }
+    return null;
+}
+/**
+ * Subscribe to the sandbox event stream and relay every broker refusal,
+ * rejected request or blocked response, plus every silent model substitution,
+ * to the dev server for terminal visibility.
+ *
+ * Browser-safe (shared by the SharedWorker host and the in-page runtime);
+ * returns nothing to unsubscribe with, mirroring the guard next door, since
+ * the subscription is observational and lives for the plane's lifetime.
+ */
+export function setupAiDiagnosticsRelay(feed, fetchFn) {
+    feed.subscribe((event) => {
+        if (event.kind !== 'service_mutation')
+            return;
+        if (event.service !== 'ai')
+            return;
+        const relay = relayForOp(event.op);
+        if (relay === null)
+            return;
+        const payload = relay.fromEvent(event);
+        if (payload === null)
+            return;
+        try {
+            void fetchFn('/__pyric/denials', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+            }).catch(() => {
+                /* Diagnostics are best-effort and must never affect app behavior. */
+            });
+        }
+        catch {
+            /* An injected or unavailable fetch must never affect app behavior. */
+        }
+    });
+}
+//# sourceMappingURL=ai-diagnostics-relay.js.map