@piagent/platform 1.3.1 → 1.4.0

package/packages/piagent-webui/server/ipc-read-model-client.ts

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+
+import type { SourceView, StreamEvent, StreamReplay, WebUiReadModelProvider } from "./read-model-provider.ts";
+
+type ResponseMessage = { channel: "piagent-webui"; type: "response"; requestId: string; ok: boolean; value?: unknown; error?: string };
+type EventMessage = { channel: "piagent-webui"; type: "event"; event: StreamEvent };
+type Pending = { resolve(value: unknown): void; reject(error: Error): void; timer: NodeJS.Timeout };
+
+export class IpcReadModelClient implements WebUiReadModelProvider {
+  readonly #pending = new Map<string, Pending>();
+  readonly #listeners = new Set<(event: StreamEvent) => void>();
+  readonly #timeoutMs: number;
+
+  constructor(timeoutMs = 30_000) {
+    if (typeof process.send !== "function") throw new Error("webui-sidecar-ipc-unavailable");
+    this.#timeoutMs = timeoutMs;
+    process.on("message", this.#onMessage);
+    process.once("disconnect", this.close);
+  }
+
+  readonly #onMessage = (message: unknown) => {
+    if (!message || typeof message !== "object") return;
+    const value = message as Record<string, unknown>;
+    if (value.channel !== "piagent-webui") return;
+    if (value.type === "event" && value.event && typeof value.event === "object") {
+      for (const listener of this.#listeners) listener(value.event as StreamEvent);
+      return;
+    }
+    if (value.type !== "response" || typeof value.requestId !== "string") return;
+    const pending = this.#pending.get(value.requestId);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.#pending.delete(value.requestId);
+    if (value.ok) pending.resolve(value.value);
+    else pending.reject(new Error(typeof value.error === "string" ? value.error : "webui-parent-request-failed"));
+  };
+
+  #request(method: string, args: unknown[] = []): Promise<any> {
+    const requestId = `request.${randomUUID()}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(requestId);
+        reject(new Error("webui-parent-request-timeout"));
+      }, this.#timeoutMs);
+      timer.unref();
+      this.#pending.set(requestId, { resolve, reject, timer });
+      process.send?.({ channel: "piagent-webui", type: "request", requestId, method, args });
+    });
+  }
+
+  capabilities(): Promise<unknown> { return this.#request("capabilities"); }
+  snapshot(): Promise<unknown> { return this.#request("snapshot"); }
+  sourceChanges(view: SourceView): Promise<unknown> { return this.#request("sourceChanges", [view]); }
+  diff(view: SourceView, fileRef: string): Promise<unknown> { return this.#request("diff", [view, fileRef]); }
+  review(view: SourceView, fileRef: string): Promise<unknown> { return this.#request("review", [view, fileRef]); }
+  sourceMutation(action: "source.stage" | "source.unstage", fileRef: string): Promise<unknown> { return this.#request("sourceMutation", [action, fileRef]); }
+  sourceRevert(fileRef: string, hunkRef: string | null): Promise<unknown> { return this.#request("sourceRevert", [fileRef, hunkRef]); }
+  commitSummary(): Promise<unknown> { return this.#request("commitSummary"); }
+  taskIndex(): Promise<unknown> { return this.#request("taskIndex"); }
+  taskTimeline(runRef: string): Promise<unknown> { return this.#request("taskTimeline", [runRef]); }
+  recoveryHistory(runRef: string): Promise<unknown> { return this.#request("recoveryHistory", [runRef]); }
+  handoffHistory(runRef: string): Promise<unknown> { return this.#request("handoffHistory", [runRef]); }
+  subagentTree(runRef: string): Promise<unknown> { return this.#request("subagentTree", [runRef]); }
+  releaseMonitor(): Promise<unknown> { return this.#request("releaseMonitor"); }
+  activity(): Promise<unknown> { return this.#request("activity"); }
+  logPreview(activityRef: string): Promise<unknown> { return this.#request("logPreview", [activityRef]); }
+  transcript(beforeCursor: string | null, limit: number): Promise<unknown> { return this.#request("transcript", [beforeCursor, limit]); }
+  queue(): Promise<unknown> { return this.#request("queue"); }
+  modelCatalog(): Promise<unknown> { return this.#request("modelCatalog"); }
+  approval(approvalRef: string): Promise<unknown> { return this.#request("approval", [approvalRef]); }
+  executeControl(command: unknown): Promise<unknown> { return this.#request("control", [command]); }
+  executeAttachment(command: unknown): Promise<unknown> { return this.#request("attachment", [command]); }
+  executeApproval(approvalRef: string, decision: unknown): Promise<unknown> { return this.#request("approvalDecision", [approvalRef, decision]); }
+  replay(after: string | null, limit: number): Promise<StreamReplay> { return this.#request("replay", [after, limit]); }
+  subscribe(listener: (event: StreamEvent) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  close = (): void => {
+    process.off("message", this.#onMessage);
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("webui-parent-disconnected"));
+    }
+    this.#pending.clear();
+    this.#listeners.clear();
+  };
+}

package/packages/piagent-webui/server/loopback-server.ts

@@ -0,0 +1,368 @@
+import http, { type IncomingMessage, type ServerResponse } from "node:http";
+import { randomBytes } from "node:crypto";
+
+import { errorResponse, applySecurityHeaders, jsonResponse } from "./http-security.ts";
+import { ReadModelNotFound, type WebUiReadModelProvider } from "./read-model-provider.ts";
+import { routeReadOnlyRequest } from "./read-only-router.ts";
+import { SessionAuthority } from "./session-auth.ts";
+import { SseHub } from "./sse-hub.ts";
+import { loadStaticBundle, type StaticAsset } from "./static-bundle.ts";
+import { attachGatewayWebSocket, type GatewayProtocolHandler } from "./gateway-websocket.ts";
+
+const MAX_BOOTSTRAP_BODY_BYTES = 4_096;
+const MAX_CONTROL_BODY_BYTES = 70_000;
+const MAX_ATTACHMENT_BODY_BYTES = 11_250_000;
+const REQUESTS_PER_MINUTE = 120;
+const BOOTSTRAPS_PER_MINUTE = 8;
+const CONTROLS_PER_MINUTE = 60;
+const MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
+const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+type ReadCapabilities = () => unknown | Promise<unknown>;
+type RateState = { windowStart: number; requests: number; bootstraps: number; controls: number };
+
+export type LoopbackServer = {
+  origin: string;
+  launchUrl: string;
+  issueLaunchUrl(): string;
+  close(): Promise<void>;
+};
+
+function requestBody(request: IncomingMessage, maximumBytes: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []; let bytes = 0, failed = false;
+    request.on("data", (chunk: Buffer) => {
+      if (failed) return;
+      bytes += chunk.length;
+      if (bytes > maximumBytes) { failed = true; reject(new Error("body-limit")); }
+      else chunks.push(chunk);
+    });
+    request.on("end", () => { if (!failed) resolve(Buffer.concat(chunks)); });
+    request.on("error", (error) => { if (!failed) reject(error); });
+  });
+}
+
+function serveAsset(response: ServerResponse, asset: StaticAsset): void {
+  response.statusCode = 200;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Content-Type", asset.contentType);
+  response.setHeader("Content-Length", asset.body.length);
+  response.end(asset.body);
+}
+
+export async function startLoopbackServer(options: {
+  staticRoot: string;
+  mode?: "session" | "gateway";
+  readCapabilities: ReadCapabilities;
+  readSessionCatalog?: () => unknown | Promise<unknown>;
+  readSessionCreationOptions?: () => unknown | Promise<unknown>;
+  readSessionModel?: (sessionRef: string) => WebUiReadModelProvider | Promise<WebUiReadModelProvider>;
+  readSessionConnections?: (sessionRef: string) => unknown | Promise<unknown>;
+  executeSessionConnection?: (command: unknown) => unknown | Promise<unknown>;
+  readMcpAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
+  cancelMcpAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
+  readProviderAuthCatalog?: () => unknown | Promise<unknown>;
+  readProviderAuthJob?: (jobRef: string) => unknown | Promise<unknown>;
+  executeProviderAuth?: (command: unknown) => unknown | Promise<unknown>;
+  executeProjectImport?: () => unknown | Promise<unknown>;
+  gatewayProtocol?: GatewayProtocolHandler;
+  readModel?: WebUiReadModelProvider;
+  executeControl?: (command: unknown) => unknown | Promise<unknown>;
+  executeAttachment?: (command: unknown) => unknown | Promise<unknown>;
+  executeApproval?: (approvalRef: string, decision: unknown) => unknown | Promise<unknown>;
+  bootstrapTtlMs?: number;
+  sessionTtlMs?: number;
+}): Promise<LoopbackServer> {
+  const assets = new Map(loadStaticBundle(options.staticRoot));
+  const styleNonce = randomBytes(16).toString("base64");
+  const indexAsset = assets.get("/");
+  if (indexAsset) assets.set("/", { ...indexAsset, body: Buffer.from(indexAsset.body.toString("utf8")
+    .replace("__PIAGENT_CSP_NONCE__", styleNonce)
+    .replace("__PIAGENT_WEBUI_MODE__", options.mode ?? "session")) });
+  const auth = new SessionAuthority({ bootstrapTtlMs: options.bootstrapTtlMs, sessionTtlMs: options.sessionTtlMs });
+  const sse = options.readModel ? new SseHub(options.readModel) : null;
+  const rates = new Map<string, RateState>();
+  let origin = "";
+  const server = http.createServer(async (request, response) => {
+    applySecurityHeaders(response, styleNonce);
+    const host = String(request.headers.host ?? "");
+    if (!origin || host !== origin.slice("http://".length)) return errorResponse(response, 421, "host-mismatch");
+    const requestOrigin = request.headers.origin;
+    if (requestOrigin && requestOrigin !== origin) return errorResponse(response, 403, "origin-mismatch");
+    const remote = request.socket.remoteAddress ?? "unknown", now = Date.now();
+    const rate = rates.get(remote) ?? { windowStart: now, requests: 0, bootstraps: 0, controls: 0 };
+    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstraps: 0, controls: 0 });
+    rate.requests += 1; rates.set(remote, rate);
+    if (rate.requests > REQUESTS_PER_MINUTE) return errorResponse(response, 429, "rate-limit");
+    let url: URL;
+    try { url = new URL(request.url ?? "/", origin); }
+    catch { return errorResponse(response, 400, "invalid-url"); }
+    if (url.hash || url.username || url.password || url.origin !== origin) return errorResponse(response, 400, "invalid-url");
+
+    if (request.method === "POST" && url.pathname === "/api/v1/bootstrap") {
+      rate.bootstraps += 1;
+      if (rate.bootstraps > BOOTSTRAPS_PER_MINUTE) return errorResponse(response, 429, "bootstrap-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let value: unknown;
+      try { value = JSON.parse((await requestBody(request, MAX_BOOTSTRAP_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-bootstrap"); }
+      const capability = value && typeof value === "object" ? (value as Record<string, unknown>).capability : null;
+      const session = typeof capability === "string" ? auth.exchange(capability) : null;
+      if (!session) return errorResponse(response, 403, "bootstrap-rejected");
+      response.setHeader("Set-Cookie", auth.cookieHeader(session));
+      return jsonResponse(response, 200, { authenticated: true, csrfToken: session.csrf, expiresAt: new Date(session.expiresAt).toISOString() });
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/v1/browser-session") {
+      const session = auth.authenticate(request);
+      if (!session) return errorResponse(response, 401, "authentication-required");
+      return jsonResponse(response, 200, { authenticated: true, csrfToken: session.csrf, expiresAt: new Date(session.expiresAt).toISOString() });
+    }
+
+    if (request.method === "POST" && ["/api/v1/chat/messages", "/api/v1/session-options", "/api/v1/lifecycle",
+      "/api/v1/control/resume-and-continue", "/api/v1/reviews", "/api/v1/source-mutations", "/api/v1/source-handoffs"].includes(url.pathname) && options.executeControl) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-control-command"); }
+      try { return jsonResponse(response, 200, await options.executeControl(command)); }
+      catch { return errorResponse(response, 503, "control-runtime-unavailable"); }
+    }
+
+    if (request.method === "POST" && url.pathname === "/api/v1/projects/import" && options.executeProjectImport) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_BOOTSTRAP_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-project-import"); }
+      if (!command || typeof command !== "object" || Array.isArray(command)
+        || Object.keys(command).length !== 1 || (command as Record<string, unknown>).action !== "project.import") {
+        return errorResponse(response, 400, "invalid-project-import");
+      }
+      try { return jsonResponse(response, 200, await options.executeProjectImport()); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "project-import-unavailable";
+        return errorResponse(response, code === "project-import-cancelled" ? 409 : code.includes("invalid") ? 400 : 503, code);
+      }
+    }
+
+    if (request.method === "POST" && url.pathname === "/api/v1/provider-auth" && options.executeProviderAuth) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-provider-auth-command"); }
+      try { return jsonResponse(response, 200, await options.executeProviderAuth(command)); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "provider-auth-unavailable";
+        return errorResponse(response, code.includes("not-found") ? 404 : code.includes("stale") || code.includes("conflict") ? 409
+          : code.includes("invalid") ? 400 : 503, code);
+      }
+    }
+
+    if (request.method === "POST" && url.pathname === "/api/v1/session-connections" && options.executeSessionConnection) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-session-connection-command"); }
+      try { return jsonResponse(response, 200, await options.executeSessionConnection(command)); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "session-connection-unavailable";
+        return errorResponse(response, code.includes("not-found") ? 404 : code.includes("invalid") ? 400 : code.includes("supported") ? 409 : 503, code);
+      }
+    }
+
+    if (request.method === "POST" && url.pathname.startsWith("/api/v1/mcp-auth/jobs/") && url.pathname.endsWith("/cancel") && options.cancelMcpAuthJob) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin || !auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      const jobRef = url.pathname.slice("/api/v1/mcp-auth/jobs/".length, -"/cancel".length);
+      if (!CURSOR.test(jobRef) || jobRef.includes("/") || url.search) return errorResponse(response, 400, "invalid-mcp-auth-job-ref");
+      try { return jsonResponse(response, 200, await options.cancelMcpAuthJob(jobRef)); }
+      catch (error) { return errorResponse(response, error instanceof Error && error.message.includes("not-found") ? 404 : 503, "mcp-auth-job-unavailable"); }
+    }
+
+    if (request.method === "POST" && url.pathname === "/api/v1/attachments" && options.executeAttachment) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      let command: unknown;
+      try { command = JSON.parse((await requestBody(request, MAX_ATTACHMENT_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-attachment-command"); }
+      try { return jsonResponse(response, 200, await options.executeAttachment(command)); }
+      catch { return errorResponse(response, 503, "attachment-runtime-unavailable"); }
+    }
+
+    if (request.method === "POST" && url.pathname.startsWith("/api/v1/approvals/") && url.pathname.endsWith("/decision") && options.executeApproval) {
+      rate.controls += 1;
+      if (rate.controls > CONTROLS_PER_MINUTE) return errorResponse(response, 429, "control-rate-limit");
+      if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
+      if (!auth.authorizeMutation(request)) return errorResponse(response, 403, "mutation-authority-rejected");
+      if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
+      const approvalRef = url.pathname.slice("/api/v1/approvals/".length, -"/decision".length);
+      if (!CURSOR.test(approvalRef) || approvalRef.includes("/")) return errorResponse(response, 400, "invalid-approval-ref");
+      let decision: unknown;
+      try { decision = JSON.parse((await requestBody(request, MAX_CONTROL_BODY_BYTES)).toString("utf8")); }
+      catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-approval-decision"); }
+      try { return jsonResponse(response, 200, await options.executeApproval(approvalRef, decision)); }
+      catch (error) {
+        const code = error instanceof Error ? error.message : "approval-runtime-unavailable";
+        return errorResponse(response, code.includes("not-pending") || code.includes("resolved") || code.includes("expired") ? 409 : code.includes("invalid") ? 400 : 503, code);
+      }
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/v1/capabilities") {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      try { return jsonResponse(response, 200, await options.readCapabilities()); }
+      catch { return errorResponse(response, 503, "capabilities-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/v1/session-catalog" && options.readSessionCatalog) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-catalog-query");
+      try { return jsonResponse(response, 200, await options.readSessionCatalog()); }
+      catch { return errorResponse(response, 503, "session-catalog-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/v1/session-creation-options" && options.readSessionCreationOptions) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-session-creation-query");
+      try {
+        const value = await options.readSessionCreationOptions();
+        if (Buffer.byteLength(JSON.stringify(value)) > MAX_JSON_RESPONSE_BYTES) return errorResponse(response, 503, "projection-response-limit");
+        return jsonResponse(response, 200, value);
+      }
+      catch { return errorResponse(response, 503, "session-creation-options-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname === "/api/v1/provider-auth" && options.readProviderAuthCatalog) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-provider-auth-query");
+      try { return jsonResponse(response, 200, await options.readProviderAuthCatalog()); }
+      catch { return errorResponse(response, 503, "provider-auth-catalog-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname.startsWith("/api/v1/provider-auth/jobs/") && options.readProviderAuthJob) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-provider-auth-job-query");
+      const jobRef = url.pathname.slice("/api/v1/provider-auth/jobs/".length);
+      if (!CURSOR.test(jobRef) || jobRef.includes("/")) return errorResponse(response, 400, "invalid-provider-auth-job-ref");
+      try { return jsonResponse(response, 200, await options.readProviderAuthJob(jobRef)); }
+      catch (error) { return errorResponse(response, error instanceof Error && error.message.includes("not-found") ? 404 : 503, "provider-auth-job-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname.startsWith("/api/v1/mcp-auth/jobs/") && options.readMcpAuthJob) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.search) return errorResponse(response, 400, "invalid-mcp-auth-job-query");
+      const jobRef = url.pathname.slice("/api/v1/mcp-auth/jobs/".length);
+      if (!CURSOR.test(jobRef) || jobRef.includes("/")) return errorResponse(response, 400, "invalid-mcp-auth-job-ref");
+      try { return jsonResponse(response, 200, await options.readMcpAuthJob(jobRef)); }
+      catch (error) { return errorResponse(response, error instanceof Error && error.message.includes("not-found") ? 404 : 503, "mcp-auth-job-unavailable"); }
+    }
+
+    if (request.method === "GET" && url.pathname.startsWith("/api/v1/sessions/")
+      && (options.readSessionModel || options.readSessionConnections)) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      const rest = url.pathname.slice("/api/v1/sessions/".length);
+      const separator = rest.indexOf("/inspection/");
+      const sessionRef = separator >= 0 ? rest.slice(0, separator) : "";
+      const inspectionPath = separator >= 0 ? rest.slice(separator + "/inspection".length) : "";
+      if (!CURSOR.test(sessionRef) || sessionRef.includes("/") || !inspectionPath.startsWith("/")) {
+        return errorResponse(response, 400, "invalid-session-inspection-ref");
+      }
+      try {
+        if (inspectionPath === "/connections") {
+          if (url.search || !options.readSessionConnections) return errorResponse(response, 404, "inspection-route-not-found");
+          const value = await options.readSessionConnections(sessionRef);
+          const bytes = Buffer.byteLength(JSON.stringify(value));
+          if (bytes > MAX_JSON_RESPONSE_BYTES) return errorResponse(response, 503, "projection-response-limit");
+          return jsonResponse(response, 200, value);
+        }
+        if (!options.readSessionModel) return errorResponse(response, 404, "inspection-route-not-found");
+        const provider = await options.readSessionModel(sessionRef);
+        const scoped = new URL(url.href);
+        scoped.pathname = `/api/v1${inspectionPath}`;
+        const result = await routeReadOnlyRequest(scoped, provider);
+        if (!result.handled) return errorResponse(response, 404, "inspection-route-not-found");
+        let bytes: number;
+        try { bytes = Buffer.byteLength(JSON.stringify(result.value)); }
+        catch { return errorResponse(response, 503, "projection-unavailable"); }
+        if (bytes > MAX_JSON_RESPONSE_BYTES) return errorResponse(response, 503, "projection-response-limit");
+        return jsonResponse(response, result.status, result.value);
+      } catch (error) {
+        return errorResponse(response, error instanceof ReadModelNotFound ? 404 : 503,
+          error instanceof ReadModelNotFound ? "opaque-ref-not-found" : "projection-unavailable");
+      }
+    }
+
+    if (request.method === "GET" && url.pathname.startsWith("/api/v1/") && options.readModel) {
+      if (!auth.authenticate(request)) return errorResponse(response, 401, "authentication-required");
+      if (url.pathname === "/api/v1/events") {
+        if ([...url.searchParams.keys()].some((key) => key !== "after") || url.searchParams.getAll("after").length > 1) return errorResponse(response, 400, "invalid-event-cursor");
+        const hasQuery = url.searchParams.has("after"), query = url.searchParams.get("after"), header = String(request.headers["last-event-id"] ?? "") || null;
+        if ((hasQuery && (!query || !CURSOR.test(query))) || (header && !CURSOR.test(header)) || (query && header && query !== header)) return errorResponse(response, 400, "invalid-event-cursor");
+        try { await sse?.open(request, response, query ?? header); }
+        catch { if (!response.headersSent) errorResponse(response, 503, "event-replay-unavailable"); else response.destroy(); }
+        return;
+      }
+      try {
+        const result = await routeReadOnlyRequest(url, options.readModel);
+        if (result.handled) {
+          let bytes: number;
+          try { bytes = Buffer.byteLength(JSON.stringify(result.value)); } catch { return errorResponse(response, 503, "projection-unavailable"); }
+          if (bytes > MAX_JSON_RESPONSE_BYTES) return errorResponse(response, 503, "projection-response-limit");
+          return jsonResponse(response, result.status, result.value);
+        }
+      } catch (error) {
+        return errorResponse(response, error instanceof ReadModelNotFound ? 404 : 503,
+          error instanceof ReadModelNotFound ? "opaque-ref-not-found" : "projection-unavailable");
+      }
+    }
+
+    if (request.method !== "GET" && request.method !== "HEAD") return errorResponse(response, 405, "method-not-allowed");
+    const asset = assets.get(url.pathname);
+    if (!asset || url.search) return errorResponse(response, 404, "not-found");
+    if (request.method === "HEAD") { response.statusCode = 200; response.setHeader("Content-Type", asset.contentType); return response.end(); }
+    serveAsset(response, asset);
+  });
+  const gatewaySocket = options.gatewayProtocol ? attachGatewayWebSocket({
+    server, origin: () => origin, authority: auth, protocol: options.gatewayProtocol
+  }) : null;
+  server.requestTimeout = 5_000; server.headersTimeout = 5_000; server.keepAliveTimeout = 5_000; server.maxHeadersCount = 64;
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen({ host: "127.0.0.1", port: 0, exclusive: true }, resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string" || address.address !== "127.0.0.1") { server.close(); throw new Error("loopback-bind-failed"); }
+  origin = `http://127.0.0.1:${address.port}`;
+  return {
+    origin,
+    launchUrl: `${origin}/#bootstrap=${auth.bootstrapCapability}`,
+    issueLaunchUrl: () => `${origin}/#bootstrap=${auth.issueBootstrapCapability()}`,
+    close: async () => {
+      auth.invalidate();
+      sse?.close();
+      await gatewaySocket?.close();
+      server.closeAllConnections();
+      await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+    }
+  };
+}

package/packages/piagent-webui/server/read-model-provider.ts

@@ -0,0 +1,37 @@
+export type SourceView = "task" | "working-tree" | "staged";
+export type StreamEvent = { cursor: string; value: unknown };
+export type StreamReplay = {
+  state: "current" | "truncated" | "resync-required";
+  events: StreamEvent[];
+  nextCursor: string;
+  latestCursor: string;
+  reasonCode: string | null;
+};
+
+export type WebUiReadModelProvider = {
+  snapshot(): unknown | Promise<unknown>;
+  sourceChanges(view: SourceView): unknown | Promise<unknown>;
+  diff(view: SourceView, fileRef: string): unknown | Promise<unknown>;
+  review(view: SourceView, fileRef: string): unknown | Promise<unknown>;
+  sourceMutation(action: "source.stage" | "source.unstage", fileRef: string): unknown | Promise<unknown>;
+  sourceRevert(fileRef: string, hunkRef: string | null): unknown | Promise<unknown>;
+  commitSummary(): unknown | Promise<unknown>;
+  taskIndex(): unknown | Promise<unknown>;
+  taskTimeline(runRef: string): unknown | Promise<unknown>;
+  recoveryHistory(runRef: string): unknown | Promise<unknown>;
+  handoffHistory(runRef: string): unknown | Promise<unknown>;
+  subagentTree(runRef: string): unknown | Promise<unknown>;
+  releaseMonitor(): unknown | Promise<unknown>;
+  activity(): unknown | Promise<unknown>;
+  logPreview(activityRef: string): unknown | Promise<unknown>;
+  transcript(beforeCursor: string | null, limit: number): unknown | Promise<unknown>;
+  queue(): unknown | Promise<unknown>;
+  modelCatalog(): unknown | Promise<unknown>;
+  approval(approvalRef: string): unknown | Promise<unknown>;
+  replay(after: string | null, limit: number): StreamReplay | Promise<StreamReplay>;
+  subscribe(listener: (event: StreamEvent) => void): () => void;
+};
+
+export class ReadModelNotFound extends Error {
+  constructor() { super("read-model-ref-not-found"); }
+}

package/packages/piagent-webui/server/read-only-router.ts

@@ -0,0 +1,105 @@
+import type { WebUiReadModelProvider, SourceView } from "./read-model-provider.ts";
+
+const OPAQUE_REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+export type ReadRouteResult = { handled: false } | { handled: true; status: number; value: unknown };
+
+export async function routeReadOnlyRequest(url: URL, provider: WebUiReadModelProvider): Promise<ReadRouteResult> {
+  if (url.pathname === "/api/v1/snapshot" && !url.search) return { handled: true, status: 200, value: await provider.snapshot() };
+  if (url.pathname === "/api/v1/activity" && !url.search) return { handled: true, status: 200, value: await provider.activity() };
+  if (url.pathname === "/api/v1/tasks" && !url.search) return { handled: true, status: 200, value: await provider.taskIndex() };
+  if (url.pathname === "/api/v1/monitoring/release" && !url.search) return { handled: true, status: 200, value: await provider.releaseMonitor() };
+  if (url.pathname.startsWith("/api/v1/tasks/") && url.pathname.endsWith("/timeline")) {
+    const ref = url.pathname.slice("/api/v1/tasks/".length, -"/timeline".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-task-run-ref" } } };
+    return { handled: true, status: 200, value: await provider.taskTimeline(ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/tasks/") && url.pathname.endsWith("/recovery-history")) {
+    const ref = url.pathname.slice("/api/v1/tasks/".length, -"/recovery-history".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-task-run-ref" } } };
+    return { handled: true, status: 200, value: await provider.recoveryHistory(ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/tasks/") && url.pathname.endsWith("/handoff-history")) {
+    const ref = url.pathname.slice("/api/v1/tasks/".length, -"/handoff-history".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-task-run-ref" } } };
+    return { handled: true, status: 200, value: await provider.handoffHistory(ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/tasks/") && url.pathname.endsWith("/subagent-tree")) {
+    const ref = url.pathname.slice("/api/v1/tasks/".length, -"/subagent-tree".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-task-run-ref" } } };
+    return { handled: true, status: 200, value: await provider.subagentTree(ref) };
+  }
+  if (url.pathname === "/api/v1/chat/queue" && !url.search) return { handled: true, status: 200, value: await provider.queue() };
+  if (url.pathname === "/api/v1/session-options/models" && !url.search) return { handled: true, status: 200, value: await provider.modelCatalog() };
+  if (url.pathname.startsWith("/api/v1/approvals/")) {
+    const ref = url.pathname.slice("/api/v1/approvals/".length);
+    if (url.search || !OPAQUE_REF.test(ref) || ref.includes("/")) return { handled: true, status: 400, value: { error: { code: "invalid-approval-ref" } } };
+    return { handled: true, status: 200, value: await provider.approval(ref) };
+  }
+  if (url.pathname === "/api/v1/transcript") {
+    if ([...url.searchParams.keys()].some((key) => key !== "before" && key !== "limit")
+      || url.searchParams.getAll("before").length > 1 || url.searchParams.getAll("limit").length > 1) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-transcript-page" } } };
+    }
+    const before = url.searchParams.get("before"), rawLimit = url.searchParams.get("limit"), limit = rawLimit === null ? 50 : Number(rawLimit);
+    if ((before !== null && !OPAQUE_REF.test(before)) || !Number.isInteger(limit) || limit < 1 || limit > 200) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-transcript-page" } } };
+    }
+    return { handled: true, status: 200, value: await provider.transcript(before, limit) };
+  }
+  if (url.pathname === "/api/v1/source-changes") {
+    if ([...url.searchParams.keys()].some((key) => key !== "view") || url.searchParams.getAll("view").length !== 1) return { handled: true, status: 400, value: { error: { code: "invalid-source-view" } } };
+    const view = url.searchParams.get("view");
+    if (!(["task", "working-tree", "staged"] as Array<string | null>).includes(view)) return { handled: true, status: 400, value: { error: { code: "invalid-source-view" } } };
+    return { handled: true, status: 200, value: await provider.sourceChanges(view as SourceView) };
+  }
+  if (url.pathname.startsWith("/api/v1/diffs/")) {
+    const ref = url.pathname.slice("/api/v1/diffs/".length);
+    const view = url.searchParams.get("view");
+    if (!OPAQUE_REF.test(ref) || url.searchParams.getAll("view").length !== 1
+      || [...url.searchParams.keys()].some((key) => key !== "view")
+      || !(view && (["task", "working-tree", "staged"] as string[]).includes(view))) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-diff-authority" } } };
+    }
+    return { handled: true, status: 200, value: await provider.diff(view as SourceView, ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/reviews/")) {
+    const ref = url.pathname.slice("/api/v1/reviews/".length);
+    const view = url.searchParams.get("view");
+    if (!OPAQUE_REF.test(ref) || url.searchParams.getAll("view").length !== 1
+      || [...url.searchParams.keys()].some((key) => key !== "view")
+      || !(view && (["task", "working-tree", "staged"] as string[]).includes(view))) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-review-authority" } } };
+    }
+    return { handled: true, status: 200, value: await provider.review(view as SourceView, ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/source-mutations/")) {
+    const ref = url.pathname.slice("/api/v1/source-mutations/".length), action = url.searchParams.get("action");
+    if (!OPAQUE_REF.test(ref) || url.searchParams.getAll("action").length !== 1
+      || [...url.searchParams.keys()].some((key) => key !== "action") || !["source.stage", "source.unstage"].includes(String(action))) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-source-mutation-authority" } } };
+    }
+    return { handled: true, status: 200, value: await provider.sourceMutation(action as "source.stage" | "source.unstage", ref) };
+  }
+  if (url.pathname.startsWith("/api/v1/source-reverts/")) {
+    const ref = url.pathname.slice("/api/v1/source-reverts/".length), hunkRef = url.searchParams.get("hunkRef");
+    if (!OPAQUE_REF.test(ref) || url.searchParams.getAll("hunkRef").length > 1
+      || [...url.searchParams.keys()].some((key) => key !== "hunkRef") || hunkRef !== null && !OPAQUE_REF.test(hunkRef)) {
+      return { handled: true, status: 400, value: { error: { code: "invalid-source-revert-authority" } } };
+    }
+    return { handled: true, status: 200, value: await provider.sourceRevert(ref, hunkRef) };
+  }
+  if (url.pathname === "/api/v1/commit-summary") {
+    if (url.search) return { handled: true, status: 400, value: { error: { code: "invalid-commit-summary-request" } } };
+    return { handled: true, status: 200, value: await provider.commitSummary() };
+  }
+  for (const [prefix, read] of [
+    ["/api/v1/log-previews/", (ref: string) => provider.logPreview(ref)]
+  ] as const) {
+    if (!url.pathname.startsWith(prefix)) continue;
+    const ref = url.pathname.slice(prefix.length);
+    if (url.search || !OPAQUE_REF.test(ref)) return { handled: true, status: 400, value: { error: { code: "invalid-opaque-ref" } } };
+    return { handled: true, status: 200, value: await read(ref) };
+  }
+  return { handled: false };
+}