@oh-my-pi/pi-ai 18.4.11 → 18.4.12

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.4.12] - 2026-10-02
+
+### Added
+
+- Added `createAuthGatewayRouter`, the auth-gateway's routes without the HTTP listener, and `serveAuthGatewayStdio`, which serves them as JSON lines (`{"id", "path", "body"}` in, `{"id", "status", "body"}` out) for a parent process.
+
 ## [18.4.11] - 2026-10-02
 
 ### Fixed

package/dist/types/auth-gateway/dispatch.d.ts

@@ -5,8 +5,9 @@ import type { Api, FetchImpl, Model, Usage } from "../types.js";
 import type { ClientUsageIdentity } from "../usage.js";
 import type { AuthGatewayServerOptions } from "./types.js";
 export type ModelResolver = (modelId: string) => Model<Api> | undefined;
-export interface AuthGatewayBootOptions extends AuthGatewayServerOptions {
-    /** Source of credentials. Caller wires this to a broker-backed AuthStorage. */
+/** What the gateway's routes need, whatever transport carries the requests. */
+export interface AuthGatewayRouteOptions {
+    /** Source of credentials: broker-backed for `serve`, the CLI's own for `stdio`. */
     storage: AuthStorage;
     /**
      * Resolve a client-requested model id to a pi-ai Model. Caller supplies
@@ -19,6 +20,9 @@ export interface AuthGatewayBootOptions extends AuthGatewayServerOptions {
     /** Upstream transport for every provider call; defaults to global `fetch`. Test seam. */
     fetch?: FetchImpl;
 }
+/** The HTTP server's options: the routes' plus its listener and inbound auth. */
+export interface AuthGatewayBootOptions extends AuthGatewayServerOptions, AuthGatewayRouteOptions {
+}
 /**
  * The client's own session key, or `undefined` when it sent none. A blank key
  * counts as none: honouring it would collapse every caller that sends an empty

package/dist/types/auth-gateway/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./dispatch.js";
 export * from "./http.js";
 export * from "./session-state.js";
+export * from "./stdio.js";
 export * from "./server.js";
 export * from "./types.js";

package/dist/types/auth-gateway/routes/embeddings.d.ts

@@ -1,3 +1,3 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
 /** OpenAI-compatible `POST /v1/embeddings` gateway handler. */
-export declare function handleEmbeddings(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+export declare function handleEmbeddings(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/images.d.ts

@@ -1,3 +1,3 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
-export declare function handleImageGenerations(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
-export declare function handleImageEdits(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
+export declare function handleImageGenerations(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;
+export declare function handleImageEdits(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/rerank.d.ts

@@ -1,3 +1,3 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
 /** OpenRouter-compatible `POST /v1/rerank` gateway handler. */
-export declare function handleRerank(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+export declare function handleRerank(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/speech.d.ts

@@ -1,2 +1,2 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
-export declare function handleSpeech(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
+export declare function handleSpeech(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/systemone.d.ts

@@ -1,2 +1,2 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
-export declare function handleSystemOne(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
+export declare function handleSystemOne(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/transcriptions.d.ts

@@ -1,3 +1,3 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
 /** OpenAI-compatible `POST /v1/audio/transcriptions` gateway handler. */
-export declare function handleTranscriptions(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+export declare function handleTranscriptions(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;

package/dist/types/auth-gateway/routes/video.d.ts

@@ -1,7 +1,7 @@
-import { type AuthGatewayBootOptions } from "../dispatch.js";
+import { type AuthGatewayRouteOptions } from "../dispatch.js";
 /** OpenRouter-compatible `POST /v1/videos` asynchronous video submit handler. */
-export declare function handleVideoSubmit(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response>;
+export declare function handleVideoSubmit(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response>;
 /** OpenRouter-compatible `GET /v1/videos/:id` asynchronous video poll handler. */
-export declare function handleVideoPoll(bootOpts: AuthGatewayBootOptions, req: Request, peer: string, gatewayId: string): Promise<Response>;
+export declare function handleVideoPoll(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string, gatewayId: string): Promise<Response>;
 /** OpenRouter-compatible `GET /v1/videos/:id/content` streaming video content handler. */
-export declare function handleVideoContent(bootOpts: AuthGatewayBootOptions, req: Request, peer: string, gatewayId: string): Promise<Response>;
+export declare function handleVideoContent(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string, gatewayId: string): Promise<Response>;

package/dist/types/auth-gateway/server.d.ts

@@ -1,5 +1,5 @@
 /**
- * omp auth-gateway HTTP server.
+ * omp auth-gateway router and HTTP server.
  *
  * Accepts any provider-format request (OpenAI chat-completions, Anthropic
  * messages, OpenAI Responses) and dispatches through pi-ai's `streamSimple()`
@@ -23,8 +23,25 @@
  *   POST /v1/audio/transcriptions          → speech-to-text, multipart or JSON base64 in (routes/transcriptions)
  *
  * Chat routes live in this file; every other modality is a `routes/*` module
- * built on the shared plumbing in `dispatch.ts`.
+ * built on the shared plumbing in `dispatch.ts`. {@link createAuthGatewayRouter}
+ * answers the `/v1/*` routes for any transport: {@link startAuthGateway}
+ * serves them over HTTP behind bearer auth, `stdio.ts` over JSON lines.
  */
-import { type AuthGatewayBootOptions } from "./dispatch.js";
+import { type AuthGatewayBootOptions, type AuthGatewayRouteOptions } from "./dispatch.js";
 import type { AuthGatewayServerHandle } from "./types.js";
+/** The gateway's `/v1/*` routes, for a transport that has already admitted the caller. */
+export interface AuthGatewayRouter {
+    /** Answers one request; `peer` names the caller in logs. Never rejects: a crashed route answers 500. */
+    route(req: Request, peer: string): Promise<Response>;
+    /**
+     * Closes the retained provider session state (Codex WebSockets, GitLab Duo
+     * workflows), whose sockets and timers would otherwise keep the process alive.
+     */
+    close(): void;
+}
+/**
+ * The gateway's routes over `opts`, owning their per-session provider state:
+ * two routers in one process never share (or tear down) each other's.
+ */
+export declare function createAuthGatewayRouter(opts: AuthGatewayRouteOptions): AuthGatewayRouter;
 export declare function startAuthGateway(opts: AuthGatewayBootOptions): AuthGatewayServerHandle;

package/dist/types/auth-gateway/stdio.d.ts

@@ -0,0 +1,12 @@
+export interface AuthGatewayStdioOptions {
+    /** Request lines. */
+    input: ReadableStream<Uint8Array>;
+    /** Writes one response line, newline included. */
+    write(line: string): void;
+    /** Answers one request; never rejects (the gateway router's `route`, or a wrapper around it). */
+    route(req: Request): Promise<Response>;
+    /** Reported on the ready line. */
+    version?: string;
+}
+/** Serves `opts.input` until it ends and every request it carried is answered. */
+export declare function serveAuthGatewayStdio(opts: AuthGatewayStdioOptions): Promise<void>;

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export { type Type, type } from "@oh-my-pi/omptype";
 export * from "./api-registry.js";
 export type * from "./auth-broker/index.js";
-export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/dispatch.js";
+export type { AuthGatewayBootOptions, AuthGatewayRouteOptions, ModelResolver } from "./auth-gateway/dispatch.js";
 export * from "./auth-gateway/types.js";
 export * from "./auth-retry.js";
 export * from "./auth-storage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.4.11",
+	"version": "18.4.12",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.4.11",
-		"@oh-my-pi/pi-catalog": "18.4.11",
-		"@oh-my-pi/pi-natives": "18.4.11",
-		"@oh-my-pi/pi-utils": "18.4.11",
-		"@oh-my-pi/pi-wire": "18.4.11"
+		"@oh-my-pi/omptype": "18.4.12",
+		"@oh-my-pi/pi-catalog": "18.4.12",
+		"@oh-my-pi/pi-natives": "18.4.12",
+		"@oh-my-pi/pi-utils": "18.4.12",
+		"@oh-my-pi/pi-wire": "18.4.12"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth-gateway/dispatch.ts

@@ -20,8 +20,9 @@ import type { AuthGatewayServerOptions } from "./types";
 
 export type ModelResolver = (modelId: string) => Model<Api> | undefined;
 
-export interface AuthGatewayBootOptions extends AuthGatewayServerOptions {
-	/** Source of credentials. Caller wires this to a broker-backed AuthStorage. */
+/** What the gateway's routes need, whatever transport carries the requests. */
+export interface AuthGatewayRouteOptions {
+	/** Source of credentials: broker-backed for `serve`, the CLI's own for `stdio`. */
 	storage: AuthStorage;
 	/**
 	 * Resolve a client-requested model id to a pi-ai Model. Caller supplies
@@ -35,6 +36,9 @@ export interface AuthGatewayBootOptions extends AuthGatewayServerOptions {
 	fetch?: FetchImpl;
 }
 
+/** The HTTP server's options: the routes' plus its listener and inbound auth. */
+export interface AuthGatewayBootOptions extends AuthGatewayServerOptions, AuthGatewayRouteOptions {}
+
 /**
  * The client's own session key, or `undefined` when it sent none. A blank key
  * counts as none: honouring it would collapse every caller that sends an empty

package/src/auth-gateway/index.ts

@@ -1,5 +1,6 @@
 export * from "./dispatch";
 export * from "./http";
 export * from "./session-state";
+export * from "./stdio";
 export * from "./server";
 export * from "./types";

package/src/auth-gateway/routes/embeddings.ts

@@ -4,7 +4,7 @@ import { classifyGatewayError } from "../../error/gateway";
 import * as embeddings from "../../providers/embeddings-server";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -14,7 +14,7 @@ import { gatewayResponseHeaders, json, resolveClientIdentity } from "../http";
 
 /** OpenAI-compatible `POST /v1/embeddings` gateway handler. */
 export async function handleEmbeddings(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 ): Promise<Response> {

package/src/auth-gateway/routes/images.ts

@@ -5,7 +5,7 @@ import { generateImage } from "../../images";
 import * as imagesServer from "../../providers/images-server";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -23,7 +23,7 @@ function isGatewayImageApi(api: string): boolean {
 }
 
 async function handleImages(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	kind: imagesServer.ImageRequestKind,
@@ -119,13 +119,13 @@ async function handleImages(
 }
 
 export function handleImageGenerations(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 ): Promise<Response> {
 	return handleImages(bootOpts, req, peer, "generations");
 }
 
-export function handleImageEdits(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response> {
+export function handleImageEdits(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response> {
 	return handleImages(bootOpts, req, peer, "edits");
 }

package/src/auth-gateway/routes/rerank.ts

@@ -4,7 +4,7 @@ import * as rerankWire from "../../providers/rerank-server";
 import { rerank } from "../../rerank";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -13,7 +13,7 @@ import {
 import { gatewayResponseHeaders, json, resolveClientIdentity } from "../http";
 
 /** OpenRouter-compatible `POST /v1/rerank` gateway handler. */
-export async function handleRerank(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response> {
+export async function handleRerank(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response> {
 	const startedAt = performance.now();
 	const requestId = crypto.randomUUID();
 	const controller = mirrorRequestAbort(req);

package/src/auth-gateway/routes/speech.ts

@@ -4,7 +4,7 @@ import * as speechWire from "../../providers/speech-server";
 import { isSpeechApi, synthesizeSpeech } from "../../speech";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -12,7 +12,7 @@ import {
 } from "../dispatch";
 import { gatewayResponseHeaders, resolveClientIdentity } from "../http";
 
-export async function handleSpeech(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response> {
+export async function handleSpeech(bootOpts: AuthGatewayRouteOptions, req: Request, peer: string): Promise<Response> {
 	const startedAt = performance.now();
 	const requestId = crypto.randomUUID();
 	const controller = mirrorRequestAbort(req);

package/src/auth-gateway/routes/systemone.ts

@@ -17,7 +17,7 @@ import { isJudgmentApi, TypeSafeJudge } from "../../judgment/typesafe";
 import * as systemOne from "../../providers/systemone-server";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -25,7 +25,11 @@ import {
 } from "../dispatch";
 import { gatewayResponseHeaders, json, resolveClientIdentity } from "../http";
 
-export async function handleSystemOne(bootOpts: AuthGatewayBootOptions, req: Request, peer: string): Promise<Response> {
+export async function handleSystemOne(
+	bootOpts: AuthGatewayRouteOptions,
+	req: Request,
+	peer: string,
+): Promise<Response> {
 	const startedAt = performance.now();
 	const requestId = crypto.randomUUID();
 	const controller = mirrorRequestAbort(req);

package/src/auth-gateway/routes/transcriptions.ts

@@ -4,7 +4,7 @@ import * as transcriptions from "../../providers/transcriptions-server";
 import { transcribeAudio } from "../../transcription";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	recordGatewayUsage,
@@ -14,7 +14,7 @@ import { gatewayResponseHeaders, json, resolveClientIdentity } from "../http";
 
 /** OpenAI-compatible `POST /v1/audio/transcriptions` gateway handler. */
 export async function handleTranscriptions(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 ): Promise<Response> {

package/src/auth-gateway/routes/video.ts

@@ -7,7 +7,7 @@ import { downloadVideo, pollVideo, submitVideo } from "../../video";
 import type { VideoJob } from "../../video/types";
 import { deterministicUuid } from "../../utils/deterministic-id";
 import {
-	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	resolveGatewayApiKey,
@@ -27,7 +27,7 @@ function aborted(): Response {
 }
 
 async function resolveVideoJob(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	gatewayId: string,
@@ -63,7 +63,7 @@ async function resolveVideoJob(
 	return { model, upstreamId: identity.upstreamId, sessionId, apiKey, controller };
 }
 
-function videoOptions(bootOpts: AuthGatewayBootOptions, resolved: ResolvedVideoRequest, peer: string) {
+function videoOptions(bootOpts: AuthGatewayRouteOptions, resolved: ResolvedVideoRequest, peer: string) {
 	return {
 		apiKey: buildGatewayApiKeyResolver(
 			bootOpts.storage,
@@ -97,7 +97,7 @@ function logVideoRequest(
 }
 
 function recordCompletedUsage(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	resolved: ResolvedVideoRequest,
 	req: Request,
 	job: VideoJob,
@@ -114,7 +114,7 @@ function recordCompletedUsage(
 
 /** OpenRouter-compatible `POST /v1/videos` asynchronous video submit handler. */
 export async function handleVideoSubmit(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 ): Promise<Response> {
@@ -186,7 +186,7 @@ export async function handleVideoSubmit(
 
 /** OpenRouter-compatible `GET /v1/videos/:id` asynchronous video poll handler. */
 export async function handleVideoPoll(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	gatewayId: string,
@@ -218,7 +218,7 @@ export async function handleVideoPoll(
 
 /** OpenRouter-compatible `GET /v1/videos/:id/content` streaming video content handler. */
 export async function handleVideoContent(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	gatewayId: string,

package/src/auth-gateway/server.ts

@@ -1,5 +1,5 @@
 /**
- * omp auth-gateway HTTP server.
+ * omp auth-gateway router and HTTP server.
  *
  * Accepts any provider-format request (OpenAI chat-completions, Anthropic
  * messages, OpenAI Responses) and dispatches through pi-ai's `streamSimple()`
@@ -23,7 +23,9 @@
  *   POST /v1/audio/transcriptions          → speech-to-text, multipart or JSON base64 in (routes/transcriptions)
  *
  * Chat routes live in this file; every other modality is a `routes/*` module
- * built on the shared plumbing in `dispatch.ts`.
+ * built on the shared plumbing in `dispatch.ts`. {@link createAuthGatewayRouter}
+ * answers the `/v1/*` routes for any transport: {@link startAuthGateway}
+ * serves them over HTTP behind bearer auth, `stdio.ts` over JSON lines.
  */
 
 import { Effort } from "@oh-my-pi/pi-catalog/effort";
@@ -41,6 +43,7 @@ import { deterministicUuid } from "../utils/deterministic-id";
 import { parseBind } from "../utils/parse-bind";
 import {
 	type AuthGatewayBootOptions,
+	type AuthGatewayRouteOptions,
 	buildGatewayApiKeyResolver,
 	mirrorRequestAbort,
 	normalizeClientSessionKey,
@@ -249,7 +252,7 @@ function chatRouteRejection(model: Model<Api>): string | undefined {
 
 async function handleFormatEndpoint(
 	route: { module: FormatModule; label: string },
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	sessionStates: AuthGatewaySessionStateStore,
@@ -493,7 +496,7 @@ async function handleFormatEndpoint(
  * path.
  */
 async function handlePiNative(
-	bootOpts: AuthGatewayBootOptions,
+	bootOpts: AuthGatewayRouteOptions,
 	req: Request,
 	peer: string,
 	sessionStates: AuthGatewaySessionStateStore,
@@ -740,7 +743,7 @@ interface ModelListRow {
 	supports_tools?: boolean;
 }
 
-function handleModelsList(opts: AuthGatewayBootOptions): Response {
+function handleModelsList(opts: AuthGatewayRouteOptions): Response {
 	const seen = new Set<string>();
 	const data: ModelListRow[] = [];
 	for (const model of opts.listModels?.() ?? []) {
@@ -786,13 +789,132 @@ const LOGGABLE_PATHS: Record<string, true> = {
 	"/v1/models": true,
 };
 
+/** Only static routes reach logs verbatim; dynamic or unknown paths may carry caller-supplied secrets. */
+function loggablePath(pathname: string): string {
+	return Object.hasOwn(FORMAT_ROUTES, pathname) || Object.hasOwn(LOGGABLE_PATHS, pathname) ? pathname : "<unrouted>";
+}
+
+/** The gateway's `/v1/*` routes, for a transport that has already admitted the caller. */
+export interface AuthGatewayRouter {
+	/** Answers one request; `peer` names the caller in logs. Never rejects: a crashed route answers 500. */
+	route(req: Request, peer: string): Promise<Response>;
+	/**
+	 * Closes the retained provider session state (Codex WebSockets, GitLab Duo
+	 * workflows), whose sockets and timers would otherwise keep the process alive.
+	 */
+	close(): void;
+}
+
+/**
+ * The gateway's routes over `opts`, owning their per-session provider state:
+ * two routers in one process never share (or tear down) each other's.
+ */
+export function createAuthGatewayRouter(opts: AuthGatewayRouteOptions): AuthGatewayRouter {
+	const sessionStates = new AuthGatewaySessionStateStore();
+	const route = async (req: Request, peer: string): Promise<Response> => {
+		const pathname = new URL(req.url).pathname;
+		try {
+			// Aggregated usage — backed by AuthStorage's 5-min per-credential cache.
+			// Same shape as the broker's `/v1/usage`, so widget/llm-git speak to either with the
+			// same client struct.
+			if (req.method === "GET" && pathname === "/v1/usage") {
+				return await handleUsage(opts.storage, req.signal);
+			}
+
+			// Per-credential auth probe — diagnoses which row in a multi-account
+			// pool is producing 401s. Aggregated `/v1/usage` silently drops failed
+			// credentials, so we need a separate endpoint that captures errors.
+			if (req.method === "GET" && pathname === "/v1/credentials/check") {
+				return await handleCredentialsCheck(opts.storage, req.signal);
+			}
+
+			// Provider-format dispatch.
+			const formatRoute = FORMAT_ROUTES[pathname];
+			if (formatRoute && req.method === "POST") {
+				return await handleFormatEndpoint(formatRoute, opts, req, peer, sessionStates);
+			}
+
+			// Pi-native fast path. Same auth + provider plumbing as the
+			// foreign-wire routes, just without the wire-format translation.
+			if (req.method === "POST" && pathname === "/v1/pi/stream") {
+				return await handlePiNative(opts, req, peer, sessionStates);
+			}
+
+			// TypeSafe System One judgments (jev). TypeSafe SDKs and omp's own
+			// judge point `TYPESAFE_BASE_URL` at the gateway; OpenRouter SDKs
+			// reach the same handler through their Decisions path.
+			if (req.method === "POST" && (pathname === "/v1/systemone" || pathname === "/alpha/decisions")) {
+				return await handleSystemOne(opts, req, peer);
+			}
+
+			// Image generation: OpenAI `/v1/images/generations` + OpenRouter `/v1/images`
+			// (JSON), and OpenAI multipart / OpenRouter JSON edits.
+			if (req.method === "POST" && (pathname === "/v1/images/generations" || pathname === "/v1/images")) {
+				return await handleImageGenerations(opts, req, peer);
+			}
+			if (req.method === "POST" && pathname === "/v1/images/edits") {
+				return await handleImageEdits(opts, req, peer);
+			}
+
+			// Text-to-speech, OpenAI/OpenRouter wire; answers raw audio bytes.
+			if (req.method === "POST" && pathname === "/v1/audio/speech") {
+				return await handleSpeech(opts, req, peer);
+			}
+
+			// Speech-to-text, OpenAI multipart or OpenRouter JSON base64 wire.
+			if (req.method === "POST" && pathname === "/v1/audio/transcriptions") {
+				return await handleTranscriptions(opts, req, peer);
+			}
+
+			// Embeddings, OpenAI wire (OpenRouter is compatible).
+			if (req.method === "POST" && pathname === "/v1/embeddings") {
+				return await handleEmbeddings(opts, req, peer);
+			}
+
+			// Rerank, OpenRouter wire.
+			if (req.method === "POST" && pathname === "/v1/rerank") {
+				return await handleRerank(opts, req, peer);
+			}
+
+			// Video generation, OpenRouter's asynchronous wire: submit, then poll
+			// and download by the gateway-issued job id (stateless — the id
+			// encodes provider, model, and upstream job).
+			if (req.method === "POST" && pathname === "/v1/videos") {
+				return await handleVideoSubmit(opts, req, peer);
+			}
+			const videoJob = req.method === "GET" ? VIDEO_JOB_PATH.exec(pathname) : null;
+			if (videoJob) {
+				const gatewayId = decodeURIComponent(videoJob[1]);
+				const handler = videoJob[2] ? handleVideoContent : handleVideoPoll;
+				return await handler(opts, req, peer, gatewayId);
+			}
+
+			// Model catalog.
+			if (req.method === "GET" && pathname === "/v1/models") {
+				return handleModelsList(opts);
+			}
+
+			// Route-table miss: no format module to defer to, so we emit a
+			// plain JSON 404 rather than guessing at a protocol-specific envelope.
+			return json(404, { error: `No route: ${req.method} ${pathname}` });
+		} catch (error) {
+			logger.error("auth-gateway handler crashed", {
+				method: req.method,
+				path: loggablePath(pathname),
+				peer,
+				error: String(error),
+			});
+			return json(500, { error: "internal error" });
+		}
+	};
+	return { route, close: () => sessionStates.close() };
+}
+
 export function startAuthGateway(opts: AuthGatewayBootOptions): AuthGatewayServerHandle {
 	const bind = parseBind(opts.bind ?? DEFAULT_AUTH_GATEWAY_BIND);
 	const tokens = new Set<string>(opts.bearerTokens);
 	const version = opts.version;
-	// Owned by this server instance so two gateways in one process never share
-	// (or tear down) each other's provider state, and so `close()` can drain it.
-	const sessionStates = new AuthGatewaySessionStateStore();
+	const router = createAuthGatewayRouter(opts);
 
 	const server = Bun.serve({
 		hostname: bind.hostname,
@@ -800,125 +922,29 @@ export function startAuthGateway(opts: AuthGatewayBootOptions): AuthGatewayServe
 		fetch: async (req, server): Promise<Response> => {
 			const url = new URL(req.url);
 			const pathname = url.pathname;
-			// Only static routes reach logs verbatim; dynamic or unknown paths may carry caller-supplied secrets.
-			const logPath =
-				Object.hasOwn(FORMAT_ROUTES, pathname) || Object.hasOwn(LOGGABLE_PATHS, pathname) ? pathname : "<unrouted>";
 			const socketPeer = server.requestIP(req)?.address ?? "unknown";
-			let peer = socketPeer;
 			// CORS preflight is always answered without auth — browsers send
 			// preflights pre-authentication and a 401 here breaks the actual
 			// request before the bearer is ever attached.
 			if (req.method === "OPTIONS") {
 				return new Response(null, { status: 204, headers: corsHeaders(req) });
 			}
-			try {
-				if (req.method === "GET" && pathname === "/healthz") {
-					return withCors(json(200, { ok: true, version }), req);
-				}
-				if (!isAuthorized(req, tokens)) {
-					logger.info("auth-gateway request unauthorized", {
-						method: req.method,
-						path: logPath,
-						peer: socketPeer,
-					});
-					return withCors(json(401, { error: "unauthorized" }), req);
-				}
-				if (hasMisplacedBearer(req, url, tokens)) {
-					return withCors(json(400, { error: "gateway bearer token outside Authorization" }), req);
-				}
-				peer = resolvePeer(req, socketPeer, opts.trustProxyHeaders);
-				// Aggregated usage — backed by AuthStorage's 5-min per-credential cache.
-				// Same shape as the broker's `/v1/usage`, so widget/llm-git speak to either with the
-				// same client struct.
-				if (req.method === "GET" && pathname === "/v1/usage") {
-					return withCors(await handleUsage(opts.storage, req.signal), req);
-				}
-
-				// Per-credential auth probe — diagnoses which row in a multi-account
-				// pool is producing 401s. Aggregated `/v1/usage` silently drops failed
-				// credentials, so we need a separate endpoint that captures errors.
-				if (req.method === "GET" && pathname === "/v1/credentials/check") {
-					return withCors(await handleCredentialsCheck(opts.storage, req.signal), req);
-				}
-
-				// Provider-format dispatch.
-				const formatRoute = FORMAT_ROUTES[pathname];
-				if (formatRoute && req.method === "POST") {
-					return withCors(await handleFormatEndpoint(formatRoute, opts, req, peer, sessionStates), req);
-				}
-
-				// Pi-native fast path. Same auth + provider plumbing as the
-				// foreign-wire routes, just without the wire-format translation.
-				if (req.method === "POST" && pathname === "/v1/pi/stream") {
-					return withCors(await handlePiNative(opts, req, peer, sessionStates), req);
-				}
-
-				// TypeSafe System One judgments (jev). TypeSafe SDKs and omp's own
-				// judge point `TYPESAFE_BASE_URL` at the gateway; OpenRouter SDKs
-				// reach the same handler through their Decisions path.
-				if (req.method === "POST" && (pathname === "/v1/systemone" || pathname === "/alpha/decisions")) {
-					return withCors(await handleSystemOne(opts, req, peer), req);
-				}
-
-				// Image generation: OpenAI `/v1/images/generations` + OpenRouter `/v1/images`
-				// (JSON), and OpenAI multipart / OpenRouter JSON edits.
-				if (req.method === "POST" && (pathname === "/v1/images/generations" || pathname === "/v1/images")) {
-					return withCors(await handleImageGenerations(opts, req, peer), req);
-				}
-				if (req.method === "POST" && pathname === "/v1/images/edits") {
-					return withCors(await handleImageEdits(opts, req, peer), req);
-				}
-
-				// Text-to-speech, OpenAI/OpenRouter wire; answers raw audio bytes.
-				if (req.method === "POST" && pathname === "/v1/audio/speech") {
-					return withCors(await handleSpeech(opts, req, peer), req);
-				}
-
-				// Speech-to-text, OpenAI multipart or OpenRouter JSON base64 wire.
-				if (req.method === "POST" && pathname === "/v1/audio/transcriptions") {
-					return withCors(await handleTranscriptions(opts, req, peer), req);
-				}
-
-				// Embeddings, OpenAI wire (OpenRouter is compatible).
-				if (req.method === "POST" && pathname === "/v1/embeddings") {
-					return withCors(await handleEmbeddings(opts, req, peer), req);
-				}
-
-				// Rerank, OpenRouter wire.
-				if (req.method === "POST" && pathname === "/v1/rerank") {
-					return withCors(await handleRerank(opts, req, peer), req);
-				}
-
-				// Video generation, OpenRouter's asynchronous wire: submit, then poll
-				// and download by the gateway-issued job id (stateless — the id
-				// encodes provider, model, and upstream job).
-				if (req.method === "POST" && pathname === "/v1/videos") {
-					return withCors(await handleVideoSubmit(opts, req, peer), req);
-				}
-				const videoJob = req.method === "GET" ? VIDEO_JOB_PATH.exec(pathname) : null;
-				if (videoJob) {
-					const gatewayId = decodeURIComponent(videoJob[1]);
-					const handler = videoJob[2] ? handleVideoContent : handleVideoPoll;
-					return withCors(await handler(opts, req, peer, gatewayId), req);
-				}
-
-				// Model catalog.
-				if (req.method === "GET" && pathname === "/v1/models") {
-					return withCors(handleModelsList(opts), req);
-				}
-
-				// Route-table miss: no format module to defer to, so we emit a
-				// plain JSON 404 rather than guessing at a protocol-specific envelope.
-				return withCors(json(404, { error: `No route: ${req.method} ${pathname}` }), req);
-			} catch (error) {
-				logger.error("auth-gateway handler crashed", {
+			if (req.method === "GET" && pathname === "/healthz") {
+				return withCors(json(200, { ok: true, version }), req);
+			}
+			if (!isAuthorized(req, tokens)) {
+				logger.info("auth-gateway request unauthorized", {
 					method: req.method,
-					path: logPath,
-					peer,
-					error: String(error),
+					path: loggablePath(pathname),
+					peer: socketPeer,
 				});
-				return withCors(json(500, { error: "internal error" }), req);
+				return withCors(json(401, { error: "unauthorized" }), req);
+			}
+			if (hasMisplacedBearer(req, url, tokens)) {
+				return withCors(json(400, { error: "gateway bearer token outside Authorization" }), req);
 			}
+			const peer = resolvePeer(req, socketPeer, opts.trustProxyHeaders);
+			return withCors(await router.route(req, peer), req);
 		},
 		// Max-out Bun's idle timeout. Long thinking-budget calls can sit idle
 		// for minutes before the first token arrives; the default kills them.
@@ -936,7 +962,7 @@ export function startAuthGateway(opts: AuthGatewayBootOptions): AuthGatewayServe
 			// Drain after the listener is down: the retained provider states own
 			// sockets and timers (Codex WebSockets, GitLab Duo workflows), so the
 			// process can't settle until each one is closed.
-			sessionStates.close();
+			router.close();
 		},
 	};
 }

package/src/auth-gateway/stdio.ts

@@ -0,0 +1,132 @@
+/**
+ * The auth-gateway's routes over JSON lines, for a parent process that owns
+ * the gateway as its child: one request per input line, one response per
+ * output line.
+ *
+ * ```text
+ * → {"id": 1, "path": "/v1/chat/completions", "body": {"model": "…", "messages": […]}}
+ * ← {"id": 1, "status": 200, "body": {"choices": […]}}
+ * ```
+ *
+ * The first output line is `{"ready": true, "version": "…"}`. `method`
+ * defaults to `POST` when a request carries a `body` and to `GET` otherwise.
+ * Requests run concurrently and answer in completion order, matched by `id`
+ * (a string or number). A JSON response body is embedded as JSON, a text one
+ * (a `stream: true` reply's SSE) as a string, anything else (audio, video) as
+ * base64 with `"encoding": "base64"`. A line that is not a request answers
+ * status 400 with the `id` it carried, if any. Serving ends once input ends
+ * and every request has been answered.
+ */
+import { logger, readLines } from "@oh-my-pi/pi-utils";
+
+/** Request ids are opaque to the transport: echoed back as received. */
+type StdioId = string | number;
+
+/** One response line. */
+interface StdioResponse {
+	id: StdioId | null;
+	status: number;
+	body: unknown;
+	encoding?: "base64";
+}
+
+export interface AuthGatewayStdioOptions {
+	/** Request lines. */
+	input: ReadableStream<Uint8Array>;
+	/** Writes one response line, newline included. */
+	write(line: string): void;
+	/** Answers one request; never rejects (the gateway router's `route`, or a wrapper around it). */
+	route(req: Request): Promise<Response>;
+	/** Reported on the ready line. */
+	version?: string;
+}
+
+/** Origin of the `Request`s built from input lines; only the path reaches the routes. */
+const STDIO_ORIGIN = "http://stdio";
+
+/** Serves `opts.input` until it ends and every request it carried is answered. */
+export async function serveAuthGatewayStdio(opts: AuthGatewayStdioOptions): Promise<void> {
+	const send = (response: StdioResponse): void => opts.write(`${JSON.stringify(response)}\n`);
+	opts.write(`${JSON.stringify({ ready: true, version: opts.version })}\n`);
+	const inFlight = new Set<Promise<void>>();
+	const decoder = new TextDecoder();
+	for await (const line of readLines(opts.input)) {
+		const text = decoder.decode(line).trim();
+		if (!text) continue;
+		const request = parseRequest(text);
+		if ("error" in request) {
+			send({
+				id: request.id,
+				status: 400,
+				body: { error: { message: request.error, type: "invalid_request_error" } },
+			});
+			continue;
+		}
+		const answered = opts
+			.route(request.req)
+			.then(readResponse)
+			.then(
+				response => send({ id: request.id, ...response }),
+				(error: unknown) => {
+					logger.error("auth-gateway stdio request failed", { error: String(error) });
+					send({
+						id: request.id,
+						status: 500,
+						body: { error: { message: "internal error", type: "server_error" } },
+					});
+				},
+			);
+		inFlight.add(answered);
+		void answered.finally(() => inFlight.delete(answered));
+	}
+	await Promise.all(inFlight);
+}
+
+/** A request line as a `Request`, or why it isn't one (with its `id` when it had a usable one). */
+function parseRequest(text: string): { id: StdioId; req: Request } | { id: StdioId | null; error: string } {
+	let frame: unknown;
+	try {
+		frame = JSON.parse(text);
+	} catch (error) {
+		return { id: null, error: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+		return { id: null, error: "A request is a JSON object" };
+	}
+	const { id, method, path, body } = frame as Record<string, unknown>;
+	if (typeof id !== "string" && typeof id !== "number") {
+		return { id: null, error: "`id` must be a string or a number" };
+	}
+	if (typeof path !== "string" || !path.startsWith("/")) {
+		return { id, error: "`path` must be an absolute path such as /v1/chat/completions" };
+	}
+	if (method !== undefined && typeof method !== "string") {
+		return { id, error: "`method` must be a string" };
+	}
+	const init: RequestInit =
+		body === undefined
+			? { method: method ?? "GET" }
+			: { method: method ?? "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+	try {
+		return { id, req: new Request(`${STDIO_ORIGIN}${path}`, init) };
+	} catch (error) {
+		return { id, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+/** A whole response as a line's `status`/`body`/`encoding`. */
+async function readResponse(response: Response): Promise<Omit<StdioResponse, "id">> {
+	const type = response.headers.get("content-type") ?? "";
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	if (bytes.length === 0) return { status: response.status, body: null };
+	if (type.includes("json")) {
+		const text = new TextDecoder().decode(bytes);
+		try {
+			return { status: response.status, body: JSON.parse(text) };
+		} catch {
+			return { status: response.status, body: text };
+		}
+	}
+	if (type.startsWith("text/")) return { status: response.status, body: new TextDecoder().decode(bytes) };
+	return { status: response.status, body: bytes.toBase64(), encoding: "base64" };
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 export { type Type, type } from "@oh-my-pi/omptype";
 export * from "./api-registry";
 export type * from "./auth-broker";
-export type { AuthGatewayBootOptions, ModelResolver } from "./auth-gateway/dispatch";
+export type { AuthGatewayBootOptions, AuthGatewayRouteOptions, ModelResolver } from "./auth-gateway/dispatch";
 export * from "./auth-gateway/types";
 export * from "./auth-retry";
 export * from "./auth-storage";