Upload 2526 files

src/acp/client.ts

@@ -0,0 +1,191 @@
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION,
+  ndJsonStream,
+  type RequestPermissionRequest,
+  type SessionNotification,
+} from "@agentclientprotocol/sdk";
+import { spawn, type ChildProcess } from "node:child_process";
+import * as readline from "node:readline";
+import { Readable, Writable } from "node:stream";
+import { ensureOpenClawCliOnPath } from "../infra/path-env.js";
+
+export type AcpClientOptions = {
+  cwd?: string;
+  serverCommand?: string;
+  serverArgs?: string[];
+  serverVerbose?: boolean;
+  verbose?: boolean;
+};
+
+export type AcpClientHandle = {
+  client: ClientSideConnection;
+  agent: ChildProcess;
+  sessionId: string;
+};
+
+function toArgs(value: string[] | string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+function buildServerArgs(opts: AcpClientOptions): string[] {
+  const args = ["acp", ...toArgs(opts.serverArgs)];
+  if (opts.serverVerbose && !args.includes("--verbose") && !args.includes("-v")) {
+    args.push("--verbose");
+  }
+  return args;
+}
+
+function printSessionUpdate(notification: SessionNotification): void {
+  const update = notification.update;
+  if (!("sessionUpdate" in update)) {
+    return;
+  }
+
+  switch (update.sessionUpdate) {
+    case "agent_message_chunk": {
+      if (update.content?.type === "text") {
+        process.stdout.write(update.content.text);
+      }
+      return;
+    }
+    case "tool_call": {
+      console.log(`\n[tool] ${update.title} (${update.status})`);
+      return;
+    }
+    case "tool_call_update": {
+      if (update.status) {
+        console.log(`[tool update] ${update.toolCallId}: ${update.status}`);
+      }
+      return;
+    }
+    case "available_commands_update": {
+      const names = update.availableCommands?.map((cmd) => `/${cmd.name}`).join(" ");
+      if (names) {
+        console.log(`\n[commands] ${names}`);
+      }
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+export async function createAcpClient(opts: AcpClientOptions = {}): Promise<AcpClientHandle> {
+  const cwd = opts.cwd ?? process.cwd();
+  const verbose = Boolean(opts.verbose);
+  const log = verbose ? (msg: string) => console.error(`[acp-client] ${msg}`) : () => {};
+
+  ensureOpenClawCliOnPath({ cwd });
+  const serverCommand = opts.serverCommand ?? "openclaw";
+  const serverArgs = buildServerArgs(opts);
+
+  log(`spawning: ${serverCommand} ${serverArgs.join(" ")}`);
+
+  const agent = spawn(serverCommand, serverArgs, {
+    stdio: ["pipe", "pipe", "inherit"],
+    cwd,
+  });
+
+  if (!agent.stdin || !agent.stdout) {
+    throw new Error("Failed to create ACP stdio pipes");
+  }
+
+  const input = Writable.toWeb(agent.stdin);
+  const output = Readable.toWeb(agent.stdout) as unknown as ReadableStream<Uint8Array>;
+  const stream = ndJsonStream(input, output);
+
+  const client = new ClientSideConnection(
+    () => ({
+      sessionUpdate: async (params: SessionNotification) => {
+        printSessionUpdate(params);
+      },
+      requestPermission: async (params: RequestPermissionRequest) => {
+        console.log("\n[permission requested]", params.toolCall?.title ?? "tool");
+        const options = params.options ?? [];
+        const allowOnce = options.find((option) => option.kind === "allow_once");
+        const fallback = options[0];
+        return {
+          outcome: {
+            outcome: "selected",
+            optionId: allowOnce?.optionId ?? fallback?.optionId ?? "allow",
+          },
+        };
+      },
+    }),
+    stream,
+  );
+
+  log("initializing");
+  await client.initialize({
+    protocolVersion: PROTOCOL_VERSION,
+    clientCapabilities: {
+      fs: { readTextFile: true, writeTextFile: true },
+      terminal: true,
+    },
+    clientInfo: { name: "openclaw-acp-client", version: "1.0.0" },
+  });
+
+  log("creating session");
+  const session = await client.newSession({
+    cwd,
+    mcpServers: [],
+  });
+
+  return {
+    client,
+    agent,
+    sessionId: session.sessionId,
+  };
+}
+
+export async function runAcpClientInteractive(opts: AcpClientOptions = {}): Promise<void> {
+  const { client, agent, sessionId } = await createAcpClient(opts);
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log("OpenClaw ACP client");
+  console.log(`Session: ${sessionId}`);
+  console.log('Type a prompt, or "exit" to quit.\n');
+
+  const prompt = () => {
+    rl.question("> ", async (input) => {
+      const text = input.trim();
+      if (!text) {
+        prompt();
+        return;
+      }
+      if (text === "exit" || text === "quit") {
+        agent.kill();
+        rl.close();
+        process.exit(0);
+      }
+
+      try {
+        const response = await client.prompt({
+          sessionId,
+          prompt: [{ type: "text", text }],
+        });
+        console.log(`\n[${response.stopReason}]\n`);
+      } catch (err) {
+        console.error(`\n[error] ${String(err)}\n`);
+      }
+
+      prompt();
+    });
+  };
+
+  prompt();
+
+  agent.on("exit", (code) => {
+    console.log(`\nAgent exited with code ${code ?? 0}`);
+    rl.close();
+    process.exit(code ?? 0);
+  });
+}

src/acp/commands.ts

@@ -0,0 +1,40 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+
+export function getAvailableCommands(): AvailableCommand[] {
+  return [
+    { name: "help", description: "Show help and common commands." },
+    { name: "commands", description: "List available commands." },
+    { name: "status", description: "Show current status." },
+    {
+      name: "context",
+      description: "Explain context usage (list|detail|json).",
+      input: { hint: "list | detail | json" },
+    },
+    { name: "whoami", description: "Show sender id (alias: /id)." },
+    { name: "id", description: "Alias for /whoami." },
+    { name: "subagents", description: "List or manage sub-agents." },
+    { name: "config", description: "Read or write config (owner-only)." },
+    { name: "debug", description: "Set runtime-only overrides (owner-only)." },
+    { name: "usage", description: "Toggle usage footer (off|tokens|full)." },
+    { name: "stop", description: "Stop the current run." },
+    { name: "restart", description: "Restart the gateway (if enabled)." },
+    { name: "dock-telegram", description: "Route replies to Telegram." },
+    { name: "dock-discord", description: "Route replies to Discord." },
+    { name: "dock-slack", description: "Route replies to Slack." },
+    { name: "activation", description: "Set group activation (mention|always)." },
+    { name: "send", description: "Set send mode (on|off|inherit)." },
+    { name: "reset", description: "Reset the session (/new)." },
+    { name: "new", description: "Reset the session (/reset)." },
+    {
+      name: "think",
+      description: "Set thinking level (off|minimal|low|medium|high|xhigh).",
+    },
+    { name: "verbose", description: "Set verbose mode (on|full|off)." },
+    { name: "reasoning", description: "Toggle reasoning output (on|off|stream)." },
+    { name: "elevated", description: "Toggle elevated mode (on|off)." },
+    { name: "model", description: "Select a model (list|status|<name>)." },
+    { name: "queue", description: "Adjust queue mode and options." },
+    { name: "bash", description: "Run a host command (if enabled)." },
+    { name: "compact", description: "Compact the session history." },
+  ];
+}

src/acp/event-mapper.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { extractAttachmentsFromPrompt, extractTextFromPrompt } from "./event-mapper.js";
+
+describe("acp event mapper", () => {
+  it("extracts text and resource blocks into prompt text", () => {
+    const text = extractTextFromPrompt([
+      { type: "text", text: "Hello" },
+      { type: "resource", resource: { text: "File contents" } },
+      { type: "resource_link", uri: "https://example.com", title: "Spec" },
+      { type: "image", data: "abc", mimeType: "image/png" },
+    ]);
+
+    expect(text).toBe("Hello\nFile contents\n[Resource link (Spec)] https://example.com");
+  });
+
+  it("extracts image blocks into gateway attachments", () => {
+    const attachments = extractAttachmentsFromPrompt([
+      { type: "image", data: "abc", mimeType: "image/png" },
+      { type: "image", data: "", mimeType: "image/png" },
+      { type: "text", text: "ignored" },
+    ]);
+
+    expect(attachments).toEqual([
+      {
+        type: "image",
+        mimeType: "image/png",
+        content: "abc",
+      },
+    ]);
+  });
+});

src/acp/event-mapper.ts

@@ -0,0 +1,95 @@
+import type { ContentBlock, ImageContent, ToolKind } from "@agentclientprotocol/sdk";
+
+export type GatewayAttachment = {
+  type: string;
+  mimeType: string;
+  content: string;
+};
+
+export function extractTextFromPrompt(prompt: ContentBlock[]): string {
+  const parts: string[] = [];
+  for (const block of prompt) {
+    if (block.type === "text") {
+      parts.push(block.text);
+      continue;
+    }
+    if (block.type === "resource") {
+      const resource = block.resource as { text?: string } | undefined;
+      if (resource?.text) {
+        parts.push(resource.text);
+      }
+      continue;
+    }
+    if (block.type === "resource_link") {
+      const title = block.title ? ` (${block.title})` : "";
+      const uri = block.uri ?? "";
+      const line = uri ? `[Resource link${title}] ${uri}` : `[Resource link${title}]`;
+      parts.push(line);
+    }
+  }
+  return parts.join("\n");
+}
+
+export function extractAttachmentsFromPrompt(prompt: ContentBlock[]): GatewayAttachment[] {
+  const attachments: GatewayAttachment[] = [];
+  for (const block of prompt) {
+    if (block.type !== "image") {
+      continue;
+    }
+    const image = block as ImageContent;
+    if (!image.data || !image.mimeType) {
+      continue;
+    }
+    attachments.push({
+      type: "image",
+      mimeType: image.mimeType,
+      content: image.data,
+    });
+  }
+  return attachments;
+}
+
+export function formatToolTitle(
+  name: string | undefined,
+  args: Record<string, unknown> | undefined,
+): string {
+  const base = name ?? "tool";
+  if (!args || Object.keys(args).length === 0) {
+    return base;
+  }
+  const parts = Object.entries(args).map(([key, value]) => {
+    const raw = typeof value === "string" ? value : JSON.stringify(value);
+    const safe = raw.length > 100 ? `${raw.slice(0, 100)}...` : raw;
+    return `${key}: ${safe}`;
+  });
+  return `${base}: ${parts.join(", ")}`;
+}
+
+export function inferToolKind(name?: string): ToolKind {
+  if (!name) {
+    return "other";
+  }
+  const normalized = name.toLowerCase();
+  if (normalized.includes("read")) {
+    return "read";
+  }
+  if (normalized.includes("write") || normalized.includes("edit")) {
+    return "edit";
+  }
+  if (normalized.includes("delete") || normalized.includes("remove")) {
+    return "delete";
+  }
+  if (normalized.includes("move") || normalized.includes("rename")) {
+    return "move";
+  }
+  if (normalized.includes("search") || normalized.includes("find")) {
+    return "search";
+  }
+  if (normalized.includes("exec") || normalized.includes("run") || normalized.includes("bash")) {
+    return "execute";
+  }
+  if (normalized.includes("fetch") || normalized.includes("http")) {
+    return "fetch";
+  }
+  return "other";
+}

src/acp/index.ts

@@ -0,0 +1,4 @@
+export { serveAcpGateway } from "./server.js";
+export { createInMemorySessionStore } from "./session.js";
+export type { AcpSessionStore } from "./session.js";
+export type { AcpServerOptions } from "./types.js";

src/acp/meta.ts

@@ -0,0 +1,47 @@
+export function readString(
+  meta: Record<string, unknown> | null | undefined,
+  keys: string[],
+): string | undefined {
+  if (!meta) {
+    return undefined;
+  }
+  for (const key of keys) {
+    const value = meta[key];
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+export function readBool(
+  meta: Record<string, unknown> | null | undefined,
+  keys: string[],
+): boolean | undefined {
+  if (!meta) {
+    return undefined;
+  }
+  for (const key of keys) {
+    const value = meta[key];
+    if (typeof value === "boolean") {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+export function readNumber(
+  meta: Record<string, unknown> | null | undefined,
+  keys: string[],
+): number | undefined {
+  if (!meta) {
+    return undefined;
+  }
+  for (const key of keys) {
+    const value = meta[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return undefined;
+}

src/acp/server.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { AgentSideConnection, ndJsonStream } from "@agentclientprotocol/sdk";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import type { AcpServerOptions } from "./types.js";
+import { loadConfig } from "../config/config.js";
+import { resolveGatewayAuth } from "../gateway/auth.js";
+import { buildGatewayConnectionDetails } from "../gateway/call.js";
+import { GatewayClient } from "../gateway/client.js";
+import { isMainModule } from "../infra/is-main.js";
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
+import { AcpGatewayAgent } from "./translator.js";
+
+export function serveAcpGateway(opts: AcpServerOptions = {}): void {
+  const cfg = loadConfig();
+  const connection = buildGatewayConnectionDetails({
+    config: cfg,
+    url: opts.gatewayUrl,
+  });
+
+  const isRemoteMode = cfg.gateway?.mode === "remote";
+  const remote = isRemoteMode ? cfg.gateway?.remote : undefined;
+  const auth = resolveGatewayAuth({ authConfig: cfg.gateway?.auth, env: process.env });
+
+  const token =
+    opts.gatewayToken ??
+    (isRemoteMode ? remote?.token?.trim() : undefined) ??
+    process.env.OPENCLAW_GATEWAY_TOKEN ??
+    auth.token;
+  const password =
+    opts.gatewayPassword ??
+    (isRemoteMode ? remote?.password?.trim() : undefined) ??
+    process.env.OPENCLAW_GATEWAY_PASSWORD ??
+    auth.password;
+
+  let agent: AcpGatewayAgent | null = null;
+  const gateway = new GatewayClient({
+    url: connection.url,
+    token: token || undefined,
+    password: password || undefined,
+    clientName: GATEWAY_CLIENT_NAMES.CLI,
+    clientDisplayName: "ACP",
+    clientVersion: "acp",
+    mode: GATEWAY_CLIENT_MODES.CLI,
+    onEvent: (evt) => {
+      void agent?.handleGatewayEvent(evt);
+    },
+    onHelloOk: () => {
+      agent?.handleGatewayReconnect();
+    },
+    onClose: (code, reason) => {
+      agent?.handleGatewayDisconnect(`${code}: ${reason}`);
+    },
+  });
+
+  const input = Writable.toWeb(process.stdout);
+  const output = Readable.toWeb(process.stdin) as unknown as ReadableStream<Uint8Array>;
+  const stream = ndJsonStream(input, output);
+
+  new AgentSideConnection((conn: AgentSideConnection) => {
+    agent = new AcpGatewayAgent(conn, gateway, opts);
+    agent.start();
+    return agent;
+  }, stream);
+
+  gateway.start();
+}
+
+function parseArgs(args: string[]): AcpServerOptions {
+  const opts: AcpServerOptions = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--url" || arg === "--gateway-url") {
+      opts.gatewayUrl = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--token" || arg === "--gateway-token") {
+      opts.gatewayToken = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--password" || arg === "--gateway-password") {
+      opts.gatewayPassword = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--session") {
+      opts.defaultSessionKey = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--session-label") {
+      opts.defaultSessionLabel = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--require-existing") {
+      opts.requireExistingSession = true;
+      continue;
+    }
+    if (arg === "--reset-session") {
+      opts.resetSession = true;
+      continue;
+    }
+    if (arg === "--no-prefix-cwd") {
+      opts.prefixCwd = false;
+      continue;
+    }
+    if (arg === "--verbose" || arg === "-v") {
+      opts.verbose = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function printHelp(): void {
+  console.log(`Usage: openclaw acp [options]
+
+Gateway-backed ACP server for IDE integration.
+
+Options:
+  --url <url>             Gateway WebSocket URL
+  --token <token>         Gateway auth token
+  --password <password>   Gateway auth password
+  --session <key>         Default session key (e.g. "agent:main:main")
+  --session-label <label> Default session label to resolve
+  --require-existing      Fail if the session key/label does not exist
+  --reset-session         Reset the session key before first use
+  --no-prefix-cwd         Do not prefix prompts with the working directory
+  --verbose, -v           Verbose logging to stderr
+  --help, -h              Show this help message
+`);
+}
+
+if (isMainModule({ currentFile: fileURLToPath(import.meta.url) })) {
+  const opts = parseArgs(process.argv.slice(2));
+  serveAcpGateway(opts);
+}

src/acp/session-mapper.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from "vitest";
+import type { GatewayClient } from "../gateway/client.js";
+import { parseSessionMeta, resolveSessionKey } from "./session-mapper.js";
+
+function createGateway(resolveLabelKey = "agent:main:label"): {
+  gateway: GatewayClient;
+  request: ReturnType<typeof vi.fn>;
+} {
+  const request = vi.fn(async (method: string, params: Record<string, unknown>) => {
+    if (method === "sessions.resolve" && "label" in params) {
+      return { ok: true, key: resolveLabelKey };
+    }
+    if (method === "sessions.resolve" && "key" in params) {
+      return { ok: true, key: params.key as string };
+    }
+    return { ok: true };
+  });
+
+  return {
+    gateway: { request } as unknown as GatewayClient,
+    request,
+  };
+}
+
+describe("acp session mapper", () => {
+  it("prefers explicit sessionLabel over sessionKey", async () => {
+    const { gateway, request } = createGateway();
+    const meta = parseSessionMeta({ sessionLabel: "support", sessionKey: "agent:main:main" });
+
+    const key = await resolveSessionKey({
+      meta,
+      fallbackKey: "acp:fallback",
+      gateway,
+      opts: {},
+    });
+
+    expect(key).toBe("agent:main:label");
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(request).toHaveBeenCalledWith("sessions.resolve", { label: "support" });
+  });
+
+  it("lets meta sessionKey override default label", async () => {
+    const { gateway, request } = createGateway();
+    const meta = parseSessionMeta({ sessionKey: "agent:main:override" });
+
+    const key = await resolveSessionKey({
+      meta,
+      fallbackKey: "acp:fallback",
+      gateway,
+      opts: { defaultSessionLabel: "default-label" },
+    });
+
+    expect(key).toBe("agent:main:override");
+    expect(request).not.toHaveBeenCalled();
+  });
+});

src/acp/session-mapper.ts

@@ -0,0 +1,98 @@
+import type { GatewayClient } from "../gateway/client.js";
+import type { AcpServerOptions } from "./types.js";
+import { readBool, readString } from "./meta.js";
+
+export type AcpSessionMeta = {
+  sessionKey?: string;
+  sessionLabel?: string;
+  resetSession?: boolean;
+  requireExisting?: boolean;
+  prefixCwd?: boolean;
+};
+
+export function parseSessionMeta(meta: unknown): AcpSessionMeta {
+  if (!meta || typeof meta !== "object") {
+    return {};
+  }
+  const record = meta as Record<string, unknown>;
+  return {
+    sessionKey: readString(record, ["sessionKey", "session", "key"]),
+    sessionLabel: readString(record, ["sessionLabel", "label"]),
+    resetSession: readBool(record, ["resetSession", "reset"]),
+    requireExisting: readBool(record, ["requireExistingSession", "requireExisting"]),
+    prefixCwd: readBool(record, ["prefixCwd"]),
+  };
+}
+
+export async function resolveSessionKey(params: {
+  meta: AcpSessionMeta;
+  fallbackKey: string;
+  gateway: GatewayClient;
+  opts: AcpServerOptions;
+}): Promise<string> {
+  const requestedLabel = params.meta.sessionLabel ?? params.opts.defaultSessionLabel;
+  const requestedKey = params.meta.sessionKey ?? params.opts.defaultSessionKey;
+  const requireExisting =
+    params.meta.requireExisting ?? params.opts.requireExistingSession ?? false;
+
+  if (params.meta.sessionLabel) {
+    const resolved = await params.gateway.request<{ ok: true; key: string }>("sessions.resolve", {
+      label: params.meta.sessionLabel,
+    });
+    if (!resolved?.key) {
+      throw new Error(`Unable to resolve session label: ${params.meta.sessionLabel}`);
+    }
+    return resolved.key;
+  }
+
+  if (params.meta.sessionKey) {
+    if (!requireExisting) {
+      return params.meta.sessionKey;
+    }
+    const resolved = await params.gateway.request<{ ok: true; key: string }>("sessions.resolve", {
+      key: params.meta.sessionKey,
+    });
+    if (!resolved?.key) {
+      throw new Error(`Session key not found: ${params.meta.sessionKey}`);
+    }
+    return resolved.key;
+  }
+
+  if (requestedLabel) {
+    const resolved = await params.gateway.request<{ ok: true; key: string }>("sessions.resolve", {
+      label: requestedLabel,
+    });
+    if (!resolved?.key) {
+      throw new Error(`Unable to resolve session label: ${requestedLabel}`);
+    }
+    return resolved.key;
+  }
+
+  if (requestedKey) {
+    if (!requireExisting) {
+      return requestedKey;
+    }
+    const resolved = await params.gateway.request<{ ok: true; key: string }>("sessions.resolve", {
+      key: requestedKey,
+    });
+    if (!resolved?.key) {
+      throw new Error(`Session key not found: ${requestedKey}`);
+    }
+    return resolved.key;
+  }
+
+  return params.fallbackKey;
+}
+
+export async function resetSessionIfNeeded(params: {
+  meta: AcpSessionMeta;
+  sessionKey: string;
+  gateway: GatewayClient;
+  opts: AcpServerOptions;
+}): Promise<void> {
+  const resetSession = params.meta.resetSession ?? params.opts.resetSession ?? false;
+  if (!resetSession) {
+    return;
+  }
+  await params.gateway.request("sessions.reset", { key: params.sessionKey });
+}

src/acp/session.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it, afterEach } from "vitest";
+import { createInMemorySessionStore } from "./session.js";
+
+describe("acp session manager", () => {
+  const store = createInMemorySessionStore();
+
+  afterEach(() => {
+    store.clearAllSessionsForTest();
+  });
+
+  it("tracks active runs and clears on cancel", () => {
+    const session = store.createSession({
+      sessionKey: "acp:test",
+      cwd: "/tmp",
+    });
+    const controller = new AbortController();
+    store.setActiveRun(session.sessionId, "run-1", controller);
+
+    expect(store.getSessionByRunId("run-1")?.sessionId).toBe(session.sessionId);
+
+    const cancelled = store.cancelActiveRun(session.sessionId);
+    expect(cancelled).toBe(true);
+    expect(store.getSessionByRunId("run-1")).toBeUndefined();
+  });
+});

src/acp/session.ts

@@ -0,0 +1,94 @@
+import { randomUUID } from "node:crypto";
+import type { AcpSession } from "./types.js";
+
+export type AcpSessionStore = {
+  createSession: (params: { sessionKey: string; cwd: string; sessionId?: string }) => AcpSession;
+  getSession: (sessionId: string) => AcpSession | undefined;
+  getSessionByRunId: (runId: string) => AcpSession | undefined;
+  setActiveRun: (sessionId: string, runId: string, abortController: AbortController) => void;
+  clearActiveRun: (sessionId: string) => void;
+  cancelActiveRun: (sessionId: string) => boolean;
+  clearAllSessionsForTest: () => void;
+};
+
+export function createInMemorySessionStore(): AcpSessionStore {
+  const sessions = new Map<string, AcpSession>();
+  const runIdToSessionId = new Map<string, string>();
+
+  const createSession: AcpSessionStore["createSession"] = (params) => {
+    const sessionId = params.sessionId ?? randomUUID();
+    const session: AcpSession = {
+      sessionId,
+      sessionKey: params.sessionKey,
+      cwd: params.cwd,
+      createdAt: Date.now(),
+      abortController: null,
+      activeRunId: null,
+    };
+    sessions.set(sessionId, session);
+    return session;
+  };
+
+  const getSession: AcpSessionStore["getSession"] = (sessionId) => sessions.get(sessionId);
+
+  const getSessionByRunId: AcpSessionStore["getSessionByRunId"] = (runId) => {
+    const sessionId = runIdToSessionId.get(runId);
+    return sessionId ? sessions.get(sessionId) : undefined;
+  };
+
+  const setActiveRun: AcpSessionStore["setActiveRun"] = (sessionId, runId, abortController) => {
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+    session.activeRunId = runId;
+    session.abortController = abortController;
+    runIdToSessionId.set(runId, sessionId);
+  };
+
+  const clearActiveRun: AcpSessionStore["clearActiveRun"] = (sessionId) => {
+    const session = sessions.get(sessionId);
+    if (!session) {
+      return;
+    }
+    if (session.activeRunId) {
+      runIdToSessionId.delete(session.activeRunId);
+    }
+    session.activeRunId = null;
+    session.abortController = null;
+  };
+
+  const cancelActiveRun: AcpSessionStore["cancelActiveRun"] = (sessionId) => {
+    const session = sessions.get(sessionId);
+    if (!session?.abortController) {
+      return false;
+    }
+    session.abortController.abort();
+    if (session.activeRunId) {
+      runIdToSessionId.delete(session.activeRunId);
+    }
+    session.abortController = null;
+    session.activeRunId = null;
+    return true;
+  };
+
+  const clearAllSessionsForTest: AcpSessionStore["clearAllSessionsForTest"] = () => {
+    for (const session of sessions.values()) {
+      session.abortController?.abort();
+    }
+    sessions.clear();
+    runIdToSessionId.clear();
+  };
+
+  return {
+    createSession,
+    getSession,
+    getSessionByRunId,
+    setActiveRun,
+    clearActiveRun,
+    cancelActiveRun,
+    clearAllSessionsForTest,
+  };
+}
+
+export const defaultAcpSessionStore = createInMemorySessionStore();

src/acp/translator.ts

@@ -0,0 +1,454 @@
+import type {
+  Agent,
+  AgentSideConnection,
+  AuthenticateRequest,
+  AuthenticateResponse,
+  CancelNotification,
+  InitializeRequest,
+  InitializeResponse,
+  ListSessionsRequest,
+  ListSessionsResponse,
+  LoadSessionRequest,
+  LoadSessionResponse,
+  NewSessionRequest,
+  NewSessionResponse,
+  PromptRequest,
+  PromptResponse,
+  SetSessionModeRequest,
+  SetSessionModeResponse,
+  StopReason,
+} from "@agentclientprotocol/sdk";
+import { PROTOCOL_VERSION } from "@agentclientprotocol/sdk";
+import { randomUUID } from "node:crypto";
+import type { GatewayClient } from "../gateway/client.js";
+import type { EventFrame } from "../gateway/protocol/index.js";
+import type { SessionsListResult } from "../gateway/session-utils.js";
+import { getAvailableCommands } from "./commands.js";
+import {
+  extractAttachmentsFromPrompt,
+  extractTextFromPrompt,
+  formatToolTitle,
+  inferToolKind,
+} from "./event-mapper.js";
+import { readBool, readNumber, readString } from "./meta.js";
+import { parseSessionMeta, resetSessionIfNeeded, resolveSessionKey } from "./session-mapper.js";
+import { defaultAcpSessionStore, type AcpSessionStore } from "./session.js";
+import { ACP_AGENT_INFO, type AcpServerOptions } from "./types.js";
+
+type PendingPrompt = {
+  sessionId: string;
+  sessionKey: string;
+  idempotencyKey: string;
+  resolve: (response: PromptResponse) => void;
+  reject: (err: Error) => void;
+  sentTextLength?: number;
+  sentText?: string;
+  toolCalls?: Set<string>;
+};
+
+type AcpGatewayAgentOptions = AcpServerOptions & {
+  sessionStore?: AcpSessionStore;
+};
+
+export class AcpGatewayAgent implements Agent {
+  private connection: AgentSideConnection;
+  private gateway: GatewayClient;
+  private opts: AcpGatewayAgentOptions;
+  private log: (msg: string) => void;
+  private sessionStore: AcpSessionStore;
+  private pendingPrompts = new Map<string, PendingPrompt>();
+
+  constructor(
+    connection: AgentSideConnection,
+    gateway: GatewayClient,
+    opts: AcpGatewayAgentOptions = {},
+  ) {
+    this.connection = connection;
+    this.gateway = gateway;
+    this.opts = opts;
+    this.log = opts.verbose ? (msg: string) => process.stderr.write(`[acp] ${msg}\n`) : () => {};
+    this.sessionStore = opts.sessionStore ?? defaultAcpSessionStore;
+  }
+
+  start(): void {
+    this.log("ready");
+  }
+
+  handleGatewayReconnect(): void {
+    this.log("gateway reconnected");
+  }
+
+  handleGatewayDisconnect(reason: string): void {
+    this.log(`gateway disconnected: ${reason}`);
+    for (const pending of this.pendingPrompts.values()) {
+      pending.reject(new Error(`Gateway disconnected: ${reason}`));
+      this.sessionStore.clearActiveRun(pending.sessionId);
+    }
+    this.pendingPrompts.clear();
+  }
+
+  async handleGatewayEvent(evt: EventFrame): Promise<void> {
+    if (evt.event === "chat") {
+      await this.handleChatEvent(evt);
+      return;
+    }
+    if (evt.event === "agent") {
+      await this.handleAgentEvent(evt);
+    }
+  }
+
+  async initialize(_params: InitializeRequest): Promise<InitializeResponse> {
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      agentCapabilities: {
+        loadSession: true,
+        promptCapabilities: {
+          image: true,
+          audio: false,
+          embeddedContext: true,
+        },
+        mcpCapabilities: {
+          http: false,
+          sse: false,
+        },
+        sessionCapabilities: {
+          list: {},
+        },
+      },
+      agentInfo: ACP_AGENT_INFO,
+      authMethods: [],
+    };
+  }
+
+  async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+    if (params.mcpServers.length > 0) {
+      this.log(`ignoring ${params.mcpServers.length} MCP servers`);
+    }
+
+    const sessionId = randomUUID();
+    const meta = parseSessionMeta(params._meta);
+    const sessionKey = await resolveSessionKey({
+      meta,
+      fallbackKey: `acp:${sessionId}`,
+      gateway: this.gateway,
+      opts: this.opts,
+    });
+    await resetSessionIfNeeded({
+      meta,
+      sessionKey,
+      gateway: this.gateway,
+      opts: this.opts,
+    });
+
+    const session = this.sessionStore.createSession({
+      sessionId,
+      sessionKey,
+      cwd: params.cwd,
+    });
+    this.log(`newSession: ${session.sessionId} -> ${session.sessionKey}`);
+    await this.sendAvailableCommands(session.sessionId);
+    return { sessionId: session.sessionId };
+  }
+
+  async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
+    if (params.mcpServers.length > 0) {
+      this.log(`ignoring ${params.mcpServers.length} MCP servers`);
+    }
+
+    const meta = parseSessionMeta(params._meta);
+    const sessionKey = await resolveSessionKey({
+      meta,
+      fallbackKey: params.sessionId,
+      gateway: this.gateway,
+      opts: this.opts,
+    });
+    await resetSessionIfNeeded({
+      meta,
+      sessionKey,
+      gateway: this.gateway,
+      opts: this.opts,
+    });
+
+    const session = this.sessionStore.createSession({
+      sessionId: params.sessionId,
+      sessionKey,
+      cwd: params.cwd,
+    });
+    this.log(`loadSession: ${session.sessionId} -> ${session.sessionKey}`);
+    await this.sendAvailableCommands(session.sessionId);
+    return {};
+  }
+
+  async unstable_listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
+    const limit = readNumber(params._meta, ["limit"]) ?? 100;
+    const result = await this.gateway.request<SessionsListResult>("sessions.list", { limit });
+    const cwd = params.cwd ?? process.cwd();
+    return {
+      sessions: result.sessions.map((session) => ({
+        sessionId: session.key,
+        cwd,
+        title: session.displayName ?? session.label ?? session.key,
+        updatedAt: session.updatedAt ? new Date(session.updatedAt).toISOString() : undefined,
+        _meta: {
+          sessionKey: session.key,
+          kind: session.kind,
+          channel: session.channel,
+        },
+      })),
+      nextCursor: null,
+    };
+  }
+
+  async authenticate(_params: AuthenticateRequest): Promise<AuthenticateResponse> {
+    return {};
+  }
+
+  async setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
+    const session = this.sessionStore.getSession(params.sessionId);
+    if (!session) {
+      throw new Error(`Session ${params.sessionId} not found`);
+    }
+    if (!params.modeId) {
+      return {};
+    }
+    try {
+      await this.gateway.request("sessions.patch", {
+        key: session.sessionKey,
+        thinkingLevel: params.modeId,
+      });
+      this.log(`setSessionMode: ${session.sessionId} -> ${params.modeId}`);
+    } catch (err) {
+      this.log(`setSessionMode error: ${String(err)}`);
+    }
+    return {};
+  }
+
+  async prompt(params: PromptRequest): Promise<PromptResponse> {
+    const session = this.sessionStore.getSession(params.sessionId);
+    if (!session) {
+      throw new Error(`Session ${params.sessionId} not found`);
+    }
+
+    if (session.abortController) {
+      this.sessionStore.cancelActiveRun(params.sessionId);
+    }
+
+    const abortController = new AbortController();
+    const runId = randomUUID();
+    this.sessionStore.setActiveRun(params.sessionId, runId, abortController);
+
+    const meta = parseSessionMeta(params._meta);
+    const userText = extractTextFromPrompt(params.prompt);
+    const attachments = extractAttachmentsFromPrompt(params.prompt);
+    const prefixCwd = meta.prefixCwd ?? this.opts.prefixCwd ?? true;
+    const message = prefixCwd ? `[Working directory: ${session.cwd}]\n\n${userText}` : userText;
+
+    return new Promise<PromptResponse>((resolve, reject) => {
+      this.pendingPrompts.set(params.sessionId, {
+        sessionId: params.sessionId,
+        sessionKey: session.sessionKey,
+        idempotencyKey: runId,
+        resolve,
+        reject,
+      });
+
+      this.gateway
+        .request(
+          "chat.send",
+          {
+            sessionKey: session.sessionKey,
+            message,
+            attachments: attachments.length > 0 ? attachments : undefined,
+            idempotencyKey: runId,
+            thinking: readString(params._meta, ["thinking", "thinkingLevel"]),
+            deliver: readBool(params._meta, ["deliver"]),
+            timeoutMs: readNumber(params._meta, ["timeoutMs"]),
+          },
+          { expectFinal: true },
+        )
+        .catch((err) => {
+          this.pendingPrompts.delete(params.sessionId);
+          this.sessionStore.clearActiveRun(params.sessionId);
+          reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+  }
+
+  async cancel(params: CancelNotification): Promise<void> {
+    const session = this.sessionStore.getSession(params.sessionId);
+    if (!session) {
+      return;
+    }
+
+    this.sessionStore.cancelActiveRun(params.sessionId);
+    try {
+      await this.gateway.request("chat.abort", { sessionKey: session.sessionKey });
+    } catch (err) {
+      this.log(`cancel error: ${String(err)}`);
+    }
+
+    const pending = this.pendingPrompts.get(params.sessionId);
+    if (pending) {
+      this.pendingPrompts.delete(params.sessionId);
+      pending.resolve({ stopReason: "cancelled" });
+    }
+  }
+
+  private async handleAgentEvent(evt: EventFrame): Promise<void> {
+    const payload = evt.payload as Record<string, unknown> | undefined;
+    if (!payload) {
+      return;
+    }
+    const stream = payload.stream as string | undefined;
+    const data = payload.data as Record<string, unknown> | undefined;
+    const sessionKey = payload.sessionKey as string | undefined;
+    if (!stream || !data || !sessionKey) {
+      return;
+    }
+
+    if (stream !== "tool") {
+      return;
+    }
+    const phase = data.phase as string | undefined;
+    const name = data.name as string | undefined;
+    const toolCallId = data.toolCallId as string | undefined;
+    if (!toolCallId) {
+      return;
+    }
+
+    const pending = this.findPendingBySessionKey(sessionKey);
+    if (!pending) {
+      return;
+    }
+
+    if (phase === "start") {
+      if (!pending.toolCalls) {
+        pending.toolCalls = new Set();
+      }
+      if (pending.toolCalls.has(toolCallId)) {
+        return;
+      }
+      pending.toolCalls.add(toolCallId);
+      const args = data.args as Record<string, unknown> | undefined;
+      await this.connection.sessionUpdate({
+        sessionId: pending.sessionId,
+        update: {
+          sessionUpdate: "tool_call",
+          toolCallId,
+          title: formatToolTitle(name, args),
+          status: "in_progress",
+          rawInput: args,
+          kind: inferToolKind(name),
+        },
+      });
+      return;
+    }
+
+    if (phase === "result") {
+      const isError = Boolean(data.isError);
+      await this.connection.sessionUpdate({
+        sessionId: pending.sessionId,
+        update: {
+          sessionUpdate: "tool_call_update",
+          toolCallId,
+          status: isError ? "failed" : "completed",
+          rawOutput: data.result,
+        },
+      });
+    }
+  }
+
+  private async handleChatEvent(evt: EventFrame): Promise<void> {
+    const payload = evt.payload as Record<string, unknown> | undefined;
+    if (!payload) {
+      return;
+    }
+
+    const sessionKey = payload.sessionKey as string | undefined;
+    const state = payload.state as string | undefined;
+    const runId = payload.runId as string | undefined;
+    const messageData = payload.message as Record<string, unknown> | undefined;
+    if (!sessionKey || !state) {
+      return;
+    }
+
+    const pending = this.findPendingBySessionKey(sessionKey);
+    if (!pending) {
+      return;
+    }
+    if (runId && pending.idempotencyKey !== runId) {
+      return;
+    }
+
+    if (state === "delta" && messageData) {
+      await this.handleDeltaEvent(pending.sessionId, messageData);
+      return;
+    }
+
+    if (state === "final") {
+      this.finishPrompt(pending.sessionId, pending, "end_turn");
+      return;
+    }
+    if (state === "aborted") {
+      this.finishPrompt(pending.sessionId, pending, "cancelled");
+      return;
+    }
+    if (state === "error") {
+      this.finishPrompt(pending.sessionId, pending, "refusal");
+    }
+  }
+
+  private async handleDeltaEvent(
+    sessionId: string,
+    messageData: Record<string, unknown>,
+  ): Promise<void> {
+    const content = messageData.content as Array<{ type: string; text?: string }> | undefined;
+    const fullText = content?.find((c) => c.type === "text")?.text ?? "";
+    const pending = this.pendingPrompts.get(sessionId);
+    if (!pending) {
+      return;
+    }
+
+    const sentSoFar = pending.sentTextLength ?? 0;
+    if (fullText.length <= sentSoFar) {
+      return;
+    }
+
+    const newText = fullText.slice(sentSoFar);
+    pending.sentTextLength = fullText.length;
+    pending.sentText = fullText;
+
+    await this.connection.sessionUpdate({
+      sessionId,
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: { type: "text", text: newText },
+      },
+    });
+  }
+
+  private finishPrompt(sessionId: string, pending: PendingPrompt, stopReason: StopReason): void {
+    this.pendingPrompts.delete(sessionId);
+    this.sessionStore.clearActiveRun(sessionId);
+    pending.resolve({ stopReason });
+  }
+
+  private findPendingBySessionKey(sessionKey: string): PendingPrompt | undefined {
+    for (const pending of this.pendingPrompts.values()) {
+      if (pending.sessionKey === sessionKey) {
+        return pending;
+      }
+    }
+    return undefined;
+  }
+
+  private async sendAvailableCommands(sessionId: string): Promise<void> {
+    await this.connection.sessionUpdate({
+      sessionId,
+      update: {
+        sessionUpdate: "available_commands_update",
+        availableCommands: getAvailableCommands(),
+      },
+    });
+  }
+}

src/acp/types.ts

@@ -0,0 +1,29 @@
+import type { SessionId } from "@agentclientprotocol/sdk";
+import { VERSION } from "../version.js";
+
+export type AcpSession = {
+  sessionId: SessionId;
+  sessionKey: string;
+  cwd: string;
+  createdAt: number;
+  abortController: AbortController | null;
+  activeRunId: string | null;
+};
+
+export type AcpServerOptions = {
+  gatewayUrl?: string;
+  gatewayToken?: string;
+  gatewayPassword?: string;
+  defaultSessionKey?: string;
+  defaultSessionLabel?: string;
+  requireExistingSession?: boolean;
+  resetSession?: boolean;
+  prefixCwd?: boolean;
+  verbose?: boolean;
+};
+
+export const ACP_AGENT_INFO = {
+  name: "openclaw-acp",
+  title: "OpenClaw ACP Gateway",
+  version: VERSION,
+};

src/agents/agent-paths.test.ts

@@ -0,0 +1,56 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveOpenClawAgentDir } from "./agent-paths.js";
+
+describe("resolveOpenClawAgentDir", () => {
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
+  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  let tempStateDir: string | null = null;
+
+  afterEach(async () => {
+    if (tempStateDir) {
+      await fs.rm(tempStateDir, { recursive: true, force: true });
+      tempStateDir = null;
+    }
+    if (previousStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousStateDir;
+    }
+    if (previousAgentDir === undefined) {
+      delete process.env.OPENCLAW_AGENT_DIR;
+    } else {
+      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
+    }
+    if (previousPiAgentDir === undefined) {
+      delete process.env.PI_CODING_AGENT_DIR;
+    } else {
+      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+    }
+  });
+
+  it("defaults to the multi-agent path when no overrides are set", async () => {
+    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-agent-"));
+    process.env.OPENCLAW_STATE_DIR = tempStateDir;
+    delete process.env.OPENCLAW_AGENT_DIR;
+    delete process.env.PI_CODING_AGENT_DIR;
+
+    const resolved = resolveOpenClawAgentDir();
+
+    expect(resolved).toBe(path.join(tempStateDir, "agents", "main", "agent"));
+  });
+
+  it("honors OPENCLAW_AGENT_DIR overrides", async () => {
+    tempStateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-agent-"));
+    const override = path.join(tempStateDir, "agent");
+    process.env.OPENCLAW_AGENT_DIR = override;
+    delete process.env.PI_CODING_AGENT_DIR;
+
+    const resolved = resolveOpenClawAgentDir();
+
+    expect(resolved).toBe(path.resolve(override));
+  });
+});

src/agents/agent-paths.ts

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { DEFAULT_AGENT_ID } from "../routing/session-key.js";
+import { resolveUserPath } from "../utils.js";
+
+export function resolveOpenClawAgentDir(): string {
+  const override =
+    process.env.OPENCLAW_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim();
+  if (override) {
+    return resolveUserPath(override);
+  }
+  const defaultAgentDir = path.join(resolveStateDir(), "agents", DEFAULT_AGENT_ID, "agent");
+  return resolveUserPath(defaultAgentDir);
+}
+
+export function ensureOpenClawAgentEnv(): string {
+  const dir = resolveOpenClawAgentDir();
+  if (!process.env.OPENCLAW_AGENT_DIR) {
+    process.env.OPENCLAW_AGENT_DIR = dir;
+  }
+  if (!process.env.PI_CODING_AGENT_DIR) {
+    process.env.PI_CODING_AGENT_DIR = dir;
+  }
+  return dir;
+}

src/agents/agent-scope.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../config/config.js";
+import {
+  resolveAgentConfig,
+  resolveAgentModelFallbacksOverride,
+  resolveAgentModelPrimary,
+} from "./agent-scope.js";
+
+describe("resolveAgentConfig", () => {
+  it("should return undefined when no agents config exists", () => {
+    const cfg: OpenClawConfig = {};
+    const result = resolveAgentConfig(cfg, "main");
+    expect(result).toBeUndefined();
+  });
+
+  it("should return undefined when agent id does not exist", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [{ id: "main", workspace: "~/openclaw" }],
+      },
+    };
+    const result = resolveAgentConfig(cfg, "nonexistent");
+    expect(result).toBeUndefined();
+  });
+
+  it("should return basic agent config", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "main",
+            name: "Main Agent",
+            workspace: "~/openclaw",
+            agentDir: "~/.openclaw/agents/main",
+            model: "anthropic/claude-opus-4",
+          },
+        ],
+      },
+    };
+    const result = resolveAgentConfig(cfg, "main");
+    expect(result).toEqual({
+      name: "Main Agent",
+      workspace: "~/openclaw",
+      agentDir: "~/.openclaw/agents/main",
+      model: "anthropic/claude-opus-4",
+      identity: undefined,
+      groupChat: undefined,
+      subagents: undefined,
+      sandbox: undefined,
+      tools: undefined,
+    });
+  });
+
+  it("supports per-agent model primary+fallbacks", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        defaults: {
+          model: {
+            primary: "anthropic/claude-sonnet-4",
+            fallbacks: ["openai/gpt-4.1"],
+          },
+        },
+        list: [
+          {
+            id: "linus",
+            model: {
+              primary: "anthropic/claude-opus-4",
+              fallbacks: ["openai/gpt-5.2"],
+            },
+          },
+        ],
+      },
+    };
+
+    expect(resolveAgentModelPrimary(cfg, "linus")).toBe("anthropic/claude-opus-4");
+    expect(resolveAgentModelFallbacksOverride(cfg, "linus")).toEqual(["openai/gpt-5.2"]);
+
+    // If fallbacks isn't present, we don't override the global fallbacks.
+    const cfgNoOverride: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "linus",
+            model: {
+              primary: "anthropic/claude-opus-4",
+            },
+          },
+        ],
+      },
+    };
+    expect(resolveAgentModelFallbacksOverride(cfgNoOverride, "linus")).toBe(undefined);
+
+    // Explicit empty list disables global fallbacks for that agent.
+    const cfgDisable: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "linus",
+            model: {
+              primary: "anthropic/claude-opus-4",
+              fallbacks: [],
+            },
+          },
+        ],
+      },
+    };
+    expect(resolveAgentModelFallbacksOverride(cfgDisable, "linus")).toEqual([]);
+  });
+
+  it("should return agent-specific sandbox config", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "work",
+            workspace: "~/openclaw-work",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+              perSession: false,
+              workspaceAccess: "ro",
+              workspaceRoot: "~/sandboxes",
+            },
+          },
+        ],
+      },
+    };
+    const result = resolveAgentConfig(cfg, "work");
+    expect(result?.sandbox).toEqual({
+      mode: "all",
+      scope: "agent",
+      perSession: false,
+      workspaceAccess: "ro",
+      workspaceRoot: "~/sandboxes",
+    });
+  });
+
+  it("should return agent-specific tools config", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "restricted",
+            workspace: "~/openclaw-restricted",
+            tools: {
+              allow: ["read"],
+              deny: ["exec", "write", "edit"],
+              elevated: {
+                enabled: false,
+                allowFrom: { whatsapp: ["+15555550123"] },
+              },
+            },
+          },
+        ],
+      },
+    };
+    const result = resolveAgentConfig(cfg, "restricted");
+    expect(result?.tools).toEqual({
+      allow: ["read"],
+      deny: ["exec", "write", "edit"],
+      elevated: {
+        enabled: false,
+        allowFrom: { whatsapp: ["+15555550123"] },
+      },
+    });
+  });
+
+  it("should return both sandbox and tools config", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [
+          {
+            id: "family",
+            workspace: "~/openclaw-family",
+            sandbox: {
+              mode: "all",
+              scope: "agent",
+            },
+            tools: {
+              allow: ["read"],
+              deny: ["exec"],
+            },
+          },
+        ],
+      },
+    };
+    const result = resolveAgentConfig(cfg, "family");
+    expect(result?.sandbox?.mode).toBe("all");
+    expect(result?.tools?.allow).toEqual(["read"]);
+  });
+
+  it("should normalize agent id", () => {
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [{ id: "main", workspace: "~/openclaw" }],
+      },
+    };
+    // Should normalize to "main" (default)
+    const result = resolveAgentConfig(cfg, "");
+    expect(result).toBeDefined();
+    expect(result?.workspace).toBe("~/openclaw");
+  });
+});

src/agents/agent-scope.ts

@@ -0,0 +1,178 @@
+import os from "node:os";
+import path from "node:path";
+import type { OpenClawConfig } from "../config/config.js";
+import { resolveStateDir } from "../config/paths.js";
+import {
+  DEFAULT_AGENT_ID,
+  normalizeAgentId,
+  parseAgentSessionKey,
+} from "../routing/session-key.js";
+import { resolveUserPath } from "../utils.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+
+export { resolveAgentIdFromSessionKey } from "../routing/session-key.js";
+
+type AgentEntry = NonNullable<NonNullable<OpenClawConfig["agents"]>["list"]>[number];
+
+type ResolvedAgentConfig = {
+  name?: string;
+  workspace?: string;
+  agentDir?: string;
+  model?: AgentEntry["model"];
+  memorySearch?: AgentEntry["memorySearch"];
+  humanDelay?: AgentEntry["humanDelay"];
+  heartbeat?: AgentEntry["heartbeat"];
+  identity?: AgentEntry["identity"];
+  groupChat?: AgentEntry["groupChat"];
+  subagents?: AgentEntry["subagents"];
+  sandbox?: AgentEntry["sandbox"];
+  tools?: AgentEntry["tools"];
+};
+
+let defaultAgentWarned = false;
+
+function listAgents(cfg: OpenClawConfig): AgentEntry[] {
+  const list = cfg.agents?.list;
+  if (!Array.isArray(list)) {
+    return [];
+  }
+  return list.filter((entry): entry is AgentEntry => Boolean(entry && typeof entry === "object"));
+}
+
+export function listAgentIds(cfg: OpenClawConfig): string[] {
+  const agents = listAgents(cfg);
+  if (agents.length === 0) {
+    return [DEFAULT_AGENT_ID];
+  }
+  const seen = new Set<string>();
+  const ids: string[] = [];
+  for (const entry of agents) {
+    const id = normalizeAgentId(entry?.id);
+    if (seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids.length > 0 ? ids : [DEFAULT_AGENT_ID];
+}
+
+export function resolveDefaultAgentId(cfg: OpenClawConfig): string {
+  const agents = listAgents(cfg);
+  if (agents.length === 0) {
+    return DEFAULT_AGENT_ID;
+  }
+  const defaults = agents.filter((agent) => agent?.default);
+  if (defaults.length > 1 && !defaultAgentWarned) {
+    defaultAgentWarned = true;
+    console.warn("Multiple agents marked default=true; using the first entry as default.");
+  }
+  const chosen = (defaults[0] ?? agents[0])?.id?.trim();
+  return normalizeAgentId(chosen || DEFAULT_AGENT_ID);
+}
+
+export function resolveSessionAgentIds(params: { sessionKey?: string; config?: OpenClawConfig }): {
+  defaultAgentId: string;
+  sessionAgentId: string;
+} {
+  const defaultAgentId = resolveDefaultAgentId(params.config ?? {});
+  const sessionKey = params.sessionKey?.trim();
+  const normalizedSessionKey = sessionKey ? sessionKey.toLowerCase() : undefined;
+  const parsed = normalizedSessionKey ? parseAgentSessionKey(normalizedSessionKey) : null;
+  const sessionAgentId = parsed?.agentId ? normalizeAgentId(parsed.agentId) : defaultAgentId;
+  return { defaultAgentId, sessionAgentId };
+}
+
+export function resolveSessionAgentId(params: {
+  sessionKey?: string;
+  config?: OpenClawConfig;
+}): string {
+  return resolveSessionAgentIds(params).sessionAgentId;
+}
+
+function resolveAgentEntry(cfg: OpenClawConfig, agentId: string): AgentEntry | undefined {
+  const id = normalizeAgentId(agentId);
+  return listAgents(cfg).find((entry) => normalizeAgentId(entry.id) === id);
+}
+
+export function resolveAgentConfig(
+  cfg: OpenClawConfig,
+  agentId: string,
+): ResolvedAgentConfig | undefined {
+  const id = normalizeAgentId(agentId);
+  const entry = resolveAgentEntry(cfg, id);
+  if (!entry) {
+    return undefined;
+  }
+  return {
+    name: typeof entry.name === "string" ? entry.name : undefined,
+    workspace: typeof entry.workspace === "string" ? entry.workspace : undefined,
+    agentDir: typeof entry.agentDir === "string" ? entry.agentDir : undefined,
+    model:
+      typeof entry.model === "string" || (entry.model && typeof entry.model === "object")
+        ? entry.model
+        : undefined,
+    memorySearch: entry.memorySearch,
+    humanDelay: entry.humanDelay,
+    heartbeat: entry.heartbeat,
+    identity: entry.identity,
+    groupChat: entry.groupChat,
+    subagents: typeof entry.subagents === "object" && entry.subagents ? entry.subagents : undefined,
+    sandbox: entry.sandbox,
+    tools: entry.tools,
+  };
+}
+
+export function resolveAgentModelPrimary(cfg: OpenClawConfig, agentId: string): string | undefined {
+  const raw = resolveAgentConfig(cfg, agentId)?.model;
+  if (!raw) {
+    return undefined;
+  }
+  if (typeof raw === "string") {
+    return raw.trim() || undefined;
+  }
+  const primary = raw.primary?.trim();
+  return primary || undefined;
+}
+
+export function resolveAgentModelFallbacksOverride(
+  cfg: OpenClawConfig,
+  agentId: string,
+): string[] | undefined {
+  const raw = resolveAgentConfig(cfg, agentId)?.model;
+  if (!raw || typeof raw === "string") {
+    return undefined;
+  }
+  // Important: treat an explicitly provided empty array as an override to disable global fallbacks.
+  if (!Object.hasOwn(raw, "fallbacks")) {
+    return undefined;
+  }
+  return Array.isArray(raw.fallbacks) ? raw.fallbacks : undefined;
+}
+
+export function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string) {
+  const id = normalizeAgentId(agentId);
+  const configured = resolveAgentConfig(cfg, id)?.workspace?.trim();
+  if (configured) {
+    return resolveUserPath(configured);
+  }
+  const defaultAgentId = resolveDefaultAgentId(cfg);
+  if (id === defaultAgentId) {
+    const fallback = cfg.agents?.defaults?.workspace?.trim();
+    if (fallback) {
+      return resolveUserPath(fallback);
+    }
+    return DEFAULT_AGENT_WORKSPACE_DIR;
+  }
+  return path.join(os.homedir(), ".openclaw", `workspace-${id}`);
+}
+
+export function resolveAgentDir(cfg: OpenClawConfig, agentId: string) {
+  const id = normalizeAgentId(agentId);
+  const configured = resolveAgentConfig(cfg, id)?.agentDir?.trim();
+  if (configured) {
+    return resolveUserPath(configured);
+  }
+  const root = resolveStateDir(process.env, os.homedir);
+  return path.join(root, "agents", id, "agent");
+}

src/agents/anthropic-payload-log.ts

@@ -0,0 +1,229 @@
+import type { AgentMessage, StreamFn } from "@mariozechner/pi-agent-core";
+import type { Api, Model } from "@mariozechner/pi-ai";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { resolveUserPath } from "../utils.js";
+import { parseBooleanValue } from "../utils/boolean.js";
+
+type PayloadLogStage = "request" | "usage";
+
+type PayloadLogEvent = {
+  ts: string;
+  stage: PayloadLogStage;
+  runId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  provider?: string;
+  modelId?: string;
+  modelApi?: string | null;
+  workspaceDir?: string;
+  payload?: unknown;
+  usage?: Record<string, unknown>;
+  error?: string;
+  payloadDigest?: string;
+};
+
+type PayloadLogConfig = {
+  enabled: boolean;
+  filePath: string;
+};
+
+type PayloadLogWriter = {
+  filePath: string;
+  write: (line: string) => void;
+};
+
+const writers = new Map<string, PayloadLogWriter>();
+const log = createSubsystemLogger("agent/anthropic-payload");
+
+function resolvePayloadLogConfig(env: NodeJS.ProcessEnv): PayloadLogConfig {
+  const enabled = parseBooleanValue(env.OPENCLAW_ANTHROPIC_PAYLOAD_LOG) ?? false;
+  const fileOverride = env.OPENCLAW_ANTHROPIC_PAYLOAD_LOG_FILE?.trim();
+  const filePath = fileOverride
+    ? resolveUserPath(fileOverride)
+    : path.join(resolveStateDir(env), "logs", "anthropic-payload.jsonl");
+  return { enabled, filePath };
+}
+
+function getWriter(filePath: string): PayloadLogWriter {
+  const existing = writers.get(filePath);
+  if (existing) {
+    return existing;
+  }
+
+  const dir = path.dirname(filePath);
+  const ready = fs.mkdir(dir, { recursive: true }).catch(() => undefined);
+  let queue = Promise.resolve();
+
+  const writer: PayloadLogWriter = {
+    filePath,
+    write: (line: string) => {
+      queue = queue
+        .then(() => ready)
+        .then(() => fs.appendFile(filePath, line, "utf8"))
+        .catch(() => undefined);
+    },
+  };
+
+  writers.set(filePath, writer);
+  return writer;
+}
+
+function safeJsonStringify(value: unknown): string | null {
+  try {
+    return JSON.stringify(value, (_key, val) => {
+      if (typeof val === "bigint") {
+        return val.toString();
+      }
+      if (typeof val === "function") {
+        return "[Function]";
+      }
+      if (val instanceof Error) {
+        return { name: val.name, message: val.message, stack: val.stack };
+      }
+      if (val instanceof Uint8Array) {
+        return { type: "Uint8Array", data: Buffer.from(val).toString("base64") };
+      }
+      return val;
+    });
+  } catch {
+    return null;
+  }
+}
+
+function formatError(error: unknown): string | undefined {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") {
+    return String(error);
+  }
+  if (error && typeof error === "object") {
+    return safeJsonStringify(error) ?? "unknown error";
+  }
+  return undefined;
+}
+
+function digest(value: unknown): string | undefined {
+  const serialized = safeJsonStringify(value);
+  if (!serialized) {
+    return undefined;
+  }
+  return crypto.createHash("sha256").update(serialized).digest("hex");
+}
+
+function isAnthropicModel(model: Model<Api> | undefined | null): boolean {
+  return (model as { api?: unknown })?.api === "anthropic-messages";
+}
+
+function findLastAssistantUsage(messages: AgentMessage[]): Record<string, unknown> | null {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const msg = messages[i] as { role?: unknown; usage?: unknown };
+    if (msg?.role === "assistant" && msg.usage && typeof msg.usage === "object") {
+      return msg.usage as Record<string, unknown>;
+    }
+  }
+  return null;
+}
+
+export type AnthropicPayloadLogger = {
+  enabled: true;
+  wrapStreamFn: (streamFn: StreamFn) => StreamFn;
+  recordUsage: (messages: AgentMessage[], error?: unknown) => void;
+};
+
+export function createAnthropicPayloadLogger(params: {
+  env?: NodeJS.ProcessEnv;
+  runId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  provider?: string;
+  modelId?: string;
+  modelApi?: string | null;
+  workspaceDir?: string;
+}): AnthropicPayloadLogger | null {
+  const env = params.env ?? process.env;
+  const cfg = resolvePayloadLogConfig(env);
+  if (!cfg.enabled) {
+    return null;
+  }
+
+  const writer = getWriter(cfg.filePath);
+  const base: Omit<PayloadLogEvent, "ts" | "stage"> = {
+    runId: params.runId,
+    sessionId: params.sessionId,
+    sessionKey: params.sessionKey,
+    provider: params.provider,
+    modelId: params.modelId,
+    modelApi: params.modelApi,
+    workspaceDir: params.workspaceDir,
+  };
+
+  const record = (event: PayloadLogEvent) => {
+    const line = safeJsonStringify(event);
+    if (!line) {
+      return;
+    }
+    writer.write(`${line}\n`);
+  };
+
+  const wrapStreamFn: AnthropicPayloadLogger["wrapStreamFn"] = (streamFn) => {
+    const wrapped: StreamFn = (model, context, options) => {
+      if (!isAnthropicModel(model)) {
+        return streamFn(model, context, options);
+      }
+      const nextOnPayload = (payload: unknown) => {
+        record({
+          ...base,
+          ts: new Date().toISOString(),
+          stage: "request",
+          payload,
+          payloadDigest: digest(payload),
+        });
+        options?.onPayload?.(payload);
+      };
+      return streamFn(model, context, {
+        ...options,
+        onPayload: nextOnPayload,
+      });
+    };
+    return wrapped;
+  };
+
+  const recordUsage: AnthropicPayloadLogger["recordUsage"] = (messages, error) => {
+    const usage = findLastAssistantUsage(messages);
+    const errorMessage = formatError(error);
+    if (!usage) {
+      if (errorMessage) {
+        record({
+          ...base,
+          ts: new Date().toISOString(),
+          stage: "usage",
+          error: errorMessage,
+        });
+      }
+      return;
+    }
+    record({
+      ...base,
+      ts: new Date().toISOString(),
+      stage: "usage",
+      usage,
+      error: errorMessage,
+    });
+    log.info("anthropic usage", {
+      runId: params.runId,
+      sessionId: params.sessionId,
+      usage,
+    });
+  };
+
+  log.info("anthropic payload logger enabled", { filePath: writer.filePath });
+  return { enabled: true, wrapStreamFn, recordUsage };
+}

src/agents/anthropic.setup-token.live.test.ts

@@ -0,0 +1,226 @@
+import { type Api, completeSimple, type Model } from "@mariozechner/pi-ai";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  ANTHROPIC_SETUP_TOKEN_PREFIX,
+  validateAnthropicSetupToken,
+} from "../commands/auth-token.js";
+import { loadConfig } from "../config/config.js";
+import { isTruthyEnvValue } from "../infra/env.js";
+import { resolveOpenClawAgentDir } from "./agent-paths.js";
+import {
+  type AuthProfileCredential,
+  ensureAuthProfileStore,
+  saveAuthProfileStore,
+} from "./auth-profiles.js";
+import { getApiKeyForModel, requireApiKey } from "./model-auth.js";
+import { normalizeProviderId, parseModelRef } from "./model-selection.js";
+import { ensureOpenClawModelsJson } from "./models-config.js";
+import { discoverAuthStorage, discoverModels } from "./pi-model-discovery.js";
+
+const LIVE = isTruthyEnvValue(process.env.LIVE) || isTruthyEnvValue(process.env.OPENCLAW_LIVE_TEST);
+const SETUP_TOKEN_RAW = process.env.OPENCLAW_LIVE_SETUP_TOKEN?.trim() ?? "";
+const SETUP_TOKEN_VALUE = process.env.OPENCLAW_LIVE_SETUP_TOKEN_VALUE?.trim() ?? "";
+const SETUP_TOKEN_PROFILE = process.env.OPENCLAW_LIVE_SETUP_TOKEN_PROFILE?.trim() ?? "";
+const SETUP_TOKEN_MODEL = process.env.OPENCLAW_LIVE_SETUP_TOKEN_MODEL?.trim() ?? "";
+
+const ENABLED = LIVE && Boolean(SETUP_TOKEN_RAW || SETUP_TOKEN_VALUE || SETUP_TOKEN_PROFILE);
+const describeLive = ENABLED ? describe : describe.skip;
+
+type TokenSource = {
+  agentDir: string;
+  profileId: string;
+  cleanup?: () => Promise<void>;
+};
+
+function isSetupToken(value: string): boolean {
+  return value.startsWith(ANTHROPIC_SETUP_TOKEN_PREFIX);
+}
+
+function listSetupTokenProfiles(store: {
+  profiles: Record<string, AuthProfileCredential>;
+}): string[] {
+  return Object.entries(store.profiles)
+    .filter(([, cred]) => {
+      if (cred.type !== "token") {
+        return false;
+      }
+      if (normalizeProviderId(cred.provider) !== "anthropic") {
+        return false;
+      }
+      return isSetupToken(cred.token);
+    })
+    .map(([id]) => id);
+}
+
+function pickSetupTokenProfile(candidates: string[]): string {
+  const preferred = ["anthropic:setup-token-test", "anthropic:setup-token", "anthropic:default"];
+  for (const id of preferred) {
+    if (candidates.includes(id)) {
+      return id;
+    }
+  }
+  return candidates[0] ?? "";
+}
+
+async function resolveTokenSource(): Promise<TokenSource> {
+  const explicitToken =
+    (SETUP_TOKEN_RAW && isSetupToken(SETUP_TOKEN_RAW) ? SETUP_TOKEN_RAW : "") || SETUP_TOKEN_VALUE;
+
+  if (explicitToken) {
+    const error = validateAnthropicSetupToken(explicitToken);
+    if (error) {
+      throw new Error(`Invalid setup-token: ${error}`);
+    }
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-setup-token-"));
+    const profileId = `anthropic:setup-token-live-${randomUUID()}`;
+    const store = ensureAuthProfileStore(tempDir, {
+      allowKeychainPrompt: false,
+    });
+    store.profiles[profileId] = {
+      type: "token",
+      provider: "anthropic",
+      token: explicitToken,
+    };
+    saveAuthProfileStore(store, tempDir);
+    return {
+      agentDir: tempDir,
+      profileId,
+      cleanup: async () => {
+        await fs.rm(tempDir, { recursive: true, force: true });
+      },
+    };
+  }
+
+  const agentDir = resolveOpenClawAgentDir();
+  const store = ensureAuthProfileStore(agentDir, {
+    allowKeychainPrompt: false,
+  });
+
+  const candidates = listSetupTokenProfiles(store);
+  if (SETUP_TOKEN_PROFILE) {
+    if (!candidates.includes(SETUP_TOKEN_PROFILE)) {
+      const available = candidates.length > 0 ? candidates.join(", ") : "(none)";
+      throw new Error(
+        `Setup-token profile "${SETUP_TOKEN_PROFILE}" not found. Available: ${available}.`,
+      );
+    }
+    return { agentDir, profileId: SETUP_TOKEN_PROFILE };
+  }
+
+  if (SETUP_TOKEN_RAW && SETUP_TOKEN_RAW !== "1" && SETUP_TOKEN_RAW !== "auto") {
+    throw new Error(
+      "OPENCLAW_LIVE_SETUP_TOKEN did not look like a setup-token. Use OPENCLAW_LIVE_SETUP_TOKEN_VALUE for raw tokens.",
+    );
+  }
+
+  if (candidates.length === 0) {
+    throw new Error(
+      "No Anthropics setup-token profiles found. Set OPENCLAW_LIVE_SETUP_TOKEN_VALUE or OPENCLAW_LIVE_SETUP_TOKEN_PROFILE.",
+    );
+  }
+  return { agentDir, profileId: pickSetupTokenProfile(candidates) };
+}
+
+function pickModel(models: Array<Model<Api>>, raw?: string): Model<Api> | null {
+  const normalized = raw?.trim() ?? "";
+  if (normalized) {
+    const parsed = parseModelRef(normalized, "anthropic");
+    if (!parsed) {
+      return null;
+    }
+    return (
+      models.find(
+        (model) =>
+          normalizeProviderId(model.provider) === parsed.provider && model.id === parsed.model,
+      ) ?? null
+    );
+  }
+
+  const preferred = [
+    "claude-opus-4-5",
+    "claude-sonnet-4-5",
+    "claude-sonnet-4-0",
+    "claude-haiku-3-5",
+  ];
+  for (const id of preferred) {
+    const match = models.find((model) => model.id === id);
+    if (match) {
+      return match;
+    }
+  }
+  return models[0] ?? null;
+}
+
+describeLive("live anthropic setup-token", () => {
+  it(
+    "completes using a setup-token profile",
+    async () => {
+      const tokenSource = await resolveTokenSource();
+      try {
+        const cfg = loadConfig();
+        await ensureOpenClawModelsJson(cfg, tokenSource.agentDir);
+
+        const authStorage = discoverAuthStorage(tokenSource.agentDir);
+        const modelRegistry = discoverModels(authStorage, tokenSource.agentDir);
+        const all = Array.isArray(modelRegistry) ? modelRegistry : modelRegistry.getAll();
+        const candidates = all.filter(
+          (model) => normalizeProviderId(model.provider) === "anthropic",
+        ) as Array<Model<Api>>;
+        expect(candidates.length).toBeGreaterThan(0);
+
+        const model = pickModel(candidates, SETUP_TOKEN_MODEL);
+        if (!model) {
+          throw new Error(
+            SETUP_TOKEN_MODEL
+              ? `Model not found: ${SETUP_TOKEN_MODEL}`
+              : "No Anthropic models available.",
+          );
+        }
+
+        const apiKeyInfo = await getApiKeyForModel({
+          model,
+          cfg,
+          profileId: tokenSource.profileId,
+          agentDir: tokenSource.agentDir,
+        });
+        const apiKey = requireApiKey(apiKeyInfo, model.provider);
+        const tokenError = validateAnthropicSetupToken(apiKey);
+        if (tokenError) {
+          throw new Error(`Resolved profile is not a setup-token: ${tokenError}`);
+        }
+
+        const res = await completeSimple(
+          model,
+          {
+            messages: [
+              {
+                role: "user",
+                content: "Reply with the word ok.",
+                timestamp: Date.now(),
+              },
+            ],
+          },
+          {
+            apiKey,
+            maxTokens: 64,
+            temperature: 0,
+          },
+        );
+        const text = res.content
+          .filter((block) => block.type === "text")
+          .map((block) => block.text.trim())
+          .join(" ");
+        expect(text.toLowerCase()).toContain("ok");
+      } finally {
+        if (tokenSource.cleanup) {
+          await tokenSource.cleanup();
+        }
+      }
+    },
+    5 * 60 * 1000,
+  );
+});

src/agents/apply-patch-update.ts

@@ -0,0 +1,199 @@
+import fs from "node:fs/promises";
+
+type UpdateFileChunk = {
+  changeContext?: string;
+  oldLines: string[];
+  newLines: string[];
+  isEndOfFile: boolean;
+};
+
+export async function applyUpdateHunk(
+  filePath: string,
+  chunks: UpdateFileChunk[],
+): Promise<string> {
+  const originalContents = await fs.readFile(filePath, "utf8").catch((err) => {
+    throw new Error(`Failed to read file to update ${filePath}: ${err}`);
+  });
+
+  const originalLines = originalContents.split("\n");
+  if (originalLines.length > 0 && originalLines[originalLines.length - 1] === "") {
+    originalLines.pop();
+  }
+
+  const replacements = computeReplacements(originalLines, filePath, chunks);
+  let newLines = applyReplacements(originalLines, replacements);
+  if (newLines.length === 0 || newLines[newLines.length - 1] !== "") {
+    newLines = [...newLines, ""];
+  }
+  return newLines.join("\n");
+}
+
+function computeReplacements(
+  originalLines: string[],
+  filePath: string,
+  chunks: UpdateFileChunk[],
+): Array<[number, number, string[]]> {
+  const replacements: Array<[number, number, string[]]> = [];
+  let lineIndex = 0;
+
+  for (const chunk of chunks) {
+    if (chunk.changeContext) {
+      const ctxIndex = seekSequence(originalLines, [chunk.changeContext], lineIndex, false);
+      if (ctxIndex === null) {
+        throw new Error(`Failed to find context '${chunk.changeContext}' in ${filePath}`);
+      }
+      lineIndex = ctxIndex + 1;
+    }
+
+    if (chunk.oldLines.length === 0) {
+      const insertionIndex =
+        originalLines.length > 0 && originalLines[originalLines.length - 1] === ""
+          ? originalLines.length - 1
+          : originalLines.length;
+      replacements.push([insertionIndex, 0, chunk.newLines]);
+      continue;
+    }
+
+    let pattern = chunk.oldLines;
+    let newSlice = chunk.newLines;
+    let found = seekSequence(originalLines, pattern, lineIndex, chunk.isEndOfFile);
+
+    if (found === null && pattern[pattern.length - 1] === "") {
+      pattern = pattern.slice(0, -1);
+      if (newSlice.length > 0 && newSlice[newSlice.length - 1] === "") {
+        newSlice = newSlice.slice(0, -1);
+      }
+      found = seekSequence(originalLines, pattern, lineIndex, chunk.isEndOfFile);
+    }
+
+    if (found === null) {
+      throw new Error(
+        `Failed to find expected lines in ${filePath}:\n${chunk.oldLines.join("\n")}`,
+      );
+    }
+
+    replacements.push([found, pattern.length, newSlice]);
+    lineIndex = found + pattern.length;
+  }
+
+  replacements.sort((a, b) => a[0] - b[0]);
+  return replacements;
+}
+
+function applyReplacements(
+  lines: string[],
+  replacements: Array<[number, number, string[]]>,
+): string[] {
+  const result = [...lines];
+  for (const [startIndex, oldLen, newLines] of [...replacements].toReversed()) {
+    for (let i = 0; i < oldLen; i += 1) {
+      if (startIndex < result.length) {
+        result.splice(startIndex, 1);
+      }
+    }
+    for (let i = 0; i < newLines.length; i += 1) {
+      result.splice(startIndex + i, 0, newLines[i]);
+    }
+  }
+  return result;
+}
+
+function seekSequence(
+  lines: string[],
+  pattern: string[],
+  start: number,
+  eof: boolean,
+): number | null {
+  if (pattern.length === 0) {
+    return start;
+  }
+  if (pattern.length > lines.length) {
+    return null;
+  }
+
+  const maxStart = lines.length - pattern.length;
+  const searchStart = eof && lines.length >= pattern.length ? maxStart : start;
+  if (searchStart > maxStart) {
+    return null;
+  }
+
+  for (let i = searchStart; i <= maxStart; i += 1) {
+    if (linesMatch(lines, pattern, i, (value) => value)) {
+      return i;
+    }
+  }
+  for (let i = searchStart; i <= maxStart; i += 1) {
+    if (linesMatch(lines, pattern, i, (value) => value.trimEnd())) {
+      return i;
+    }
+  }
+  for (let i = searchStart; i <= maxStart; i += 1) {
+    if (linesMatch(lines, pattern, i, (value) => value.trim())) {
+      return i;
+    }
+  }
+  for (let i = searchStart; i <= maxStart; i += 1) {
+    if (linesMatch(lines, pattern, i, (value) => normalizePunctuation(value.trim()))) {
+      return i;
+    }
+  }
+
+  return null;
+}
+
+function linesMatch(
+  lines: string[],
+  pattern: string[],
+  start: number,
+  normalize: (value: string) => string,
+): boolean {
+  for (let idx = 0; idx < pattern.length; idx += 1) {
+    if (normalize(lines[start + idx]) !== normalize(pattern[idx])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function normalizePunctuation(value: string): string {
+  return Array.from(value)
+    .map((char) => {
+      switch (char) {
+        case "\u2010":
+        case "\u2011":
+        case "\u2012":
+        case "\u2013":
+        case "\u2014":
+        case "\u2015":
+        case "\u2212":
+          return "-";
+        case "\u2018":
+        case "\u2019":
+        case "\u201A":
+        case "\u201B":
+          return "'";
+        case "\u201C":
+        case "\u201D":
+        case "\u201E":
+        case "\u201F":
+          return '"';
+        case "\u00A0":
+        case "\u2002":
+        case "\u2003":
+        case "\u2004":
+        case "\u2005":
+        case "\u2006":
+        case "\u2007":
+        case "\u2008":
+        case "\u2009":
+        case "\u200A":
+        case "\u202F":
+        case "\u205F":
+        case "\u3000":
+          return " ";
+        default:
+          return char;
+      }
+    })
+    .join("");
+}

src/agents/apply-patch.test.ts

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { applyPatch } from "./apply-patch.js";
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-patch-"));
+  try {
+    return await fn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("applyPatch", () => {
+  it("adds a file", async () => {
+    await withTempDir(async (dir) => {
+      const patch = `*** Begin Patch
+*** Add File: hello.txt
++hello
+*** End Patch`;
+
+      const result = await applyPatch(patch, { cwd: dir });
+      const contents = await fs.readFile(path.join(dir, "hello.txt"), "utf8");
+
+      expect(contents).toBe("hello\n");
+      expect(result.summary.added).toEqual(["hello.txt"]);
+    });
+  });
+
+  it("updates and moves a file", async () => {
+    await withTempDir(async (dir) => {
+      const source = path.join(dir, "source.txt");
+      await fs.writeFile(source, "foo\nbar\n", "utf8");
+
+      const patch = `*** Begin Patch
+*** Update File: source.txt
+*** Move to: dest.txt
+@@
+ foo
+-bar
++baz
+*** End Patch`;
+
+      const result = await applyPatch(patch, { cwd: dir });
+      const dest = path.join(dir, "dest.txt");
+      const contents = await fs.readFile(dest, "utf8");
+
+      expect(contents).toBe("foo\nbaz\n");
+      await expect(fs.stat(source)).rejects.toBeDefined();
+      expect(result.summary.modified).toEqual(["dest.txt"]);
+    });
+  });
+
+  it("supports end-of-file inserts", async () => {
+    await withTempDir(async (dir) => {
+      const target = path.join(dir, "end.txt");
+      await fs.writeFile(target, "line1\n", "utf8");
+
+      const patch = `*** Begin Patch
+*** Update File: end.txt
+@@
++line2
+*** End of File
+*** End Patch`;
+
+      await applyPatch(patch, { cwd: dir });
+      const contents = await fs.readFile(target, "utf8");
+      expect(contents).toBe("line1\nline2\n");
+    });
+  });
+});

src/agents/apply-patch.ts

@@ -0,0 +1,503 @@
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { applyUpdateHunk } from "./apply-patch-update.js";
+import { assertSandboxPath } from "./sandbox-paths.js";
+
+const BEGIN_PATCH_MARKER = "*** Begin Patch";
+const END_PATCH_MARKER = "*** End Patch";
+const ADD_FILE_MARKER = "*** Add File: ";
+const DELETE_FILE_MARKER = "*** Delete File: ";
+const UPDATE_FILE_MARKER = "*** Update File: ";
+const MOVE_TO_MARKER = "*** Move to: ";
+const EOF_MARKER = "*** End of File";
+const CHANGE_CONTEXT_MARKER = "@@ ";
+const EMPTY_CHANGE_CONTEXT_MARKER = "@@";
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+type AddFileHunk = {
+  kind: "add";
+  path: string;
+  contents: string;
+};
+
+type DeleteFileHunk = {
+  kind: "delete";
+  path: string;
+};
+
+type UpdateFileChunk = {
+  changeContext?: string;
+  oldLines: string[];
+  newLines: string[];
+  isEndOfFile: boolean;
+};
+
+type UpdateFileHunk = {
+  kind: "update";
+  path: string;
+  movePath?: string;
+  chunks: UpdateFileChunk[];
+};
+
+type Hunk = AddFileHunk | DeleteFileHunk | UpdateFileHunk;
+
+export type ApplyPatchSummary = {
+  added: string[];
+  modified: string[];
+  deleted: string[];
+};
+
+export type ApplyPatchResult = {
+  summary: ApplyPatchSummary;
+  text: string;
+};
+
+export type ApplyPatchToolDetails = {
+  summary: ApplyPatchSummary;
+};
+
+type ApplyPatchOptions = {
+  cwd: string;
+  sandboxRoot?: string;
+  signal?: AbortSignal;
+};
+
+const applyPatchSchema = Type.Object({
+  input: Type.String({
+    description: "Patch content using the *** Begin Patch/End Patch format.",
+  }),
+});
+
+export function createApplyPatchTool(
+  options: { cwd?: string; sandboxRoot?: string } = {},
+  // biome-ignore lint/suspicious/noExplicitAny: TypeBox schema type from pi-agent-core uses a different module instance.
+): AgentTool<any, ApplyPatchToolDetails> {
+  const cwd = options.cwd ?? process.cwd();
+  const sandboxRoot = options.sandboxRoot;
+
+  return {
+    name: "apply_patch",
+    label: "apply_patch",
+    description:
+      "Apply a patch to one or more files using the apply_patch format. The input should include *** Begin Patch and *** End Patch markers.",
+    parameters: applyPatchSchema,
+    execute: async (_toolCallId, args, signal) => {
+      const params = args as { input?: string };
+      const input = typeof params.input === "string" ? params.input : "";
+      if (!input.trim()) {
+        throw new Error("Provide a patch input.");
+      }
+      if (signal?.aborted) {
+        const err = new Error("Aborted");
+        err.name = "AbortError";
+        throw err;
+      }
+
+      const result = await applyPatch(input, {
+        cwd,
+        sandboxRoot,
+        signal,
+      });
+
+      return {
+        content: [{ type: "text", text: result.text }],
+        details: { summary: result.summary },
+      };
+    },
+  };
+}
+
+export async function applyPatch(
+  input: string,
+  options: ApplyPatchOptions,
+): Promise<ApplyPatchResult> {
+  const parsed = parsePatchText(input);
+  if (parsed.hunks.length === 0) {
+    throw new Error("No files were modified.");
+  }
+
+  const summary: ApplyPatchSummary = {
+    added: [],
+    modified: [],
+    deleted: [],
+  };
+  const seen = {
+    added: new Set<string>(),
+    modified: new Set<string>(),
+    deleted: new Set<string>(),
+  };
+
+  for (const hunk of parsed.hunks) {
+    if (options.signal?.aborted) {
+      const err = new Error("Aborted");
+      err.name = "AbortError";
+      throw err;
+    }
+
+    if (hunk.kind === "add") {
+      const target = await resolvePatchPath(hunk.path, options);
+      await ensureDir(target.resolved);
+      await fs.writeFile(target.resolved, hunk.contents, "utf8");
+      recordSummary(summary, seen, "added", target.display);
+      continue;
+    }
+
+    if (hunk.kind === "delete") {
+      const target = await resolvePatchPath(hunk.path, options);
+      await fs.rm(target.resolved);
+      recordSummary(summary, seen, "deleted", target.display);
+      continue;
+    }
+
+    const target = await resolvePatchPath(hunk.path, options);
+    const applied = await applyUpdateHunk(target.resolved, hunk.chunks);
+
+    if (hunk.movePath) {
+      const moveTarget = await resolvePatchPath(hunk.movePath, options);
+      await ensureDir(moveTarget.resolved);
+      await fs.writeFile(moveTarget.resolved, applied, "utf8");
+      await fs.rm(target.resolved);
+      recordSummary(summary, seen, "modified", moveTarget.display);
+    } else {
+      await fs.writeFile(target.resolved, applied, "utf8");
+      recordSummary(summary, seen, "modified", target.display);
+    }
+  }
+
+  return {
+    summary,
+    text: formatSummary(summary),
+  };
+}
+
+function recordSummary(
+  summary: ApplyPatchSummary,
+  seen: {
+    added: Set<string>;
+    modified: Set<string>;
+    deleted: Set<string>;
+  },
+  bucket: keyof ApplyPatchSummary,
+  value: string,
+) {
+  if (seen[bucket].has(value)) {
+    return;
+  }
+  seen[bucket].add(value);
+  summary[bucket].push(value);
+}
+
+function formatSummary(summary: ApplyPatchSummary): string {
+  const lines = ["Success. Updated the following files:"];
+  for (const file of summary.added) {
+    lines.push(`A ${file}`);
+  }
+  for (const file of summary.modified) {
+    lines.push(`M ${file}`);
+  }
+  for (const file of summary.deleted) {
+    lines.push(`D ${file}`);
+  }
+  return lines.join("\n");
+}
+
+async function ensureDir(filePath: string) {
+  const parent = path.dirname(filePath);
+  if (!parent || parent === ".") {
+    return;
+  }
+  await fs.mkdir(parent, { recursive: true });
+}
+
+async function resolvePatchPath(
+  filePath: string,
+  options: ApplyPatchOptions,
+): Promise<{ resolved: string; display: string }> {
+  if (options.sandboxRoot) {
+    const resolved = await assertSandboxPath({
+      filePath,
+      cwd: options.cwd,
+      root: options.sandboxRoot,
+    });
+    return {
+      resolved: resolved.resolved,
+      display: resolved.relative || resolved.resolved,
+    };
+  }
+
+  const resolved = resolvePathFromCwd(filePath, options.cwd);
+  return {
+    resolved,
+    display: toDisplayPath(resolved, options.cwd),
+  };
+}
+
+function normalizeUnicodeSpaces(value: string): string {
+  return value.replace(UNICODE_SPACES, " ");
+}
+
+function expandPath(filePath: string): string {
+  const normalized = normalizeUnicodeSpaces(filePath);
+  if (normalized === "~") {
+    return os.homedir();
+  }
+  if (normalized.startsWith("~/")) {
+    return os.homedir() + normalized.slice(1);
+  }
+  return normalized;
+}
+
+function resolvePathFromCwd(filePath: string, cwd: string): string {
+  const expanded = expandPath(filePath);
+  if (path.isAbsolute(expanded)) {
+    return path.normalize(expanded);
+  }
+  return path.resolve(cwd, expanded);
+}
+
+function toDisplayPath(resolved: string, cwd: string): string {
+  const relative = path.relative(cwd, resolved);
+  if (!relative || relative === "") {
+    return path.basename(resolved);
+  }
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return resolved;
+  }
+  return relative;
+}
+
+function parsePatchText(input: string): { hunks: Hunk[]; patch: string } {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("Invalid patch: input is empty.");
+  }
+
+  const lines = trimmed.split(/\r?\n/);
+  const validated = checkPatchBoundariesLenient(lines);
+  const hunks: Hunk[] = [];
+
+  const lastLineIndex = validated.length - 1;
+  let remaining = validated.slice(1, lastLineIndex);
+  let lineNumber = 2;
+
+  while (remaining.length > 0) {
+    const { hunk, consumed } = parseOneHunk(remaining, lineNumber);
+    hunks.push(hunk);
+    lineNumber += consumed;
+    remaining = remaining.slice(consumed);
+  }
+
+  return { hunks, patch: validated.join("\n") };
+}
+
+function checkPatchBoundariesLenient(lines: string[]): string[] {
+  const strictError = checkPatchBoundariesStrict(lines);
+  if (!strictError) {
+    return lines;
+  }
+
+  if (lines.length < 4) {
+    throw new Error(strictError);
+  }
+  const first = lines[0];
+  const last = lines[lines.length - 1];
+  if ((first === "<<EOF" || first === "<<'EOF'" || first === '<<"EOF"') && last.endsWith("EOF")) {
+    const inner = lines.slice(1, lines.length - 1);
+    const innerError = checkPatchBoundariesStrict(inner);
+    if (!innerError) {
+      return inner;
+    }
+    throw new Error(innerError);
+  }
+
+  throw new Error(strictError);
+}
+
+function checkPatchBoundariesStrict(lines: string[]): string | null {
+  const firstLine = lines[0]?.trim();
+  const lastLine = lines[lines.length - 1]?.trim();
+
+  if (firstLine === BEGIN_PATCH_MARKER && lastLine === END_PATCH_MARKER) {
+    return null;
+  }
+  if (firstLine !== BEGIN_PATCH_MARKER) {
+    return "The first line of the patch must be '*** Begin Patch'";
+  }
+  return "The last line of the patch must be '*** End Patch'";
+}
+
+function parseOneHunk(lines: string[], lineNumber: number): { hunk: Hunk; consumed: number } {
+  if (lines.length === 0) {
+    throw new Error(`Invalid patch hunk at line ${lineNumber}: empty hunk`);
+  }
+  const firstLine = lines[0].trim();
+  if (firstLine.startsWith(ADD_FILE_MARKER)) {
+    const targetPath = firstLine.slice(ADD_FILE_MARKER.length);
+    let contents = "";
+    let consumed = 1;
+    for (const addLine of lines.slice(1)) {
+      if (addLine.startsWith("+")) {
+        contents += `${addLine.slice(1)}\n`;
+        consumed += 1;
+      } else {
+        break;
+      }
+    }
+    return {
+      hunk: { kind: "add", path: targetPath, contents },
+      consumed,
+    };
+  }
+
+  if (firstLine.startsWith(DELETE_FILE_MARKER)) {
+    const targetPath = firstLine.slice(DELETE_FILE_MARKER.length);
+    return {
+      hunk: { kind: "delete", path: targetPath },
+      consumed: 1,
+    };
+  }
+
+  if (firstLine.startsWith(UPDATE_FILE_MARKER)) {
+    const targetPath = firstLine.slice(UPDATE_FILE_MARKER.length);
+    let remaining = lines.slice(1);
+    let consumed = 1;
+    let movePath: string | undefined;
+
+    const moveCandidate = remaining[0]?.trim();
+    if (moveCandidate?.startsWith(MOVE_TO_MARKER)) {
+      movePath = moveCandidate.slice(MOVE_TO_MARKER.length);
+      remaining = remaining.slice(1);
+      consumed += 1;
+    }
+
+    const chunks: UpdateFileChunk[] = [];
+    while (remaining.length > 0) {
+      if (remaining[0].trim() === "") {
+        remaining = remaining.slice(1);
+        consumed += 1;
+        continue;
+      }
+      if (remaining[0].startsWith("***")) {
+        break;
+      }
+      const { chunk, consumed: chunkLines } = parseUpdateFileChunk(
+        remaining,
+        lineNumber + consumed,
+        chunks.length === 0,
+      );
+      chunks.push(chunk);
+      remaining = remaining.slice(chunkLines);
+      consumed += chunkLines;
+    }
+
+    if (chunks.length === 0) {
+      throw new Error(
+        `Invalid patch hunk at line ${lineNumber}: Update file hunk for path '${targetPath}' is empty`,
+      );
+    }
+
+    return {
+      hunk: {
+        kind: "update",
+        path: targetPath,
+        movePath,
+        chunks,
+      },
+      consumed,
+    };
+  }
+
+  throw new Error(
+    `Invalid patch hunk at line ${lineNumber}: '${lines[0]}' is not a valid hunk header. Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'`,
+  );
+}
+
+function parseUpdateFileChunk(
+  lines: string[],
+  lineNumber: number,
+  allowMissingContext: boolean,
+): { chunk: UpdateFileChunk; consumed: number } {
+  if (lines.length === 0) {
+    throw new Error(
+      `Invalid patch hunk at line ${lineNumber}: Update hunk does not contain any lines`,
+    );
+  }
+
+  let changeContext: string | undefined;
+  let startIndex = 0;
+  if (lines[0] === EMPTY_CHANGE_CONTEXT_MARKER) {
+    startIndex = 1;
+  } else if (lines[0].startsWith(CHANGE_CONTEXT_MARKER)) {
+    changeContext = lines[0].slice(CHANGE_CONTEXT_MARKER.length);
+    startIndex = 1;
+  } else if (!allowMissingContext) {
+    throw new Error(
+      `Invalid patch hunk at line ${lineNumber}: Expected update hunk to start with a @@ context marker, got: '${lines[0]}'`,
+    );
+  }
+
+  if (startIndex >= lines.length) {
+    throw new Error(
+      `Invalid patch hunk at line ${lineNumber + 1}: Update hunk does not contain any lines`,
+    );
+  }
+
+  const chunk: UpdateFileChunk = {
+    changeContext,
+    oldLines: [],
+    newLines: [],
+    isEndOfFile: false,
+  };
+
+  let parsedLines = 0;
+  for (const line of lines.slice(startIndex)) {
+    if (line === EOF_MARKER) {
+      if (parsedLines === 0) {
+        throw new Error(
+          `Invalid patch hunk at line ${lineNumber + 1}: Update hunk does not contain any lines`,
+        );
+      }
+      chunk.isEndOfFile = true;
+      parsedLines += 1;
+      break;
+    }
+
+    const marker = line[0];
+    if (!marker) {
+      chunk.oldLines.push("");
+      chunk.newLines.push("");
+      parsedLines += 1;
+      continue;
+    }
+
+    if (marker === " ") {
+      const content = line.slice(1);
+      chunk.oldLines.push(content);
+      chunk.newLines.push(content);
+      parsedLines += 1;
+      continue;
+    }
+    if (marker === "+") {
+      chunk.newLines.push(line.slice(1));
+      parsedLines += 1;
+      continue;
+    }
+    if (marker === "-") {
+      chunk.oldLines.push(line.slice(1));
+      parsedLines += 1;
+      continue;
+    }
+
+    if (parsedLines === 0) {
+      throw new Error(
+        `Invalid patch hunk at line ${lineNumber + 1}: Unexpected line found in update hunk: '${line}'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)`,
+      );
+    }
+    break;
+  }
+
+  return { chunk, consumed: parsedLines + startIndex };
+}

src/agents/auth-health.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildAuthHealthSummary, DEFAULT_OAUTH_WARN_MS } from "./auth-health.js";
+
+describe("buildAuthHealthSummary", () => {
+  const now = 1_700_000_000_000;
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("classifies OAuth and API key profiles", () => {
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    const store = {
+      version: 1,
+      profiles: {
+        "anthropic:ok": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now + DEFAULT_OAUTH_WARN_MS + 60_000,
+        },
+        "anthropic:expiring": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now + 10_000,
+        },
+        "anthropic:expired": {
+          type: "oauth" as const,
+          provider: "anthropic",
+          access: "access",
+          refresh: "refresh",
+          expires: now - 10_000,
+        },
+        "anthropic:api": {
+          type: "api_key" as const,
+          provider: "anthropic",
+          key: "sk-ant-api",
+        },
+      },
+    };
+
+    const summary = buildAuthHealthSummary({
+      store,
+      warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+    });
+
+    const statuses = Object.fromEntries(
+      summary.profiles.map((profile) => [profile.profileId, profile.status]),
+    );
+
+    expect(statuses["anthropic:ok"]).toBe("ok");
+    // OAuth credentials with refresh tokens are auto-renewable, so they report "ok"
+    expect(statuses["anthropic:expiring"]).toBe("ok");
+    expect(statuses["anthropic:expired"]).toBe("ok");
+    expect(statuses["anthropic:api"]).toBe("static");
+
+    const provider = summary.providers.find((entry) => entry.provider === "anthropic");
+    expect(provider?.status).toBe("ok");
+  });
+
+  it("reports expired for OAuth without a refresh token", () => {
+    vi.spyOn(Date, "now").mockReturnValue(now);
+    const store = {
+      version: 1,
+      profiles: {
+        "google:no-refresh": {
+          type: "oauth" as const,
+          provider: "google-antigravity",
+          access: "access",
+          refresh: "",
+          expires: now - 10_000,
+        },
+      },
+    };
+
+    const summary = buildAuthHealthSummary({
+      store,
+      warnAfterMs: DEFAULT_OAUTH_WARN_MS,
+    });
+
+    const statuses = Object.fromEntries(
+      summary.profiles.map((profile) => [profile.profileId, profile.status]),
+    );
+
+    expect(statuses["google:no-refresh"]).toBe("expired");
+  });
+});

src/agents/auth-health.ts

@@ -0,0 +1,252 @@
+import type { OpenClawConfig } from "../config/config.js";
+import {
+  type AuthProfileCredential,
+  type AuthProfileStore,
+  resolveAuthProfileDisplayLabel,
+} from "./auth-profiles.js";
+
+export type AuthProfileSource = "store";
+
+export type AuthProfileHealthStatus = "ok" | "expiring" | "expired" | "missing" | "static";
+
+export type AuthProfileHealth = {
+  profileId: string;
+  provider: string;
+  type: "oauth" | "token" | "api_key";
+  status: AuthProfileHealthStatus;
+  expiresAt?: number;
+  remainingMs?: number;
+  source: AuthProfileSource;
+  label: string;
+};
+
+export type AuthProviderHealthStatus = "ok" | "expiring" | "expired" | "missing" | "static";
+
+export type AuthProviderHealth = {
+  provider: string;
+  status: AuthProviderHealthStatus;
+  expiresAt?: number;
+  remainingMs?: number;
+  profiles: AuthProfileHealth[];
+};
+
+export type AuthHealthSummary = {
+  now: number;
+  warnAfterMs: number;
+  profiles: AuthProfileHealth[];
+  providers: AuthProviderHealth[];
+};
+
+export const DEFAULT_OAUTH_WARN_MS = 24 * 60 * 60 * 1000;
+
+export function resolveAuthProfileSource(_profileId: string): AuthProfileSource {
+  return "store";
+}
+
+export function formatRemainingShort(remainingMs?: number): string {
+  if (remainingMs === undefined || Number.isNaN(remainingMs)) {
+    return "unknown";
+  }
+  if (remainingMs <= 0) {
+    return "0m";
+  }
+  const minutes = Math.max(1, Math.round(remainingMs / 60_000));
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) {
+    return `${hours}h`;
+  }
+  const days = Math.round(hours / 24);
+  return `${days}d`;
+}
+
+function resolveOAuthStatus(
+  expiresAt: number | undefined,
+  now: number,
+  warnAfterMs: number,
+): { status: AuthProfileHealthStatus; remainingMs?: number } {
+  if (!expiresAt || !Number.isFinite(expiresAt) || expiresAt <= 0) {
+    return { status: "missing" };
+  }
+  const remainingMs = expiresAt - now;
+  if (remainingMs <= 0) {
+    return { status: "expired", remainingMs };
+  }
+  if (remainingMs <= warnAfterMs) {
+    return { status: "expiring", remainingMs };
+  }
+  return { status: "ok", remainingMs };
+}
+
+function buildProfileHealth(params: {
+  profileId: string;
+  credential: AuthProfileCredential;
+  store: AuthProfileStore;
+  cfg?: OpenClawConfig;
+  now: number;
+  warnAfterMs: number;
+}): AuthProfileHealth {
+  const { profileId, credential, store, cfg, now, warnAfterMs } = params;
+  const label = resolveAuthProfileDisplayLabel({ cfg, store, profileId });
+  const source = resolveAuthProfileSource(profileId);
+
+  if (credential.type === "api_key") {
+    return {
+      profileId,
+      provider: credential.provider,
+      type: "api_key",
+      status: "static",
+      source,
+      label,
+    };
+  }
+
+  if (credential.type === "token") {
+    const expiresAt =
+      typeof credential.expires === "number" && Number.isFinite(credential.expires)
+        ? credential.expires
+        : undefined;
+    if (!expiresAt || expiresAt <= 0) {
+      return {
+        profileId,
+        provider: credential.provider,
+        type: "token",
+        status: "static",
+        source,
+        label,
+      };
+    }
+    const { status, remainingMs } = resolveOAuthStatus(expiresAt, now, warnAfterMs);
+    return {
+      profileId,
+      provider: credential.provider,
+      type: "token",
+      status,
+      expiresAt,
+      remainingMs,
+      source,
+      label,
+    };
+  }
+
+  const hasRefreshToken = typeof credential.refresh === "string" && credential.refresh.length > 0;
+  const { status: rawStatus, remainingMs } = resolveOAuthStatus(
+    credential.expires,
+    now,
+    warnAfterMs,
+  );
+  // OAuth credentials with a valid refresh token auto-renew on first API call,
+  // so don't warn about access token expiration.
+  const status =
+    hasRefreshToken && (rawStatus === "expired" || rawStatus === "expiring") ? "ok" : rawStatus;
+  return {
+    profileId,
+    provider: credential.provider,
+    type: "oauth",
+    status,
+    expiresAt: credential.expires,
+    remainingMs,
+    source,
+    label,
+  };
+}
+
+export function buildAuthHealthSummary(params: {
+  store: AuthProfileStore;
+  cfg?: OpenClawConfig;
+  warnAfterMs?: number;
+  providers?: string[];
+}): AuthHealthSummary {
+  const now = Date.now();
+  const warnAfterMs = params.warnAfterMs ?? DEFAULT_OAUTH_WARN_MS;
+  const providerFilter = params.providers
+    ? new Set(params.providers.map((p) => p.trim()).filter(Boolean))
+    : null;
+
+  const profiles = Object.entries(params.store.profiles)
+    .filter(([_, cred]) => (providerFilter ? providerFilter.has(cred.provider) : true))
+    .map(([profileId, credential]) =>
+      buildProfileHealth({
+        profileId,
+        credential,
+        store: params.store,
+        cfg: params.cfg,
+        now,
+        warnAfterMs,
+      }),
+    )
+    .toSorted((a, b) => {
+      if (a.provider !== b.provider) {
+        return a.provider.localeCompare(b.provider);
+      }
+      return a.profileId.localeCompare(b.profileId);
+    });
+
+  const providersMap = new Map<string, AuthProviderHealth>();
+  for (const profile of profiles) {
+    const existing = providersMap.get(profile.provider);
+    if (!existing) {
+      providersMap.set(profile.provider, {
+        provider: profile.provider,
+        status: "missing",
+        profiles: [profile],
+      });
+    } else {
+      existing.profiles.push(profile);
+    }
+  }
+
+  if (providerFilter) {
+    for (const provider of providerFilter) {
+      if (!providersMap.has(provider)) {
+        providersMap.set(provider, {
+          provider,
+          status: "missing",
+          profiles: [],
+        });
+      }
+    }
+  }
+
+  for (const provider of providersMap.values()) {
+    if (provider.profiles.length === 0) {
+      provider.status = "missing";
+      continue;
+    }
+
+    const oauthProfiles = provider.profiles.filter((p) => p.type === "oauth");
+    const tokenProfiles = provider.profiles.filter((p) => p.type === "token");
+    const apiKeyProfiles = provider.profiles.filter((p) => p.type === "api_key");
+
+    const expirable = [...oauthProfiles, ...tokenProfiles];
+    if (expirable.length === 0) {
+      provider.status = apiKeyProfiles.length > 0 ? "static" : "missing";
+      continue;
+    }
+
+    const expiryCandidates = expirable
+      .map((p) => p.expiresAt)
+      .filter((v): v is number => typeof v === "number" && Number.isFinite(v));
+    if (expiryCandidates.length > 0) {
+      provider.expiresAt = Math.min(...expiryCandidates);
+      provider.remainingMs = provider.expiresAt - now;
+    }
+
+    const statuses = new Set(expirable.map((p) => p.status));
+    if (statuses.has("expired") || statuses.has("missing")) {
+      provider.status = "expired";
+    } else if (statuses.has("expiring")) {
+      provider.status = "expiring";
+    } else {
+      provider.status = "ok";
+    }
+  }
+
+  const providers = Array.from(providersMap.values()).toSorted((a, b) =>
+    a.provider.localeCompare(b.provider),
+  );
+
+  return { now, warnAfterMs, profiles, providers };
+}

src/agents/auth-profiles.auth-profile-cooldowns.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { calculateAuthProfileCooldownMs } from "./auth-profiles.js";
+
+describe("auth profile cooldowns", () => {
+  it("applies exponential backoff with a 1h cap", () => {
+    expect(calculateAuthProfileCooldownMs(1)).toBe(60_000);
+    expect(calculateAuthProfileCooldownMs(2)).toBe(5 * 60_000);
+    expect(calculateAuthProfileCooldownMs(3)).toBe(25 * 60_000);
+    expect(calculateAuthProfileCooldownMs(4)).toBe(60 * 60_000);
+    expect(calculateAuthProfileCooldownMs(5)).toBe(60 * 60_000);
+  });
+});

src/agents/auth-profiles.chutes.test.ts

@@ -0,0 +1,100 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  type AuthProfileStore,
+  ensureAuthProfileStore,
+  resolveApiKeyForProfile,
+} from "./auth-profiles.js";
+import { CHUTES_TOKEN_ENDPOINT, type ChutesStoredOAuth } from "./chutes-oauth.js";
+
+describe("auth-profiles (chutes)", () => {
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
+  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  const previousChutesClientId = process.env.CHUTES_CLIENT_ID;
+  let tempDir: string | null = null;
+
+  afterEach(async () => {
+    vi.unstubAllGlobals();
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+      tempDir = null;
+    }
+    if (previousStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousStateDir;
+    }
+    if (previousAgentDir === undefined) {
+      delete process.env.OPENCLAW_AGENT_DIR;
+    } else {
+      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
+    }
+    if (previousPiAgentDir === undefined) {
+      delete process.env.PI_CODING_AGENT_DIR;
+    } else {
+      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+    }
+    if (previousChutesClientId === undefined) {
+      delete process.env.CHUTES_CLIENT_ID;
+    } else {
+      process.env.CHUTES_CLIENT_ID = previousChutesClientId;
+    }
+  });
+
+  it("refreshes expired Chutes OAuth credentials", async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chutes-"));
+    process.env.OPENCLAW_STATE_DIR = tempDir;
+    process.env.OPENCLAW_AGENT_DIR = path.join(tempDir, "agents", "main", "agent");
+    process.env.PI_CODING_AGENT_DIR = process.env.OPENCLAW_AGENT_DIR;
+
+    const authProfilePath = path.join(tempDir, "agents", "main", "agent", "auth-profiles.json");
+    await fs.mkdir(path.dirname(authProfilePath), { recursive: true });
+
+    const store: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        "chutes:default": {
+          type: "oauth",
+          provider: "chutes",
+          access: "at_old",
+          refresh: "rt_old",
+          expires: Date.now() - 60_000,
+          clientId: "cid_test",
+        } as unknown as ChutesStoredOAuth,
+      },
+    };
+    await fs.writeFile(authProfilePath, `${JSON.stringify(store)}\n`);
+
+    const fetchSpy = vi.fn(async (input: string | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url !== CHUTES_TOKEN_ENDPOINT) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(
+        JSON.stringify({
+          access_token: "at_new",
+          expires_in: 3600,
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const loaded = ensureAuthProfileStore();
+    const resolved = await resolveApiKeyForProfile({
+      store: loaded,
+      profileId: "chutes:default",
+    });
+
+    expect(resolved?.apiKey).toBe("at_new");
+    expect(fetchSpy).toHaveBeenCalled();
+
+    const persisted = JSON.parse(await fs.readFile(authProfilePath, "utf8")) as {
+      profiles?: Record<string, { access?: string }>;
+    };
+    expect(persisted.profiles?.["chutes:default"]?.access).toBe("at_new");
+  });
+});

src/agents/auth-profiles.ensureauthprofilestore.test.ts

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureAuthProfileStore } from "./auth-profiles.js";
+import { AUTH_STORE_VERSION } from "./auth-profiles/constants.js";
+
+describe("ensureAuthProfileStore", () => {
+  it("migrates legacy auth.json and deletes it (PR #368)", () => {
+    const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-auth-profiles-"));
+    try {
+      const legacyPath = path.join(agentDir, "auth.json");
+      fs.writeFileSync(
+        legacyPath,
+        `${JSON.stringify(
+          {
+            anthropic: {
+              type: "oauth",
+              provider: "anthropic",
+              access: "access-token",
+              refresh: "refresh-token",
+              expires: Date.now() + 60_000,
+            },
+          },
+          null,
+          2,
+        )}\n`,
+        "utf8",
+      );
+
+      const store = ensureAuthProfileStore(agentDir);
+      expect(store.profiles["anthropic:default"]).toMatchObject({
+        type: "oauth",
+        provider: "anthropic",
+      });
+
+      const migratedPath = path.join(agentDir, "auth-profiles.json");
+      expect(fs.existsSync(migratedPath)).toBe(true);
+      expect(fs.existsSync(legacyPath)).toBe(false);
+
+      // idempotent
+      const store2 = ensureAuthProfileStore(agentDir);
+      expect(store2.profiles["anthropic:default"]).toBeDefined();
+      expect(fs.existsSync(legacyPath)).toBe(false);
+    } finally {
+      fs.rmSync(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("merges main auth profiles into agent store and keeps agent overrides", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-auth-merge-"));
+    const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
+    const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+    try {
+      const mainDir = path.join(root, "main-agent");
+      const agentDir = path.join(root, "agent-x");
+      fs.mkdirSync(mainDir, { recursive: true });
+      fs.mkdirSync(agentDir, { recursive: true });
+
+      process.env.OPENCLAW_AGENT_DIR = mainDir;
+      process.env.PI_CODING_AGENT_DIR = mainDir;
+
+      const mainStore = {
+        version: AUTH_STORE_VERSION,
+        profiles: {
+          "openai:default": {
+            type: "api_key",
+            provider: "openai",
+            key: "main-key",
+          },
+          "anthropic:default": {
+            type: "api_key",
+            provider: "anthropic",
+            key: "main-anthropic-key",
+          },
+        },
+      };
+      fs.writeFileSync(
+        path.join(mainDir, "auth-profiles.json"),
+        `${JSON.stringify(mainStore, null, 2)}\n`,
+        "utf8",
+      );
+
+      const agentStore = {
+        version: AUTH_STORE_VERSION,
+        profiles: {
+          "openai:default": {
+            type: "api_key",
+            provider: "openai",
+            key: "agent-key",
+          },
+        },
+      };
+      fs.writeFileSync(
+        path.join(agentDir, "auth-profiles.json"),
+        `${JSON.stringify(agentStore, null, 2)}\n`,
+        "utf8",
+      );
+
+      const store = ensureAuthProfileStore(agentDir);
+      expect(store.profiles["anthropic:default"]).toMatchObject({
+        type: "api_key",
+        provider: "anthropic",
+        key: "main-anthropic-key",
+      });
+      expect(store.profiles["openai:default"]).toMatchObject({
+        type: "api_key",
+        provider: "openai",
+        key: "agent-key",
+      });
+    } finally {
+      if (previousAgentDir === undefined) {
+        delete process.env.OPENCLAW_AGENT_DIR;
+      } else {
+        process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
+      }
+      if (previousPiAgentDir === undefined) {
+        delete process.env.PI_CODING_AGENT_DIR;
+      } else {
+        process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+      }
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

src/agents/auth-profiles.markauthprofilefailure.test.ts

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { ensureAuthProfileStore, markAuthProfileFailure } from "./auth-profiles.js";
+
+describe("markAuthProfileFailure", () => {
+  it("disables billing failures for ~5 hours by default", async () => {
+    const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-auth-"));
+    try {
+      const authPath = path.join(agentDir, "auth-profiles.json");
+      fs.writeFileSync(
+        authPath,
+        JSON.stringify({
+          version: 1,
+          profiles: {
+            "anthropic:default": {
+              type: "api_key",
+              provider: "anthropic",
+              key: "sk-default",
+            },
+          },
+        }),
+      );
+
+      const store = ensureAuthProfileStore(agentDir);
+      const startedAt = Date.now();
+      await markAuthProfileFailure({
+        store,
+        profileId: "anthropic:default",
+        reason: "billing",
+        agentDir,
+      });
+
+      const disabledUntil = store.usageStats?.["anthropic:default"]?.disabledUntil;
+      expect(typeof disabledUntil).toBe("number");
+      const remainingMs = (disabledUntil as number) - startedAt;
+      expect(remainingMs).toBeGreaterThan(4.5 * 60 * 60 * 1000);
+      expect(remainingMs).toBeLessThan(5.5 * 60 * 60 * 1000);
+    } finally {
+      fs.rmSync(agentDir, { recursive: true, force: true });
+    }
+  });
+  it("honors per-provider billing backoff overrides", async () => {
+    const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-auth-"));
+    try {
+      const authPath = path.join(agentDir, "auth-profiles.json");
+      fs.writeFileSync(
+        authPath,
+        JSON.stringify({
+          version: 1,
+          profiles: {
+            "anthropic:default": {
+              type: "api_key",
+              provider: "anthropic",
+              key: "sk-default",
+            },
+          },
+        }),
+      );
+
+      const store = ensureAuthProfileStore(agentDir);
+      const startedAt = Date.now();
+      await markAuthProfileFailure({
+        store,
+        profileId: "anthropic:default",
+        reason: "billing",
+        agentDir,
+        cfg: {
+          auth: {
+            cooldowns: {
+              billingBackoffHoursByProvider: { Anthropic: 1 },
+              billingMaxHours: 2,
+            },
+          },
+        } as never,
+      });
+
+      const disabledUntil = store.usageStats?.["anthropic:default"]?.disabledUntil;
+      expect(typeof disabledUntil).toBe("number");
+      const remainingMs = (disabledUntil as number) - startedAt;
+      expect(remainingMs).toBeGreaterThan(0.8 * 60 * 60 * 1000);
+      expect(remainingMs).toBeLessThan(1.2 * 60 * 60 * 1000);
+    } finally {
+      fs.rmSync(agentDir, { recursive: true, force: true });
+    }
+  });
+  it("resets backoff counters outside the failure window", async () => {
+    const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-auth-"));
+    try {
+      const authPath = path.join(agentDir, "auth-profiles.json");
+      const now = Date.now();
+      fs.writeFileSync(
+        authPath,
+        JSON.stringify({
+          version: 1,
+          profiles: {
+            "anthropic:default": {
+              type: "api_key",
+              provider: "anthropic",
+              key: "sk-default",
+            },
+          },
+          usageStats: {
+            "anthropic:default": {
+              errorCount: 9,
+              failureCounts: { billing: 3 },
+              lastFailureAt: now - 48 * 60 * 60 * 1000,
+            },
+          },
+        }),
+      );
+
+      const store = ensureAuthProfileStore(agentDir);
+      await markAuthProfileFailure({
+        store,
+        profileId: "anthropic:default",
+        reason: "billing",
+        agentDir,
+        cfg: {
+          auth: { cooldowns: { failureWindowHours: 24 } },
+        } as never,
+      });
+
+      expect(store.usageStats?.["anthropic:default"]?.errorCount).toBe(1);
+      expect(store.usageStats?.["anthropic:default"]?.failureCounts?.billing).toBe(1);
+    } finally {
+      fs.rmSync(agentDir, { recursive: true, force: true });
+    }
+  });
+});

src/agents/auth-profiles.resolve-auth-profile-order.does-not-prioritize-lastgood-round-robin-ordering.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from "vitest";
+import { resolveAuthProfileOrder } from "./auth-profiles.js";
+
+describe("resolveAuthProfileOrder", () => {
+  const store: AuthProfileStore = {
+    version: 1,
+    profiles: {
+      "anthropic:default": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-default",
+      },
+      "anthropic:work": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-work",
+      },
+    },
+  };
+  const cfg = {
+    auth: {
+      profiles: {
+        "anthropic:default": { provider: "anthropic", mode: "api_key" },
+        "anthropic:work": { provider: "anthropic", mode: "api_key" },
+      },
+    },
+  };
+
+  it("does not prioritize lastGood over round-robin ordering", () => {
+    const order = resolveAuthProfileOrder({
+      cfg,
+      store: {
+        ...store,
+        lastGood: { anthropic: "anthropic:work" },
+        usageStats: {
+          "anthropic:default": { lastUsed: 100 },
+          "anthropic:work": { lastUsed: 200 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order[0]).toBe("anthropic:default");
+  });
+  it("uses explicit profiles when order is missing", () => {
+    const order = resolveAuthProfileOrder({
+      cfg,
+      store,
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:default", "anthropic:work"]);
+  });
+  it("uses configured order when provided", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { anthropic: ["anthropic:work", "anthropic:default"] },
+          profiles: cfg.auth.profiles,
+        },
+      },
+      store,
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+  it("prefers store order over config order", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { anthropic: ["anthropic:default", "anthropic:work"] },
+          profiles: cfg.auth.profiles,
+        },
+      },
+      store: {
+        ...store,
+        order: { anthropic: ["anthropic:work", "anthropic:default"] },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+  it("pushes cooldown profiles to the end even with store order", () => {
+    const now = Date.now();
+    const order = resolveAuthProfileOrder({
+      store: {
+        ...store,
+        order: { anthropic: ["anthropic:default", "anthropic:work"] },
+        usageStats: {
+          "anthropic:default": { cooldownUntil: now + 60_000 },
+          "anthropic:work": { lastUsed: 1 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+  it("pushes cooldown profiles to the end even with configured order", () => {
+    const now = Date.now();
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { anthropic: ["anthropic:default", "anthropic:work"] },
+          profiles: cfg.auth.profiles,
+        },
+      },
+      store: {
+        ...store,
+        usageStats: {
+          "anthropic:default": { cooldownUntil: now + 60_000 },
+          "anthropic:work": { lastUsed: 1 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+  it("pushes disabled profiles to the end even with store order", () => {
+    const now = Date.now();
+    const order = resolveAuthProfileOrder({
+      store: {
+        ...store,
+        order: { anthropic: ["anthropic:default", "anthropic:work"] },
+        usageStats: {
+          "anthropic:default": {
+            disabledUntil: now + 60_000,
+            disabledReason: "billing",
+          },
+          "anthropic:work": { lastUsed: 1 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+  it("pushes disabled profiles to the end even with configured order", () => {
+    const now = Date.now();
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { anthropic: ["anthropic:default", "anthropic:work"] },
+          profiles: cfg.auth.profiles,
+        },
+      },
+      store: {
+        ...store,
+        usageStats: {
+          "anthropic:default": {
+            disabledUntil: now + 60_000,
+            disabledReason: "billing",
+          },
+          "anthropic:work": { lastUsed: 1 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:work", "anthropic:default"]);
+  });
+
+  it("mode: oauth config accepts both oauth and token credentials (issue #559)", () => {
+    const now = Date.now();
+    const storeWithBothTypes: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        "anthropic:oauth-cred": {
+          type: "oauth",
+          provider: "anthropic",
+          access: "access-token",
+          refresh: "refresh-token",
+          expires: now + 60_000,
+        },
+        "anthropic:token-cred": {
+          type: "token",
+          provider: "anthropic",
+          token: "just-a-token",
+          expires: now + 60_000,
+        },
+      },
+    };
+
+    const orderOauthCred = resolveAuthProfileOrder({
+      store: storeWithBothTypes,
+      provider: "anthropic",
+      cfg: {
+        auth: {
+          profiles: {
+            "anthropic:oauth-cred": { provider: "anthropic", mode: "oauth" },
+          },
+        },
+      },
+    });
+    expect(orderOauthCred).toContain("anthropic:oauth-cred");
+
+    const orderTokenCred = resolveAuthProfileOrder({
+      store: storeWithBothTypes,
+      provider: "anthropic",
+      cfg: {
+        auth: {
+          profiles: {
+            "anthropic:token-cred": { provider: "anthropic", mode: "oauth" },
+          },
+        },
+      },
+    });
+    expect(orderTokenCred).toContain("anthropic:token-cred");
+  });
+
+  it("mode: token config rejects oauth credentials (issue #559 root cause)", () => {
+    const now = Date.now();
+    const storeWithOauth: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        "anthropic:oauth-cred": {
+          type: "oauth",
+          provider: "anthropic",
+          access: "access-token",
+          refresh: "refresh-token",
+          expires: now + 60_000,
+        },
+      },
+    };
+
+    const order = resolveAuthProfileOrder({
+      store: storeWithOauth,
+      provider: "anthropic",
+      cfg: {
+        auth: {
+          profiles: {
+            "anthropic:oauth-cred": { provider: "anthropic", mode: "token" },
+          },
+        },
+      },
+    });
+    expect(order).not.toContain("anthropic:oauth-cred");
+  });
+});

src/agents/auth-profiles.resolve-auth-profile-order.normalizes-z-ai-aliases-auth-order.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import { resolveAuthProfileOrder } from "./auth-profiles.js";
+
+describe("resolveAuthProfileOrder", () => {
+  const _store: AuthProfileStore = {
+    version: 1,
+    profiles: {
+      "anthropic:default": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-default",
+      },
+      "anthropic:work": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-work",
+      },
+    },
+  };
+  const _cfg = {
+    auth: {
+      profiles: {
+        "anthropic:default": { provider: "anthropic", mode: "api_key" },
+        "anthropic:work": { provider: "anthropic", mode: "api_key" },
+      },
+    },
+  };
+
+  it("normalizes z.ai aliases in auth.order", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { "z.ai": ["zai:work", "zai:default"] },
+          profiles: {
+            "zai:default": { provider: "zai", mode: "api_key" },
+            "zai:work": { provider: "zai", mode: "api_key" },
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "zai:default": {
+            type: "api_key",
+            provider: "zai",
+            key: "sk-default",
+          },
+          "zai:work": {
+            type: "api_key",
+            provider: "zai",
+            key: "sk-work",
+          },
+        },
+      },
+      provider: "zai",
+    });
+    expect(order).toEqual(["zai:work", "zai:default"]);
+  });
+  it("normalizes provider casing in auth.order keys", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: { OpenAI: ["openai:work", "openai:default"] },
+          profiles: {
+            "openai:default": { provider: "openai", mode: "api_key" },
+            "openai:work": { provider: "openai", mode: "api_key" },
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "openai:default": {
+            type: "api_key",
+            provider: "openai",
+            key: "sk-default",
+          },
+          "openai:work": {
+            type: "api_key",
+            provider: "openai",
+            key: "sk-work",
+          },
+        },
+      },
+      provider: "openai",
+    });
+    expect(order).toEqual(["openai:work", "openai:default"]);
+  });
+  it("normalizes z.ai aliases in auth.profiles", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          profiles: {
+            "zai:default": { provider: "z.ai", mode: "api_key" },
+            "zai:work": { provider: "Z.AI", mode: "api_key" },
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "zai:default": {
+            type: "api_key",
+            provider: "zai",
+            key: "sk-default",
+          },
+          "zai:work": {
+            type: "api_key",
+            provider: "zai",
+            key: "sk-work",
+          },
+        },
+      },
+      provider: "zai",
+    });
+    expect(order).toEqual(["zai:default", "zai:work"]);
+  });
+  it("prioritizes oauth profiles when order missing", () => {
+    const mixedStore: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        "anthropic:default": {
+          type: "api_key",
+          provider: "anthropic",
+          key: "sk-default",
+        },
+        "anthropic:oauth": {
+          type: "oauth",
+          provider: "anthropic",
+          access: "access-token",
+          refresh: "refresh-token",
+          expires: Date.now() + 60_000,
+        },
+      },
+    };
+    const order = resolveAuthProfileOrder({
+      store: mixedStore,
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:oauth", "anthropic:default"]);
+  });
+});

src/agents/auth-profiles.resolve-auth-profile-order.orders-by-lastused-no-explicit-order-exists.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { resolveAuthProfileOrder } from "./auth-profiles.js";
+
+describe("resolveAuthProfileOrder", () => {
+  const _store: AuthProfileStore = {
+    version: 1,
+    profiles: {
+      "anthropic:default": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-default",
+      },
+      "anthropic:work": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-work",
+      },
+    },
+  };
+  const _cfg = {
+    auth: {
+      profiles: {
+        "anthropic:default": { provider: "anthropic", mode: "api_key" },
+        "anthropic:work": { provider: "anthropic", mode: "api_key" },
+      },
+    },
+  };
+
+  it("orders by lastUsed when no explicit order exists", () => {
+    const order = resolveAuthProfileOrder({
+      store: {
+        version: 1,
+        profiles: {
+          "anthropic:a": {
+            type: "oauth",
+            provider: "anthropic",
+            access: "access-token",
+            refresh: "refresh-token",
+            expires: Date.now() + 60_000,
+          },
+          "anthropic:b": {
+            type: "api_key",
+            provider: "anthropic",
+            key: "sk-b",
+          },
+          "anthropic:c": {
+            type: "api_key",
+            provider: "anthropic",
+            key: "sk-c",
+          },
+        },
+        usageStats: {
+          "anthropic:a": { lastUsed: 200 },
+          "anthropic:b": { lastUsed: 100 },
+          "anthropic:c": { lastUsed: 300 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:a", "anthropic:b", "anthropic:c"]);
+  });
+  it("pushes cooldown profiles to the end, ordered by cooldown expiry", () => {
+    const now = Date.now();
+    const order = resolveAuthProfileOrder({
+      store: {
+        version: 1,
+        profiles: {
+          "anthropic:ready": {
+            type: "api_key",
+            provider: "anthropic",
+            key: "sk-ready",
+          },
+          "anthropic:cool1": {
+            type: "oauth",
+            provider: "anthropic",
+            access: "access-token",
+            refresh: "refresh-token",
+            expires: now + 60_000,
+          },
+          "anthropic:cool2": {
+            type: "api_key",
+            provider: "anthropic",
+            key: "sk-cool",
+          },
+        },
+        usageStats: {
+          "anthropic:ready": { lastUsed: 50 },
+          "anthropic:cool1": { cooldownUntil: now + 5_000 },
+          "anthropic:cool2": { cooldownUntil: now + 1_000 },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:ready", "anthropic:cool2", "anthropic:cool1"]);
+  });
+});

src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+import { resolveAuthProfileOrder } from "./auth-profiles.js";
+
+describe("resolveAuthProfileOrder", () => {
+  const store: AuthProfileStore = {
+    version: 1,
+    profiles: {
+      "anthropic:default": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-default",
+      },
+      "anthropic:work": {
+        type: "api_key",
+        provider: "anthropic",
+        key: "sk-work",
+      },
+    },
+  };
+  const cfg = {
+    auth: {
+      profiles: {
+        "anthropic:default": { provider: "anthropic", mode: "api_key" },
+        "anthropic:work": { provider: "anthropic", mode: "api_key" },
+      },
+    },
+  };
+
+  it("uses stored profiles when no config exists", () => {
+    const order = resolveAuthProfileOrder({
+      store,
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:default", "anthropic:work"]);
+  });
+  it("prioritizes preferred profiles", () => {
+    const order = resolveAuthProfileOrder({
+      cfg,
+      store,
+      provider: "anthropic",
+      preferredProfile: "anthropic:work",
+    });
+    expect(order[0]).toBe("anthropic:work");
+    expect(order).toContain("anthropic:default");
+  });
+  it("drops explicit order entries that are missing from the store", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: {
+            minimax: ["minimax:default", "minimax:prod"],
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "minimax:prod": {
+            type: "api_key",
+            provider: "minimax",
+            key: "sk-prod",
+          },
+        },
+      },
+      provider: "minimax",
+    });
+    expect(order).toEqual(["minimax:prod"]);
+  });
+  it("drops explicit order entries that belong to another provider", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: {
+            minimax: ["openai:default", "minimax:prod"],
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "openai:default": {
+            type: "api_key",
+            provider: "openai",
+            key: "sk-openai",
+          },
+          "minimax:prod": {
+            type: "api_key",
+            provider: "minimax",
+            key: "sk-mini",
+          },
+        },
+      },
+      provider: "minimax",
+    });
+    expect(order).toEqual(["minimax:prod"]);
+  });
+  it("drops token profiles with empty credentials", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: {
+            minimax: ["minimax:default"],
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "minimax:default": {
+            type: "token",
+            provider: "minimax",
+            token: "   ",
+          },
+        },
+      },
+      provider: "minimax",
+    });
+    expect(order).toEqual([]);
+  });
+  it("drops token profiles that are already expired", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: {
+            minimax: ["minimax:default"],
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "minimax:default": {
+            type: "token",
+            provider: "minimax",
+            token: "sk-minimax",
+            expires: Date.now() - 1000,
+          },
+        },
+      },
+      provider: "minimax",
+    });
+    expect(order).toEqual([]);
+  });
+  it("keeps oauth profiles that can refresh", () => {
+    const order = resolveAuthProfileOrder({
+      cfg: {
+        auth: {
+          order: {
+            anthropic: ["anthropic:oauth"],
+          },
+        },
+      },
+      store: {
+        version: 1,
+        profiles: {
+          "anthropic:oauth": {
+            type: "oauth",
+            provider: "anthropic",
+            access: "",
+            refresh: "refresh-token",
+            expires: Date.now() - 1000,
+          },
+        },
+      },
+      provider: "anthropic",
+    });
+    expect(order).toEqual(["anthropic:oauth"]);
+  });
+});

src/agents/auth-profiles.ts

@@ -0,0 +1,40 @@
+export { CLAUDE_CLI_PROFILE_ID, CODEX_CLI_PROFILE_ID } from "./auth-profiles/constants.js";
+export { resolveAuthProfileDisplayLabel } from "./auth-profiles/display.js";
+export { formatAuthDoctorHint } from "./auth-profiles/doctor.js";
+export { resolveApiKeyForProfile } from "./auth-profiles/oauth.js";
+export { resolveAuthProfileOrder } from "./auth-profiles/order.js";
+export { resolveAuthStorePathForDisplay } from "./auth-profiles/paths.js";
+export {
+  listProfilesForProvider,
+  markAuthProfileGood,
+  setAuthProfileOrder,
+  upsertAuthProfile,
+} from "./auth-profiles/profiles.js";
+export {
+  repairOAuthProfileIdMismatch,
+  suggestOAuthProfileIdForLegacyDefault,
+} from "./auth-profiles/repair.js";
+export {
+  ensureAuthProfileStore,
+  loadAuthProfileStore,
+  saveAuthProfileStore,
+} from "./auth-profiles/store.js";
+export type {
+  ApiKeyCredential,
+  AuthProfileCredential,
+  AuthProfileFailureReason,
+  AuthProfileIdRepairResult,
+  AuthProfileStore,
+  OAuthCredential,
+  ProfileUsageStats,
+  TokenCredential,
+} from "./auth-profiles/types.js";
+export {
+  calculateAuthProfileCooldownMs,
+  clearAuthProfileCooldown,
+  isProfileInCooldown,
+  markAuthProfileCooldown,
+  markAuthProfileFailure,
+  markAuthProfileUsed,
+  resolveProfileUnusableUntilForDisplay,
+} from "./auth-profiles/usage.js";

src/agents/auth-profiles/constants.ts

@@ -0,0 +1,26 @@
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+
+export const AUTH_STORE_VERSION = 1;
+export const AUTH_PROFILE_FILENAME = "auth-profiles.json";
+export const LEGACY_AUTH_FILENAME = "auth.json";
+
+export const CLAUDE_CLI_PROFILE_ID = "anthropic:claude-cli";
+export const CODEX_CLI_PROFILE_ID = "openai-codex:codex-cli";
+export const QWEN_CLI_PROFILE_ID = "qwen-portal:qwen-cli";
+export const MINIMAX_CLI_PROFILE_ID = "minimax-portal:minimax-cli";
+
+export const AUTH_STORE_LOCK_OPTIONS = {
+  retries: {
+    retries: 10,
+    factor: 2,
+    minTimeout: 100,
+    maxTimeout: 10_000,
+    randomize: true,
+  },
+  stale: 30_000,
+} as const;
+
+export const EXTERNAL_CLI_SYNC_TTL_MS = 15 * 60 * 1000;
+export const EXTERNAL_CLI_NEAR_EXPIRY_MS = 10 * 60 * 1000;
+
+export const log = createSubsystemLogger("agents/auth-profiles");

src/agents/auth-profiles/display.ts

@@ -0,0 +1,17 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileStore } from "./types.js";
+
+export function resolveAuthProfileDisplayLabel(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  profileId: string;
+}): string {
+  const { cfg, store, profileId } = params;
+  const profile = store.profiles[profileId];
+  const configEmail = cfg?.auth?.profiles?.[profileId]?.email?.trim();
+  const email = configEmail || (profile && "email" in profile ? profile.email?.trim() : undefined);
+  if (email) {
+    return `${profileId} (${email})`;
+  }
+  return profileId;
+}

src/agents/auth-profiles/doctor.ts

@@ -0,0 +1,47 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileStore } from "./types.js";
+import { formatCliCommand } from "../../cli/command-format.js";
+import { normalizeProviderId } from "../model-selection.js";
+import { listProfilesForProvider } from "./profiles.js";
+import { suggestOAuthProfileIdForLegacyDefault } from "./repair.js";
+
+export function formatAuthDoctorHint(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  provider: string;
+  profileId?: string;
+}): string {
+  const providerKey = normalizeProviderId(params.provider);
+  if (providerKey !== "anthropic") {
+    return "";
+  }
+
+  const legacyProfileId = params.profileId ?? "anthropic:default";
+  const suggested = suggestOAuthProfileIdForLegacyDefault({
+    cfg: params.cfg,
+    store: params.store,
+    provider: providerKey,
+    legacyProfileId,
+  });
+  if (!suggested || suggested === legacyProfileId) {
+    return "";
+  }
+
+  const storeOauthProfiles = listProfilesForProvider(params.store, providerKey)
+    .filter((id) => params.store.profiles[id]?.type === "oauth")
+    .join(", ");
+
+  const cfgMode = params.cfg?.auth?.profiles?.[legacyProfileId]?.mode;
+  const cfgProvider = params.cfg?.auth?.profiles?.[legacyProfileId]?.provider;
+
+  return [
+    "Doctor hint (for GitHub issue):",
+    `- provider: ${providerKey}`,
+    `- config: ${legacyProfileId}${
+      cfgProvider || cfgMode ? ` (provider=${cfgProvider ?? "?"}, mode=${cfgMode ?? "?"})` : ""
+    }`,
+    `- auth store oauth profiles: ${storeOauthProfiles || "(none)"}`,
+    `- suggested profile: ${suggested}`,
+    `Fix: run "${formatCliCommand("openclaw doctor --yes")}"`,
+  ].join("\n");
+}

src/agents/auth-profiles/external-cli-sync.ts

@@ -0,0 +1,135 @@
+import type { AuthProfileCredential, AuthProfileStore, OAuthCredential } from "./types.js";
+import {
+  readQwenCliCredentialsCached,
+  readMiniMaxCliCredentialsCached,
+} from "../cli-credentials.js";
+import {
+  EXTERNAL_CLI_NEAR_EXPIRY_MS,
+  EXTERNAL_CLI_SYNC_TTL_MS,
+  QWEN_CLI_PROFILE_ID,
+  MINIMAX_CLI_PROFILE_ID,
+  log,
+} from "./constants.js";
+
+function shallowEqualOAuthCredentials(a: OAuthCredential | undefined, b: OAuthCredential): boolean {
+  if (!a) {
+    return false;
+  }
+  if (a.type !== "oauth") {
+    return false;
+  }
+  return (
+    a.provider === b.provider &&
+    a.access === b.access &&
+    a.refresh === b.refresh &&
+    a.expires === b.expires &&
+    a.email === b.email &&
+    a.enterpriseUrl === b.enterpriseUrl &&
+    a.projectId === b.projectId &&
+    a.accountId === b.accountId
+  );
+}
+
+function isExternalProfileFresh(cred: AuthProfileCredential | undefined, now: number): boolean {
+  if (!cred) {
+    return false;
+  }
+  if (cred.type !== "oauth" && cred.type !== "token") {
+    return false;
+  }
+  if (cred.provider !== "qwen-portal" && cred.provider !== "minimax-portal") {
+    return false;
+  }
+  if (typeof cred.expires !== "number") {
+    return true;
+  }
+  return cred.expires > now + EXTERNAL_CLI_NEAR_EXPIRY_MS;
+}
+
+/** Sync external CLI credentials into the store for a given provider. */
+function syncExternalCliCredentialsForProvider(
+  store: AuthProfileStore,
+  profileId: string,
+  provider: string,
+  readCredentials: () => OAuthCredential | null,
+  now: number,
+): boolean {
+  const existing = store.profiles[profileId];
+  const shouldSync =
+    !existing || existing.provider !== provider || !isExternalProfileFresh(existing, now);
+  const creds = shouldSync ? readCredentials() : null;
+  if (!creds) {
+    return false;
+  }
+
+  const existingOAuth = existing?.type === "oauth" ? existing : undefined;
+  const shouldUpdate =
+    !existingOAuth ||
+    existingOAuth.provider !== provider ||
+    existingOAuth.expires <= now ||
+    creds.expires > existingOAuth.expires;
+
+  if (shouldUpdate && !shallowEqualOAuthCredentials(existingOAuth, creds)) {
+    store.profiles[profileId] = creds;
+    log.info(`synced ${provider} credentials from external cli`, {
+      profileId,
+      expires: new Date(creds.expires).toISOString(),
+    });
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Sync OAuth credentials from external CLI tools (Qwen Code CLI, MiniMax CLI) into the store.
+ *
+ * Returns true if any credentials were updated.
+ */
+export function syncExternalCliCredentials(store: AuthProfileStore): boolean {
+  let mutated = false;
+  const now = Date.now();
+
+  // Sync from Qwen Code CLI
+  const existingQwen = store.profiles[QWEN_CLI_PROFILE_ID];
+  const shouldSyncQwen =
+    !existingQwen ||
+    existingQwen.provider !== "qwen-portal" ||
+    !isExternalProfileFresh(existingQwen, now);
+  const qwenCreds = shouldSyncQwen
+    ? readQwenCliCredentialsCached({ ttlMs: EXTERNAL_CLI_SYNC_TTL_MS })
+    : null;
+  if (qwenCreds) {
+    const existing = store.profiles[QWEN_CLI_PROFILE_ID];
+    const existingOAuth = existing?.type === "oauth" ? existing : undefined;
+    const shouldUpdate =
+      !existingOAuth ||
+      existingOAuth.provider !== "qwen-portal" ||
+      existingOAuth.expires <= now ||
+      qwenCreds.expires > existingOAuth.expires;
+
+    if (shouldUpdate && !shallowEqualOAuthCredentials(existingOAuth, qwenCreds)) {
+      store.profiles[QWEN_CLI_PROFILE_ID] = qwenCreds;
+      mutated = true;
+      log.info("synced qwen credentials from qwen cli", {
+        profileId: QWEN_CLI_PROFILE_ID,
+        expires: new Date(qwenCreds.expires).toISOString(),
+      });
+    }
+  }
+
+  // Sync from MiniMax Portal CLI
+  if (
+    syncExternalCliCredentialsForProvider(
+      store,
+      MINIMAX_CLI_PROFILE_ID,
+      "minimax-portal",
+      () => readMiniMaxCliCredentialsCached({ ttlMs: EXTERNAL_CLI_SYNC_TTL_MS }),
+      now,
+    )
+  ) {
+    mutated = true;
+  }
+
+  return mutated;
+}

src/agents/auth-profiles/oauth.fallback-to-main-agent.test.ts

@@ -0,0 +1,173 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AuthProfileStore } from "./types.js";
+import { resolveApiKeyForProfile } from "./oauth.js";
+import { ensureAuthProfileStore } from "./store.js";
+
+describe("resolveApiKeyForProfile fallback to main agent", () => {
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const previousAgentDir = process.env.OPENCLAW_AGENT_DIR;
+  const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+  let tmpDir: string;
+  let mainAgentDir: string;
+  let secondaryAgentDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "oauth-fallback-test-"));
+    mainAgentDir = path.join(tmpDir, "agents", "main", "agent");
+    secondaryAgentDir = path.join(tmpDir, "agents", "kids", "agent");
+    await fs.mkdir(mainAgentDir, { recursive: true });
+    await fs.mkdir(secondaryAgentDir, { recursive: true });
+
+    // Set environment variables so resolveOpenClawAgentDir() returns mainAgentDir
+    process.env.OPENCLAW_STATE_DIR = tmpDir;
+    process.env.OPENCLAW_AGENT_DIR = mainAgentDir;
+    process.env.PI_CODING_AGENT_DIR = mainAgentDir;
+  });
+
+  afterEach(async () => {
+    vi.unstubAllGlobals();
+
+    // Restore original environment
+    if (previousStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousStateDir;
+    }
+    if (previousAgentDir === undefined) {
+      delete process.env.OPENCLAW_AGENT_DIR;
+    } else {
+      process.env.OPENCLAW_AGENT_DIR = previousAgentDir;
+    }
+    if (previousPiAgentDir === undefined) {
+      delete process.env.PI_CODING_AGENT_DIR;
+    } else {
+      process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+    }
+
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("falls back to main agent credentials when secondary agent token is expired and refresh fails", async () => {
+    const profileId = "anthropic:claude-cli";
+    const now = Date.now();
+    const expiredTime = now - 60 * 60 * 1000; // 1 hour ago
+    const freshTime = now + 60 * 60 * 1000; // 1 hour from now
+
+    // Write expired credentials for secondary agent
+    const secondaryStore: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        [profileId]: {
+          type: "oauth",
+          provider: "anthropic",
+          access: "expired-access-token",
+          refresh: "expired-refresh-token",
+          expires: expiredTime,
+        },
+      },
+    };
+    await fs.writeFile(
+      path.join(secondaryAgentDir, "auth-profiles.json"),
+      JSON.stringify(secondaryStore),
+    );
+
+    // Write fresh credentials for main agent
+    const mainStore: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        [profileId]: {
+          type: "oauth",
+          provider: "anthropic",
+          access: "fresh-access-token",
+          refresh: "fresh-refresh-token",
+          expires: freshTime,
+        },
+      },
+    };
+    await fs.writeFile(path.join(mainAgentDir, "auth-profiles.json"), JSON.stringify(mainStore));
+
+    // Mock fetch to simulate OAuth refresh failure
+    const fetchSpy = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: "invalid_grant" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+
+    // Load the secondary agent's store (will merge with main agent's store)
+    const loadedSecondaryStore = ensureAuthProfileStore(secondaryAgentDir);
+
+    // Call resolveApiKeyForProfile with the secondary agent's expired credentials
+    // This should:
+    // 1. Try to refresh the expired token (fails due to mocked fetch)
+    // 2. Fall back to main agent's fresh credentials
+    // 3. Copy those credentials to the secondary agent
+    const result = await resolveApiKeyForProfile({
+      store: loadedSecondaryStore,
+      profileId,
+      agentDir: secondaryAgentDir,
+    });
+
+    expect(result).not.toBeNull();
+    expect(result?.apiKey).toBe("fresh-access-token");
+    expect(result?.provider).toBe("anthropic");
+
+    // Verify the credentials were copied to the secondary agent
+    const updatedSecondaryStore = JSON.parse(
+      await fs.readFile(path.join(secondaryAgentDir, "auth-profiles.json"), "utf8"),
+    ) as AuthProfileStore;
+    expect(updatedSecondaryStore.profiles[profileId]).toMatchObject({
+      access: "fresh-access-token",
+      expires: freshTime,
+    });
+  });
+
+  it("throws error when both secondary and main agent credentials are expired", async () => {
+    const profileId = "anthropic:claude-cli";
+    const now = Date.now();
+    const expiredTime = now - 60 * 60 * 1000; // 1 hour ago
+
+    // Write expired credentials for both agents
+    const expiredStore: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        [profileId]: {
+          type: "oauth",
+          provider: "anthropic",
+          access: "expired-access-token",
+          refresh: "expired-refresh-token",
+          expires: expiredTime,
+        },
+      },
+    };
+    await fs.writeFile(
+      path.join(secondaryAgentDir, "auth-profiles.json"),
+      JSON.stringify(expiredStore),
+    );
+    await fs.writeFile(path.join(mainAgentDir, "auth-profiles.json"), JSON.stringify(expiredStore));
+
+    // Mock fetch to simulate OAuth refresh failure
+    const fetchSpy = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: "invalid_grant" }), {
+        status: 400,
+        headers: { "Content-Type": "application/json" },
+      });
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+
+    const loadedSecondaryStore = ensureAuthProfileStore(secondaryAgentDir);
+
+    // Should throw because both agents have expired credentials
+    await expect(
+      resolveApiKeyForProfile({
+        store: loadedSecondaryStore,
+        profileId,
+        agentDir: secondaryAgentDir,
+      }),
+    ).rejects.toThrow(/OAuth token refresh failed/);
+  });
+});

src/agents/auth-profiles/oauth.ts

@@ -0,0 +1,285 @@
+import {
+  getOAuthApiKey,
+  getOAuthProviders,
+  type OAuthCredentials,
+  type OAuthProvider,
+} from "@mariozechner/pi-ai";
+import lockfile from "proper-lockfile";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileStore } from "./types.js";
+import { refreshQwenPortalCredentials } from "../../providers/qwen-portal-oauth.js";
+import { refreshChutesTokens } from "../chutes-oauth.js";
+import { AUTH_STORE_LOCK_OPTIONS, log } from "./constants.js";
+import { formatAuthDoctorHint } from "./doctor.js";
+import { ensureAuthStoreFile, resolveAuthStorePath } from "./paths.js";
+import { suggestOAuthProfileIdForLegacyDefault } from "./repair.js";
+import { ensureAuthProfileStore, saveAuthProfileStore } from "./store.js";
+
+const OAUTH_PROVIDER_IDS = new Set<OAuthProvider>(
+  getOAuthProviders().map((provider) => provider.id),
+);
+
+function isOAuthProvider(provider: string): provider is OAuthProvider {
+  // biome-ignore lint/suspicious/noExplicitAny: type guard needs runtime check
+  return OAUTH_PROVIDER_IDS.has(provider as any);
+}
+
+const resolveOAuthProvider = (provider: string): OAuthProvider | null =>
+  isOAuthProvider(provider) ? provider : null;
+
+function buildOAuthApiKey(provider: string, credentials: OAuthCredentials): string {
+  const needsProjectId = provider === "google-gemini-cli" || provider === "google-antigravity";
+  return needsProjectId
+    ? JSON.stringify({
+        token: credentials.access,
+        projectId: credentials.projectId,
+      })
+    : credentials.access;
+}
+
+async function refreshOAuthTokenWithLock(params: {
+  profileId: string;
+  agentDir?: string;
+}): Promise<{ apiKey: string; newCredentials: OAuthCredentials } | null> {
+  const authPath = resolveAuthStorePath(params.agentDir);
+  ensureAuthStoreFile(authPath);
+
+  let release: (() => Promise<void>) | undefined;
+  try {
+    release = await lockfile.lock(authPath, {
+      ...AUTH_STORE_LOCK_OPTIONS,
+    });
+
+    const store = ensureAuthProfileStore(params.agentDir);
+    const cred = store.profiles[params.profileId];
+    if (!cred || cred.type !== "oauth") {
+      return null;
+    }
+
+    if (Date.now() < cred.expires) {
+      return {
+        apiKey: buildOAuthApiKey(cred.provider, cred),
+        newCredentials: cred,
+      };
+    }
+
+    const oauthCreds: Record<string, OAuthCredentials> = {
+      [cred.provider]: cred,
+    };
+
+    const result =
+      String(cred.provider) === "chutes"
+        ? await (async () => {
+            const newCredentials = await refreshChutesTokens({
+              credential: cred,
+            });
+            return { apiKey: newCredentials.access, newCredentials };
+          })()
+        : String(cred.provider) === "qwen-portal"
+          ? await (async () => {
+              const newCredentials = await refreshQwenPortalCredentials(cred);
+              return { apiKey: newCredentials.access, newCredentials };
+            })()
+          : await (async () => {
+              const oauthProvider = resolveOAuthProvider(cred.provider);
+              if (!oauthProvider) {
+                return null;
+              }
+              return await getOAuthApiKey(oauthProvider, oauthCreds);
+            })();
+    if (!result) {
+      return null;
+    }
+    store.profiles[params.profileId] = {
+      ...cred,
+      ...result.newCredentials,
+      type: "oauth",
+    };
+    saveAuthProfileStore(store, params.agentDir);
+
+    return result;
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch {
+        // ignore unlock errors
+      }
+    }
+  }
+}
+
+async function tryResolveOAuthProfile(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  profileId: string;
+  agentDir?: string;
+}): Promise<{ apiKey: string; provider: string; email?: string } | null> {
+  const { cfg, store, profileId } = params;
+  const cred = store.profiles[profileId];
+  if (!cred || cred.type !== "oauth") {
+    return null;
+  }
+  const profileConfig = cfg?.auth?.profiles?.[profileId];
+  if (profileConfig && profileConfig.provider !== cred.provider) {
+    return null;
+  }
+  if (profileConfig && profileConfig.mode !== cred.type) {
+    return null;
+  }
+
+  if (Date.now() < cred.expires) {
+    return {
+      apiKey: buildOAuthApiKey(cred.provider, cred),
+      provider: cred.provider,
+      email: cred.email,
+    };
+  }
+
+  const refreshed = await refreshOAuthTokenWithLock({
+    profileId,
+    agentDir: params.agentDir,
+  });
+  if (!refreshed) {
+    return null;
+  }
+  return {
+    apiKey: refreshed.apiKey,
+    provider: cred.provider,
+    email: cred.email,
+  };
+}
+
+export async function resolveApiKeyForProfile(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  profileId: string;
+  agentDir?: string;
+}): Promise<{ apiKey: string; provider: string; email?: string } | null> {
+  const { cfg, store, profileId } = params;
+  const cred = store.profiles[profileId];
+  if (!cred) {
+    return null;
+  }
+  const profileConfig = cfg?.auth?.profiles?.[profileId];
+  if (profileConfig && profileConfig.provider !== cred.provider) {
+    return null;
+  }
+  if (profileConfig && profileConfig.mode !== cred.type) {
+    // Compatibility: treat "oauth" config as compatible with stored token profiles.
+    if (!(profileConfig.mode === "oauth" && cred.type === "token")) {
+      return null;
+    }
+  }
+
+  if (cred.type === "api_key") {
+    return { apiKey: cred.key, provider: cred.provider, email: cred.email };
+  }
+  if (cred.type === "token") {
+    const token = cred.token?.trim();
+    if (!token) {
+      return null;
+    }
+    if (
+      typeof cred.expires === "number" &&
+      Number.isFinite(cred.expires) &&
+      cred.expires > 0 &&
+      Date.now() >= cred.expires
+    ) {
+      return null;
+    }
+    return { apiKey: token, provider: cred.provider, email: cred.email };
+  }
+  if (Date.now() < cred.expires) {
+    return {
+      apiKey: buildOAuthApiKey(cred.provider, cred),
+      provider: cred.provider,
+      email: cred.email,
+    };
+  }
+
+  try {
+    const result = await refreshOAuthTokenWithLock({
+      profileId,
+      agentDir: params.agentDir,
+    });
+    if (!result) {
+      return null;
+    }
+    return {
+      apiKey: result.apiKey,
+      provider: cred.provider,
+      email: cred.email,
+    };
+  } catch (error) {
+    const refreshedStore = ensureAuthProfileStore(params.agentDir);
+    const refreshed = refreshedStore.profiles[profileId];
+    if (refreshed?.type === "oauth" && Date.now() < refreshed.expires) {
+      return {
+        apiKey: buildOAuthApiKey(refreshed.provider, refreshed),
+        provider: refreshed.provider,
+        email: refreshed.email ?? cred.email,
+      };
+    }
+    const fallbackProfileId = suggestOAuthProfileIdForLegacyDefault({
+      cfg,
+      store: refreshedStore,
+      provider: cred.provider,
+      legacyProfileId: profileId,
+    });
+    if (fallbackProfileId && fallbackProfileId !== profileId) {
+      try {
+        const fallbackResolved = await tryResolveOAuthProfile({
+          cfg,
+          store: refreshedStore,
+          profileId: fallbackProfileId,
+          agentDir: params.agentDir,
+        });
+        if (fallbackResolved) {
+          return fallbackResolved;
+        }
+      } catch {
+        // keep original error
+      }
+    }
+
+    // Fallback: if this is a secondary agent, try using the main agent's credentials
+    if (params.agentDir) {
+      try {
+        const mainStore = ensureAuthProfileStore(undefined); // main agent (no agentDir)
+        const mainCred = mainStore.profiles[profileId];
+        if (mainCred?.type === "oauth" && Date.now() < mainCred.expires) {
+          // Main agent has fresh credentials - copy them to this agent and use them
+          refreshedStore.profiles[profileId] = { ...mainCred };
+          saveAuthProfileStore(refreshedStore, params.agentDir);
+          log.info("inherited fresh OAuth credentials from main agent", {
+            profileId,
+            agentDir: params.agentDir,
+            expires: new Date(mainCred.expires).toISOString(),
+          });
+          return {
+            apiKey: buildOAuthApiKey(mainCred.provider, mainCred),
+            provider: mainCred.provider,
+            email: mainCred.email,
+          };
+        }
+      } catch {
+        // keep original error if main agent fallback also fails
+      }
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    const hint = formatAuthDoctorHint({
+      cfg,
+      store: refreshedStore,
+      provider: cred.provider,
+      profileId,
+    });
+    throw new Error(
+      `OAuth token refresh failed for ${cred.provider}: ${message}. ` +
+        "Please try again or re-authenticate." +
+        (hint ? `\n\n${hint}` : ""),
+      { cause: error },
+    );
+  }
+}

src/agents/auth-profiles/order.ts

@@ -0,0 +1,210 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileStore } from "./types.js";
+import { normalizeProviderId } from "../model-selection.js";
+import { listProfilesForProvider } from "./profiles.js";
+import { isProfileInCooldown } from "./usage.js";
+
+function resolveProfileUnusableUntil(stats: {
+  cooldownUntil?: number;
+  disabledUntil?: number;
+}): number | null {
+  const values = [stats.cooldownUntil, stats.disabledUntil]
+    .filter((value): value is number => typeof value === "number")
+    .filter((value) => Number.isFinite(value) && value > 0);
+  if (values.length === 0) {
+    return null;
+  }
+  return Math.max(...values);
+}
+
+export function resolveAuthProfileOrder(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  provider: string;
+  preferredProfile?: string;
+}): string[] {
+  const { cfg, store, provider, preferredProfile } = params;
+  const providerKey = normalizeProviderId(provider);
+  const now = Date.now();
+  const storedOrder = (() => {
+    const order = store.order;
+    if (!order) {
+      return undefined;
+    }
+    for (const [key, value] of Object.entries(order)) {
+      if (normalizeProviderId(key) === providerKey) {
+        return value;
+      }
+    }
+    return undefined;
+  })();
+  const configuredOrder = (() => {
+    const order = cfg?.auth?.order;
+    if (!order) {
+      return undefined;
+    }
+    for (const [key, value] of Object.entries(order)) {
+      if (normalizeProviderId(key) === providerKey) {
+        return value;
+      }
+    }
+    return undefined;
+  })();
+  const explicitOrder = storedOrder ?? configuredOrder;
+  const explicitProfiles = cfg?.auth?.profiles
+    ? Object.entries(cfg.auth.profiles)
+        .filter(([, profile]) => normalizeProviderId(profile.provider) === providerKey)
+        .map(([profileId]) => profileId)
+    : [];
+  const baseOrder =
+    explicitOrder ??
+    (explicitProfiles.length > 0 ? explicitProfiles : listProfilesForProvider(store, providerKey));
+  if (baseOrder.length === 0) {
+    return [];
+  }
+
+  const filtered = baseOrder.filter((profileId) => {
+    const cred = store.profiles[profileId];
+    if (!cred) {
+      return false;
+    }
+    if (normalizeProviderId(cred.provider) !== providerKey) {
+      return false;
+    }
+    const profileConfig = cfg?.auth?.profiles?.[profileId];
+    if (profileConfig) {
+      if (normalizeProviderId(profileConfig.provider) !== providerKey) {
+        return false;
+      }
+      if (profileConfig.mode !== cred.type) {
+        const oauthCompatible = profileConfig.mode === "oauth" && cred.type === "token";
+        if (!oauthCompatible) {
+          return false;
+        }
+      }
+    }
+    if (cred.type === "api_key") {
+      return Boolean(cred.key?.trim());
+    }
+    if (cred.type === "token") {
+      if (!cred.token?.trim()) {
+        return false;
+      }
+      if (
+        typeof cred.expires === "number" &&
+        Number.isFinite(cred.expires) &&
+        cred.expires > 0 &&
+        now >= cred.expires
+      ) {
+        return false;
+      }
+      return true;
+    }
+    if (cred.type === "oauth") {
+      return Boolean(cred.access?.trim() || cred.refresh?.trim());
+    }
+    return false;
+  });
+  const deduped: string[] = [];
+  for (const entry of filtered) {
+    if (!deduped.includes(entry)) {
+      deduped.push(entry);
+    }
+  }
+
+  // If user specified explicit order (store override or config), respect it
+  // exactly, but still apply cooldown sorting to avoid repeatedly selecting
+  // known-bad/rate-limited keys as the first candidate.
+  if (explicitOrder && explicitOrder.length > 0) {
+    // ...but still respect cooldown tracking to avoid repeatedly selecting a
+    // known-bad/rate-limited key as the first candidate.
+    const available: string[] = [];
+    const inCooldown: Array<{ profileId: string; cooldownUntil: number }> = [];
+
+    for (const profileId of deduped) {
+      const cooldownUntil = resolveProfileUnusableUntil(store.usageStats?.[profileId] ?? {}) ?? 0;
+      if (
+        typeof cooldownUntil === "number" &&
+        Number.isFinite(cooldownUntil) &&
+        cooldownUntil > 0 &&
+        now < cooldownUntil
+      ) {
+        inCooldown.push({ profileId, cooldownUntil });
+      } else {
+        available.push(profileId);
+      }
+    }
+
+    const cooldownSorted = inCooldown
+      .toSorted((a, b) => a.cooldownUntil - b.cooldownUntil)
+      .map((entry) => entry.profileId);
+
+    const ordered = [...available, ...cooldownSorted];
+
+    // Still put preferredProfile first if specified
+    if (preferredProfile && ordered.includes(preferredProfile)) {
+      return [preferredProfile, ...ordered.filter((e) => e !== preferredProfile)];
+    }
+    return ordered;
+  }
+
+  // Otherwise, use round-robin: sort by lastUsed (oldest first)
+  // preferredProfile goes first if specified (for explicit user choice)
+  // lastGood is NOT prioritized - that would defeat round-robin
+  const sorted = orderProfilesByMode(deduped, store);
+
+  if (preferredProfile && sorted.includes(preferredProfile)) {
+    return [preferredProfile, ...sorted.filter((e) => e !== preferredProfile)];
+  }
+
+  return sorted;
+}
+
+function orderProfilesByMode(order: string[], store: AuthProfileStore): string[] {
+  const now = Date.now();
+
+  // Partition into available and in-cooldown
+  const available: string[] = [];
+  const inCooldown: string[] = [];
+
+  for (const profileId of order) {
+    if (isProfileInCooldown(store, profileId)) {
+      inCooldown.push(profileId);
+    } else {
+      available.push(profileId);
+    }
+  }
+
+  // Sort available profiles by lastUsed (oldest first = round-robin)
+  // Then by lastUsed (oldest first = round-robin within type)
+  const scored = available.map((profileId) => {
+    const type = store.profiles[profileId]?.type;
+    const typeScore = type === "oauth" ? 0 : type === "token" ? 1 : type === "api_key" ? 2 : 3;
+    const lastUsed = store.usageStats?.[profileId]?.lastUsed ?? 0;
+    return { profileId, typeScore, lastUsed };
+  });
+
+  // Primary sort: type preference (oauth > token > api_key).
+  // Secondary sort: lastUsed (oldest first for round-robin within type).
+  const sorted = scored
+    .toSorted((a, b) => {
+      // First by type (oauth > token > api_key)
+      if (a.typeScore !== b.typeScore) {
+        return a.typeScore - b.typeScore;
+      }
+      // Then by lastUsed (oldest first)
+      return a.lastUsed - b.lastUsed;
+    })
+    .map((entry) => entry.profileId);
+
+  // Append cooldown profiles at the end (sorted by cooldown expiry, soonest first)
+  const cooldownSorted = inCooldown
+    .map((profileId) => ({
+      profileId,
+      cooldownUntil: resolveProfileUnusableUntil(store.usageStats?.[profileId] ?? {}) ?? now,
+    }))
+    .toSorted((a, b) => a.cooldownUntil - b.cooldownUntil)
+    .map((entry) => entry.profileId);
+
+  return [...sorted, ...cooldownSorted];
+}

src/agents/auth-profiles/paths.ts

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { AuthProfileStore } from "./types.js";
+import { saveJsonFile } from "../../infra/json-file.js";
+import { resolveUserPath } from "../../utils.js";
+import { resolveOpenClawAgentDir } from "../agent-paths.js";
+import { AUTH_PROFILE_FILENAME, AUTH_STORE_VERSION, LEGACY_AUTH_FILENAME } from "./constants.js";
+
+export function resolveAuthStorePath(agentDir?: string): string {
+  const resolved = resolveUserPath(agentDir ?? resolveOpenClawAgentDir());
+  return path.join(resolved, AUTH_PROFILE_FILENAME);
+}
+
+export function resolveLegacyAuthStorePath(agentDir?: string): string {
+  const resolved = resolveUserPath(agentDir ?? resolveOpenClawAgentDir());
+  return path.join(resolved, LEGACY_AUTH_FILENAME);
+}
+
+export function resolveAuthStorePathForDisplay(agentDir?: string): string {
+  const pathname = resolveAuthStorePath(agentDir);
+  return pathname.startsWith("~") ? pathname : resolveUserPath(pathname);
+}
+
+export function ensureAuthStoreFile(pathname: string) {
+  if (fs.existsSync(pathname)) {
+    return;
+  }
+  const payload: AuthProfileStore = {
+    version: AUTH_STORE_VERSION,
+    profiles: {},
+  };
+  saveJsonFile(pathname, payload);
+}

src/agents/auth-profiles/profiles.ts

@@ -0,0 +1,92 @@
+import type { AuthProfileCredential, AuthProfileStore } from "./types.js";
+import { normalizeProviderId } from "../model-selection.js";
+import {
+  ensureAuthProfileStore,
+  saveAuthProfileStore,
+  updateAuthProfileStoreWithLock,
+} from "./store.js";
+
+export async function setAuthProfileOrder(params: {
+  agentDir?: string;
+  provider: string;
+  order?: string[] | null;
+}): Promise<AuthProfileStore | null> {
+  const providerKey = normalizeProviderId(params.provider);
+  const sanitized =
+    params.order && Array.isArray(params.order)
+      ? params.order.map((entry) => String(entry).trim()).filter(Boolean)
+      : [];
+
+  const deduped: string[] = [];
+  for (const entry of sanitized) {
+    if (!deduped.includes(entry)) {
+      deduped.push(entry);
+    }
+  }
+
+  return await updateAuthProfileStoreWithLock({
+    agentDir: params.agentDir,
+    updater: (store) => {
+      store.order = store.order ?? {};
+      if (deduped.length === 0) {
+        if (!store.order[providerKey]) {
+          return false;
+        }
+        delete store.order[providerKey];
+        if (Object.keys(store.order).length === 0) {
+          store.order = undefined;
+        }
+        return true;
+      }
+      store.order[providerKey] = deduped;
+      return true;
+    },
+  });
+}
+
+export function upsertAuthProfile(params: {
+  profileId: string;
+  credential: AuthProfileCredential;
+  agentDir?: string;
+}): void {
+  const store = ensureAuthProfileStore(params.agentDir);
+  store.profiles[params.profileId] = params.credential;
+  saveAuthProfileStore(store, params.agentDir);
+}
+
+export function listProfilesForProvider(store: AuthProfileStore, provider: string): string[] {
+  const providerKey = normalizeProviderId(provider);
+  return Object.entries(store.profiles)
+    .filter(([, cred]) => normalizeProviderId(cred.provider) === providerKey)
+    .map(([id]) => id);
+}
+
+export async function markAuthProfileGood(params: {
+  store: AuthProfileStore;
+  provider: string;
+  profileId: string;
+  agentDir?: string;
+}): Promise<void> {
+  const { store, provider, profileId, agentDir } = params;
+  const updated = await updateAuthProfileStoreWithLock({
+    agentDir,
+    updater: (freshStore) => {
+      const profile = freshStore.profiles[profileId];
+      if (!profile || profile.provider !== provider) {
+        return false;
+      }
+      freshStore.lastGood = { ...freshStore.lastGood, [provider]: profileId };
+      return true;
+    },
+  });
+  if (updated) {
+    store.lastGood = updated.lastGood;
+    return;
+  }
+  const profile = store.profiles[profileId];
+  if (!profile || profile.provider !== provider) {
+    return;
+  }
+  store.lastGood = { ...store.lastGood, [provider]: profileId };
+  saveAuthProfileStore(store, agentDir);
+}

src/agents/auth-profiles/repair.ts

@@ -0,0 +1,169 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileConfig } from "../../config/types.js";
+import type { AuthProfileIdRepairResult, AuthProfileStore } from "./types.js";
+import { normalizeProviderId } from "../model-selection.js";
+import { listProfilesForProvider } from "./profiles.js";
+
+function getProfileSuffix(profileId: string): string {
+  const idx = profileId.indexOf(":");
+  if (idx < 0) {
+    return "";
+  }
+  return profileId.slice(idx + 1);
+}
+
+function isEmailLike(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return trimmed.includes("@") && trimmed.includes(".");
+}
+
+export function suggestOAuthProfileIdForLegacyDefault(params: {
+  cfg?: OpenClawConfig;
+  store: AuthProfileStore;
+  provider: string;
+  legacyProfileId: string;
+}): string | null {
+  const providerKey = normalizeProviderId(params.provider);
+  const legacySuffix = getProfileSuffix(params.legacyProfileId);
+  if (legacySuffix !== "default") {
+    return null;
+  }
+
+  const legacyCfg = params.cfg?.auth?.profiles?.[params.legacyProfileId];
+  if (
+    legacyCfg &&
+    normalizeProviderId(legacyCfg.provider) === providerKey &&
+    legacyCfg.mode !== "oauth"
+  ) {
+    return null;
+  }
+
+  const oauthProfiles = listProfilesForProvider(params.store, providerKey).filter(
+    (id) => params.store.profiles[id]?.type === "oauth",
+  );
+  if (oauthProfiles.length === 0) {
+    return null;
+  }
+
+  const configuredEmail = legacyCfg?.email?.trim();
+  if (configuredEmail) {
+    const byEmail = oauthProfiles.find((id) => {
+      const cred = params.store.profiles[id];
+      if (!cred || cred.type !== "oauth") {
+        return false;
+      }
+      const email = cred.email?.trim();
+      return email === configuredEmail || id === `${providerKey}:${configuredEmail}`;
+    });
+    if (byEmail) {
+      return byEmail;
+    }
+  }
+
+  const lastGood = params.store.lastGood?.[providerKey] ?? params.store.lastGood?.[params.provider];
+  if (lastGood && oauthProfiles.includes(lastGood)) {
+    return lastGood;
+  }
+
+  const nonLegacy = oauthProfiles.filter((id) => id !== params.legacyProfileId);
+  if (nonLegacy.length === 1) {
+    return nonLegacy[0] ?? null;
+  }
+
+  const emailLike = nonLegacy.filter((id) => isEmailLike(getProfileSuffix(id)));
+  if (emailLike.length === 1) {
+    return emailLike[0] ?? null;
+  }
+
+  return null;
+}
+
+export function repairOAuthProfileIdMismatch(params: {
+  cfg: OpenClawConfig;
+  store: AuthProfileStore;
+  provider: string;
+  legacyProfileId?: string;
+}): AuthProfileIdRepairResult {
+  const legacyProfileId =
+    params.legacyProfileId ?? `${normalizeProviderId(params.provider)}:default`;
+  const legacyCfg = params.cfg.auth?.profiles?.[legacyProfileId];
+  if (!legacyCfg) {
+    return { config: params.cfg, changes: [], migrated: false };
+  }
+  if (legacyCfg.mode !== "oauth") {
+    return { config: params.cfg, changes: [], migrated: false };
+  }
+  if (normalizeProviderId(legacyCfg.provider) !== normalizeProviderId(params.provider)) {
+    return { config: params.cfg, changes: [], migrated: false };
+  }
+
+  const toProfileId = suggestOAuthProfileIdForLegacyDefault({
+    cfg: params.cfg,
+    store: params.store,
+    provider: params.provider,
+    legacyProfileId,
+  });
+  if (!toProfileId || toProfileId === legacyProfileId) {
+    return { config: params.cfg, changes: [], migrated: false };
+  }
+
+  const toCred = params.store.profiles[toProfileId];
+  const toEmail = toCred?.type === "oauth" ? toCred.email?.trim() : undefined;
+
+  const nextProfiles = {
+    ...params.cfg.auth?.profiles,
+  } as Record<string, AuthProfileConfig>;
+  delete nextProfiles[legacyProfileId];
+  nextProfiles[toProfileId] = {
+    ...legacyCfg,
+    ...(toEmail ? { email: toEmail } : {}),
+  };
+
+  const providerKey = normalizeProviderId(params.provider);
+  const nextOrder = (() => {
+    const order = params.cfg.auth?.order;
+    if (!order) {
+      return undefined;
+    }
+    const resolvedKey = Object.keys(order).find((key) => normalizeProviderId(key) === providerKey);
+    if (!resolvedKey) {
+      return order;
+    }
+    const existing = order[resolvedKey];
+    if (!Array.isArray(existing)) {
+      return order;
+    }
+    const replaced = existing
+      .map((id) => (id === legacyProfileId ? toProfileId : id))
+      .filter((id): id is string => typeof id === "string" && id.trim().length > 0);
+    const deduped: string[] = [];
+    for (const entry of replaced) {
+      if (!deduped.includes(entry)) {
+        deduped.push(entry);
+      }
+    }
+    return { ...order, [resolvedKey]: deduped };
+  })();
+
+  const nextCfg: OpenClawConfig = {
+    ...params.cfg,
+    auth: {
+      ...params.cfg.auth,
+      profiles: nextProfiles,
+      ...(nextOrder ? { order: nextOrder } : {}),
+    },
+  };
+
+  const changes = [`Auth: migrate ${legacyProfileId} → ${toProfileId} (OAuth profile id)`];
+
+  return {
+    config: nextCfg,
+    changes,
+    migrated: true,
+    fromProfileId: legacyProfileId,
+    toProfileId,
+  };
+}

src/agents/auth-profiles/session-override.test.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { resolveSessionAuthProfileOverride } from "./session-override.js";
+
+async function writeAuthStore(agentDir: string) {
+  const authPath = path.join(agentDir, "auth-profiles.json");
+  const payload = {
+    version: 1,
+    profiles: {
+      "zai:work": { type: "api_key", provider: "zai", key: "sk-test" },
+    },
+    order: {
+      zai: ["zai:work"],
+    },
+  };
+  await fs.writeFile(authPath, JSON.stringify(payload), "utf-8");
+}
+
+describe("resolveSessionAuthProfileOverride", () => {
+  it("keeps user override when provider alias differs", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-auth-"));
+    const prevStateDir = process.env.OPENCLAW_STATE_DIR;
+    process.env.OPENCLAW_STATE_DIR = tmpDir;
+    try {
+      const agentDir = path.join(tmpDir, "agent");
+      await fs.mkdir(agentDir, { recursive: true });
+      await writeAuthStore(agentDir);
+
+      const sessionEntry: SessionEntry = {
+        sessionId: "s1",
+        updatedAt: Date.now(),
+        authProfileOverride: "zai:work",
+        authProfileOverrideSource: "user",
+      };
+      const sessionStore = { "agent:main:main": sessionEntry };
+
+      const resolved = await resolveSessionAuthProfileOverride({
+        cfg: {} as OpenClawConfig,
+        provider: "z.ai",
+        agentDir,
+        sessionEntry,
+        sessionStore,
+        sessionKey: "agent:main:main",
+        storePath: undefined,
+        isNewSession: false,
+      });
+
+      expect(resolved).toBe("zai:work");
+      expect(sessionEntry.authProfileOverride).toBe("zai:work");
+    } finally {
+      if (prevStateDir === undefined) {
+        delete process.env.OPENCLAW_STATE_DIR;
+      } else {
+        process.env.OPENCLAW_STATE_DIR = prevStateDir;
+      }
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

src/agents/auth-profiles/session-override.ts

@@ -0,0 +1,151 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import { updateSessionStore, type SessionEntry } from "../../config/sessions.js";
+import {
+  ensureAuthProfileStore,
+  isProfileInCooldown,
+  resolveAuthProfileOrder,
+} from "../auth-profiles.js";
+import { normalizeProviderId } from "../model-selection.js";
+
+function isProfileForProvider(params: {
+  provider: string;
+  profileId: string;
+  store: ReturnType<typeof ensureAuthProfileStore>;
+}): boolean {
+  const entry = params.store.profiles[params.profileId];
+  if (!entry?.provider) {
+    return false;
+  }
+  return normalizeProviderId(entry.provider) === normalizeProviderId(params.provider);
+}
+
+export async function clearSessionAuthProfileOverride(params: {
+  sessionEntry: SessionEntry;
+  sessionStore: Record<string, SessionEntry>;
+  sessionKey: string;
+  storePath?: string;
+}) {
+  const { sessionEntry, sessionStore, sessionKey, storePath } = params;
+  delete sessionEntry.authProfileOverride;
+  delete sessionEntry.authProfileOverrideSource;
+  delete sessionEntry.authProfileOverrideCompactionCount;
+  sessionEntry.updatedAt = Date.now();
+  sessionStore[sessionKey] = sessionEntry;
+  if (storePath) {
+    await updateSessionStore(storePath, (store) => {
+      store[sessionKey] = sessionEntry;
+    });
+  }
+}
+
+export async function resolveSessionAuthProfileOverride(params: {
+  cfg: OpenClawConfig;
+  provider: string;
+  agentDir: string;
+  sessionEntry?: SessionEntry;
+  sessionStore?: Record<string, SessionEntry>;
+  sessionKey?: string;
+  storePath?: string;
+  isNewSession: boolean;
+}): Promise<string | undefined> {
+  const {
+    cfg,
+    provider,
+    agentDir,
+    sessionEntry,
+    sessionStore,
+    sessionKey,
+    storePath,
+    isNewSession,
+  } = params;
+  if (!sessionEntry || !sessionStore || !sessionKey) {
+    return sessionEntry?.authProfileOverride;
+  }
+
+  const store = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
+  const order = resolveAuthProfileOrder({ cfg, store, provider });
+  let current = sessionEntry.authProfileOverride?.trim();
+
+  if (current && !store.profiles[current]) {
+    await clearSessionAuthProfileOverride({ sessionEntry, sessionStore, sessionKey, storePath });
+    current = undefined;
+  }
+
+  if (current && !isProfileForProvider({ provider, profileId: current, store })) {
+    await clearSessionAuthProfileOverride({ sessionEntry, sessionStore, sessionKey, storePath });
+    current = undefined;
+  }
+
+  if (current && order.length > 0 && !order.includes(current)) {
+    await clearSessionAuthProfileOverride({ sessionEntry, sessionStore, sessionKey, storePath });
+    current = undefined;
+  }
+
+  if (order.length === 0) {
+    return undefined;
+  }
+
+  const pickFirstAvailable = () =>
+    order.find((profileId) => !isProfileInCooldown(store, profileId)) ?? order[0];
+  const pickNextAvailable = (active: string) => {
+    const startIndex = order.indexOf(active);
+    if (startIndex < 0) {
+      return pickFirstAvailable();
+    }
+    for (let offset = 1; offset <= order.length; offset += 1) {
+      const candidate = order[(startIndex + offset) % order.length];
+      if (!isProfileInCooldown(store, candidate)) {
+        return candidate;
+      }
+    }
+    return order[startIndex] ?? order[0];
+  };
+
+  const compactionCount = sessionEntry.compactionCount ?? 0;
+  const storedCompaction =
+    typeof sessionEntry.authProfileOverrideCompactionCount === "number"
+      ? sessionEntry.authProfileOverrideCompactionCount
+      : compactionCount;
+
+  const source =
+    sessionEntry.authProfileOverrideSource ??
+    (typeof sessionEntry.authProfileOverrideCompactionCount === "number"
+      ? "auto"
+      : current
+        ? "user"
+        : undefined);
+  if (source === "user" && current && !isNewSession) {
+    return current;
+  }
+
+  let next = current;
+  if (isNewSession) {
+    next = current ? pickNextAvailable(current) : pickFirstAvailable();
+  } else if (current && compactionCount > storedCompaction) {
+    next = pickNextAvailable(current);
+  } else if (!current || isProfileInCooldown(store, current)) {
+    next = pickFirstAvailable();
+  }
+
+  if (!next) {
+    return current;
+  }
+  const shouldPersist =
+    next !== sessionEntry.authProfileOverride ||
+    sessionEntry.authProfileOverrideSource !== "auto" ||
+    sessionEntry.authProfileOverrideCompactionCount !== compactionCount;
+  if (shouldPersist) {
+    sessionEntry.authProfileOverride = next;
+    sessionEntry.authProfileOverrideSource = "auto";
+    sessionEntry.authProfileOverrideCompactionCount = compactionCount;
+    sessionEntry.updatedAt = Date.now();
+    sessionStore[sessionKey] = sessionEntry;
+    if (storePath) {
+      await updateSessionStore(storePath, (store) => {
+        store[sessionKey] = sessionEntry;
+      });
+    }
+  }
+
+  return next;
+}

src/agents/auth-profiles/store.ts

@@ -0,0 +1,378 @@
+import type { OAuthCredentials } from "@mariozechner/pi-ai";
+import fs from "node:fs";
+import lockfile from "proper-lockfile";
+import type { AuthProfileCredential, AuthProfileStore, ProfileUsageStats } from "./types.js";
+import { resolveOAuthPath } from "../../config/paths.js";
+import { loadJsonFile, saveJsonFile } from "../../infra/json-file.js";
+import { AUTH_STORE_LOCK_OPTIONS, AUTH_STORE_VERSION, log } from "./constants.js";
+import { syncExternalCliCredentials } from "./external-cli-sync.js";
+import { ensureAuthStoreFile, resolveAuthStorePath, resolveLegacyAuthStorePath } from "./paths.js";
+
+type LegacyAuthStore = Record<string, AuthProfileCredential>;
+
+function _syncAuthProfileStore(target: AuthProfileStore, source: AuthProfileStore): void {
+  target.version = source.version;
+  target.profiles = source.profiles;
+  target.order = source.order;
+  target.lastGood = source.lastGood;
+  target.usageStats = source.usageStats;
+}
+
+export async function updateAuthProfileStoreWithLock(params: {
+  agentDir?: string;
+  updater: (store: AuthProfileStore) => boolean;
+}): Promise<AuthProfileStore | null> {
+  const authPath = resolveAuthStorePath(params.agentDir);
+  ensureAuthStoreFile(authPath);
+
+  let release: (() => Promise<void>) | undefined;
+  try {
+    release = await lockfile.lock(authPath, AUTH_STORE_LOCK_OPTIONS);
+    const store = ensureAuthProfileStore(params.agentDir);
+    const shouldSave = params.updater(store);
+    if (shouldSave) {
+      saveAuthProfileStore(store, params.agentDir);
+    }
+    return store;
+  } catch {
+    return null;
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch {
+        // ignore unlock errors
+      }
+    }
+  }
+}
+
+function coerceLegacyStore(raw: unknown): LegacyAuthStore | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  if ("profiles" in record) {
+    return null;
+  }
+  const entries: LegacyAuthStore = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (!value || typeof value !== "object") {
+      continue;
+    }
+    const typed = value as Partial<AuthProfileCredential>;
+    if (typed.type !== "api_key" && typed.type !== "oauth" && typed.type !== "token") {
+      continue;
+    }
+    entries[key] = {
+      ...typed,
+      provider: String(typed.provider ?? key),
+    } as AuthProfileCredential;
+  }
+  return Object.keys(entries).length > 0 ? entries : null;
+}
+
+function coerceAuthStore(raw: unknown): AuthProfileStore | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const record = raw as Record<string, unknown>;
+  if (!record.profiles || typeof record.profiles !== "object") {
+    return null;
+  }
+  const profiles = record.profiles as Record<string, unknown>;
+  const normalized: Record<string, AuthProfileCredential> = {};
+  for (const [key, value] of Object.entries(profiles)) {
+    if (!value || typeof value !== "object") {
+      continue;
+    }
+    const typed = value as Partial<AuthProfileCredential>;
+    if (typed.type !== "api_key" && typed.type !== "oauth" && typed.type !== "token") {
+      continue;
+    }
+    if (!typed.provider) {
+      continue;
+    }
+    normalized[key] = typed as AuthProfileCredential;
+  }
+  const order =
+    record.order && typeof record.order === "object"
+      ? Object.entries(record.order as Record<string, unknown>).reduce(
+          (acc, [provider, value]) => {
+            if (!Array.isArray(value)) {
+              return acc;
+            }
+            const list = value
+              .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+              .filter(Boolean);
+            if (list.length === 0) {
+              return acc;
+            }
+            acc[provider] = list;
+            return acc;
+          },
+          {} as Record<string, string[]>,
+        )
+      : undefined;
+  return {
+    version: Number(record.version ?? AUTH_STORE_VERSION),
+    profiles: normalized,
+    order,
+    lastGood:
+      record.lastGood && typeof record.lastGood === "object"
+        ? (record.lastGood as Record<string, string>)
+        : undefined,
+    usageStats:
+      record.usageStats && typeof record.usageStats === "object"
+        ? (record.usageStats as Record<string, ProfileUsageStats>)
+        : undefined,
+  };
+}
+
+function mergeRecord<T>(
+  base?: Record<string, T>,
+  override?: Record<string, T>,
+): Record<string, T> | undefined {
+  if (!base && !override) {
+    return undefined;
+  }
+  if (!base) {
+    return { ...override };
+  }
+  if (!override) {
+    return { ...base };
+  }
+  return { ...base, ...override };
+}
+
+function mergeAuthProfileStores(
+  base: AuthProfileStore,
+  override: AuthProfileStore,
+): AuthProfileStore {
+  if (
+    Object.keys(override.profiles).length === 0 &&
+    !override.order &&
+    !override.lastGood &&
+    !override.usageStats
+  ) {
+    return base;
+  }
+  return {
+    version: Math.max(base.version, override.version ?? base.version),
+    profiles: { ...base.profiles, ...override.profiles },
+    order: mergeRecord(base.order, override.order),
+    lastGood: mergeRecord(base.lastGood, override.lastGood),
+    usageStats: mergeRecord(base.usageStats, override.usageStats),
+  };
+}
+
+function mergeOAuthFileIntoStore(store: AuthProfileStore): boolean {
+  const oauthPath = resolveOAuthPath();
+  const oauthRaw = loadJsonFile(oauthPath);
+  if (!oauthRaw || typeof oauthRaw !== "object") {
+    return false;
+  }
+  const oauthEntries = oauthRaw as Record<string, OAuthCredentials>;
+  let mutated = false;
+  for (const [provider, creds] of Object.entries(oauthEntries)) {
+    if (!creds || typeof creds !== "object") {
+      continue;
+    }
+    const profileId = `${provider}:default`;
+    if (store.profiles[profileId]) {
+      continue;
+    }
+    store.profiles[profileId] = {
+      type: "oauth",
+      provider,
+      ...creds,
+    };
+    mutated = true;
+  }
+  return mutated;
+}
+
+export function loadAuthProfileStore(): AuthProfileStore {
+  const authPath = resolveAuthStorePath();
+  const raw = loadJsonFile(authPath);
+  const asStore = coerceAuthStore(raw);
+  if (asStore) {
+    // Sync from external CLI tools on every load
+    const synced = syncExternalCliCredentials(asStore);
+    if (synced) {
+      saveJsonFile(authPath, asStore);
+    }
+    return asStore;
+  }
+
+  const legacyRaw = loadJsonFile(resolveLegacyAuthStorePath());
+  const legacy = coerceLegacyStore(legacyRaw);
+  if (legacy) {
+    const store: AuthProfileStore = {
+      version: AUTH_STORE_VERSION,
+      profiles: {},
+    };
+    for (const [provider, cred] of Object.entries(legacy)) {
+      const profileId = `${provider}:default`;
+      if (cred.type === "api_key") {
+        store.profiles[profileId] = {
+          type: "api_key",
+          provider: String(cred.provider ?? provider),
+          key: cred.key,
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      } else if (cred.type === "token") {
+        store.profiles[profileId] = {
+          type: "token",
+          provider: String(cred.provider ?? provider),
+          token: cred.token,
+          ...(typeof cred.expires === "number" ? { expires: cred.expires } : {}),
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      } else {
+        store.profiles[profileId] = {
+          type: "oauth",
+          provider: String(cred.provider ?? provider),
+          access: cred.access,
+          refresh: cred.refresh,
+          expires: cred.expires,
+          ...(cred.enterpriseUrl ? { enterpriseUrl: cred.enterpriseUrl } : {}),
+          ...(cred.projectId ? { projectId: cred.projectId } : {}),
+          ...(cred.accountId ? { accountId: cred.accountId } : {}),
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      }
+    }
+    syncExternalCliCredentials(store);
+    return store;
+  }
+
+  const store: AuthProfileStore = { version: AUTH_STORE_VERSION, profiles: {} };
+  syncExternalCliCredentials(store);
+  return store;
+}
+
+function loadAuthProfileStoreForAgent(
+  agentDir?: string,
+  _options?: { allowKeychainPrompt?: boolean },
+): AuthProfileStore {
+  const authPath = resolveAuthStorePath(agentDir);
+  const raw = loadJsonFile(authPath);
+  const asStore = coerceAuthStore(raw);
+  if (asStore) {
+    // Sync from external CLI tools on every load
+    const synced = syncExternalCliCredentials(asStore);
+    if (synced) {
+      saveJsonFile(authPath, asStore);
+    }
+    return asStore;
+  }
+
+  // Fallback: inherit auth-profiles from main agent if subagent has none
+  if (agentDir) {
+    const mainAuthPath = resolveAuthStorePath(); // without agentDir = main
+    const mainRaw = loadJsonFile(mainAuthPath);
+    const mainStore = coerceAuthStore(mainRaw);
+    if (mainStore && Object.keys(mainStore.profiles).length > 0) {
+      // Clone main store to subagent directory for auth inheritance
+      saveJsonFile(authPath, mainStore);
+      log.info("inherited auth-profiles from main agent", { agentDir });
+      return mainStore;
+    }
+  }
+
+  const legacyRaw = loadJsonFile(resolveLegacyAuthStorePath(agentDir));
+  const legacy = coerceLegacyStore(legacyRaw);
+  const store: AuthProfileStore = {
+    version: AUTH_STORE_VERSION,
+    profiles: {},
+  };
+  if (legacy) {
+    for (const [provider, cred] of Object.entries(legacy)) {
+      const profileId = `${provider}:default`;
+      if (cred.type === "api_key") {
+        store.profiles[profileId] = {
+          type: "api_key",
+          provider: String(cred.provider ?? provider),
+          key: cred.key,
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      } else if (cred.type === "token") {
+        store.profiles[profileId] = {
+          type: "token",
+          provider: String(cred.provider ?? provider),
+          token: cred.token,
+          ...(typeof cred.expires === "number" ? { expires: cred.expires } : {}),
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      } else {
+        store.profiles[profileId] = {
+          type: "oauth",
+          provider: String(cred.provider ?? provider),
+          access: cred.access,
+          refresh: cred.refresh,
+          expires: cred.expires,
+          ...(cred.enterpriseUrl ? { enterpriseUrl: cred.enterpriseUrl } : {}),
+          ...(cred.projectId ? { projectId: cred.projectId } : {}),
+          ...(cred.accountId ? { accountId: cred.accountId } : {}),
+          ...(cred.email ? { email: cred.email } : {}),
+        };
+      }
+    }
+  }
+
+  const mergedOAuth = mergeOAuthFileIntoStore(store);
+  const syncedCli = syncExternalCliCredentials(store);
+  const shouldWrite = legacy !== null || mergedOAuth || syncedCli;
+  if (shouldWrite) {
+    saveJsonFile(authPath, store);
+  }
+
+  // PR #368: legacy auth.json could get re-migrated from other agent dirs,
+  // overwriting fresh OAuth creds with stale tokens (fixes #363). Delete only
+  // after we've successfully written auth-profiles.json.
+  if (shouldWrite && legacy !== null) {
+    const legacyPath = resolveLegacyAuthStorePath(agentDir);
+    try {
+      fs.unlinkSync(legacyPath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
+        log.warn("failed to delete legacy auth.json after migration", {
+          err,
+          legacyPath,
+        });
+      }
+    }
+  }
+
+  return store;
+}
+
+export function ensureAuthProfileStore(
+  agentDir?: string,
+  options?: { allowKeychainPrompt?: boolean },
+): AuthProfileStore {
+  const store = loadAuthProfileStoreForAgent(agentDir, options);
+  const authPath = resolveAuthStorePath(agentDir);
+  const mainAuthPath = resolveAuthStorePath();
+  if (!agentDir || authPath === mainAuthPath) {
+    return store;
+  }
+
+  const mainStore = loadAuthProfileStoreForAgent(undefined, options);
+  const merged = mergeAuthProfileStores(mainStore, store);
+
+  return merged;
+}
+
+export function saveAuthProfileStore(store: AuthProfileStore, agentDir?: string): void {
+  const authPath = resolveAuthStorePath(agentDir);
+  const payload = {
+    version: AUTH_STORE_VERSION,
+    profiles: store.profiles,
+    order: store.order ?? undefined,
+    lastGood: store.lastGood ?? undefined,
+    usageStats: store.usageStats ?? undefined,
+  } satisfies AuthProfileStore;
+  saveJsonFile(authPath, payload);
+}

src/agents/auth-profiles/types.ts

@@ -0,0 +1,72 @@
+import type { OAuthCredentials } from "@mariozechner/pi-ai";
+import type { OpenClawConfig } from "../../config/config.js";
+
+export type ApiKeyCredential = {
+  type: "api_key";
+  provider: string;
+  key: string;
+  email?: string;
+};
+
+export type TokenCredential = {
+  /**
+   * Static bearer-style token (often OAuth access token / PAT).
+   * Not refreshable by OpenClaw (unlike `type: "oauth"`).
+   */
+  type: "token";
+  provider: string;
+  token: string;
+  /** Optional expiry timestamp (ms since epoch). */
+  expires?: number;
+  email?: string;
+};
+
+export type OAuthCredential = OAuthCredentials & {
+  type: "oauth";
+  provider: string;
+  clientId?: string;
+  email?: string;
+};
+
+export type AuthProfileCredential = ApiKeyCredential | TokenCredential | OAuthCredential;
+
+export type AuthProfileFailureReason =
+  | "auth"
+  | "format"
+  | "rate_limit"
+  | "billing"
+  | "timeout"
+  | "unknown";
+
+/** Per-profile usage statistics for round-robin and cooldown tracking */
+export type ProfileUsageStats = {
+  lastUsed?: number;
+  cooldownUntil?: number;
+  disabledUntil?: number;
+  disabledReason?: AuthProfileFailureReason;
+  errorCount?: number;
+  failureCounts?: Partial<Record<AuthProfileFailureReason, number>>;
+  lastFailureAt?: number;
+};
+
+export type AuthProfileStore = {
+  version: number;
+  profiles: Record<string, AuthProfileCredential>;
+  /**
+   * Optional per-agent preferred profile order overrides.
+   * This lets you lock/override auth rotation for a specific agent without
+   * changing the global config.
+   */
+  order?: Record<string, string[]>;
+  lastGood?: Record<string, string>;
+  /** Usage statistics per profile for round-robin rotation */
+  usageStats?: Record<string, ProfileUsageStats>;
+};
+
+export type AuthProfileIdRepairResult = {
+  config: OpenClawConfig;
+  changes: string[];
+  migrated: boolean;
+  fromProfileId?: string;
+  toProfileId?: string;
+};

src/agents/auth-profiles/usage.ts

@@ -0,0 +1,322 @@
+import type { OpenClawConfig } from "../../config/config.js";
+import type { AuthProfileFailureReason, AuthProfileStore, ProfileUsageStats } from "./types.js";
+import { normalizeProviderId } from "../model-selection.js";
+import { saveAuthProfileStore, updateAuthProfileStoreWithLock } from "./store.js";
+
+function resolveProfileUnusableUntil(stats: ProfileUsageStats): number | null {
+  const values = [stats.cooldownUntil, stats.disabledUntil]
+    .filter((value): value is number => typeof value === "number")
+    .filter((value) => Number.isFinite(value) && value > 0);
+  if (values.length === 0) {
+    return null;
+  }
+  return Math.max(...values);
+}
+
+/**
+ * Check if a profile is currently in cooldown (due to rate limiting or errors).
+ */
+export function isProfileInCooldown(store: AuthProfileStore, profileId: string): boolean {
+  const stats = store.usageStats?.[profileId];
+  if (!stats) {
+    return false;
+  }
+  const unusableUntil = resolveProfileUnusableUntil(stats);
+  return unusableUntil ? Date.now() < unusableUntil : false;
+}
+
+/**
+ * Mark a profile as successfully used. Resets error count and updates lastUsed.
+ * Uses store lock to avoid overwriting concurrent usage updates.
+ */
+export async function markAuthProfileUsed(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  agentDir?: string;
+}): Promise<void> {
+  const { store, profileId, agentDir } = params;
+  const updated = await updateAuthProfileStoreWithLock({
+    agentDir,
+    updater: (freshStore) => {
+      if (!freshStore.profiles[profileId]) {
+        return false;
+      }
+      freshStore.usageStats = freshStore.usageStats ?? {};
+      freshStore.usageStats[profileId] = {
+        ...freshStore.usageStats[profileId],
+        lastUsed: Date.now(),
+        errorCount: 0,
+        cooldownUntil: undefined,
+        disabledUntil: undefined,
+        disabledReason: undefined,
+        failureCounts: undefined,
+      };
+      return true;
+    },
+  });
+  if (updated) {
+    store.usageStats = updated.usageStats;
+    return;
+  }
+  if (!store.profiles[profileId]) {
+    return;
+  }
+
+  store.usageStats = store.usageStats ?? {};
+  store.usageStats[profileId] = {
+    ...store.usageStats[profileId],
+    lastUsed: Date.now(),
+    errorCount: 0,
+    cooldownUntil: undefined,
+    disabledUntil: undefined,
+    disabledReason: undefined,
+    failureCounts: undefined,
+  };
+  saveAuthProfileStore(store, agentDir);
+}
+
+export function calculateAuthProfileCooldownMs(errorCount: number): number {
+  const normalized = Math.max(1, errorCount);
+  return Math.min(
+    60 * 60 * 1000, // 1 hour max
+    60 * 1000 * 5 ** Math.min(normalized - 1, 3),
+  );
+}
+
+type ResolvedAuthCooldownConfig = {
+  billingBackoffMs: number;
+  billingMaxMs: number;
+  failureWindowMs: number;
+};
+
+function resolveAuthCooldownConfig(params: {
+  cfg?: OpenClawConfig;
+  providerId: string;
+}): ResolvedAuthCooldownConfig {
+  const defaults = {
+    billingBackoffHours: 5,
+    billingMaxHours: 24,
+    failureWindowHours: 24,
+  } as const;
+
+  const resolveHours = (value: unknown, fallback: number) =>
+    typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+
+  const cooldowns = params.cfg?.auth?.cooldowns;
+  const billingOverride = (() => {
+    const map = cooldowns?.billingBackoffHoursByProvider;
+    if (!map) {
+      return undefined;
+    }
+    for (const [key, value] of Object.entries(map)) {
+      if (normalizeProviderId(key) === params.providerId) {
+        return value;
+      }
+    }
+    return undefined;
+  })();
+
+  const billingBackoffHours = resolveHours(
+    billingOverride ?? cooldowns?.billingBackoffHours,
+    defaults.billingBackoffHours,
+  );
+  const billingMaxHours = resolveHours(cooldowns?.billingMaxHours, defaults.billingMaxHours);
+  const failureWindowHours = resolveHours(
+    cooldowns?.failureWindowHours,
+    defaults.failureWindowHours,
+  );
+
+  return {
+    billingBackoffMs: billingBackoffHours * 60 * 60 * 1000,
+    billingMaxMs: billingMaxHours * 60 * 60 * 1000,
+    failureWindowMs: failureWindowHours * 60 * 60 * 1000,
+  };
+}
+
+function calculateAuthProfileBillingDisableMsWithConfig(params: {
+  errorCount: number;
+  baseMs: number;
+  maxMs: number;
+}): number {
+  const normalized = Math.max(1, params.errorCount);
+  const baseMs = Math.max(60_000, params.baseMs);
+  const maxMs = Math.max(baseMs, params.maxMs);
+  const exponent = Math.min(normalized - 1, 10);
+  const raw = baseMs * 2 ** exponent;
+  return Math.min(maxMs, raw);
+}
+
+export function resolveProfileUnusableUntilForDisplay(
+  store: AuthProfileStore,
+  profileId: string,
+): number | null {
+  const stats = store.usageStats?.[profileId];
+  if (!stats) {
+    return null;
+  }
+  return resolveProfileUnusableUntil(stats);
+}
+
+function computeNextProfileUsageStats(params: {
+  existing: ProfileUsageStats;
+  now: number;
+  reason: AuthProfileFailureReason;
+  cfgResolved: ResolvedAuthCooldownConfig;
+}): ProfileUsageStats {
+  const windowMs = params.cfgResolved.failureWindowMs;
+  const windowExpired =
+    typeof params.existing.lastFailureAt === "number" &&
+    params.existing.lastFailureAt > 0 &&
+    params.now - params.existing.lastFailureAt > windowMs;
+
+  const baseErrorCount = windowExpired ? 0 : (params.existing.errorCount ?? 0);
+  const nextErrorCount = baseErrorCount + 1;
+  const failureCounts = windowExpired ? {} : { ...params.existing.failureCounts };
+  failureCounts[params.reason] = (failureCounts[params.reason] ?? 0) + 1;
+
+  const updatedStats: ProfileUsageStats = {
+    ...params.existing,
+    errorCount: nextErrorCount,
+    failureCounts,
+    lastFailureAt: params.now,
+  };
+
+  if (params.reason === "billing") {
+    const billingCount = failureCounts.billing ?? 1;
+    const backoffMs = calculateAuthProfileBillingDisableMsWithConfig({
+      errorCount: billingCount,
+      baseMs: params.cfgResolved.billingBackoffMs,
+      maxMs: params.cfgResolved.billingMaxMs,
+    });
+    updatedStats.disabledUntil = params.now + backoffMs;
+    updatedStats.disabledReason = "billing";
+  } else {
+    const backoffMs = calculateAuthProfileCooldownMs(nextErrorCount);
+    updatedStats.cooldownUntil = params.now + backoffMs;
+  }
+
+  return updatedStats;
+}
+
+/**
+ * Mark a profile as failed for a specific reason. Billing failures are treated
+ * as "disabled" (longer backoff) vs the regular cooldown window.
+ */
+export async function markAuthProfileFailure(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  reason: AuthProfileFailureReason;
+  cfg?: OpenClawConfig;
+  agentDir?: string;
+}): Promise<void> {
+  const { store, profileId, reason, agentDir, cfg } = params;
+  const updated = await updateAuthProfileStoreWithLock({
+    agentDir,
+    updater: (freshStore) => {
+      const profile = freshStore.profiles[profileId];
+      if (!profile) {
+        return false;
+      }
+      freshStore.usageStats = freshStore.usageStats ?? {};
+      const existing = freshStore.usageStats[profileId] ?? {};
+
+      const now = Date.now();
+      const providerKey = normalizeProviderId(profile.provider);
+      const cfgResolved = resolveAuthCooldownConfig({
+        cfg,
+        providerId: providerKey,
+      });
+
+      freshStore.usageStats[profileId] = computeNextProfileUsageStats({
+        existing,
+        now,
+        reason,
+        cfgResolved,
+      });
+      return true;
+    },
+  });
+  if (updated) {
+    store.usageStats = updated.usageStats;
+    return;
+  }
+  if (!store.profiles[profileId]) {
+    return;
+  }
+
+  store.usageStats = store.usageStats ?? {};
+  const existing = store.usageStats[profileId] ?? {};
+  const now = Date.now();
+  const providerKey = normalizeProviderId(store.profiles[profileId]?.provider ?? "");
+  const cfgResolved = resolveAuthCooldownConfig({
+    cfg,
+    providerId: providerKey,
+  });
+
+  store.usageStats[profileId] = computeNextProfileUsageStats({
+    existing,
+    now,
+    reason,
+    cfgResolved,
+  });
+  saveAuthProfileStore(store, agentDir);
+}
+
+/**
+ * Mark a profile as failed/rate-limited. Applies exponential backoff cooldown.
+ * Cooldown times: 1min, 5min, 25min, max 1 hour.
+ * Uses store lock to avoid overwriting concurrent usage updates.
+ */
+export async function markAuthProfileCooldown(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  agentDir?: string;
+}): Promise<void> {
+  await markAuthProfileFailure({
+    store: params.store,
+    profileId: params.profileId,
+    reason: "unknown",
+    agentDir: params.agentDir,
+  });
+}
+
+/**
+ * Clear cooldown for a profile (e.g., manual reset).
+ * Uses store lock to avoid overwriting concurrent usage updates.
+ */
+export async function clearAuthProfileCooldown(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  agentDir?: string;
+}): Promise<void> {
+  const { store, profileId, agentDir } = params;
+  const updated = await updateAuthProfileStoreWithLock({
+    agentDir,
+    updater: (freshStore) => {
+      if (!freshStore.usageStats?.[profileId]) {
+        return false;
+      }
+
+      freshStore.usageStats[profileId] = {
+        ...freshStore.usageStats[profileId],
+        errorCount: 0,
+        cooldownUntil: undefined,
+      };
+      return true;
+    },
+  });
+  if (updated) {
+    store.usageStats = updated.usageStats;
+    return;
+  }
+  if (!store.usageStats?.[profileId]) {
+    return;
+  }
+
+  store.usageStats[profileId] = {
+    ...store.usageStats[profileId],
+    errorCount: 0,
+    cooldownUntil: undefined,
+  };
+  saveAuthProfileStore(store, agentDir);
+}

src/agents/bash-process-registry.test.ts

@@ -0,0 +1,180 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { beforeEach, describe, expect, it } from "vitest";
+import type { ProcessSession } from "./bash-process-registry.js";
+import {
+  addSession,
+  appendOutput,
+  drainSession,
+  listFinishedSessions,
+  markBackgrounded,
+  markExited,
+  resetProcessRegistryForTests,
+} from "./bash-process-registry.js";
+
+describe("bash process registry", () => {
+  beforeEach(() => {
+    resetProcessRegistryForTests();
+  });
+
+  it("captures output and truncates", () => {
+    const session: ProcessSession = {
+      id: "sess",
+      command: "echo test",
+      child: { pid: 123 } as ChildProcessWithoutNullStreams,
+      startedAt: Date.now(),
+      cwd: "/tmp",
+      maxOutputChars: 10,
+      pendingMaxOutputChars: 30_000,
+      totalOutputChars: 0,
+      pendingStdout: [],
+      pendingStderr: [],
+      pendingStdoutChars: 0,
+      pendingStderrChars: 0,
+      aggregated: "",
+      tail: "",
+      exited: false,
+      exitCode: undefined,
+      exitSignal: undefined,
+      truncated: false,
+      backgrounded: false,
+    };
+
+    addSession(session);
+    appendOutput(session, "stdout", "0123456789");
+    appendOutput(session, "stdout", "abcdef");
+
+    expect(session.aggregated).toBe("6789abcdef");
+    expect(session.truncated).toBe(true);
+  });
+
+  it("caps pending output to avoid runaway polls", () => {
+    const session: ProcessSession = {
+      id: "sess",
+      command: "echo test",
+      child: { pid: 123 } as ChildProcessWithoutNullStreams,
+      startedAt: Date.now(),
+      cwd: "/tmp",
+      maxOutputChars: 100_000,
+      pendingMaxOutputChars: 20_000,
+      totalOutputChars: 0,
+      pendingStdout: [],
+      pendingStderr: [],
+      pendingStdoutChars: 0,
+      pendingStderrChars: 0,
+      aggregated: "",
+      tail: "",
+      exited: false,
+      exitCode: undefined,
+      exitSignal: undefined,
+      truncated: false,
+      backgrounded: true,
+    };
+
+    addSession(session);
+    const payload = `${"a".repeat(70_000)}${"b".repeat(20_000)}`;
+    appendOutput(session, "stdout", payload);
+
+    const drained = drainSession(session);
+    expect(drained.stdout).toBe("b".repeat(20_000));
+    expect(session.pendingStdout).toHaveLength(0);
+    expect(session.pendingStdoutChars).toBe(0);
+    expect(session.truncated).toBe(true);
+  });
+
+  it("respects max output cap when pending cap is larger", () => {
+    const session: ProcessSession = {
+      id: "sess",
+      command: "echo test",
+      child: { pid: 123 } as ChildProcessWithoutNullStreams,
+      startedAt: Date.now(),
+      cwd: "/tmp",
+      maxOutputChars: 5_000,
+      pendingMaxOutputChars: 30_000,
+      totalOutputChars: 0,
+      pendingStdout: [],
+      pendingStderr: [],
+      pendingStdoutChars: 0,
+      pendingStderrChars: 0,
+      aggregated: "",
+      tail: "",
+      exited: false,
+      exitCode: undefined,
+      exitSignal: undefined,
+      truncated: false,
+      backgrounded: true,
+    };
+
+    addSession(session);
+    appendOutput(session, "stdout", "x".repeat(10_000));
+
+    const drained = drainSession(session);
+    expect(drained.stdout.length).toBe(5_000);
+    expect(session.truncated).toBe(true);
+  });
+
+  it("caps stdout and stderr independently", () => {
+    const session: ProcessSession = {
+      id: "sess",
+      command: "echo test",
+      child: { pid: 123 } as ChildProcessWithoutNullStreams,
+      startedAt: Date.now(),
+      cwd: "/tmp",
+      maxOutputChars: 100,
+      pendingMaxOutputChars: 10,
+      totalOutputChars: 0,
+      pendingStdout: [],
+      pendingStderr: [],
+      pendingStdoutChars: 0,
+      pendingStderrChars: 0,
+      aggregated: "",
+      tail: "",
+      exited: false,
+      exitCode: undefined,
+      exitSignal: undefined,
+      truncated: false,
+      backgrounded: true,
+    };
+
+    addSession(session);
+    appendOutput(session, "stdout", "a".repeat(6));
+    appendOutput(session, "stdout", "b".repeat(6));
+    appendOutput(session, "stderr", "c".repeat(12));
+
+    const drained = drainSession(session);
+    expect(drained.stdout).toBe("a".repeat(4) + "b".repeat(6));
+    expect(drained.stderr).toBe("c".repeat(10));
+    expect(session.truncated).toBe(true);
+  });
+
+  it("only persists finished sessions when backgrounded", () => {
+    const session: ProcessSession = {
+      id: "sess",
+      command: "echo test",
+      child: { pid: 123 } as ChildProcessWithoutNullStreams,
+      startedAt: Date.now(),
+      cwd: "/tmp",
+      maxOutputChars: 100,
+      pendingMaxOutputChars: 30_000,
+      totalOutputChars: 0,
+      pendingStdout: [],
+      pendingStderr: [],
+      pendingStdoutChars: 0,
+      pendingStderrChars: 0,
+      aggregated: "",
+      tail: "",
+      exited: false,
+      exitCode: undefined,
+      exitSignal: undefined,
+      truncated: false,
+      backgrounded: false,
+    };
+
+    addSession(session);
+    markExited(session, 0, null, "completed");
+    expect(listFinishedSessions()).toHaveLength(0);
+
+    markBackgrounded(session);
+    markExited(session, 0, null, "completed");
+    expect(listFinishedSessions()).toHaveLength(1);
+  });
+});

src/agents/bash-process-registry.ts

@@ -0,0 +1,274 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { createSessionSlug as createSessionSlugId } from "./session-slug.js";
+
+const DEFAULT_JOB_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const MIN_JOB_TTL_MS = 60 * 1000; // 1 minute
+const MAX_JOB_TTL_MS = 3 * 60 * 60 * 1000; // 3 hours
+const DEFAULT_PENDING_OUTPUT_CHARS = 30_000;
+
+function clampTtl(value: number | undefined) {
+  if (!value || Number.isNaN(value)) {
+    return DEFAULT_JOB_TTL_MS;
+  }
+  return Math.min(Math.max(value, MIN_JOB_TTL_MS), MAX_JOB_TTL_MS);
+}
+
+let jobTtlMs = clampTtl(Number.parseInt(process.env.PI_BASH_JOB_TTL_MS ?? "", 10));
+
+export type ProcessStatus = "running" | "completed" | "failed" | "killed";
+
+export type SessionStdin = {
+  write: (data: string, cb?: (err?: Error | null) => void) => void;
+  end: () => void;
+  destroyed?: boolean;
+};
+
+export interface ProcessSession {
+  id: string;
+  command: string;
+  scopeKey?: string;
+  sessionKey?: string;
+  notifyOnExit?: boolean;
+  exitNotified?: boolean;
+  child?: ChildProcessWithoutNullStreams;
+  stdin?: SessionStdin;
+  pid?: number;
+  startedAt: number;
+  cwd?: string;
+  maxOutputChars: number;
+  pendingMaxOutputChars?: number;
+  totalOutputChars: number;
+  pendingStdout: string[];
+  pendingStderr: string[];
+  pendingStdoutChars: number;
+  pendingStderrChars: number;
+  aggregated: string;
+  tail: string;
+  exitCode?: number | null;
+  exitSignal?: NodeJS.Signals | number | null;
+  exited: boolean;
+  truncated: boolean;
+  backgrounded: boolean;
+}
+
+export interface FinishedSession {
+  id: string;
+  command: string;
+  scopeKey?: string;
+  startedAt: number;
+  endedAt: number;
+  cwd?: string;
+  status: ProcessStatus;
+  exitCode?: number | null;
+  exitSignal?: NodeJS.Signals | number | null;
+  aggregated: string;
+  tail: string;
+  truncated: boolean;
+  totalOutputChars: number;
+}
+
+const runningSessions = new Map<string, ProcessSession>();
+const finishedSessions = new Map<string, FinishedSession>();
+
+let sweeper: NodeJS.Timeout | null = null;
+
+function isSessionIdTaken(id: string) {
+  return runningSessions.has(id) || finishedSessions.has(id);
+}
+
+export function createSessionSlug(): string {
+  return createSessionSlugId(isSessionIdTaken);
+}
+
+export function addSession(session: ProcessSession) {
+  runningSessions.set(session.id, session);
+  startSweeper();
+}
+
+export function getSession(id: string) {
+  return runningSessions.get(id);
+}
+
+export function getFinishedSession(id: string) {
+  return finishedSessions.get(id);
+}
+
+export function deleteSession(id: string) {
+  runningSessions.delete(id);
+  finishedSessions.delete(id);
+}
+
+export function appendOutput(session: ProcessSession, stream: "stdout" | "stderr", chunk: string) {
+  session.pendingStdout ??= [];
+  session.pendingStderr ??= [];
+  session.pendingStdoutChars ??= sumPendingChars(session.pendingStdout);
+  session.pendingStderrChars ??= sumPendingChars(session.pendingStderr);
+  const buffer = stream === "stdout" ? session.pendingStdout : session.pendingStderr;
+  const bufferChars = stream === "stdout" ? session.pendingStdoutChars : session.pendingStderrChars;
+  const pendingCap = Math.min(
+    session.pendingMaxOutputChars ?? DEFAULT_PENDING_OUTPUT_CHARS,
+    session.maxOutputChars,
+  );
+  buffer.push(chunk);
+  let pendingChars = bufferChars + chunk.length;
+  if (pendingChars > pendingCap) {
+    session.truncated = true;
+    pendingChars = capPendingBuffer(buffer, pendingChars, pendingCap);
+  }
+  if (stream === "stdout") {
+    session.pendingStdoutChars = pendingChars;
+  } else {
+    session.pendingStderrChars = pendingChars;
+  }
+  session.totalOutputChars += chunk.length;
+  const aggregated = trimWithCap(session.aggregated + chunk, session.maxOutputChars);
+  session.truncated =
+    session.truncated || aggregated.length < session.aggregated.length + chunk.length;
+  session.aggregated = aggregated;
+  session.tail = tail(session.aggregated, 2000);
+}
+
+export function drainSession(session: ProcessSession) {
+  const stdout = session.pendingStdout.join("");
+  const stderr = session.pendingStderr.join("");
+  session.pendingStdout = [];
+  session.pendingStderr = [];
+  session.pendingStdoutChars = 0;
+  session.pendingStderrChars = 0;
+  return { stdout, stderr };
+}
+
+export function markExited(
+  session: ProcessSession,
+  exitCode: number | null,
+  exitSignal: NodeJS.Signals | number | null,
+  status: ProcessStatus,
+) {
+  session.exited = true;
+  session.exitCode = exitCode;
+  session.exitSignal = exitSignal;
+  session.tail = tail(session.aggregated, 2000);
+  moveToFinished(session, status);
+}
+
+export function markBackgrounded(session: ProcessSession) {
+  session.backgrounded = true;
+}
+
+function moveToFinished(session: ProcessSession, status: ProcessStatus) {
+  runningSessions.delete(session.id);
+  if (!session.backgrounded) {
+    return;
+  }
+  finishedSessions.set(session.id, {
+    id: session.id,
+    command: session.command,
+    scopeKey: session.scopeKey,
+    startedAt: session.startedAt,
+    endedAt: Date.now(),
+    cwd: session.cwd,
+    status,
+    exitCode: session.exitCode,
+    exitSignal: session.exitSignal,
+    aggregated: session.aggregated,
+    tail: session.tail,
+    truncated: session.truncated,
+    totalOutputChars: session.totalOutputChars,
+  });
+}
+
+export function tail(text: string, max = 2000) {
+  if (text.length <= max) {
+    return text;
+  }
+  return text.slice(text.length - max);
+}
+
+function sumPendingChars(buffer: string[]) {
+  let total = 0;
+  for (const chunk of buffer) {
+    total += chunk.length;
+  }
+  return total;
+}
+
+function capPendingBuffer(buffer: string[], pendingChars: number, cap: number) {
+  if (pendingChars <= cap) {
+    return pendingChars;
+  }
+  const last = buffer.at(-1);
+  if (last && last.length >= cap) {
+    buffer.length = 0;
+    buffer.push(last.slice(last.length - cap));
+    return cap;
+  }
+  while (buffer.length && pendingChars - buffer[0].length >= cap) {
+    pendingChars -= buffer[0].length;
+    buffer.shift();
+  }
+  if (buffer.length && pendingChars > cap) {
+    const overflow = pendingChars - cap;
+    buffer[0] = buffer[0].slice(overflow);
+    pendingChars = cap;
+  }
+  return pendingChars;
+}
+
+export function trimWithCap(text: string, max: number) {
+  if (text.length <= max) {
+    return text;
+  }
+  return text.slice(text.length - max);
+}
+
+export function listRunningSessions() {
+  return Array.from(runningSessions.values()).filter((s) => s.backgrounded);
+}
+
+export function listFinishedSessions() {
+  return Array.from(finishedSessions.values());
+}
+
+export function clearFinished() {
+  finishedSessions.clear();
+}
+
+export function resetProcessRegistryForTests() {
+  runningSessions.clear();
+  finishedSessions.clear();
+  stopSweeper();
+}
+
+export function setJobTtlMs(value?: number) {
+  if (value === undefined || Number.isNaN(value)) {
+    return;
+  }
+  jobTtlMs = clampTtl(value);
+  stopSweeper();
+  startSweeper();
+}
+
+function pruneFinishedSessions() {
+  const cutoff = Date.now() - jobTtlMs;
+  for (const [id, session] of finishedSessions.entries()) {
+    if (session.endedAt < cutoff) {
+      finishedSessions.delete(id);
+    }
+  }
+}
+
+function startSweeper() {
+  if (sweeper) {
+    return;
+  }
+  sweeper = setInterval(pruneFinishedSessions, Math.max(30_000, jobTtlMs / 6));
+  sweeper.unref?.();
+}
+
+function stopSweeper() {
+  if (!sweeper) {
+    return;
+  }
+  clearInterval(sweeper);
+  sweeper = null;
+}