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

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

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

package/dist/serve/ai-proxy.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `/__pyric/ai-proxy`: the same-origin passthrough to an OpenAI-compatible
+ * upstream, plus the terminal diagnostics that make an upstream failure
+ * visible to a developer with no browser console open.
+ *
+ * The route is always mounted; it only touches the network when a request
+ * arrives. Everything about WHERE it forwards is resolved by
+ * {@link resolveAiProxyUpstream}, which the startup banner (`ai-status.ts`)
+ * shares so the two can never disagree.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { ServeLogger } from './server.js';
+/** The dev server's diagnostics throttle, as this module needs it: the
+ *  denials route owns the instance, and the proxy shares it so a failing
+ *  upstream cannot out-shout a denied listener. */
+export interface AiDiagnosticThrottle {
+    shouldPrint(key: string, now: number): boolean;
+}
+/** Default upstream: local Ollama's OpenAI-compatible endpoint. */
+export declare const AI_PROXY_DEFAULT_UPSTREAM = "http://localhost:11434/v1";
+/** The route the dev server mounts for OpenAI-compatible traffic. */
+export declare const AI_PROXY_ROUTE = "/__pyric/ai-proxy";
+/** The upstream-failure shapes the proxy surfaces to the terminal. */
+type AiProxyFailure = {
+    kind: 'unreachable';
+    target: string;
+    latencyMs: number;
+    cause: string;
+} | {
+    kind: 'status';
+    target: string;
+    latencyMs: number;
+    status: number;
+    /** The upstream's raw `Retry-After` header, when it sent one. */
+    retryAfter?: string;
+} | {
+    kind: 'stream-abort';
+    target: string;
+    latencyMs: number;
+    cause: string;
+};
+/**
+ * Format an upstream failure into the compact terminal block, the same
+ * `  [pyric] ...` idiom the denial relay prints, so ai-proxy trouble reads
+ * like every other dev-server diagnostic. Two lines: what went wrong, then
+ * the (redacted) upstream URL with the elapsed time. Exported for unit tests.
+ *
+ * A 429 says so in words (`rate limited`): the bare number reads as one more
+ * failed request, when it actually means the upstream is shedding load or the
+ * key is out of quota. When the upstream sent a `Retry-After`, a third line
+ * prints the wait it asked for, and states that NOTHING here waits on the
+ * developer's behalf. The proxy has no retry loop (the status rides straight
+ * through to the caller), so the backoff is the app's decision, not pyric's.
+ */
+export declare function formatAiProxyWarning(failure: AiProxyFailure): string;
+/**
+ * Resolve the upstream `/__pyric/ai-proxy` forwards to, and say WHERE that
+ * value came from. One resolution shared by the proxy handler (which needs
+ * the target) and the startup line (which needs the provenance, so a
+ * developer can tell a deliberate `PYRIC_AI_PROXY_UPSTREAM` from the Ollama
+ * default nobody chose).
+ */
+export declare function resolveAiProxyUpstream(configured: string | undefined): {
+    target: string;
+    source: 'option' | 'env' | 'default';
+};
+/**
+ * Handle `POST /__pyric/ai-proxy/<suffix>`: a same-origin passthrough to the
+ * configured OpenAI-compatible upstream, so the browser openai engine
+ * (running in the served page or the SharedWorker host) reaches a localhost
+ * upstream like Ollama with ZERO CORS setup (no `OLLAMA_ORIGINS`, ever).
+ *
+ * Behavior:
+ *   - POST only (the OpenAI chat-completions surface is POST); 405 otherwise.
+ *   - the path suffix + query ride through verbatim
+ *     (`/__pyric/ai-proxy/chat/completions` becomes `<upstream>/chat/completions`).
+ *   - the request body is forwarded verbatim; headers minus the
+ *     origin-sensitive/hop-by-hop set above (`authorization` DOES forward,
+ *     since upstreams may require a key).
+ *   - the response body is STREAMED through chunk-by-chunk. SSE passthrough
+ *     must never buffer, or `stream: true` completions would arrive all at
+ *     once at the end.
+ *   - an unreachable upstream answers 502 with a plain-text explanation.
+ *   - every upstream failure (unreachable/timeout, non-2xx status, mid-stream
+ *     abort) ALSO prints a structured warning on the dev server's terminal
+ *     logger; a stopped Ollama used to fail in total silence. Diagnostics
+ *     only: nothing here changes what the caller receives. No logger wired
+ *     means dropped silently (same opt-out contract as the denial relay).
+ */
+export declare function handleAiProxy(configuredUpstream: string | undefined, throttle: AiDiagnosticThrottle, req: IncomingMessage, res: ServerResponse, url: URL, logger?: ServeLogger): Promise<void>;
+export {};
+//# sourceMappingURL=ai-proxy.d.ts.map

package/dist/serve/ai-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-proxy.d.ts","sourceRoot":"","sources":["../../src/serve/ai-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C;;mDAEmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE,qEAAqE;AACrE,eAAO,MAAM,cAAc,sBAAsB,CAAC;AA0BlD,sEAAsE;AACtE,KAAK,cAAc,GACf;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzE;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAuD/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CA2BpE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;CAAE,CAY1D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAiHf"}

package/dist/serve/ai-proxy.js

@@ -0,0 +1,269 @@
+import { redactUrl } from 'pyric/ai/internal';
+import { sanitizeForTerminal } from './ai-terminal-text.js';
+/** Default upstream: local Ollama's OpenAI-compatible endpoint. */
+export const AI_PROXY_DEFAULT_UPSTREAM = 'http://localhost:11434/v1';
+/** The route the dev server mounts for OpenAI-compatible traffic. */
+export const AI_PROXY_ROUTE = '/__pyric/ai-proxy';
+/**
+ * Request headers that must NOT be forwarded upstream: origin-sensitive
+ * browser context (`origin`/`referer`/`cookie`, since the upstream is a
+ * different origin and must never see the page's), hop-by-hop headers, and
+ * the two the proxy re-derives (`host`, `content-length`). `accept-encoding`
+ * is dropped so fetch negotiates its own compression and the streamed body
+ * needs no length fixups.
+ */
+const AI_PROXY_STRIPPED_HEADERS = new Set([
+    'host',
+    'origin',
+    'referer',
+    'cookie',
+    'connection',
+    'content-length',
+    'accept-encoding',
+    'keep-alive',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+/** Longest `Retry-After` value echoed to the terminal (delta-seconds and
+ *  HTTP-dates are both far shorter; anything longer is upstream noise). */
+const AI_PROXY_RETRY_AFTER_MAX = 64;
+/**
+ * Render a `Retry-After` value for the terminal, or `null` when there is
+ * nothing worth printing.
+ *
+ * The header is remote-authored, so it is sanitized and length-capped like
+ * every other upstream string that reaches the terminal. Delta-seconds (the
+ * common form) get an `s` suffix so the wait reads as a duration; the
+ * HTTP-date form is echoed verbatim, since `Wed, 21 Oct 2026 07:28:00 GMTs`
+ * would be nonsense.
+ */
+function formatRetryAfter(raw) {
+    const clean = sanitizeForTerminal(raw).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
+    if (clean === '')
+        return null;
+    if (/^\d+$/.test(clean))
+        return `${clean}s`;
+    return clean;
+}
+/**
+ * Mask credentials, then flatten and cap, in that order. Both the target and
+ * a raw fetch error message are remote-influenced: the URL carries whatever
+ * the page put in the query string, and an error message can quote it back.
+ */
+function safeUpstreamText(text) {
+    return sanitizeForTerminal(redactUrl(text));
+}
+/**
+ * The throttle key for one upstream failure. A failing upstream fails on
+ * every request, so the key is the failure itself (kind, status, and the
+ * redacted target) rather than anything per-request: one line per window,
+ * exactly like a denied listener that re-fires.
+ */
+function aiProxyThrottleKey(failure) {
+    const target = redactUrl(failure.target);
+    if (failure.kind === 'status')
+        return `ai-proxy status ${failure.status} ${target}`;
+    return `ai-proxy ${failure.kind} ${target}`;
+}
+/** Print one upstream failure, unless the throttle already printed it. */
+function noteAiProxyFailure(failure, throttle, logger) {
+    if (logger === undefined)
+        return;
+    if (!throttle.shouldPrint(aiProxyThrottleKey(failure), Date.now()))
+        return;
+    logger.note(formatAiProxyWarning(failure));
+}
+/**
+ * Format an upstream failure into the compact terminal block, the same
+ * `  [pyric] ...` idiom the denial relay prints, so ai-proxy trouble reads
+ * like every other dev-server diagnostic. Two lines: what went wrong, then
+ * the (redacted) upstream URL with the elapsed time. Exported for unit tests.
+ *
+ * A 429 says so in words (`rate limited`): the bare number reads as one more
+ * failed request, when it actually means the upstream is shedding load or the
+ * key is out of quota. When the upstream sent a `Retry-After`, a third line
+ * prints the wait it asked for, and states that NOTHING here waits on the
+ * developer's behalf. The proxy has no retry loop (the status rides straight
+ * through to the caller), so the backoff is the app's decision, not pyric's.
+ */
+export function formatAiProxyWarning(failure) {
+    const target = safeUpstreamText(failure.target);
+    let headline;
+    if (failure.kind === 'unreachable') {
+        headline = `upstream unreachable: ${safeUpstreamText(failure.cause)}`;
+    }
+    else if (failure.kind === 'status') {
+        const rateLimited = failure.status === 429;
+        headline = `upstream returned ${failure.status}${rateLimited ? ' (rate limited / quota exhausted)' : ''}`;
+    }
+    else {
+        headline = `upstream stream aborted mid-response: ${safeUpstreamText(failure.cause)}`;
+    }
+    const lines = [
+        `  ⚠ [pyric] ai-proxy: ${headline}`,
+        `      POST ${target} (${failure.latencyMs}ms)`,
+    ];
+    if (failure.kind === 'unreachable') {
+        lines.push(`      set PYRIC_AI_PROXY_UPSTREAM to an OpenAI-compatible base URL (default ${AI_PROXY_DEFAULT_UPSTREAM})`);
+    }
+    if (failure.kind === 'status' && failure.retryAfter !== undefined) {
+        const wait = formatRetryAfter(failure.retryAfter);
+        if (wait !== null) {
+            lines.push(`      Retry-After: ${wait}, no automatic retry; the status went to the caller`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Resolve the upstream `/__pyric/ai-proxy` forwards to, and say WHERE that
+ * value came from. One resolution shared by the proxy handler (which needs
+ * the target) and the startup line (which needs the provenance, so a
+ * developer can tell a deliberate `PYRIC_AI_PROXY_UPSTREAM` from the Ollama
+ * default nobody chose).
+ */
+export function resolveAiProxyUpstream(configured) {
+    const envUpstream = process.env.PYRIC_AI_PROXY_UPSTREAM;
+    let raw = AI_PROXY_DEFAULT_UPSTREAM;
+    let source = 'default';
+    if (configured !== undefined) {
+        raw = configured;
+        source = 'option';
+    }
+    else if (envUpstream !== undefined) {
+        raw = envUpstream;
+        source = 'env';
+    }
+    return { target: raw.replace(/\/$/, ''), source };
+}
+/**
+ * Handle `POST /__pyric/ai-proxy/<suffix>`: a same-origin passthrough to the
+ * configured OpenAI-compatible upstream, so the browser openai engine
+ * (running in the served page or the SharedWorker host) reaches a localhost
+ * upstream like Ollama with ZERO CORS setup (no `OLLAMA_ORIGINS`, ever).
+ *
+ * Behavior:
+ *   - POST only (the OpenAI chat-completions surface is POST); 405 otherwise.
+ *   - the path suffix + query ride through verbatim
+ *     (`/__pyric/ai-proxy/chat/completions` becomes `<upstream>/chat/completions`).
+ *   - the request body is forwarded verbatim; headers minus the
+ *     origin-sensitive/hop-by-hop set above (`authorization` DOES forward,
+ *     since upstreams may require a key).
+ *   - the response body is STREAMED through chunk-by-chunk. SSE passthrough
+ *     must never buffer, or `stream: true` completions would arrive all at
+ *     once at the end.
+ *   - an unreachable upstream answers 502 with a plain-text explanation.
+ *   - every upstream failure (unreachable/timeout, non-2xx status, mid-stream
+ *     abort) ALSO prints a structured warning on the dev server's terminal
+ *     logger; a stopped Ollama used to fail in total silence. Diagnostics
+ *     only: nothing here changes what the caller receives. No logger wired
+ *     means dropped silently (same opt-out contract as the denial relay).
+ */
+export async function handleAiProxy(configuredUpstream, throttle, req, res, url, logger) {
+    if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' }).end('method not allowed');
+        return;
+    }
+    const upstreamBase = resolveAiProxyUpstream(configuredUpstream).target;
+    const suffix = url.pathname.slice(AI_PROXY_ROUTE.length);
+    const target = `${upstreamBase}${suffix}${url.search}`;
+    // Buffer the REQUEST body (small JSON payloads); the RESPONSE streams.
+    const raw = await new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+    // Copy into a plain-ArrayBuffer view; fetch's BodyInit typing rejects
+    // Buffer's ArrayBufferLike backing.
+    const body = new Uint8Array(raw.byteLength);
+    body.set(raw);
+    const headers = {};
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined)
+            continue;
+        if (AI_PROXY_STRIPPED_HEADERS.has(key.toLowerCase()))
+            continue;
+        headers[key] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    const startedAt = Date.now();
+    let upstream;
+    try {
+        upstream = await fetch(target, { method: 'POST', headers, body });
+    }
+    catch (e) {
+        const cause = e instanceof Error ? e.message : String(e);
+        noteAiProxyFailure({ kind: 'unreachable', target, latencyMs: Date.now() - startedAt, cause }, throttle, logger);
+        // The 502 body quotes the same two strings the terminal block does, so it
+        // gets the same masking: the target carries the page's own query string,
+        // and a fetch error routinely echoes the URL back.
+        res.writeHead(502, { 'content-type': 'text/plain' });
+        res.end(`pyric dev ai-proxy: upstream ${redactUrl(target)} unreachable: ${redactUrl(cause)}\n` +
+            'Set PYRIC_AI_PROXY_UPSTREAM to an OpenAI-compatible base URL ' +
+            `(default ${AI_PROXY_DEFAULT_UPSTREAM}).`);
+        return;
+    }
+    // A refusal from a reachable upstream (bad model, missing key, rate limit)
+    // is just as invisible to a headless developer as a dead socket: the
+    // status rides through to the caller untouched, and is ALSO announced here.
+    // `Retry-After` rides along when the upstream sent one (429s and 503s carry
+    // it): it is the only place the requested backoff appears, since nothing in
+    // this path retries or sleeps.
+    if (!upstream.ok) {
+        const retryAfter = upstream.headers.get('retry-after');
+        const failure = {
+            kind: 'status',
+            target,
+            latencyMs: Date.now() - startedAt,
+            status: upstream.status,
+        };
+        if (retryAfter !== null)
+            failure.retryAfter = retryAfter;
+        noteAiProxyFailure(failure, throttle, logger);
+    }
+    const responseHeaders = { 'cache-control': 'no-store' };
+    const contentType = upstream.headers.get('content-type');
+    if (contentType)
+        responseHeaders['content-type'] = contentType;
+    res.writeHead(upstream.status, responseHeaders);
+    if (!upstream.body) {
+        res.end();
+        return;
+    }
+    res.flushHeaders?.();
+    // Chunk-by-chunk passthrough. A dropped client cancels the upstream read
+    // so an abandoned SSE stream doesn't keep the upstream generating.
+    const reader = upstream.body.getReader();
+    let clientGone = false;
+    res.on('close', () => {
+        clientGone = true;
+        void reader.cancel().catch(() => { });
+    });
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            res.write(value);
+        }
+    }
+    catch (e) {
+        // Nothing to salvage for the caller: the response is already committed
+        // with the upstream's status, so a truncated body is all it gets. But a
+        // half-delivered completion is exactly the failure that used to vanish,
+        // so announce it, unless the CLIENT is the one who walked away (a closed
+        // tab cancelling an SSE stream is normal, not a fault worth a warning).
+        if (!clientGone) {
+            noteAiProxyFailure({
+                kind: 'stream-abort',
+                target,
+                latencyMs: Date.now() - startedAt,
+                cause: e instanceof Error ? e.message : String(e),
+            }, throttle, logger);
+        }
+    }
+    res.end();
+}
+//# sourceMappingURL=ai-proxy.js.map

package/dist/serve/ai-proxy.js.map

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

package/dist/serve/ai-status.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The AI line in the dev server's startup banner.
+ *
+ * AI is the only live service that used to boot silently: hosting, sandbox
+ * bundles, rules, Studio, the bridge and persistence all announce themselves,
+ * so "nothing about AI" read as "AI isn't part of this server" rather than
+ * "AI is here, unconfigured". One description ({@link describeAiStatus}),
+ * rendered in the two dev-server flavors, so the `pyric dev` banner and the
+ * Vite plugin can never disagree about what AI resolved to.
+ */
+import type { AiEngineConfigWire } from './worker/protocol.js';
+/**
+ * What the dev server itself knows about AI by the time it finishes booting.
+ *
+ * Everything here is resolved SYNCHRONOUSLY at bootstrap: the plugin's
+ * `ai.engine`/`ai.model` (already reduced to the worker wire shape) and the
+ * proxy upstream. Nothing in this shape forces a broker, a page, or an
+ * upstream connection into existence just to be reported. The engine is
+ * instantiated lazily, on the first `ai.*` op, in the page or the worker.
+ */
+export interface AiStartupStatus {
+    /** Engine resolved by the dev server (the Vite plugin's `ai.engine` /
+     *  `ai.model`). Absent means nothing server-side: the served page's own
+     *  `getAI(...)` chooses the engine at runtime, and the server cannot know
+     *  which (there is no CLI surface for it under `pyric dev`). */
+    engine?: AiEngineConfigWire;
+    /** `ai.mode`: `production` passes through to Google AI instead of mirroring. */
+    mode?: 'sandbox' | 'production';
+    /** Configured OpenAI-compatible upstream (`ai.proxyUpstream`). Absent falls
+     *  back to `PYRIC_AI_PROXY_UPSTREAM`, then the local-Ollama default. */
+    proxyUpstream?: string;
+}
+/**
+ * The banner line for `pyric dev`'s aligned status column (`✔ hosting  ...`).
+ * Exported for unit tests.
+ */
+export declare function formatAiStatusLine(status: AiStartupStatus): string;
+/**
+ * The same report in the Vite dev server's flavor (`  ✔ [pyric] ...`, the
+ * idiom `vite-functions-development.ts` prints). Same content, so the two
+ * dev-server front doors never disagree about what AI resolved to.
+ */
+export declare function formatAiStatusNote(status: AiStartupStatus): string;
+//# sourceMappingURL=ai-status.d.ts.map

package/dist/serve/ai-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-status.d.ts","sourceRoot":"","sources":["../../src/serve/ai-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;;oEAGgE;IAChE,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,gFAAgF;IAChF,IAAI,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IAChC;4EACwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAwDD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAGlE"}

package/dist/serve/ai-status.js

@@ -0,0 +1,77 @@
+import { GEMINI_DEFAULT_BASE_URL, redactUrl } from 'pyric/ai/internal';
+import { AI_PROXY_ROUTE, resolveAiProxyUpstream } from './ai-proxy.js';
+import { sanitizeForTerminal } from './ai-terminal-text.js';
+/** Where the resolved proxy upstream came from, in the terminal's words. The
+ *  provenance is the point of the line: a developer has to be able to tell a
+ *  deliberate upstream from the Ollama default nobody chose, so every source
+ *  names the knob that set it. */
+function describeUpstreamProvenance(source) {
+    if (source === 'option')
+        return ' (ai.proxyUpstream)';
+    if (source === 'env')
+        return ' (PYRIC_AI_PROXY_UPSTREAM)';
+    return ' (default)';
+}
+/** The openai engine's model binding, which may not be pinned at all. */
+function describeOpenAiModel(model) {
+    if (model === undefined)
+        return 'no model pinned';
+    return `model ${sanitizeForTerminal(model)}`;
+}
+/** Mark + body for one AI status line, in both terminal flavors. */
+function describeAiStatus(status) {
+    const upstream = resolveAiProxyUpstream(status.proxyUpstream);
+    const provenance = describeUpstreamProvenance(upstream.source);
+    const proxyChain = `${AI_PROXY_ROUTE} → ${redactUrl(upstream.target)}${provenance}`;
+    const engine = status.engine;
+    if (engine === undefined) {
+        // Visible absence, the `• rules    no firestore.rules ...` idiom: AI
+        // silence used to be indistinguishable from AI-not-wired-up.
+        return {
+            mark: '•',
+            body: `no engine configured; the served page's getAI() picks one; ${proxyChain}`,
+        };
+    }
+    if (engine.kind === 'openai') {
+        const model = describeOpenAiModel(engine.model);
+        const baseUrl = engine.baseUrl ?? AI_PROXY_ROUTE;
+        let endpoint = proxyChain;
+        if (baseUrl !== AI_PROXY_ROUTE) {
+            endpoint = `${redactUrl(baseUrl)} (direct, bypasses ${AI_PROXY_ROUTE})`;
+        }
+        return { mark: '✔', body: `openai (${model}) → ${endpoint}` };
+    }
+    if (engine.kind === 'gemini') {
+        let passthrough = '';
+        if (status.mode === 'production')
+            passthrough = 'production passthrough, ';
+        const hasKey = engine.apiKey !== undefined && engine.apiKey !== '';
+        let key = 'no API key; set GEMINI_API_KEY';
+        if (hasKey)
+            key = 'API key set';
+        let endpoint = GEMINI_DEFAULT_BASE_URL;
+        if (engine.baseUrl !== undefined)
+            endpoint = redactUrl(engine.baseUrl);
+        return { mark: '✔', body: `gemini (${passthrough}${key}) → ${endpoint}` };
+    }
+    const responses = engine.script?.length ?? 0;
+    return { mark: '✔', body: `scripted (${responses} canned response(s), no network)` };
+}
+/**
+ * The banner line for `pyric dev`'s aligned status column (`✔ hosting  ...`).
+ * Exported for unit tests.
+ */
+export function formatAiStatusLine(status) {
+    const { mark, body } = describeAiStatus(status);
+    return `${mark} ai       ${body}`;
+}
+/**
+ * The same report in the Vite dev server's flavor (`  ✔ [pyric] ...`, the
+ * idiom `vite-functions-development.ts` prints). Same content, so the two
+ * dev-server front doors never disagree about what AI resolved to.
+ */
+export function formatAiStatusNote(status) {
+    const { mark, body } = describeAiStatus(status);
+    return `  ${mark} [pyric] ai: ${body}`;
+}
+//# sourceMappingURL=ai-status.js.map

package/dist/serve/ai-status.js.map

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

package/dist/serve/ai-terminal-blocks.d.ts

@@ -0,0 +1,97 @@
+/** Loosely-typed mirror of the AI rejection payload POSTed by
+ *  `ai-diagnostics-relay.ts` (the wire shape lives there). */
+export interface AiRejectionPayload {
+    /** `'ai-rejection'`: what tells the route the body is NOT a rules denial. */
+    kind?: unknown;
+    /** Model resource the rejected op targeted. */
+    model?: unknown;
+    /** Resolved broker engine (`scripted` | `openai` | `gemini` | `custom`). */
+    engine?: unknown;
+    /** Wire error status (e.g. `INVALID_ARGUMENT`) and HTTP-ish code. */
+    status?: unknown;
+    code?: unknown;
+    /** The rejection reason: production's own message for shape errors. */
+    message?: unknown;
+}
+/** Loosely-typed mirror of the AI blocked-response payload. Unlike a
+ *  rejection this carries no `message`: a filter block has no error envelope
+ *  at all (HTTP 200, empty candidate), only the wire's reason enums, so the
+ *  phrasing is this file's job. */
+export interface AiBlockedPayload {
+    /** `'ai-blocked'`: what tells the route the body is a filter block. */
+    kind?: unknown;
+    /** Model resource the blocked op targeted. */
+    model?: unknown;
+    /** Resolved broker engine (`scripted` | `openai` | `gemini` | `custom`). */
+    engine?: unknown;
+    /** Candidate-level block: `SAFETY`, `RECITATION`, `BLOCKLIST`, and so on. */
+    finishReason?: unknown;
+    /** Production's own explanatory text for the block, when it sent one. */
+    finishMessage?: unknown;
+    /** Prompt-level block: `promptFeedback.blockReason`. */
+    blockReason?: unknown;
+}
+/** Loosely-typed mirror of the AI model-substitution payload. Not a refusal:
+ *  the request SUCCEEDED, answered by a model the developer never named,
+ *  which is why nothing else in the stack reports it. */
+export interface AiModelSubstitutionPayload {
+    /** `'ai-model-substituted'`: what tells the route the body is a swap. */
+    kind?: unknown;
+    /** The model the request asked for. */
+    requestedModel?: unknown;
+    /** The model the engine actually calls. */
+    effectiveModel?: unknown;
+    /** Resolved broker engine (`openai` | `gemini` | ...). */
+    engine?: unknown;
+    /** Why it differs, e.g. `engine modelMap`, `experimental alias`. */
+    reason?: unknown;
+}
+/** What the route reads off a body before it knows which kind it holds. */
+export type AiDiagnosticPayload = AiRejectionPayload & AiBlockedPayload & AiModelSubstitutionPayload;
+/**
+ * Format a relayed AI broker rejection into the compact terminal block, the
+ * same `  [pyric] ...` idiom the denial relay and the ai-proxy warning print.
+ * Three lines at most: the reason production itself gives, then the model
+ * (with the resolved engine, since a rejection reads very differently for
+ * `scripted` than for a real upstream), then the wire status. Exported for
+ * unit tests.
+ */
+export declare function formatAiRejectionBlock(payload: AiRejectionPayload): string;
+/**
+ * Format a relayed AI filter block, in the same three lines as
+ * {@link formatAiRejectionBlock}: the wire's own reason, the model + resolved
+ * engine, then WHY there is no content. That third line matters more here
+ * than for a rejection: a block throws nothing, so the only symptom a
+ * developer sees is an empty answer, and production's `finishMessage` (when
+ * it sent one) is the whole explanation. Exported for unit tests.
+ */
+export declare function formatAiBlockedBlock(payload: AiBlockedPayload): string;
+/**
+ * Format a relayed AI model substitution into ONE terminal line, a single
+ * line on purpose: there is no error, no status, and no missing content to
+ * explain. The whole fact IS the arrow, and the parenthetical says which
+ * engine did it and why (`engine modelMap`, `experimental alias`, ...).
+ * Exported for unit tests.
+ */
+export declare function formatAiModelSubstitutionBlock(payload: AiModelSubstitutionPayload): string;
+/**
+ * One record per AI diagnostic kind: how it prints, and the (target, reason)
+ * pair the denials route throttles it by.
+ *
+ * The prefixes on `throttleTarget` keep an AI key from colliding with a
+ * rules-denial key built from a Firestore path, or with each other: a
+ * rejection, a block, and a substitution on the same model are three
+ * different problems. `throttleReason` is each kind's identity: a block has
+ * no message of its own, so its reason enum is what collapses an agent's
+ * retry loop into one line, and a substitution's identity is the model it
+ * actually called, so a swap onto a DIFFERENT model still prints.
+ */
+export interface AiTerminalBlock {
+    format(payload: AiDiagnosticPayload): string;
+    throttleTarget(payload: AiDiagnosticPayload): string;
+    throttleReason(payload: AiDiagnosticPayload): string;
+}
+/** The record for a relayed body's `kind`, or `null` when the body is a rules
+ *  denial (or anything else this route does not recognize). */
+export declare function aiTerminalBlockFor(kind: unknown): AiTerminalBlock | null;
+//# sourceMappingURL=ai-terminal-blocks.d.ts.map

package/dist/serve/ai-terminal-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-terminal-blocks.d.ts","sourceRoot":"","sources":["../../src/serve/ai-terminal-blocks.ts"],"names":[],"mappings":"AAkBA;8DAC8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;mCAGmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;yDAEyD;AACzD,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,0BAA0B,CAAC;AA4BrG;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAc1E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAgBtE;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,0BAA0B,GAAG,MAAM,CAS1F;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC;IAC7C,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC;IACrD,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAAC;CACtD;AAqBD;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAIxE"}