@cortexkit/common-auth 0.4.5 → 0.5.0

package/dist/opencode2/index.d.ts

@@ -1,8 +1,8 @@
 export type { OpenCode2AuthFailureKind } from './errors.js';
 export { OpenCode2AuthError } from './errors.js';
-export { applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export { ATTEMPT_HEADER, applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
 export type { FormAnswer, PoolAuthorization, PoolLoginMethod, RegisterOpenCode2AuthMethodsOptions, } from './integration.js';
 export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, } from './integration.js';
 export type { ServerSentEvent } from './sse.js';
 export { watchServerSentEvents } from './sse.js';
-export type { AccountHeadersResult, AccountRequest, Attempt, AttemptEndReason, AttemptOutcome, ChooseAccountInput, EventVerdict, HeaderEdits, HostError, InstallOpenCode2AuthOptions, LimitSignal, OpenCode2AuthAdapter, OpenCode2AuthEventName, OpenCode2AuthEvents, OpenCode2AuthInstallation, OpenCode2AuthLogger, OpenCode2HookContext, RequestKind, RequestScope, RetryReason, SelectingHook, Transport, } from './types.js';
+export type { AccountHeadersResult, AccountRequest, Attempt, AttemptEndReason, AttemptOutcome, ChooseAccountInput, EventVerdict, HeaderEdits, HostError, InstallOpenCode2AuthOptions, LimitSignal, OpenCode2AuthAdapter, OpenCode2AuthEventName, OpenCode2AuthEvents, OpenCode2AuthInstallation, OpenCode2AuthLogger, OpenCode2HookContext, RequestKind, RequestScope, ResponseAccount, RetryReason, SelectingHook, Transport, } from './types.js';

package/dist/opencode2/index.js

@@ -1,4 +1,4 @@
 export { OpenCode2AuthError } from './errors.js';
-export { applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export { ATTEMPT_HEADER, applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
 export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, } from './integration.js';
 export { watchServerSentEvents } from './sse.js';

package/dist/opencode2/install.d.ts

@@ -1,15 +1,25 @@
 import type { HeaderEdits, InstallOpenCode2AuthOptions, OpenCode2AuthAdapter, OpenCode2AuthInstallation, OpenCode2HookContext } from './types.js';
 export declare const DEFAULT_MAX_RECORDS = 512;
+/**
+ * The request header `model.request` sets to the attempt it started. The
+ * host builds the HTTP request and the WebSocket handshake from the headers
+ * `model.request` leaves, so `http.request` and `experimental.ws.handshake`
+ * read it to find their own attempt among several of one session and kind,
+ * and remove it: it never reaches the wire.
+ */
+export declare const ATTEMPT_HEADER = "x-common-auth-attempt";
 /** Applies edits to a plain header record, replacing every spelling of each name. */
 export declare function applyHeaderEdits(target: Record<string, string>, edits: HeaderEdits): void;
 /**
  * Installs multi-account auth on OpenCode 2's own provider drivers. Every
  * hook is scoped to `adapter.providerID`:
  *
- * - `model.request` picks the account for the request's `sessionID:kind`,
- *   which starts a new attempt, and sets its headers;
- * - `http.request` and `experimental.ws.handshake` set them again, because
- *   the host applies its own credential after `model.request`;
+ * - `model.request` picks the account for one model call of a session and
+ *   request kind, which starts a new attempt, sets its headers and marks the
+ *   request with the attempt (`ATTEMPT_HEADER`);
+ * - `http.request` and `experimental.ws.handshake` find the attempt by that
+ *   mark, remove it and set the account headers again, because the host
+ *   applies its own credential after `model.request`;
  * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
  *   each outgoing frame;
  * - `http.response` and `experimental.ws.receive` read quota, refusals,
@@ -19,19 +29,19 @@ export declare function applyHeaderEdits(target: Record<string, string>, edits:
  *   before any output, so `model.request` runs again and can pick another
  *   account, and refuses to retry once output has started.
  *
- * Attribution. An HTTP response belongs to the attempt whose `http.request`
- * produced its request object, and to nothing else. The host hands
- * `http.response` the request object the `http.request` hooks left, so a
- * different object means a later hook replaced it; nothing then proves which
- * send the response answers (an earlier attempt's send may still be in
- * flight, and only the newest attempt of each session and kind is kept), and
- * its feedback is dropped rather than guessed by recency. No marker can ride
- * on the request instead: the host builds the wire request from that same
- * object, so a marker would be sent to the provider. A WebSocket frame
- * belongs to the newest attempt of its session and kind only while that
- * attempt went out over WebSocket and has not ended: the host runs one
- * exchange at a time per session socket, so frames between one handshake
- * and the next belong to the earlier attempt. Anything else is attributed to
- * no attempt and reaches no adapter callback or listener.
+ * Attribution. A send belongs to the attempt named by the mark
+ * `model.request` left on it, so several attempts of one session and kind
+ * can be in flight at once, each on its own account. An HTTP response
+ * belongs to the attempt whose `http.request` produced its request object,
+ * and to nothing else. The host hands `http.response` the request object the
+ * `http.request` hooks left, so a different object means a later hook
+ * replaced it; nothing then proves which send the response answers, and its
+ * feedback is dropped rather than guessed by recency. A WebSocket frame
+ * names no attempt, so frames go to the newest open attempt of their session
+ * and kind that went out over WebSocket, and an older one is abandoned as
+ * soon as a newer attempt of that session and kind begins or goes out over
+ * WebSocket: the host runs one exchange at a time on a session's socket.
+ * Anything else is attributed to no attempt and reaches no adapter callback
+ * or listener.
  */
 export declare function installOpenCode2Auth<Q, A = unknown>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q, A>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q, A>>;

package/dist/opencode2/install.js

@@ -2,6 +2,14 @@ import { OpenCode2AuthError } from './errors.js';
 import { placeholderSecret } from './integration.js';
 import { watchServerSentEvents } from './sse.js';
 export const DEFAULT_MAX_RECORDS = 512;
+/**
+ * The request header `model.request` sets to the attempt it started. The
+ * host builds the HTTP request and the WebSocket handshake from the headers
+ * `model.request` leaves, so `http.request` and `experimental.ws.handshake`
+ * read it to find their own attempt among several of one session and kind,
+ * and remove it: it never reaches the wire.
+ */
+export const ATTEMPT_HEADER = 'x-common-auth-attempt';
 const keyOf = (sessionID, kind) => JSON.stringify([sessionID, kind]);
 const scopeOf = (draft) => ({
     providerID: draft.model.providerID,
@@ -77,10 +85,12 @@ function applyHeaderEditsTo(target, edits) {
  * Installs multi-account auth on OpenCode 2's own provider drivers. Every
  * hook is scoped to `adapter.providerID`:
  *
- * - `model.request` picks the account for the request's `sessionID:kind`,
- *   which starts a new attempt, and sets its headers;
- * - `http.request` and `experimental.ws.handshake` set them again, because
- *   the host applies its own credential after `model.request`;
+ * - `model.request` picks the account for one model call of a session and
+ *   request kind, which starts a new attempt, sets its headers and marks the
+ *   request with the attempt (`ATTEMPT_HEADER`);
+ * - `http.request` and `experimental.ws.handshake` find the attempt by that
+ *   mark, remove it and set the account headers again, because the host
+ *   applies its own credential after `model.request`;
  * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
  *   each outgoing frame;
  * - `http.response` and `experimental.ws.receive` read quota, refusals,
@@ -90,29 +100,33 @@ function applyHeaderEditsTo(target, edits) {
  *   before any output, so `model.request` runs again and can pick another
  *   account, and refuses to retry once output has started.
  *
- * Attribution. An HTTP response belongs to the attempt whose `http.request`
- * produced its request object, and to nothing else. The host hands
- * `http.response` the request object the `http.request` hooks left, so a
- * different object means a later hook replaced it; nothing then proves which
- * send the response answers (an earlier attempt's send may still be in
- * flight, and only the newest attempt of each session and kind is kept), and
- * its feedback is dropped rather than guessed by recency. No marker can ride
- * on the request instead: the host builds the wire request from that same
- * object, so a marker would be sent to the provider. A WebSocket frame
- * belongs to the newest attempt of its session and kind only while that
- * attempt went out over WebSocket and has not ended: the host runs one
- * exchange at a time per session socket, so frames between one handshake
- * and the next belong to the earlier attempt. Anything else is attributed to
- * no attempt and reaches no adapter callback or listener.
+ * Attribution. A send belongs to the attempt named by the mark
+ * `model.request` left on it, so several attempts of one session and kind
+ * can be in flight at once, each on its own account. An HTTP response
+ * belongs to the attempt whose `http.request` produced its request object,
+ * and to nothing else. The host hands `http.response` the request object the
+ * `http.request` hooks left, so a different object means a later hook
+ * replaced it; nothing then proves which send the response answers, and its
+ * feedback is dropped rather than guessed by recency. A WebSocket frame
+ * names no attempt, so frames go to the newest open attempt of their session
+ * and kind that went out over WebSocket, and an older one is abandoned as
+ * soon as a newer attempt of that session and kind begins or goes out over
+ * WebSocket: the host runs one exchange at a time on a session's socket.
+ * Anything else is attributed to no attempt and reaches no adapter callback
+ * or listener.
  */
 export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     const { providerID } = adapter;
     const logger = options.logger;
     const maxRecords = Math.max(1, options.maxRecords ?? DEFAULT_MAX_RECORDS);
     const forbidden = (options.hostCredentials ?? [placeholderSecret(providerID)]).filter((value) => value !== '');
-    const records = new Map();
+    /** Every attempt still held, oldest first. */
+    const attempts = new Map();
     const byRequest = new WeakMap();
+    /** Retries the retry hook asked for, by `sessionID:kind`. */
+    const pendingRetries = new Map();
     let warnedUnprovenResponse = false;
+    let warnedUnmarkedSend = false;
     const listeners = new Map();
     let seq = 0;
     const warn = (message, data) => {
@@ -159,19 +173,28 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             ...(rec.limit ? { limit: rec.limit.signal } : {}),
             ...(error ? { error } : {}),
         };
+        if (error)
+            rec.endError = error;
         rec.ended = deliverEnd(rec.attempt, outcome);
     };
     const abandon = (rec, message) => finish(rec, { reason: 'abandoned', message });
+    /** The attempts of one session and kind, oldest first. */
+    const attemptsOf = (key) => [...attempts.values()].filter((rec) => rec.key === key);
+    const newestOf = (key) => attemptsOf(key).at(-1);
+    /** Forgets an attempt, and its key's pending retry once nothing else holds the key. */
+    const drop = (rec) => {
+        attempts.delete(rec.id);
+        if (!attemptsOf(rec.key).length)
+            pendingRetries.delete(rec.key);
+    };
     const remember = (rec) => {
-        const key = keyOf(rec.scope.sessionID, rec.scope.kind);
-        records.delete(key);
-        records.set(key, rec);
-        while (records.size > maxRecords) {
-            const oldest = records.entries().next().value;
+        attempts.set(rec.id, rec);
+        while (attempts.size > maxRecords) {
+            const oldest = attempts.values().next().value;
             if (oldest === undefined)
                 break;
-            abandon(oldest[1], 'dropped to keep the record bound');
-            records.delete(oldest[0]);
+            abandon(oldest, 'dropped to keep the record bound');
+            drop(oldest);
         }
     };
     const accountOf = (rec) => rec.accountId === undefined
@@ -196,18 +219,39 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }
     };
+    /**
+     * Retires the attempts a new attempt of the same session and kind
+     * supersedes. One that has ended is dropped. One still open stays when it
+     * may yet be sent or answered (waiting for its transport, or an HTTP send
+     * whose response will name it), since another call of the same session and
+     * kind may run beside this one. One on WebSocket is abandoned, because
+     * frames name no attempt and the host runs one exchange at a time on a
+     * session's socket; one the retry hook already judged is abandoned too,
+     * because the host has finished with that call.
+     */
+    const supersede = (key) => {
+        for (const rec of attemptsOf(key)) {
+            if (rec.ended || !rec.attempt) {
+                drop(rec);
+            }
+            else if (rec.transport === 'ws' || rec.judged) {
+                abandon(rec, 'a newer attempt of its session and kind began');
+                drop(rec);
+            }
+        }
+    };
     const select = async (scope, hook, transport) => {
-        const prior = records.get(keyOf(scope.sessionID, scope.kind));
-        if (prior)
-            abandon(prior, 'a newer attempt of its session and kind began');
+        const key = keyOf(scope.sessionID, scope.kind);
+        const retried = pendingRetries.get(key);
+        pendingRetries.delete(key);
+        const previousAccountId = retried?.accountId ?? newestOf(key)?.accountId;
+        supersede(key);
         const input = {
             ...scope,
-            ...(prior?.accountId === undefined
-                ? {}
-                : { previousAccountId: prior.accountId }),
-            ...(prior?.rerouteFrom === undefined
+            ...(previousAccountId === undefined ? {} : { previousAccountId }),
+            ...(retried?.rerouteFrom === undefined
                 ? {}
-                : { rerouteFrom: prior.rerouteFrom }),
+                : { rerouteFrom: retried.rerouteFrom }),
         };
         const accountId = await adapter.chooseAccount(input);
         let headers = {};
@@ -222,18 +266,19 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 headers = result;
             }
         }
-        const id = ++seq;
+        const id = `attempt-${++seq}`;
         const rec = {
+            id,
+            key,
             scope,
             accountId,
             headers,
-            seq: id,
             attempt: accountId === undefined
                 ? undefined
                 : {
                     ...scope,
                     accountId,
-                    attemptId: `attempt-${id}`,
+                    attemptId: id,
                     transport,
                     data,
                 },
@@ -257,17 +302,38 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         }
         return rec;
     };
-    // The transport hooks normally follow `model.request` and carry the
-    // attempt it started. Choosing here too keeps a request that skipped it
-    // from going out under the host credential, and a second send without a
-    // `model.request` in between from reusing the first send's attempt.
-    const bind = async (scope, hook, transport) => {
-        const rec = records.get(keyOf(scope.sessionID, scope.kind));
+    // The transport hooks normally follow `model.request` and carry the mark
+    // of the attempt it started. Choosing here too keeps a request that skipped
+    // it from going out under the host credential, and a second send of the
+    // same attempt from reusing the first send's attempt.
+    const bind = async (scope, hook, transport, mark) => {
+        const key = keyOf(scope.sessionID, scope.kind);
+        let rec = mark === undefined ? undefined : attempts.get(mark);
+        if (rec?.key !== key)
+            rec = undefined;
+        if (!rec) {
+            // No mark: the newest attempt of the session and kind is the only
+            // candidate the hook can name. Say so once when that is a guess.
+            rec = newestOf(key);
+            const waiting = attemptsOf(key).filter((other) => other.transport === undefined && !other.ended);
+            if (waiting.length > 1 && !warnedUnmarkedSend) {
+                warnedUnmarkedSend = true;
+                warn('opencode2 auth tied a send without its attempt mark to the newest of several waiting attempts', { sessionID: scope.sessionID, kind: scope.kind });
+            }
+        }
         if (!rec || rec.transport !== undefined || rec.ended)
-            return select(scope, hook, transport);
-        rec.transport = transport;
-        if (rec.attempt)
-            rec.attempt.transport = transport;
+            rec = await select(scope, hook, transport);
+        else {
+            rec.transport = transport;
+            if (rec.attempt)
+                rec.attempt.transport = transport;
+        }
+        if (transport === 'ws') {
+            for (const other of attemptsOf(key)) {
+                if (other !== rec && other.transport === 'ws')
+                    abandon(other, 'a newer attempt of its session and kind went out over WebSocket');
+            }
+        }
         return rec;
     };
     // A transport hook that throws stops the send, so its attempt is over.
@@ -280,9 +346,13 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             throw error;
         }
     };
-    const liveOn = (rec, transport) => rec?.attempt !== undefined && rec.transport === transport && !rec.ended
-        ? rec
-        : undefined;
+    /** The attempt a frame of this session and kind belongs to, if any. */
+    const liveOnSocket = (sessionID, kind) => {
+        const rec = attemptsOf(keyOf(sessionID, kind))
+            .filter((each) => each.transport === 'ws')
+            .at(-1);
+        return rec?.attempt !== undefined && !rec.ended ? rec : undefined;
+    };
     const noteLimit = (rec, signal, via) => {
         const account = accountOf(rec);
         if (!account || !rec.attempt || rec.limit)
@@ -330,21 +400,46 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         else if (verdict.done)
             finish(rec);
     };
+    /** Moves an attempt to the account that answered its response. */
+    const rebind = (rec, answered) => {
+        const attempt = rec.attempt;
+        if (!attempt || answered.accountId === rec.accountId)
+            return;
+        attempt.reboundFrom ??= attempt.accountId;
+        attempt.accountId = answered.accountId;
+        if ('data' in answered)
+            attempt.data = answered.data;
+        rec.accountId = answered.accountId;
+    };
+    const failedOutcome = (rec) => !rec.attempt ||
+        rec.endError !== undefined ||
+        (rec.status !== undefined && rec.status >= 400);
+    /**
+     * The attempt a retry is about. The retry hook names only the session, so:
+     * the newest refused attempt not yet rerouted; else, among the session's
+     * primary attempts (or all of them when it has none), the only one, the
+     * newest that failed and was not yet judged, the only one still open, or
+     * the newest. Two or more open with nothing else to tell them apart is
+     * `ambiguous`: deciding for one could reroute or end the other.
+     */
     const pickForRetry = (sessionID) => {
-        let refused;
-        let primary;
-        let latest;
-        for (const rec of records.values()) {
-            if (rec.scope.sessionID !== sessionID)
-                continue;
-            if (!latest || rec.seq > latest.seq)
-                latest = rec;
-            if (rec.scope.kind === 'primary')
-                primary = rec;
-            if (rec.limit && !rec.rerouteFrom && (!refused || rec.seq > refused.seq))
-                refused = rec;
-        }
-        return refused ?? primary ?? latest;
+        const held = [...attempts.values()].filter((rec) => rec.scope.sessionID === sessionID);
+        const refused = held.filter((rec) => rec.limit && !rec.rerouted).at(-1);
+        if (refused)
+            return refused;
+        const primary = held.filter((rec) => rec.scope.kind === 'primary');
+        const pool = primary.length > 0 ? primary : held;
+        if (pool.length <= 1)
+            return pool[0];
+        const failed = pool
+            .filter((rec) => !rec.judged && failedOutcome(rec))
+            .at(-1);
+        if (failed)
+            return failed;
+        const open = pool.filter((rec) => rec.attempt && !rec.ended);
+        if (open.length > 1)
+            return 'ambiguous';
+        return open[0] ?? pool.at(-1);
     };
     const scoped = { providerID };
     const registrations = [];
@@ -352,10 +447,14 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         const rec = await select(scopeOf(draft), 'model.request');
         if (rec.accountId === undefined)
             throw noAccount(rec.scope);
-        applyHeaderEdits(draft.headers, rec.headers);
+        applyHeaderEdits(draft.headers, {
+            ...rec.headers,
+            [ATTEMPT_HEADER]: rec.id,
+        });
     }, scoped));
     registrations.push(await ctx.session.hook('http.request', async (draft) => {
-        const rec = await bind(scopeOf(draft), 'http.request', 'http');
+        const mark = draft.request.headers.get(ATTEMPT_HEADER) ?? undefined;
+        const rec = await bind(scopeOf(draft), 'http.request', 'http', mark);
         const account = accountOf(rec);
         const attempt = rec.attempt;
         if (!account || !attempt)
@@ -363,6 +462,13 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         await failing(rec, async () => {
             let request = draft.request;
             if (adapter.rewriteRequest) {
+                if (mark !== undefined) {
+                    // The mark is the installer's own; the adapter's rewrite never
+                    // sees it.
+                    const unmarked = new Headers(request.headers);
+                    unmarked.delete(ATTEMPT_HEADER);
+                    request = new Request(request, { headers: unmarked });
+                }
                 request =
                     (await adapter.rewriteRequest({
                         ...account,
@@ -371,6 +477,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                     })) ?? request;
             }
             const headers = new Headers(request.headers);
+            headers.delete(ATTEMPT_HEADER);
             applyHeaderEditsTo(headers, rec.headers);
             guard(rec.scope, headers.entries());
             const final = new Request(request, { headers });
@@ -387,11 +494,21 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
             return;
         }
+        const original = draft.response;
+        if (adapter.answeredBy && rec.attempt) {
+            const attempt = rec.attempt;
+            const answered = await failing(rec, async () => adapter.answeredBy?.({
+                request: draft.request,
+                response: original,
+                attempt,
+            }));
+            if (answered)
+                rebind(rec, answered);
+        }
         const account = accountOf(rec);
-        const attempt = rec?.attempt;
-        if (!rec || !account || !attempt)
+        const attempt = rec.attempt;
+        if (!account || !attempt)
             return;
-        const original = draft.response;
         rec.status = original.status;
         const quota = adapter.quotaFromHeaders?.(original.headers, original.status, attempt);
         if (quota !== undefined)
@@ -438,7 +555,14 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             draft.response = response;
     }, scoped));
     registrations.push(await ctx.session.hook('experimental.ws.handshake', async (draft) => {
-        const rec = await bind(scopeOf(draft), 'experimental.ws.handshake', 'ws');
+        let mark;
+        for (const name of Object.keys(draft.headers)) {
+            if (name.toLowerCase() !== ATTEMPT_HEADER)
+                continue;
+            mark ??= draft.headers[name];
+            delete draft.headers[name];
+        }
+        const rec = await bind(scopeOf(draft), 'experimental.ws.handshake', 'ws', mark);
         const account = accountOf(rec);
         const attempt = rec.attempt;
         if (!account || !attempt)
@@ -459,7 +583,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     if (rewriteFrame) {
         registrations.push(await ctx.session.hook('experimental.ws.send', async (draft) => {
             const scope = scopeOf(draft);
-            const rec = liveOn(records.get(keyOf(scope.sessionID, scope.kind)), 'ws');
+            const rec = liveOnSocket(scope.sessionID, scope.kind);
             const frame = await rewriteFrame({
                 ...scope,
                 attempt: rec?.attempt,
@@ -470,7 +594,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         }, scoped));
     }
     registrations.push(await ctx.session.hook('experimental.ws.receive', (draft) => {
-        const rec = liveOn(records.get(keyOf(draft.sessionID, draft.kind)), 'ws');
+        const rec = liveOnSocket(draft.sessionID, draft.kind);
         if (!rec)
             return;
         try {
@@ -483,12 +607,27 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         }
     }, scoped));
     registrations.push(await ctx.session.hook('retry', async (draft) => {
-        const rec = pickForRetry(draft.sessionID);
-        if (!rec)
+        const picked = pickForRetry(draft.sessionID);
+        if (!picked)
             return;
         const hostDecision = draft.decision;
+        if (picked === 'ambiguous') {
+            // Nothing tells which open attempt failed: keep the host's
+            // decision and leave every attempt as it is.
+            await emit('retry', {
+                sessionID: draft.sessionID,
+                attempt: draft.attempt,
+                reason: 'host-decides',
+                hostDecision,
+                decision: hostDecision,
+            });
+            return;
+        }
+        const rec = picked;
+        rec.judged = true;
         let decision = hostDecision;
         let reason;
+        let rerouteFrom;
         const attempt = rec.attempt;
         if (rec.accountId === undefined || !attempt) {
             decision = { retry: false };
@@ -512,10 +651,8 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 await rec.ended;
             if (rec.limit) {
                 await rec.limit.delivered;
-                rec.rerouteFrom = {
-                    accountId: rec.accountId,
-                    limit: rec.limit.signal,
-                };
+                rec.rerouted = true;
+                rerouteFrom = { accountId: rec.accountId, limit: rec.limit.signal };
                 // No delay: the next attempt goes to another account, and the
                 // host would otherwise wait out the refused account's backoff,
                 // or not retry at all for errors it deems final.
@@ -527,6 +664,16 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }
         draft.decision = decision;
+        // The host's retry runs `model.request` again for this attempt's
+        // session and kind; that next attempt, and no other attempt of the
+        // session, is told what this one ended with.
+        if (decision.retry && rec.accountId !== undefined) {
+            pendingRetries.set(rec.key, {
+                sessionID: rec.scope.sessionID,
+                accountId: rec.accountId,
+                ...(rerouteFrom === undefined ? {} : { rerouteFrom }),
+            });
+        }
         await emit('retry', {
             sessionID: draft.sessionID,
             ...(rec.accountId === undefined ? {} : { accountId: rec.accountId }),
@@ -539,11 +686,15 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         });
     }, scoped));
     const forgetSession = (sessionID) => {
-        for (const [key, rec] of records) {
+        for (const rec of [...attempts.values()]) {
             if (rec.scope.sessionID !== sessionID)
                 continue;
             abandon(rec, 'its session was forgotten');
-            records.delete(key);
+            attempts.delete(rec.id);
+        }
+        for (const [key, pending] of pendingRetries) {
+            if (pending.sessionID === sessionID)
+                pendingRetries.delete(key);
         }
     };
     const abort = new AbortController();
@@ -580,20 +731,21 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             };
         },
         accountFor(sessionID, kind) {
-            return records.get(keyOf(sessionID, kind))?.accountId;
+            return newestOf(keyOf(sessionID, kind))?.accountId;
         },
         forgetSession,
         get size() {
-            return records.size;
+            return attempts.size;
         },
         async dispose() {
             if (disposed)
                 return;
             disposed = true;
             abort.abort();
-            for (const rec of records.values())
+            for (const rec of attempts.values())
                 abandon(rec, 'the installation was disposed');
-            records.clear();
+            attempts.clear();
+            pendingRetries.clear();
             listeners.clear();
             await Promise.all(registrations.map(async (registration) => {
                 try {

package/dist/opencode2/types.d.ts

@@ -53,12 +53,16 @@ export interface EventVerdict<Q> {
  */
 export type HeaderEdits = Readonly<Record<string, string | null>>;
 export interface ChooseAccountInput extends RequestScope {
-    /** The account the previous attempt of this session and kind used. */
+    /**
+     * The account of the attempt this one retries, when the retry hook just
+     * asked the host to retry an attempt of this session and kind; otherwise
+     * the account of the newest attempt of this session and kind.
+     */
     readonly previousAccountId?: string;
     /**
-     * Set when the previous attempt was refused for a limit before any output
-     * and the retry hook asked the host to try again. The adapter should not
-     * pick `accountId` again unless it has nothing else.
+     * Set when the attempt this one retries was refused for a limit before any
+     * output and the retry hook asked the host to try again. The adapter
+     * should not pick `accountId` again unless it has nothing else.
      */
     readonly rerouteFrom?: {
         readonly accountId: string;
@@ -87,8 +91,27 @@ export interface Attempt<A = unknown> extends AccountRequest {
      * `model.request` is chosen before the host has picked the transport.
      */
     readonly transport: Transport | undefined;
-    /** What `accountHeaders` returned as `attempt`, if anything. */
+    /**
+     * What `accountHeaders` returned as `attempt`, if anything, or what
+     * `answeredBy` replaced it with.
+     */
     readonly data: A | undefined;
+    /**
+     * Set when `answeredBy` said another account answered this attempt's HTTP
+     * response: the account `chooseAccount` picked. `accountId` is then the
+     * account that answered, and everything from the response on is attributed
+     * to it.
+     */
+    readonly reboundFrom?: string;
+}
+/**
+ * The account that actually answered an HTTP response, as `answeredBy`
+ * reports it. `data`, when the key is present, replaces the attempt's `data`
+ * (the answering account's own credential receipt, say).
+ */
+export interface ResponseAccount<A = unknown> {
+    readonly accountId: string;
+    readonly data?: A;
 }
 /**
  * Why an attempt ended without completing.
@@ -97,11 +120,12 @@ export interface Attempt<A = unknown> extends AccountRequest {
  *   reported the response as failed;
  * - `cancelled`: the host cancelled the HTTP response body (the user stopped
  *   the turn, say);
- * - `abandoned`: the attempt was still open when a newer attempt of the same
- *   session and kind began, its session was forgotten, its record was
- *   dropped for space, or the installation was disposed. A WebSocket closed
- *   or cancelled mid-response ends this way, since the host has no hook for
- *   either.
+ * - `abandoned`: the attempt can no longer be observed: it was on WebSocket
+ *   (or the retry hook had already judged it) when a newer attempt of the
+ *   same session and kind began, another attempt of its session and kind
+ *   went out over WebSocket, its session was forgotten, it was dropped for
+ *   space, or the installation was disposed. A WebSocket closed or cancelled
+ *   mid-response ends this way, since the host has no hook for either.
  */
 export type AttemptEndReason = 'failed' | 'cancelled' | 'abandoned';
 /** How an attempt ended, as `onAttemptEnd` reports it. */
@@ -176,6 +200,25 @@ export interface OpenCode2AuthAdapter<Q = unknown, A = unknown> {
         readonly response: Response;
         readonly attempt: Attempt<A>;
     }): Promise<Response | undefined> | Response | undefined;
+    /**
+     * Optional. For an adapter whose own sender can move a request to another
+     * account after `rewriteRequest` (a bridge that answers a 401 or 403 by
+     * retrying on the next account, say): runs first in `http.response`,
+     * before quota, refusal, output or end detection, and returns the account
+     * that actually answered, or `undefined` when the attempt's own account
+     * did. A different account rebinds the attempt to it (`Attempt.accountId`
+     * becomes that account and `reboundFrom` the one chosen), so the response's
+     * quota, refusal, stream events, end and any retry reroute are attributed
+     * to the answering account, once, and never to the chosen one. What the
+     * sender saw from the chosen account before it moved on (the 401 itself)
+     * never reaches the installer: the adapter accounts for it itself.
+     * Throwing ends the attempt as `failed` and fails the response hook.
+     */
+    answeredBy?(input: {
+        readonly request: Request;
+        readonly response: Response;
+        readonly attempt: Attempt<A>;
+    }): Promise<ResponseAccount<A> | undefined> | ResponseAccount<A> | undefined;
     /** Optional WebSocket URL rewrite. Return `undefined` to keep the URL. */
     rewriteHandshakeURL?(input: AccountRequest & {
         readonly url: string;
@@ -270,7 +313,7 @@ export interface InstallOpenCode2AuthOptions {
      * adapter's provider.
      */
     readonly hostCredentials?: readonly string[];
-    /** Most `sessionID:kind` records kept before the oldest is dropped. */
+    /** Most attempts kept before the oldest is abandoned and dropped. */
     readonly maxRecords?: number;
     readonly logger?: OpenCode2AuthLogger;
 }
@@ -331,11 +374,16 @@ export interface OpenCode2AuthInstallation<Q, A = unknown> {
      * host. Returns a function that removes the listener.
      */
     on<E extends OpenCode2AuthEventName>(event: E, listener: (payload: OpenCode2AuthEvents<Q, A>[E]) => void | Promise<void>): () => void;
-    /** The account last chosen for a session and request kind. */
+    /**
+     * The account of the newest attempt of a session and request kind (after
+     * any `answeredBy` rebind). With several attempts of one session and kind
+     * in flight it names only the newest; each attempt's own account is on its
+     * handle.
+     */
     accountFor(sessionID: string, kind: RequestKind): string | undefined;
-    /** Drops every record of a session. Session deletion does this itself. */
+    /** Drops every attempt of a session. Session deletion does this itself. */
     forgetSession(sessionID: string): void;
-    /** Number of `sessionID:kind` records held. */
+    /** Number of attempts held. */
     readonly size: number;
     /** Removes every hook and stops listening for session deletion. */
     dispose(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {
@@ -87,7 +87,7 @@
     "types": "bun run typecheck",
     "format": "biome check --write --unsafe .",
     "format:check": "biome format .",
-    "lint": "biome lint .",
+    "lint": "biome check .",
     "prepublishOnly": "bun run build",
     "check:ranges": "bun scripts/check-installed-ranges.mjs"
   },