@piagent/platform 1.3.1 → 1.4.1

package/packages/piagent-webui/gateway/gateway-session-stream.ts

@@ -0,0 +1,110 @@
+import { randomBytes } from "node:crypto";
+
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import { GatewayEventStore } from "./gateway-events.ts";
+
+const MAX_BUFFER = 65_536;
+const MAX_EVENTS = 128;
+const MAX_DELTA = 16_384;
+const PRIVATE_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PRIVATE_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+
+function clean(value: unknown): string {
+  return String(value ?? "").replace(/\u001b(?:[@-_]|\[[0-?]*[ -/]*[@-~])/g, "")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ");
+}
+function safeTool(value: unknown): string {
+  const safe = redactSensitiveText(clean(value));
+  if (safe.redacted) return "redacted-tool";
+  return safe.text.replace(/[^A-Za-z0-9._:-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 160) || "tool";
+}
+function ref(prefix: string): string { return `${prefix}_${randomBytes(18).toString("base64url")}`; }
+
+export class GatewaySessionStream {
+  readonly sessionRef: string;
+  readonly operationRef: string;
+  readonly #events: GatewayEventStore;
+  #messageRef: string | null = null;
+  #messageSequence = 0;
+  #eventCount = 0;
+  #buffer = "";
+  #truncated = false;
+  #started = false;
+  #startListeners: Array<() => void> = [];
+  readonly #toolRefs = new Map<string, string>();
+
+  constructor(options: { sessionRef: string; operationRef: string; events: GatewayEventStore }) {
+    this.sessionRef = options.sessionRef; this.operationRef = options.operationRef; this.#events = options.events;
+  }
+
+  started(): Promise<void> {
+    if (this.#started) return Promise.resolve();
+    return new Promise((resolve) => this.#startListeners.push(resolve));
+  }
+
+  observe(event: any): void {
+    if (event?.type === "agent_start") {
+      this.#started = true; for (const resolve of this.#startListeners.splice(0)) resolve(); return;
+    }
+    if (event?.type === "message_start" && event.message?.role === "assistant") {
+      this.#messageRef = ref("message"); this.#buffer = ""; return;
+    }
+    if (event?.type === "message_update" && event.assistantMessageEvent?.type === "text_delta"
+      && typeof event.assistantMessageEvent.delta === "string") {
+      const remaining = MAX_BUFFER - this.#buffer.length;
+      if (remaining <= 0) { this.#truncated = true; return; }
+      this.#buffer += event.assistantMessageEvent.delta.slice(0, remaining);
+      if (event.assistantMessageEvent.delta.length > remaining) this.#truncated = true;
+      this.#flush(false); return;
+    }
+    if (event?.type === "message_end" && event.message?.role === "assistant") { this.#flush(true); return; }
+    if (event?.type === "tool_execution_start" && typeof event.toolCallId === "string") {
+      const toolCallRef = ref("tool"); this.#toolRefs.set(event.toolCallId, toolCallRef);
+      this.#events.publish("tool.started", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
+        toolLabel: safeTool(event.toolName), isError: null });
+      return;
+    }
+    if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") {
+      const toolCallRef = this.#toolRefs.get(event.toolCallId); if (!toolCallRef) return;
+      this.#events.publish("tool.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef, toolCallRef,
+        toolLabel: safeTool(event.toolName), isError: event.isError === true });
+      this.#toolRefs.delete(event.toolCallId);
+    }
+  }
+
+  #flush(final: boolean): void {
+    if (!this.#messageRef || !this.#buffer || this.#eventCount >= MAX_EVENTS) {
+      if (this.#eventCount >= MAX_EVENTS) this.#truncated = true;
+      return;
+    }
+    let take = final ? this.#buffer.length : this.#buffer.lastIndexOf("\n") + 1;
+    if (take <= 0 && this.#buffer.length >= 1_024) take = this.#buffer.length;
+    if (take <= 0) return;
+    const candidate = this.#buffer.slice(0, take), privateStart = candidate.search(PRIVATE_BEGIN);
+    if (privateStart >= 0 && !PRIVATE_END.test(candidate.slice(privateStart))) {
+      if (!final) take = privateStart;
+      else {
+        const before = redactSensitiveText(clean(candidate.slice(0, privateStart))).text;
+        this.#buffer = ""; this.#emit(`${before}[REDACTED_SECRET]`); return;
+      }
+    }
+    if (take <= 0) return;
+    const source = this.#buffer.slice(0, take); this.#buffer = this.#buffer.slice(take);
+    this.#emit(redactSensitiveText(clean(source)).text);
+  }
+
+  #emit(value: string): void {
+    for (let offset = 0; offset < value.length; offset += MAX_DELTA) {
+      if (this.#eventCount >= MAX_EVENTS) { this.#truncated = true; break; }
+      this.#events.publish("message.delta", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+        messageRef: this.#messageRef!, messageSequence: this.#messageSequence++, delta: value.slice(offset, offset + MAX_DELTA) });
+      this.#eventCount += 1;
+    }
+  }
+
+  complete(sessionRevision: string): void {
+    this.#flush(true);
+    if (this.#messageRef) this.#events.publish("message.completed", { sessionRef: this.sessionRef, operationRef: this.operationRef,
+      messageRef: this.#messageRef, sessionRevision, truncated: this.#truncated });
+  }
+}

package/packages/piagent-webui/gateway/mcp-auth-broker.ts

@@ -0,0 +1,158 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+
+export type McpAdapterModules = {
+  loadMcpConfig(overridePath?: string, cwd?: string): any;
+  resolveServerUrl(definition: any): string | undefined;
+  supportsOAuth(definition: any): boolean;
+  createOAuthRuntime(signal?: AbortSignal): any;
+  shutdownOAuth(runtime: any): Promise<void>;
+  authenticate(name: string, url: string, definition: any, options: any): Promise<string>;
+  getAuthStatus(name: string, options: any): Promise<"authenticated" | "expired" | "not_authenticated">;
+  getAuthStorageOptions(oauthDir: unknown, cwd?: string): any;
+};
+
+type Job = {
+  jobRef: string;
+  sessionRef: string;
+  connectionRef: string;
+  name: string;
+  createdAt: string;
+  expiresAt: string;
+  state: "running" | "completed" | "failed" | "cancelled";
+  authorizationUrl: string | null;
+  reasonCode: string | null;
+  controller: AbortController;
+  runtime: any;
+};
+
+const MAX_JOBS = 16;
+const JOB_TTL_MS = 10 * 60_000;
+
+function safeReason(error: unknown): string {
+  if (error instanceof Error && /abort|cancel/i.test(error.message)) return "mcp-oauth-cancelled";
+  const detail = error && typeof error === "object" ? error as { name?: unknown; status?: unknown; message?: unknown } : {};
+  const registrationRejected = detail.name === "RegistrationRejectedError"
+    || (typeof detail.message === "string" && /Dynamic Client Registration rejected/i.test(detail.message));
+  if (registrationRejected && (detail.status === 403
+    || (typeof detail.message === "string" && /HTTP 403/i.test(detail.message)))) return "mcp-oauth-client-not-approved";
+  if (registrationRejected) return "mcp-oauth-registration-rejected";
+  return "mcp-oauth-failed";
+}
+
+function safeName(value: string): string {
+  return redactSensitiveText(value).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 120) || "MCP";
+}
+
+function safeAuthorizationUrl(value: string): string {
+  const parsed = new URL(value);
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname))) {
+    throw new Error("mcp-oauth-url-invalid");
+  }
+  if (parsed.username || parsed.password) throw new Error("mcp-oauth-url-invalid");
+  return parsed.toString();
+}
+
+function isLoopbackHttpUrl(value: string | undefined): boolean {
+  if (!value) return false;
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]", "::1"].includes(parsed.hostname);
+  } catch { return false; }
+}
+
+export class McpAuthBroker {
+  readonly #adapterRoot: string;
+  readonly #moduleLoader: (() => Promise<McpAdapterModules>) | null;
+  readonly #jobs = new Map<string, Job>();
+  #modules: Promise<McpAdapterModules> | null = null;
+
+  constructor(agentDir: string, moduleLoader?: () => Promise<McpAdapterModules>) {
+    this.#adapterRoot = path.join(agentDir, "npm", "node_modules", "pi-mcp-adapter");
+    this.#moduleLoader = moduleLoader ?? null;
+  }
+
+  async #load(): Promise<McpAdapterModules> {
+    if (this.#modules) return await this.#modules;
+    if (this.#moduleLoader) {
+      this.#modules = this.#moduleLoader();
+      return await this.#modules;
+    }
+    this.#modules = (async () => {
+      const files = ["config.ts", "utils.ts", "mcp-auth-flow.ts", "mcp-auth.ts"];
+      for (const file of files) {
+        const stat = fs.lstatSync(path.join(this.#adapterRoot, file));
+        if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("mcp-adapter-auth-unavailable");
+      }
+      const [config, utils, flow, storage] = await Promise.all(files.map((file) => import(pathToFileURL(path.join(this.#adapterRoot, file)).href)));
+      return { loadMcpConfig: config.loadMcpConfig, resolveServerUrl: utils.resolveServerUrl, supportsOAuth: flow.supportsOAuth,
+        createOAuthRuntime: flow.createOAuthRuntime, shutdownOAuth: flow.shutdownOAuth, authenticate: flow.authenticate,
+        getAuthStatus: flow.getAuthStatus, getAuthStorageOptions: storage.getAuthStorageOptions } as McpAdapterModules;
+    })();
+    return await this.#modules;
+  }
+
+  async describe(cwd: string, name: string): Promise<{ oauthSupported: boolean; authState: "connected" | "expired" | "not-connected" | "unavailable" }> {
+    try {
+      const adapter = await this.#load(), config = adapter.loadMcpConfig(undefined, cwd), definition = config.mcpServers?.[name];
+      const url = definition ? adapter.resolveServerUrl(definition) : undefined;
+      if (!definition || isLoopbackHttpUrl(url) || !adapter.supportsOAuth(definition)) return { oauthSupported: false, authState: "unavailable" };
+      const authStorageOptions = adapter.getAuthStorageOptions(config.settings?.oauthDir, cwd);
+      const state = await adapter.getAuthStatus(name, { authStorageOptions });
+      return { oauthSupported: true, authState: state === "authenticated" ? "connected" : state === "expired" ? "expired" : "not-connected" };
+    } catch { return { oauthSupported: false, authState: "unavailable" }; }
+  }
+
+  async start(input: { sessionRef: string; connectionRef: string; cwd: string; name: string }): Promise<ReturnType<McpAuthBroker["read"]>> {
+    this.#prune();
+    const adapter = await this.#load(), config = adapter.loadMcpConfig(undefined, input.cwd), definition = config.mcpServers?.[input.name];
+    const url = definition ? adapter.resolveServerUrl(definition) : undefined;
+    if (!definition || isLoopbackHttpUrl(url) || !adapter.supportsOAuth(definition)) throw new Error("mcp-oauth-not-supported");
+    if (!url) throw new Error("mcp-oauth-url-unavailable");
+    const duplicate = [...this.#jobs.values()].find((job) => job.sessionRef === input.sessionRef && job.connectionRef === input.connectionRef && job.state === "running");
+    if (duplicate) return this.read(duplicate.jobRef);
+    const controller = new AbortController(), runtime = adapter.createOAuthRuntime(controller.signal), now = new Date();
+    const job: Job = { jobRef: `mcp_auth_${randomBytes(24).toString("base64url")}`, sessionRef: input.sessionRef,
+      connectionRef: input.connectionRef, name: safeName(input.name), createdAt: now.toISOString(), expiresAt: new Date(now.getTime() + JOB_TTL_MS).toISOString(),
+      state: "running", authorizationUrl: null, reasonCode: null, controller, runtime };
+    this.#jobs.set(job.jobRef, job);
+    const authStorageOptions = adapter.getAuthStorageOptions(config.settings?.oauthDir, input.cwd);
+    void adapter.authenticate(input.name, url, definition, { signal: controller.signal, runtime, authStorageOptions,
+      onAuthorizationUrl: (authorizationUrl: string) => { if (job.state === "running") job.authorizationUrl = safeAuthorizationUrl(authorizationUrl); }
+    }).then(() => { if (job.state === "running") job.state = "completed"; }, (error) => {
+      if (job.state !== "running") return; job.state = controller.signal.aborted ? "cancelled" : "failed"; job.reasonCode = safeReason(error);
+    }).finally(() => void adapter.shutdownOAuth(runtime).catch(() => undefined));
+    return this.read(job.jobRef);
+  }
+
+  read(jobRef: string) {
+    this.#prune();
+    const job = this.#jobs.get(jobRef); if (!job) throw new Error("mcp-oauth-job-not-found");
+    return { schemaVersion: 1 as const, version: "piagent-mcp-auth-job-v1" as const, generatedAt: new Date().toISOString(),
+      jobRef: job.jobRef, sessionRef: job.sessionRef, connectionRef: job.connectionRef, name: job.name, createdAt: job.createdAt,
+      expiresAt: job.expiresAt, state: job.state, authorizationUrl: job.authorizationUrl, reasonCode: job.reasonCode };
+  }
+
+  async cancel(jobRef: string): Promise<ReturnType<McpAuthBroker["read"]>> {
+    const job = this.#jobs.get(jobRef); if (!job) throw new Error("mcp-oauth-job-not-found");
+    if (job.state === "running") { job.state = "cancelled"; job.reasonCode = "cancelled-by-user"; job.controller.abort(); }
+    return this.read(jobRef);
+  }
+
+  async close(): Promise<void> {
+    for (const job of this.#jobs.values()) if (job.state === "running") { job.state = "cancelled"; job.controller.abort(); }
+    this.#jobs.clear();
+  }
+
+  #prune(): void {
+    const now = Date.now();
+    for (const [jobRef, job] of this.#jobs) if (Date.parse(job.expiresAt) <= now) {
+      if (job.state === "running") job.controller.abort(); this.#jobs.delete(jobRef);
+    }
+    while (this.#jobs.size > MAX_JOBS) this.#jobs.delete(this.#jobs.keys().next().value as string);
+  }
+}

package/packages/piagent-webui/gateway/native-project-picker.ts

@@ -0,0 +1,29 @@
+import { execFile } from "node:child_process";
+
+export function nativeProjectPickerAvailable(): boolean { return process.platform === "darwin"; }
+
+export function pickNativeProjectFolders(): Promise<string[]> {
+  if (!nativeProjectPickerAvailable()) return Promise.reject(new Error("native-project-picker-unavailable"));
+  return new Promise((resolve, reject) => {
+    const script = [
+      'set chosenFolders to choose folder with prompt "Choose project folders for Piagent" with multiple selections allowed',
+      'set output to ""',
+      'repeat with chosenFolder in chosenFolders',
+      'set output to output & POSIX path of chosenFolder & linefeed',
+      'end repeat',
+      'return output'
+    ].join("\n");
+    execFile("/usr/bin/osascript", ["-e", script], { timeout: 5 * 60_000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+      if (error) { reject(new Error("project-import-cancelled")); return; }
+      const selected = [...new Set(stdout.split("\n").map((value) => value.trim()).filter(Boolean))].slice(0, 32);
+      if (!selected.length) { reject(new Error("project-import-cancelled")); return; }
+      resolve(selected);
+    });
+  });
+}
+
+export async function pickNativeProjectFolder(): Promise<string> {
+  const [selected] = await pickNativeProjectFolders();
+  if (!selected) throw new Error("project-import-cancelled");
+  return selected;
+}

package/packages/piagent-webui/gateway/pi-host.ts

@@ -0,0 +1,41 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+function packageRootFrom(start: string): string | null {
+  let current = path.dirname(start);
+  while (current !== path.dirname(current)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(current, "package.json"), "utf8")) as { name?: string };
+      if (pkg.name === "@earendil-works/pi-coding-agent") return current;
+    } catch {
+      // Keep walking toward the package root.
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+export function installedPiHostRoot(): string {
+  try {
+    const local = packageRootFrom(require.resolve("@earendil-works/pi-coding-agent"));
+    if (local) return local;
+  } catch {
+    // The operator installation is normally global.
+  }
+  const executable = execFileSync("which", ["pi"], { encoding: "utf8", timeout: 2_000 }).trim();
+  const found = packageRootFrom(fs.realpathSync(executable));
+  if (!found) throw new Error("pi-host-unavailable");
+  return found;
+}
+
+export async function loadPinnedPiHost(expectedVersion: string): Promise<any> {
+  const root = installedPiHostRoot();
+  const actual = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as { version?: string };
+  if (actual.version !== expectedVersion) throw new Error("pi-host-version-mismatch");
+  return await import(pathToFileURL(path.join(root, "dist", "index.js")).href);
+}

package/packages/piagent-webui/gateway/profile-state.ts

@@ -0,0 +1 @@
+export * from "../ownership/profile-state.ts";

package/packages/piagent-webui/gateway/project-registry.ts

@@ -0,0 +1,108 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import { projectRefForCwd } from "./session-catalog.ts";
+
+const VERSION = "piagent-project-registry-v1";
+const MAX_PROJECTS = 200;
+const MAX_BYTES = 256 * 1024;
+
+type ProjectRecord = { projectRef: string; cwd: string; label: string; importedAt: string };
+type RegistryFile = { version: typeof VERSION; projects: ProjectRecord[] };
+export type ProjectProjection = { projectRef: string; placeRef: string; label: string };
+
+function cleanLabel(value: string): string {
+  return (redactSensitiveText(value).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim() || "Project").slice(0, 120);
+}
+
+function validRecord(value: unknown): value is ProjectRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const item = value as Partial<ProjectRecord>;
+  return Object.keys(item).every((key) => ["projectRef", "cwd", "label", "importedAt"].includes(key))
+    && typeof item.projectRef === "string" && /^project_[A-Za-z0-9_-]{40,80}$/.test(item.projectRef)
+    && typeof item.cwd === "string" && path.isAbsolute(item.cwd) && item.cwd.length <= 4_096
+    && typeof item.label === "string" && item.label.length > 0 && item.label.length <= 120 && !/[\u0000-\u001f\u007f]/.test(item.label)
+    && typeof item.importedAt === "string" && Number.isFinite(Date.parse(item.importedAt));
+}
+
+export class ProjectRegistry {
+  readonly file: string;
+  readonly #root: string;
+  readonly #key: Buffer;
+
+  constructor(root: string, key: Buffer) {
+    this.#root = root;
+    this.#key = key;
+    this.file = path.join(root, "projects.json");
+  }
+
+  #read(): RegistryFile {
+    let stat: fs.Stats;
+    try { stat = fs.lstatSync(this.file); }
+    catch { return { version: VERSION, projects: [] }; }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_BYTES) throw new Error("project-registry-file-invalid");
+    const descriptor = fs.openSync(this.file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const opened = fs.fstatSync(descriptor);
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) throw new Error("project-registry-file-race");
+      const value = JSON.parse(fs.readFileSync(descriptor, "utf8")) as Partial<RegistryFile>;
+      if (value.version !== VERSION || !Array.isArray(value.projects) || value.projects.length > MAX_PROJECTS
+        || !value.projects.every(validRecord)) throw new Error("project-registry-content-invalid");
+      const refs = new Set<string>(), paths = new Set<string>();
+      for (const item of value.projects) {
+        if (item.projectRef !== projectRefForCwd(this.#key, item.cwd) || refs.has(item.projectRef) || paths.has(item.cwd)) {
+          throw new Error("project-registry-content-invalid");
+        }
+        refs.add(item.projectRef); paths.add(item.cwd);
+      }
+      return value as RegistryFile;
+    } finally { fs.closeSync(descriptor); }
+  }
+
+  #write(value: RegistryFile): void {
+    const body = Buffer.from(`${JSON.stringify(value)}\n`);
+    if (body.length > MAX_BYTES) throw new Error("project-registry-limit");
+    const temporary = path.join(this.#root, `.projects-${process.pid}-${randomBytes(8).toString("hex")}.tmp`);
+    const descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try { fs.writeFileSync(descriptor, body); fs.fsyncSync(descriptor); }
+    finally { fs.closeSync(descriptor); }
+    fs.renameSync(temporary, this.file); fs.chmodSync(this.file, 0o600);
+  }
+
+  register(input: string, now = new Date()): ProjectProjection {
+    if (!Number.isFinite(now.getTime())) throw new Error("project-import-time-invalid");
+    const cwd = fs.realpathSync(path.resolve(input));
+    const stat = fs.lstatSync(cwd);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || cwd === path.parse(cwd).root) throw new Error("project-import-folder-invalid");
+    const current = this.#read(), projectRef = projectRefForCwd(this.#key, cwd);
+    const existing = current.projects.find((item) => item.projectRef === projectRef);
+    if (!existing) {
+      if (current.projects.length >= MAX_PROJECTS) throw new Error("project-registry-limit");
+      current.projects.push({ projectRef, cwd, label: cleanLabel(path.basename(cwd)), importedAt: now.toISOString() });
+      this.#write(current);
+    }
+    const item = existing ?? current.projects.at(-1)!;
+    return { projectRef: item.projectRef, placeRef: item.projectRef, label: item.label };
+  }
+
+  list(): ProjectProjection[] {
+    return this.#read().projects.flatMap((item) => {
+      try {
+        const canonical = fs.realpathSync(item.cwd), stat = fs.lstatSync(canonical);
+        return canonical === item.cwd && stat.isDirectory() && !stat.isSymbolicLink()
+          ? [{ projectRef: item.projectRef, placeRef: item.projectRef, label: item.label }] : [];
+      } catch { return []; }
+    });
+  }
+
+  resolve(projectRef: string): string | null {
+    const item = this.#read().projects.find((candidate) => candidate.projectRef === projectRef);
+    if (!item) return null;
+    try {
+      const canonical = fs.realpathSync(item.cwd), stat = fs.lstatSync(canonical);
+      return canonical === item.cwd && stat.isDirectory() && !stat.isSymbolicLink() ? canonical : null;
+    } catch { return null; }
+  }
+}

package/packages/piagent-webui/gateway/provider-auth-broker.ts

@@ -0,0 +1,172 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+
+const JOB_TTL_MS = 10 * 60_000;
+const MAX_EVENTS = 16;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+type AuthPrompt = { signal?: AbortSignal; type: "text" | "secret" | "select" | "manual_code"; message: string; placeholder?: string;
+  options?: readonly { id: string; label: string; description?: string }[] };
+type AuthEvent = { type: "info"; message: string; links?: readonly { url: string; label?: string }[] }
+  | { type: "auth_url"; url: string; instructions?: string } | { type: "device_code"; userCode: string; verificationUri: string;
+    intervalSeconds?: number; expiresInSeconds?: number } | { type: "progress"; message: string };
+type ModelRuntime = { getProviders(): readonly any[]; hasConfiguredAuth(providerId: string): boolean;
+  login(providerId: string, type: "oauth", interaction: { signal: AbortSignal; prompt(prompt: AuthPrompt): Promise<string>; notify(event: AuthEvent): void }): Promise<unknown> };
+
+type PublicEvent = { sequence: number; type: "info" | "auth-url" | "device-code" | "progress"; message: string | null;
+  url: string | null; links: Array<{ url: string; label: string | null }>; userCode: string | null; expiresInSeconds: number | null };
+type PublicPrompt = { promptRef: string; type: AuthPrompt["type"]; message: string; placeholder: string | null;
+  options: Array<{ id: string; label: string; description: string | null }> };
+type Job = { jobRef: string; providerRef: string; providerId: string; providerName: string; startedAt: string; expiresAt: string;
+  state: "running" | "completed" | "failed" | "cancelled"; events: PublicEvent[]; sequence: number; prompt: PublicPrompt | null;
+  promptResolve: ((value: string) => void) | null; promptReject: ((error: Error) => void) | null; controller: AbortController;
+  promptOptionValues: Map<string, string> | null; reasonCode: string | null };
+
+function safeText(value: unknown, fallback = ""): string {
+  const text = redactSensitiveText(typeof value === "string" ? value : fallback).text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  return text.slice(0, 512) || fallback;
+}
+
+function safeHttpsUrl(value: unknown): string | null {
+  if (typeof value !== "string" || value.length > 4_096) return null;
+  try { const url = new URL(value); return url.protocol === "https:" && !url.username && !url.password ? url.href : null; }
+  catch { return null; }
+}
+
+function providerRef(providerId: string): string {
+  return `provider.${createHash("sha256").update(providerId).digest("hex")}`;
+}
+
+export class ProviderAuthBroker {
+  readonly #runtime: ModelRuntime;
+  readonly #jobs = new Map<string, Job>();
+
+  constructor(runtime: ModelRuntime) { this.#runtime = runtime; }
+
+  #providers() {
+    return this.#runtime.getProviders().filter((provider) => provider?.auth?.oauth).map((provider) => ({
+      providerRef: providerRef(String(provider.id)), providerId: String(provider.id), name: safeText(provider.name, String(provider.id)),
+      configured: this.#runtime.hasConfiguredAuth(String(provider.id))
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  catalog() {
+    const providers = this.#providers();
+    return { schemaVersion: 1, version: "piagent-provider-auth-catalog-v1", generatedAt: new Date().toISOString(),
+      state: "ready", providers: providers.map(({ providerRef, name, configured }) => ({ providerRef, name, method: "oauth", state: configured ? "connected" : "not-connected" })),
+      reasonCode: providers.length ? null : "no-oauth-provider" };
+  }
+
+  #cleanup(): void {
+    const now = Date.now();
+    for (const [ref, job] of this.#jobs) if (Date.parse(job.expiresAt) <= now) {
+      job.controller.abort(); job.promptReject?.(new Error("provider-auth-expired")); this.#jobs.delete(ref);
+    }
+  }
+
+  #public(job: Job) {
+    return { schemaVersion: 1, version: "piagent-provider-auth-job-v1", generatedAt: new Date().toISOString(), jobRef: job.jobRef,
+      providerRef: job.providerRef, providerName: job.providerName, startedAt: job.startedAt, expiresAt: job.expiresAt,
+      state: job.state, events: job.events, prompt: job.prompt, reasonCode: job.reasonCode };
+  }
+
+  read(jobRef: string) {
+    this.#cleanup(); if (!REF.test(jobRef)) throw new Error("provider-auth-job-invalid");
+    const job = this.#jobs.get(jobRef); if (!job) throw new Error("provider-auth-job-not-found"); return this.#public(job);
+  }
+
+  start(command: unknown) {
+    this.#cleanup();
+    if (!command || typeof command !== "object" || Array.isArray(command)) throw new Error("provider-auth-command-invalid");
+    const record = command as Record<string, unknown>;
+    if (record.action !== "provider-auth.start" || typeof record.providerRef !== "string" || Object.keys(record).some((key) => !["action", "providerRef"].includes(key))) {
+      throw new Error("provider-auth-command-invalid");
+    }
+    const provider = this.#providers().find((candidate) => candidate.providerRef === record.providerRef);
+    if (!provider) throw new Error("provider-auth-provider-not-found");
+    const existing = [...this.#jobs.values()].find((job) => job.providerRef === provider.providerRef && job.state === "running");
+    if (existing) return this.#public(existing);
+    const started = Date.now(), controller = new AbortController();
+    const job: Job = { jobRef: `authjob.${randomBytes(24).toString("base64url")}`, providerRef: provider.providerRef,
+      providerId: provider.providerId, providerName: provider.name, startedAt: new Date(started).toISOString(),
+      expiresAt: new Date(started + JOB_TTL_MS).toISOString(), state: "running", events: [], sequence: 0, prompt: null,
+      promptResolve: null, promptReject: null, promptOptionValues: null, controller, reasonCode: null };
+    this.#jobs.set(job.jobRef, job);
+    void this.#runtime.login(provider.providerId, "oauth", { signal: controller.signal,
+      notify: (event) => this.#notify(job, event), prompt: (prompt) => this.#prompt(job, prompt) })
+      .then(() => { job.state = "completed"; job.prompt = null; job.promptResolve = null; job.promptReject = null; job.promptOptionValues = null; })
+      .catch((error) => { job.state = controller.signal.aborted ? "cancelled" : "failed"; job.prompt = null;
+        job.promptResolve = null; job.promptReject = null; job.promptOptionValues = null; job.reasonCode = controller.signal.aborted ? "provider-auth-cancelled"
+          : error instanceof Error && error.message.includes("synchron") ? "provider-auth-sync-failed" : "provider-auth-failed"; });
+    return this.#public(job);
+  }
+
+  #notify(job: Job, event: AuthEvent): void {
+    if (job.state !== "running") return;
+    let projected: Omit<PublicEvent, "sequence"> | null = null;
+    if (event.type === "auth_url") {
+      const url = safeHttpsUrl(event.url); if (url) projected = { type: "auth-url", message: safeText(event.instructions) || null,
+        url, links: [], userCode: null, expiresInSeconds: null };
+    } else if (event.type === "device_code") {
+      const url = safeHttpsUrl(event.verificationUri), code = safeText(event.userCode).slice(0, 128);
+      if (url && code) projected = { type: "device-code", message: null, url, links: [], userCode: code,
+        expiresInSeconds: Number.isFinite(event.expiresInSeconds) ? Math.max(1, Math.min(3600, Number(event.expiresInSeconds))) : null };
+    } else if (event.type === "info") projected = { type: "info", message: safeText(event.message) || null, url: null,
+      links: (event.links ?? []).slice(0, 6).flatMap((link) => { const url = safeHttpsUrl(link.url); return url ? [{ url, label: safeText(link.label) || null }] : []; }),
+      userCode: null, expiresInSeconds: null };
+    else projected = { type: "progress", message: safeText(event.message) || null, url: null, links: [], userCode: null, expiresInSeconds: null };
+    if (!projected) return;
+    job.events.push({ sequence: ++job.sequence, ...projected });
+    if (job.events.length > MAX_EVENTS) job.events.splice(0, job.events.length - MAX_EVENTS);
+  }
+
+  #prompt(job: Job, prompt: AuthPrompt): Promise<string> {
+    if (job.state !== "running" || job.prompt) return Promise.reject(new Error("provider-auth-prompt-conflict"));
+    if (prompt.type === "secret") return Promise.reject(new Error("provider-auth-secret-prompt-unsupported"));
+    const promptRef = `authprompt.${randomBytes(18).toString("base64url")}`;
+    const options = prompt.type === "select" ? (prompt.options ?? []).slice(0, 32).flatMap((option) => {
+      if (typeof option.id !== "string" || option.id.length > 1_024) return [];
+      const id = `authoption.${randomBytes(18).toString("base64url")}`;
+      return [{ id, value: option.id, label: safeText(option.label), description: safeText(option.description) || null }];
+    }).filter((option) => option.label) : [];
+    job.promptOptionValues = prompt.type === "select" ? new Map(options.map((option) => [option.id, option.value])) : null;
+    job.prompt = { promptRef, type: prompt.type, message: safeText(prompt.message, "Authentication"),
+      placeholder: safeText(prompt.placeholder) || null,
+      options: options.map(({ id, label, description }) => ({ id, label, description })) };
+    return new Promise((resolve, reject) => {
+      job.promptResolve = resolve; job.promptReject = reject;
+      const abort = () => { if (job.prompt?.promptRef === promptRef) { job.prompt = null; job.promptResolve = null; job.promptReject = null;
+        job.promptOptionValues = null; reject(new Error("provider-auth-prompt-cancelled")); } };
+      if (prompt.signal?.aborted) abort(); else prompt.signal?.addEventListener("abort", abort, { once: true });
+    });
+  }
+
+  respond(command: unknown) {
+    if (!command || typeof command !== "object" || Array.isArray(command)) throw new Error("provider-auth-response-invalid");
+    const record = command as Record<string, unknown>;
+    if (record.action !== "provider-auth.respond" || typeof record.jobRef !== "string" || typeof record.promptRef !== "string"
+      || typeof record.value !== "string" || record.value.length > 16_384 || Object.keys(record).some((key) => !["action", "jobRef", "promptRef", "value"].includes(key))) {
+      throw new Error("provider-auth-response-invalid");
+    }
+    const job = this.#jobs.get(record.jobRef); if (!job || job.state !== "running" || job.prompt?.promptRef !== record.promptRef || !job.promptResolve) {
+      throw new Error("provider-auth-prompt-stale");
+    }
+    const answer = job.prompt.type === "select" ? job.promptOptionValues?.get(record.value) : record.value;
+    if (answer === undefined) throw new Error("provider-auth-response-invalid");
+    const resolve = job.promptResolve; job.prompt = null; job.promptResolve = null; job.promptReject = null; job.promptOptionValues = null; resolve(answer);
+    return this.#public(job);
+  }
+
+  cancel(command: unknown) {
+    if (!command || typeof command !== "object" || Array.isArray(command)) throw new Error("provider-auth-cancel-invalid");
+    const record = command as Record<string, unknown>;
+    if (record.action !== "provider-auth.cancel" || typeof record.jobRef !== "string" || Object.keys(record).some((key) => !["action", "jobRef"].includes(key))) {
+      throw new Error("provider-auth-cancel-invalid");
+    }
+    const job = this.#jobs.get(record.jobRef); if (!job) throw new Error("provider-auth-job-not-found");
+    if (job.state === "running") { job.controller.abort(); job.promptReject?.(new Error("provider-auth-cancelled")); job.prompt = null;
+      job.promptResolve = null; job.promptReject = null; job.state = "cancelled"; job.reasonCode = "provider-auth-cancelled"; }
+    return this.#public(job);
+  }
+}