multiple

contracts/acp.ts

@@ -40,6 +40,13 @@ export type AcpAgentInstallKind = "binary" | "npx" | "mock";
 /** Registry entry describing an ACP agent Pipper can spawn. */
 export interface AcpAgentDescriptor {
   id: string;
+  /**
+   * The underlying provider/driver this descriptor belongs to. For a plain
+   * driver descriptor this is omitted and `id` is the driver id; for a
+   * materialized account instance (`AcpAgentInstance`) `id` is the instance id
+   * and this points back at the driver for display/analytics/install metadata.
+   */
+  driverId?: string;
   name: string;
   /** Display name shown in the UI. */
   displayName: string;
@@ -48,6 +55,13 @@ export interface AcpAgentDescriptor {
   command: string;
   args: string[];
   env?: Record<string, string>;
+  /**
+   * Names to delete from the child's environment before spawn. Used to drop
+   * ambient provider credentials (e.g. OPENAI_API_KEY) for an isolated account
+   * so its process cannot silently authenticate as the machine's default
+   * account.
+   */
+  unsetEnv?: string[];
   /** Optional icon key for tab indicators. */
   icon?: string;
   /** Short description for onboarding. */
@@ -87,6 +101,67 @@ export interface AgentProbeResult {
   authMethods?: AuthMethod[];
 }
 
+/**
+ * A single environment variable supplied to a provider instance's child
+ * process. Values never leave the main process in cleartext: a `sensitive`
+ * value is redacted before an instance is sent to the renderer.
+ */
+export interface AcpAgentInstanceEnvVar {
+  name: string;
+  value: string;
+  /** When true, the value is redacted in renderer-facing copies. */
+  sensitive?: boolean;
+}
+
+/**
+ * One named account/configuration of a provider driver. Pipper keeps a
+ * separate child process, environment, and credential root per instance so
+ * two accounts of the same driver (e.g. personal + work Codex) can coexist and
+ * run side by side. An instance with `id === driverId` is the legacy/default
+ * configuration that uses the ambient CLI login.
+ */
+export interface AcpAgentInstance {
+  /** Routing key passed to {@link AcpAgentDescriptor.id} when spawning. */
+  id: string;
+  /** The provider driver this instance is a configuration of. */
+  driverId: string;
+  /** User-facing label, e.g. "Codex — Work". */
+  displayName: string;
+  enabled: boolean;
+  /** Per-instance environment overrides, merged over the driver defaults. */
+  env?: AcpAgentInstanceEnvVar[];
+  /** Driver-specific, opaque configuration (e.g. a profile directory). */
+  config?: Record<string, unknown>;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+/** Create/update payload for a provider instance. */
+export interface AcpAgentInstanceInput {
+  driverId: string;
+  displayName: string;
+  /** Optional explicit id; generated from driver + label when omitted. */
+  id?: string;
+  enabled?: boolean;
+  env?: AcpAgentInstanceEnvVar[];
+  config?: Record<string, unknown>;
+}
+
+/** Per-driver account-creation capabilities, surfaced to the settings UI. */
+export interface AgentAccountSchema {
+  driverId: string;
+  displayName: string;
+  icon?: string;
+  /** Env var that points the CLI at an isolated credential root, if any. */
+  profileEnvVar: string | null;
+  /** Env var that carries an explicit credential value, if any. */
+  authEnvVar: string | null;
+  /** True when a driver beyond the ambient default can be configured. */
+  supportsMultipleAccounts: boolean;
+  /** True when the driver has an interactive sign-in command to launch. */
+  supportsLogin: boolean;
+}
+
 /**
  * Account-level subscription rate limit for a session, when the agent reports
  * one. Distinct from `used`/`size` (per-turn context window): this describes the

contracts/remote.ts

@@ -11,6 +11,8 @@ export interface RemoteProject {
 export interface RemoteModel {
   id: string;
   name: string;
+  /** Provider/driver display name; used to group accounts on the phone. */
+  provider?: string;
 }
 
 export interface RemoteThreadSummary {

contracts/threads.ts

@@ -1,7 +1,11 @@
 export interface Thread {
   id: string;
   project_id: string;
-  /** Which ACP agent owns this thread (e.g. "cursor-acp@1.0"). */
+  /**
+   * Which ACP provider instance owns this thread — the spawn routing key.
+   * Equals the driver id for a driver's default account, or an instance id
+   * (e.g. "codex-acp:work") for an additional account.
+   */
   agent_id: string;
   /** ACP session.id from session/new (or session/resume). */
   agent_session_id: string;

electron/agent-connection-manager.ts

@@ -19,7 +19,7 @@ import type {
 import type { OpenTabsState, Thread } from "../contracts/threads.ts";
 import { readOpenTabsState, recordThreadSwitch } from "./open-tabs.ts";
 import { getProject } from "./projects.ts";
-import { getSelectedAgentIds } from "./db.ts";
+import { getAppSetting, setAppSetting, getSelectedAgentIds } from "./db.ts";
 import { setActiveProjectId } from "./session.ts";
 import {
   getThread,
@@ -39,6 +39,7 @@ import {
 import { normalizeWorkspacePath, pickWorkspaceThread } from "../contracts/workspace-scope.ts";
 import { isLiveWorktree } from "./worktree-manager.ts";
 import { getAgentDescriptor, getDefaultAgentId, listRegisteredAgents } from "./agents/registry.ts";
+import { listAgentInstanceDescriptors, hasAgentInstances } from "./agent-instances.ts";
 import {
   ACP_SWITCH_PHASE_TIMEOUT_MS,
   ConnectionLifecycle,
@@ -92,6 +93,27 @@ import type {
   MonitorSwitchRecord,
 } from "../contracts/monitor.ts";
 
+/** Persisted pointer to the last-used provider instance. */
+const PREFERRED_INSTANCE_KEY = "preferred_agent_instance";
+
+function loadPreferredAgentId(): string {
+  try {
+    const stored = getAppSetting(PREFERRED_INSTANCE_KEY);
+    if (stored && getAgentDescriptor(stored)) return stored;
+  } catch {
+    // Database may not be ready in some embedding contexts; fall back.
+  }
+  return getDefaultAgentId();
+}
+
+function persistPreferredAgentId(agentId: string): void {
+  try {
+    setAppSetting(PREFERRED_INSTANCE_KEY, agentId);
+  } catch {
+    // Non-fatal: preference simply won't survive a restart.
+  }
+}
+
 function modelOptionsFromConfig(
   options: SessionConfigOption[] | undefined,
 ): Array<{ modelId: string; name: string; provider?: string }> {
@@ -219,7 +241,7 @@ export class AgentConnectionManager {
   private connecting: Promise<LiveConnection> | null = null;
   private activeProjectId: string | null = null;
   private activeThreadId: string | null = null;
-  private preferredAgentId: string = getDefaultAgentId();
+  private preferredAgentId: string = loadPreferredAgentId();
   private readonly sessions = new ThreadSessionRegistry();
   /**
    * Session replay is delivered as session/update notifications while
@@ -371,10 +393,40 @@ export class AgentConnectionManager {
   }
 
   listAgents(): AcpAgentDescriptor[] {
-    // Always re-probe PATH so onboarding reflects install state.
+    // Once instance storage is seeded, it is the source of truth: return the
+    // enabled instances even when that list is empty (all accounts disabled).
+    // Only fall back to the raw driver catalog in the uninitialized/legacy
+    // state, so a disabled default account is never re-exposed as selectable.
+    if (hasAgentInstances()) return listAgentInstanceDescriptors();
     return listRegisteredAgents();
   }
 
+  /**
+   * Reconcile a removed account: drop its cached sessions, close its process,
+   * and move the preferred pointer off it. Thread rows are re-pointed at the
+   * driver's default instance by `deleteAgentInstance`.
+   */
+  async removeAgentInstance(instanceId: string): Promise<void> {
+    // Collect first: removing entries while iterating the registry would skip
+    // siblings when several threads share the account.
+    const ownedThreadIds: string[] = [];
+    for (const [threadId, runtime] of this.sessions.entries()) {
+      if (runtime.agentId === instanceId) ownedThreadIds.push(threadId);
+    }
+    for (const threadId of ownedThreadIds) {
+      const runtime = this.sessions.get(threadId);
+      if (!runtime) continue;
+      this.permissions.cancelForSession(runtime.agentSessionId);
+      this.prompts.cancelInFlight(threadId, "account removed");
+      this.sessions.remove(threadId);
+    }
+    await this.lifecycle.close(instanceId);
+    if (this.preferredAgentId === instanceId) {
+      this.preferredAgentId = getDefaultAgentId();
+      persistPreferredAgentId(this.preferredAgentId);
+    }
+  }
+
   async getModelCatalogs(): Promise<
     Record<string, Array<{ modelId: string; name: string; provider?: string }>>
   > {
@@ -384,8 +436,18 @@ export class AgentConnectionManager {
     // needs authentication is skipped; its catalog can still be populated by
     // a later successful session.
     const selectedAgentIds = getSelectedAgentIds();
+    // Selections are provider-level (a driver id or a default instance id), but
+    // catalogs are keyed per instance. Warm every enabled instance whose driver
+    // is selected so accounts added later in Settings have catalogs too.
+    const selectedSet = new Set(selectedAgentIds);
+    const warmIds = new Set(selectedAgentIds);
+    for (const instance of listAgentInstanceDescriptors()) {
+      const driver = instance.driverId ?? instance.id;
+      if (selectedSet.has(instance.id) || selectedSet.has(driver)) warmIds.add(instance.id);
+    }
+    const agentsToWarm = [...warmIds];
     await Promise.all(
-      selectedAgentIds.map(async (agentId) => {
+      agentsToWarm.map(async (agentId) => {
         try {
           await this.acquireConnection(agentId);
         } catch {
@@ -434,7 +496,7 @@ export class AgentConnectionManager {
         ? (getProject(this.activeProjectId)?.path ?? process.cwd())
         : process.cwd());
     await Promise.all(
-      selectedAgentIds.map(async (agentId) => {
+      agentsToWarm.map(async (agentId) => {
         if (result[agentId]?.length) return;
         const live = this.lifecycle.getCached(agentId);
         if (!live) return;
@@ -794,6 +856,7 @@ export class AgentConnectionManager {
       );
     }
     this.preferredAgentId = agentId;
+    persistPreferredAgentId(agentId);
   }
 
   /** Bridge-event output goes through RendererBroadcaster (see that module). */
@@ -1112,6 +1175,7 @@ export class AgentConnectionManager {
     const live = await this.acquireConnection(agentId);
     this.lifecycle.setActive(live);
     this.preferredAgentId = agentId;
+    persistPreferredAgentId(agentId);
     if (previousAgentId && previousAgentId !== live.agentId) {
       this.captureAnalytics?.("agent_switched", {
         from_agent_id: previousAgentId,