@automatalabs/acp-agents 0.21.1 → 0.22.0

package/dist/runner.d.ts

@@ -6,6 +6,8 @@ import { type AcpEventListener, type AcpEventName } from "./events.js";
 import type { Backend } from "./backend.js";
 import { InteractiveSession, type InteractiveSessionOptions } from "./interactive.js";
 import { type BackendRegistry, type CustomBackendConfig } from "./registry.js";
+import { type AuthMethodDescriptor, type AuthResolution, type AuthResolver } from "./auth/auth-types.js";
+import { type AuthMethodType, type BackendAuthState } from "./auth/auth-store.js";
 import type { ElicitationResolver, PermissionResolver } from "./permissions.js";
 interface LifecycleRoutingOptions {
     /** Model spec used only to select the backend process. */
@@ -73,6 +75,60 @@ export interface ReattachSessionOptions extends InteractiveSessionOptions {
     /** Alias for onPermissionRequest for hosts that name the resolver by role. */
     permissionResolver?: PermissionResolver;
 }
+/** Options for AcpAgentRunner.completeAuth() (§1.3, §4.1). */
+export interface CompleteAuthOptions extends AuthMethodsOptions {
+    /** A method id from describeAuthMethods(). */
+    methodId: string;
+    /** The host-collected resolution (env values / gateway meta / completed / cancelled) (§1.3). */
+    resolution: AuthResolution;
+    /** Event/telemetry label used in strict capability errors. */
+    label?: string;
+    signal?: AbortSignal;
+}
+/** The outcome of a host-completed auth step (§1.3, §4.1). Carries no secret. */
+export type AuthOutcome = {
+    status: "authenticated" | "cancelled";
+    methodId: string;
+    recycled: boolean;
+};
+/** Redacted status view surfaced by the controller, MCP tool, and web (canonical shape; §2.14). */
+export interface AuthStatusSnapshot {
+    backendId: string;
+    poolKey: string;
+    state: BackendAuthState;
+    authenticated: boolean;
+    canResume: boolean;
+    methods: {
+        id: string;
+        type: AuthMethodType;
+        name?: string;
+    }[];
+}
+/** The `runner.auth` controller — the auth verbs as one addressable object (§2.10, §4.1). */
+export interface AuthController {
+    /** Alias of describeAuthMethods(). */
+    methods(opts?: AuthMethodsOptions): Promise<AuthMethodDescriptor[]>;
+    /** Alias of completeAuth(). */
+    authenticate(opts: CompleteAuthOptions): Promise<AuthOutcome>;
+    /** Clears the AuthStore for the backend, zeroizes secrets (§2.14), and recycles the pool. */
+    logout(opts?: LogoutOptions): Promise<void>;
+    /** Redacted, synchronous snapshot — ids/types/names + state only, NEVER secrets (§2.14). */
+    status(opts?: {
+        backend?: string;
+    }): AuthStatusSnapshot[];
+    /** Cold-resume re-arm predicate (§2.13): true iff state ∈ {authenticated,credentials_held} or diskBacked. */
+    canResume(backendId: string): boolean;
+}
+/** Structural capability interface the MCP composition root duck-types to register auth tools
+ *  without widening the frozen `AgentRunner` seam (§4.1). `AcpAgentRunner` implements it. */
+export interface AuthCapableRunner {
+    describeAuthMethods(opts?: AuthMethodsOptions): Promise<AuthMethodDescriptor[]>;
+    completeAuth(opts: CompleteAuthOptions): Promise<AuthOutcome>;
+    /** Ids of every configured backend (built-ins + AcpRunnerOptions.backends), whether or not it
+     *  yet has a BackendAuthMachine. */
+    listBackends(): string[];
+    readonly auth: AuthController;
+}
 /** Constructor options for the runner: pool sizing, client-side handlers, and the custom-backend
  *  registry. `backends` merges over (and wins against) env-declared AGENTPRISM_BACKENDS entries. */
 export interface AcpRunnerOptions extends AcpPoolOptions {
@@ -85,13 +141,27 @@ export interface AcpRunnerOptions extends AcpPoolOptions {
     /** Runner-wide ACP elicitation responder. When set, initialize advertises unstable
      *  elicitation form/url support on every connection; sessions may override the resolver. */
     onElicitation?: ElicitationResolver;
+    /** Which auth method TYPES this host can complete (§1.2). When set, initialize advertises the
+     *  matching client auth capability (`auth.terminal` + top-level `_meta["terminal-auth"]`, and/or
+     *  `auth._meta.gateway`) on every connection, fixed for the connection lifetime. Unset (and
+     *  `onAuth` unset) omits the `auth` capability entirely — the default-OFF, zero-behavior-change
+     *  baseline. When `onAuth` is set but this is unset it derives to `{ terminal: false, gateway: true }`
+     *  (§1.2). A native-TTY CLI host passes `{ terminal: true, gateway: true }`. */
+    authCapabilities?: {
+        terminal?: boolean;
+        gateway?: boolean;
+    };
+    /** Inline auth resolver (§1.3, §2.11). When set, a -32000 at session/new resolves-and-retries-once
+     *  and the run NEVER pauses; when unset, a -32000 run pauses with reason:"auth_required" (§2.12,
+     *  PR4). Mutually exclusive with pause by construction. */
+    onAuth?: AuthResolver;
 }
 /**
  * ACP-backed AgentRunner implementation. The caller that constructs an AcpAgentRunner owns it:
  * pass it into managers/runs as needed, then call dispose() (or use `await using`) when that
  * owner is done with the pooled and dedicated backend processes.
  */
-export declare class AcpAgentRunner implements AgentRunner {
+export declare class AcpAgentRunner implements AgentRunner, AuthCapableRunner {
     private readonly pool;
     /** The resolved custom-backend registry (env + option, validated at construction). */
     private readonly backends;
@@ -105,6 +175,18 @@ export declare class AcpAgentRunner implements AgentRunner {
     private readonly clientHandlers;
     private readonly permissionResolver;
     private readonly elicitationResolver;
+    /** Client auth advertisement, derived ONCE at construction and fixed for every connection this
+     *  runner opens (pooled and dedicated). Undefined => the `auth` capability is omitted (§1.2). */
+    private readonly authCapabilities;
+    /** Inline auth resolver (§2.11). When set, run() resolves a -32000 and retries once instead of
+     *  surfacing AUTH_REQUIRED. Undefined => the (PR4) pause-and-resume path. */
+    private readonly onAuth;
+    /** The single per-runner auth store (§2.2). Holds every backend's `BackendAuthMachine`; the only
+     *  home for credential material in the library. Threaded into the pool and every dedicated
+     *  connection so all connection types reconcile to the same intent. */
+    private readonly authStore;
+    /** The auth verbs as one addressable object (§2.10). */
+    readonly auth: AuthController;
     private readonly structuredOutputTools;
     /** FIFO turn queue per pooled connection for injected-tool schema runs (see the injection
      *  site for why concurrent injected sessions on one process cannot be isolated). */
@@ -143,15 +225,33 @@ export declare class AcpAgentRunner implements AgentRunner {
     openSession(opts: InteractiveSessionOptions): Promise<InteractiveSession>;
     /** Return the selected backend's initialize-advertised authentication methods. */
     authMethods(opts?: AuthMethodsOptions): Promise<AuthMethod[]>;
-    /** Drive ACP authenticate on the selected backend. */
+    /** Drive ACP authenticate on the selected backend. REBUILT off dispose-after-authenticate (§2.9):
+     *  instead of opening a dedicated connection and disposing it in `finally` — which lost any
+     *  in-process (gateway) credential the agent stored on that process (gap 3) — this records the
+     *  credential into the durable `AuthStore` and recycles the pool. A method with `_meta` records an
+     *  in-process/disk intent replayed on every pooled connection's initialize; a bare method with no
+     *  `_meta` fires the one-shot `agent-login` RPC so the agent runs its own login. */
     authenticate(opts: AuthenticateOptions): Promise<AuthenticateResponse | void>;
+    /** Proactively enumerate the selected backend's advertised methods, already type-dispatched (§1.3)
+     *  and label-enriched by the backend's `AuthProfile.describe` (§3.1, identity for a profile-less
+     *  custom backend). A read-only probe: opens a dedicated connection, reads the initialize-advertised
+     *  methods, runs the base dispatcher through the profile seam, and disposes. */
+    describeAuthMethods(opts?: AuthMethodsOptions): Promise<AuthMethodDescriptor[]>;
+    /** Record the host-collected resolution into the AuthStore, advance the generation, and recycle
+     *  the pool (§2.9/§2.6) so a subsequent run() always lands on a current connection. */
+    completeAuth(opts: CompleteAuthOptions): Promise<AuthOutcome>;
+    /** Ids of every configured backend (built-ins + AcpRunnerOptions.backends). */
+    listBackends(): string[];
     /** List configurable providers from the selected backend. */
     listProviders(opts?: ListProvidersOptions): Promise<ListProvidersResponse>;
     /** Configure one provider on the selected backend. */
     setProvider(opts: SetProviderOptions): Promise<SetProviderResponse | void>;
     /** Disable one provider on the selected backend. */
     disableProvider(opts: DisableProviderOptions): Promise<DisableProviderResponse | void>;
-    /** Logout through the selected backend. */
+    /** Logout through the selected backend. REBUILT (§2.9): first clear the AuthStore machine
+     *  (zeroizing `authenticateMeta`/`envValues`, §2.14) and recycle the pool so no pooled process
+     *  replays a stale gateway credential, THEN issue the agent `logout` RPC only where advertised
+     *  (gated on `supportsLogout`; opencode advertises none → store-clear + recycle, no RPC, §3.4). */
     logout(opts?: LogoutOptions): Promise<LogoutResponse | void>;
     /** List persisted ACP sessions from the selected backend. */
     listSessions(opts?: ListSessionsOptions): Promise<ListSessionsResponse>;
@@ -171,6 +271,23 @@ export declare class AcpAgentRunner implements AgentRunner {
     [Symbol.asyncDispose](): Promise<void>;
     private createInteractiveSession;
     private createDedicatedConnection;
+    /** Read the selected backend's initialize-advertised auth methods on a dedicated connection and
+     *  build their type-dispatched descriptors (§1.3). A read-only probe; the connection is disposed. */
+    private probeAuthMethods;
+    /** The shared write path (§2.9) behind completeAuth, the inline resolver (§2.11), and the rebuilt
+     *  legacy authenticate(). Records the payload/methodType from the outcome but DERIVES `klass` from
+     *  the chosen method's type + `_meta` shape (§2.1) — never from the resolution outcome. */
+    private applyResolution;
+    /** Inline resolve-and-retry-once at the run() session-acquisition seam (§2.11). Builds the
+     *  AuthContext from the backend's advertised methods, invokes `onAuth`, and applies the result.
+     *  Returns false on a cancelled/absent resolution (the caller propagates AUTH_REQUIRED). */
+    private resolveInlineAuth;
+    /** Redacted status snapshots (§2.10/§4.1). Enumerates every configured backend when `backend` is
+     *  omitted; never exposes secrets. */
+    private authStatus;
+    private snapshotFor;
+    /** Cold-resume re-arm predicate (§2.13). */
+    canResume(backendId: string): boolean;
     /** Build the backend choice, model-selection spec, tool policy, and session/new options in one
      *  place for run() and openSession() so new AcpSessionOptions fields cannot drift by path. */
     private prepareSession;

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/runner.js

@@ -17,7 +17,7 @@
 // Timeout and abort are the ENGINE's job: we honor opts.signal (wired to ACP session/cancel)
 // and re-throw on abort, but never implement our own timeout.
 import { isAbsolute } from "node:path";
-import { WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
+import { isWorkflowError, WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
 import { PooledConnection } from "./acp-client.js";
 import { AcpAgentPool } from "./pool.js";
 import { TypedEventEmitter, } from "./events.js";
@@ -28,6 +28,8 @@ import { OpenCodeBackend } from "./backends/opencode.js";
 import { CustomAcpBackend } from "./backends/custom.js";
 import { registryWithRunBackends, resolveBackendRegistry, } from "./registry.js";
 import { mapThrownError } from "./errors-map.js";
+import { buildAuthDescriptor, } from "./auth/auth-types.js";
+import { AuthStore, classifyCredential, } from "./auth/auth-store.js";
 import { resolveStructuredOutput } from "./structured-output.js";
 import { STRUCTURED_OUTPUT_SERVER_NAME, StructuredOutputToolHost, } from "./structured-tool.js";
 import { buildRunPrompt, mergeTurnMeta, promptWithImages, validatePromptImages, } from "./prompt.js";
@@ -51,6 +53,18 @@ export class AcpAgentRunner {
     clientHandlers;
     permissionResolver;
     elicitationResolver;
+    /** Client auth advertisement, derived ONCE at construction and fixed for every connection this
+     *  runner opens (pooled and dedicated). Undefined => the `auth` capability is omitted (§1.2). */
+    authCapabilities;
+    /** Inline auth resolver (§2.11). When set, run() resolves a -32000 and retries once instead of
+     *  surfacing AUTH_REQUIRED. Undefined => the (PR4) pause-and-resume path. */
+    onAuth;
+    /** The single per-runner auth store (§2.2). Holds every backend's `BackendAuthMachine`; the only
+     *  home for credential material in the library. Threaded into the pool and every dedicated
+     *  connection so all connection types reconcile to the same intent. */
+    authStore = new AuthStore();
+    /** The auth verbs as one addressable object (§2.10). */
+    auth;
     structuredOutputTools = new StructuredOutputToolHost();
     /** FIFO turn queue per pooled connection for injected-tool schema runs (see the injection
      *  site for why concurrent injected sessions on one process cannot be isolated). */
@@ -66,13 +80,31 @@ export class AcpAgentRunner {
         this.clientHandlers = options.clientHandlers;
         this.permissionResolver = options.onPermissionRequest;
         this.elicitationResolver = options.onElicitation;
+        this.onAuth = options.onAuth;
+        // Default derivation (§1.2): explicit `authCapabilities` wins; else, when an `onAuth` resolver is
+        // present, derive `{ terminal: false, gateway: true }` (gateway is cheap and non-destructive;
+        // terminal needs a real TTY a generic programmatic host lacks); else omit `auth` entirely — the
+        // default-OFF, byte-identical baseline.
+        this.authCapabilities =
+            options.authCapabilities ?? (options.onAuth ? { terminal: false, gateway: true } : undefined);
         this.pool = new AcpAgentPool(options, {
             onEvent: this.emitEvent,
             permissionResolver: options.onPermissionRequest,
             elicitationResolver: options.onElicitation,
             advertiseElicitation: Boolean(options.onElicitation),
+            authCapabilities: this.authCapabilities,
+            authStore: this.authStore,
         });
         this.backends = resolveBackendRegistry(options.backends);
+        this.auth = {
+            methods: (opts) => this.describeAuthMethods(opts),
+            authenticate: (opts) => this.completeAuth(opts),
+            logout: async (opts) => {
+                await this.logout(opts ?? {});
+            },
+            status: (opts) => this.authStatus(opts),
+            canResume: (backendId) => this.canResume(backendId),
+        };
     }
     /**
      * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
@@ -125,28 +157,55 @@ export class AcpAgentRunner {
             await disposeBestEffort(connection);
         }
     }
-    /** Drive ACP authenticate on the selected backend. */
+    /** Drive ACP authenticate on the selected backend. REBUILT off dispose-after-authenticate (§2.9):
+     *  instead of opening a dedicated connection and disposing it in `finally` — which lost any
+     *  in-process (gateway) credential the agent stored on that process (gap 3) — this records the
+     *  credential into the durable `AuthStore` and recycles the pool. A method with `_meta` records an
+     *  in-process/disk intent replayed on every pooled connection's initialize; a bare method with no
+     *  `_meta` fires the one-shot `agent-login` RPC so the agent runs its own login. */
     async authenticate(opts) {
         if (this.disposed)
             throw new Error("ACP agent runner is disposed");
         validateRequiredString(opts.methodId, opts.label, "authenticate", "methodId");
         opts.signal?.throwIfAborted();
         const backend = selectBackend(opts, this.backends);
-        const connection = this.createDedicatedConnection(backend, () => undefined);
-        try {
-            const request = {
-                methodId: opts.methodId,
-                ...(opts.meta ? { _meta: opts.meta } : {}),
-            };
-            const response = await connection.authenticate(request, opts.label);
-            opts.signal?.throwIfAborted();
-            if (this.disposed)
-                throw new Error("ACP agent runner is disposed");
-            return response;
-        }
-        finally {
-            await disposeBestEffort(connection);
-        }
+        const { methods } = await this.probeAuthMethods(backend);
+        const resolution = opts.meta
+            ? { outcome: "meta", methodId: opts.methodId, meta: opts.meta }
+            : { outcome: "agent-login", methodId: opts.methodId };
+        await this.applyResolution(backend, resolution, methods, opts.methodId, opts.label);
+        opts.signal?.throwIfAborted();
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        return;
+    }
+    /** Proactively enumerate the selected backend's advertised methods, already type-dispatched (§1.3)
+     *  and label-enriched by the backend's `AuthProfile.describe` (§3.1, identity for a profile-less
+     *  custom backend). A read-only probe: opens a dedicated connection, reads the initialize-advertised
+     *  methods, runs the base dispatcher through the profile seam, and disposes. */
+    async describeAuthMethods(opts = {}) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        const backend = selectBackend(opts, this.backends);
+        return (await this.probeAuthMethods(backend)).descriptors;
+    }
+    /** Record the host-collected resolution into the AuthStore, advance the generation, and recycle
+     *  the pool (§2.9/§2.6) so a subsequent run() always lands on a current connection. */
+    async completeAuth(opts) {
+        if (this.disposed)
+            throw new Error("ACP agent runner is disposed");
+        validateRequiredString(opts.methodId, opts.label, "completeAuth", "methodId");
+        opts.signal?.throwIfAborted();
+        const backend = selectBackend(opts, this.backends);
+        const { methods } = await this.probeAuthMethods(backend);
+        return this.applyResolution(backend, opts.resolution, methods, opts.methodId, opts.label);
+    }
+    /** Ids of every configured backend (built-ins + AcpRunnerOptions.backends). */
+    listBackends() {
+        const ids = new Set(["claude", "codex", "opencode"]);
+        for (const name of this.backends.keys())
+            ids.add(name);
+        return [...ids];
     }
     /** List configurable providers from the selected backend. */
     async listProviders(opts = {}) {
@@ -220,14 +279,28 @@ export class AcpAgentRunner {
             await disposeBestEffort(connection);
         }
     }
-    /** Logout through the selected backend. */
+    /** Logout through the selected backend. REBUILT (§2.9): first clear the AuthStore machine
+     *  (zeroizing `authenticateMeta`/`envValues`, §2.14) and recycle the pool so no pooled process
+     *  replays a stale gateway credential, THEN issue the agent `logout` RPC only where advertised
+     *  (gated on `supportsLogout`; opencode advertises none → store-clear + recycle, no RPC, §3.4). */
     async logout(opts = {}) {
         if (this.disposed)
             throw new Error("ACP agent runner is disposed");
         opts.signal?.throwIfAborted();
         const backend = selectBackend(opts, this.backends);
+        const poolKey = backend.poolKey ?? backend.id;
+        this.authStore.machineFor(poolKey, backend.authProfile).send({ t: "logout" });
+        this.pool.recycle(poolKey);
         const connection = this.createDedicatedConnection(backend, () => undefined);
         try {
+            // await ready + negotiate before reading the logout advertisement.
+            await connection.authMethods();
+            if (!connection.capabilities?.supportsLogout) {
+                opts.signal?.throwIfAborted();
+                if (this.disposed)
+                    throw new Error("ACP agent runner is disposed");
+                return; // logout unadvertised — store already cleared + recycled, no RPC (§3.4)
+            }
             const request = {
                 ...(opts.meta ? { _meta: opts.meta } : {}),
             };
@@ -328,7 +401,7 @@ export class AcpAgentRunner {
         let structuredToolActive = false;
         let releaseStructuredToolTurn;
         try {
-            session = await this.pool.acquirePrepared(prepared.backend, async (connection) => {
+            const prepare = async (connection) => {
                 let sessionOptions = prepared.sessionOptions;
                 if (shouldInjectStructuredOutputTool(schema, prepared.backend, connection.capabilities)) {
                     // Injected runs are SERIALIZED per connection, and the server name stays CONSTANT.
@@ -357,7 +430,43 @@ export class AcpAgentRunner {
                     };
                 }
                 return sessionOptions;
-            }, { signal: opts.signal, label: opts.label });
+            };
+            // Inline resolve-and-retry-once (§2.11): when `onAuth` is set, a -32000 at session/new is
+            // resolved via the resolver and the acquire retried EXACTLY once — the run never pauses. A
+            // second -32000 propagates as AUTH_REQUIRED. When `onAuth` is unset this loop runs once and
+            // the error propagates unchanged (the PR4 pause-and-resume path), byte-identical to today.
+            let authRetried = false;
+            for (;;) {
+                try {
+                    session = await this.pool.acquirePrepared(prepared.backend, prepare, {
+                        signal: opts.signal,
+                        label: opts.label,
+                    });
+                    break;
+                }
+                catch (error) {
+                    if (this.onAuth && !authRetried && !opts.signal?.aborted && isAuthRequiredError(error)) {
+                        authRetried = true;
+                        // Discard the failed attempt's partial structured-tool registration so the retry's
+                        // prepare re-registers cleanly (the failure happened at session/new, after prepare ran).
+                        releaseStructuredToolTurn?.();
+                        releaseStructuredToolTurn = undefined;
+                        try {
+                            structuredTool?.release();
+                        }
+                        catch {
+                            // best-effort cleanup between attempts.
+                        }
+                        structuredTool = undefined;
+                        structuredToolActive = false;
+                        const resolved = await this.resolveInlineAuth(prepared.backend, opts, error);
+                        if (!resolved)
+                            throw error; // cancelled/unresolved -> propagate AUTH_REQUIRED
+                        continue;
+                    }
+                    throw error;
+                }
+            }
             const activeSession = session;
             opts.signal?.throwIfAborted();
             // Hand the host the re-attach identity BEFORE any turn runs: the session id plus the
@@ -563,9 +672,139 @@ export class AcpAgentRunner {
             permissionResolver: this.permissionResolver,
             elicitationResolver: this.elicitationResolver,
             advertiseElicitation: Boolean(this.elicitationResolver),
+            authCapabilities: this.authCapabilities,
+            // Same store as the pool: a dedicated connection re-primes the durable intent at its own
+            // initialize (§2.5) — the direct fix for the dispose-after-authenticate bug (gap 3).
+            authStore: this.authStore,
             clientHandlers: this.clientHandlers,
         });
     }
+    /** Read the selected backend's initialize-advertised auth methods on a dedicated connection and
+     *  build their type-dispatched descriptors (§1.3). A read-only probe; the connection is disposed. */
+    async probeAuthMethods(backend) {
+        const connection = this.createDedicatedConnection(backend, () => undefined);
+        try {
+            const methods = await connection.authMethods();
+            return { methods, descriptors: describeMethods(methods, backend) };
+        }
+        finally {
+            await disposeBestEffort(connection);
+        }
+    }
+    /** The shared write path (§2.9) behind completeAuth, the inline resolver (§2.11), and the rebuilt
+     *  legacy authenticate(). Records the payload/methodType from the outcome but DERIVES `klass` from
+     *  the chosen method's type + `_meta` shape (§2.1) — never from the resolution outcome. */
+    async applyResolution(backend, resolution, advertised, methodIdHint, label) {
+        const poolKey = backend.poolKey ?? backend.id;
+        const machine = this.authStore.machineFor(poolKey, backend.authProfile);
+        if (resolution.outcome === "cancelled") {
+            return { status: "cancelled", methodId: methodIdHint ?? "", recycled: false };
+        }
+        const methodId = resolutionMethodId(resolution) ?? methodIdHint ?? inferMethodId(resolution, advertised);
+        if (!methodId) {
+            throw new WorkflowError("completeAuth requires a methodId to record the resolution", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
+        }
+        const chosen = advertised.find((m) => m.id === methodId);
+        const methodType = chosen ? authMethodType(chosen) : resolution.outcome === "env" ? "env_var" : "agent";
+        const advertisedMeta = chosen ? authMethodMeta(chosen) : undefined;
+        if (resolution.outcome === "agent-login") {
+            // The sole path from which the bare-`agent` login RPC ever fires (§2.9 step 3): the agent runs
+            // its own login on a live connection and persists to its native store, so every subsequent
+            // fresh initialize re-reads it and needs no replay.
+            const connection = this.createDedicatedConnection(backend, () => undefined);
+            try {
+                await connection.authenticate({ methodId }, label);
+            }
+            catch (error) {
+                throw mapThrownError(error, { label, backendId: backend.id, authMethods: [...advertised] });
+            }
+            finally {
+                await disposeBestEffort(connection);
+            }
+            const intent = { backendId: backend.id, poolKey, methodId, methodType, klass: "disk", diskBacked: true };
+            machine.send({ t: "host_authenticate", intent });
+            machine.send({ t: "apply_ok", connectionId: "host", generation: machine.generation });
+            this.pool.recycle(poolKey);
+            return { status: "authenticated", methodId, recycled: true };
+        }
+        // meta / env / completed: derive klass from the chosen advertised method (§2.1), never the outcome.
+        const { klass, diskBacked } = classifyCredential(methodType, advertisedMeta);
+        // A `meta` payload passes through the backend's pure-data `AuthProfile.buildMeta` (§3.1) so the
+        // agent's expected authenticate `_meta` shape is honored; a custom backend (no profile), or one
+        // whose advertised method could not be matched, records the host-supplied `meta` verbatim
+        // (conformance-by-absence). buildMeta is SECRET-preserving — it only reshapes the payload, never
+        // logs it (§2.14/Principle 9).
+        let authenticateMeta;
+        if (resolution.outcome === "meta") {
+            const buildMeta = backend.authProfile?.buildMeta;
+            authenticateMeta = buildMeta && chosen ? buildMeta(chosen, resolution) : resolution.meta;
+        }
+        const envValues = resolution.outcome === "env" ? resolution.values : undefined;
+        const intent = {
+            backendId: backend.id,
+            poolKey,
+            methodId,
+            methodType,
+            klass,
+            diskBacked,
+            ...(authenticateMeta ? { authenticateMeta } : {}),
+            ...(envValues ? { envValues } : {}),
+        };
+        machine.send({ t: "host_authenticate", intent });
+        this.pool.recycle(poolKey);
+        return { status: "authenticated", methodId, recycled: true };
+    }
+    /** Inline resolve-and-retry-once at the run() session-acquisition seam (§2.11). Builds the
+     *  AuthContext from the backend's advertised methods, invokes `onAuth`, and applies the result.
+     *  Returns false on a cancelled/absent resolution (the caller propagates AUTH_REQUIRED). */
+    async resolveInlineAuth(backend, opts, error) {
+        const { methods, descriptors } = await this.probeAuthMethods(backend);
+        // Mark the machine's authenticated->auth_required transition on the protocol signal (§2.3).
+        this.authStore
+            .machineFor(backend.poolKey ?? backend.id, backend.authProfile)
+            .send({ t: "auth_required_tripped", connectionId: "run", error });
+        const ctx = {
+            backendId: backend.id,
+            ...(opts.label ? { label: opts.label } : {}),
+            methods: descriptors,
+            cause: "required",
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        };
+        const resolution = await this.onAuth(ctx);
+        if (resolution.outcome === "cancelled")
+            return false;
+        await this.applyResolution(backend, resolution, methods, undefined, opts.label);
+        return true;
+    }
+    /** Redacted status snapshots (§2.10/§4.1). Enumerates every configured backend when `backend` is
+     *  omitted; never exposes secrets. */
+    authStatus(opts) {
+        const ids = opts?.backend ? [opts.backend] : this.listBackends();
+        return ids.map((id) => this.snapshotFor(id));
+    }
+    snapshotFor(backendId) {
+        const backend = selectBackend({ model: backendId }, this.backends);
+        const poolKey = backend.poolKey ?? backend.id;
+        const machine = this.authStore.existing(poolKey);
+        const state = machine?.state ?? "unauthenticated";
+        return {
+            backendId: backend.id,
+            poolKey,
+            state,
+            authenticated: state === "authenticated",
+            canResume: machine?.canResume() ?? false,
+            methods: (machine?.advertised ?? []).map((m) => ({
+                id: m.id,
+                type: authMethodType(m),
+                ...(m.name ? { name: m.name } : {}),
+            })),
+        };
+    }
+    /** Cold-resume re-arm predicate (§2.13). */
+    canResume(backendId) {
+        const backend = selectBackend({ model: backendId }, this.backends);
+        return this.authStore.existing(backend.poolKey ?? backend.id)?.canResume() ?? false;
+    }
     /** Build the backend choice, model-selection spec, tool policy, and session/new options in one
      *  place for run() and openSession() so new AcpSessionOptions fields cannot drift by path. */
     prepareSession(opts, config) {
@@ -773,6 +1012,54 @@ function validateRequiredString(value, label, methodName, fieldName) {
         throw new WorkflowError(`${methodName} requires ${fieldName} to be a non-empty string`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
     }
 }
+/** The mapped run error is a WorkflowError; the auth-required classification already ran in the
+ *  pool via mapThrownError (§1.5), so the inline seam keys on the code, not the raw -32000. */
+function isAuthRequiredError(error) {
+    return isWorkflowError(error) && error.code === WorkflowErrorCode.AUTH_REQUIRED;
+}
+/** The SDK types a missing `type` discriminant as `agent`. */
+/** Dispatch each advertised method through the base §1.3 dispatcher, then hand the result to the
+ *  backend's pure-data `AuthProfile.describe` (§3.1) for label enrichment. A custom backend has NO
+ *  profile, so the base descriptor is returned verbatim (conformance-by-absence, §3.5). The profile
+ *  may only relabel; it never changes the `type` discriminant the base dispatcher chose (§3.1). */
+function describeMethods(methods, backend) {
+    const spawn = backend.spawnConfig();
+    const profile = backend.authProfile;
+    return methods.map((method) => {
+        const base = buildAuthDescriptor(method, spawn);
+        return profile ? profile.describe(method, base) : base;
+    });
+}
+function authMethodType(method) {
+    return (("type" in method ? method.type : undefined) ?? "agent");
+}
+/** The advertised method's `_meta`, or undefined. This is agent-PUBLISHED metadata (e.g.
+ *  `gateway.protocol`), never a credential — the credential is only the resolver's payload. */
+function authMethodMeta(method) {
+    const meta = method._meta;
+    return meta ?? undefined;
+}
+/** A resolution that names its own method (meta / agent-login), else undefined. */
+function resolutionMethodId(resolution) {
+    if (resolution.outcome === "meta" || resolution.outcome === "agent-login")
+        return resolution.methodId;
+    if (resolution.outcome === "env" || resolution.outcome === "completed")
+        return resolution.methodId;
+    return undefined;
+}
+/** Infer the target method for an env/completed resolution that did not name one: match by outcome
+ *  against the advertised methods (there is typically exactly one env_var / terminal method). */
+function inferMethodId(resolution, advertised) {
+    if (resolution.outcome === "env") {
+        return advertised.find((m) => authMethodType(m) === "env_var")?.id ?? advertised.find((m) => authMethodType(m) === "agent")?.id;
+    }
+    if (resolution.outcome === "completed") {
+        return (advertised.find((m) => authMethodType(m) === "terminal")?.id ??
+            advertised.find((m) => authMethodType(m) === "agent")?.id ??
+            advertised[0]?.id);
+    }
+    return undefined;
+}
 async function disposeBestEffort(connection) {
     try {
         await connection.dispose();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -29,10 +29,10 @@
   "dependencies": {
     "@agentclientprotocol/claude-agent-acp": "0.57.0",
     "@agentclientprotocol/sdk": "^1.2.1",
-    "@automatalabs/codex-acp": "1.5.0",
+    "@automatalabs/codex-acp": "1.5.1",
     "@modelcontextprotocol/sdk": "^1.29",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.13.0"
+    "@automatalabs/shared-types": "0.14.0"
   },
   "scripts": {
     "build": "tsc -b",