@cortexkit/common-auth 0.2.9 → 0.3.0

package/dist/opencode2/index.d.ts

@@ -5,4 +5,4 @@ export type { FormAnswer, PoolAuthorization, PoolLoginMethod, RegisterOpenCode2A
 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 { AccountRequest, 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, RetryReason, SelectingHook, Transport, } from './types.js';

package/dist/opencode2/install.d.ts

@@ -6,14 +6,27 @@ export declare function applyHeaderEdits(target: Record<string, string>, 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` and
- *   sets its headers;
+ * - `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`;
- * - `http.response` and `experimental.ws.receive` read quota, refusals and
- *   whether output has started, attributed through the record above;
+ * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
+ *   each outgoing frame;
+ * - `http.response` and `experimental.ws.receive` read quota, refusals,
+ *   whether output has started and when the response ended, attributed to
+ *   an attempt by the rules below;
  * - `retry` asks the host to retry at once when an account was refused
  *   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; if the host hands back a different request object,
+ * it belongs to the newest attempt of its session and kind only while that
+ * attempt went out over HTTP and has no response yet. 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.
  */
-export declare function installOpenCode2Auth<Q>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q>>;
+export declare function installOpenCode2Auth<Q, A = unknown>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q, A>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q, A>>;

package/dist/opencode2/install.js

@@ -10,6 +10,49 @@ const scopeOf = (draft) => ({
     agent: draft.agent,
     kind: draft.kind,
 });
+// A header value is a string or null, so an object under `headers` can only
+// be the `{headers, attempt}` form.
+function isHeadersResult(value) {
+    const headers = value.headers;
+    return typeof headers === 'object' && headers !== null;
+}
+/**
+ * Forwards a response body and reports how it ended: read to the end
+ * (`undefined`), errored, or cancelled by whoever was reading it.
+ */
+function trackBody(source, onEnd) {
+    const reader = source.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                onEnd({
+                    reason: 'failed',
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                controller.error(error);
+                return;
+            }
+            if (chunk.done) {
+                onEnd();
+                controller.close();
+            }
+            else {
+                controller.enqueue(chunk.value);
+            }
+        },
+        async cancel(reason) {
+            onEnd({
+                reason: 'cancelled',
+                ...(reason === undefined ? {} : { message: String(reason) }),
+            });
+            await reader.cancel(reason);
+        },
+    });
+}
 /** Applies edits to a plain header record, replacing every spelling of each name. */
 export function applyHeaderEdits(target, edits) {
     for (const [name, value] of Object.entries(edits)) {
@@ -34,15 +77,28 @@ 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` and
- *   sets its headers;
+ * - `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`;
- * - `http.response` and `experimental.ws.receive` read quota, refusals and
- *   whether output has started, attributed through the record above;
+ * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
+ *   each outgoing frame;
+ * - `http.response` and `experimental.ws.receive` read quota, refusals,
+ *   whether output has started and when the response ended, attributed to
+ *   an attempt by the rules below;
  * - `retry` asks the host to retry at once when an account was refused
  *   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; if the host hands back a different request object,
+ * it belongs to the newest attempt of its session and kind only while that
+ * attempt went out over HTTP and has no response yet. 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.
  */
 export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     const { providerID } = adapter;
@@ -76,15 +132,40 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }));
     };
+    const deliverEnd = async (attempt, outcome) => {
+        try {
+            await adapter.onAttemptEnd?.(attempt, outcome);
+        }
+        catch (error) {
+            warn('opencode2 auth onAttemptEnd threw; the request is unaffected', {
+                attemptId: attempt.attemptId,
+                error: describe(error),
+            });
+        }
+    };
+    /** Ends an attempt once; later calls for the same attempt do nothing. */
+    const finish = (rec, error) => {
+        if (rec.ended || !rec.attempt)
+            return;
+        const outcome = {
+            ...(rec.status === undefined ? {} : { status: rec.status }),
+            outputStarted: rec.outputStarted,
+            ...(rec.limit ? { limit: rec.limit.signal } : {}),
+            ...(error ? { error } : {}),
+        };
+        rec.ended = deliverEnd(rec.attempt, outcome);
+    };
+    const abandon = (rec, message) => finish(rec, { reason: 'abandoned', message });
     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.keys().next().value;
+            const oldest = records.entries().next().value;
             if (oldest === undefined)
                 break;
-            records.delete(oldest);
+            abandon(oldest[1], 'dropped to keep the record bound');
+            records.delete(oldest[0]);
         }
     };
     const accountOf = (rec) => rec.accountId === undefined
@@ -109,8 +190,10 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             }
         }
     };
-    const select = async (scope, hook) => {
+    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 input = {
             ...scope,
             ...(prior?.accountId === undefined
@@ -121,21 +204,42 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 : { rerouteFrom: prior.rerouteFrom }),
         };
         const accountId = await adapter.chooseAccount(input);
-        const headers = accountId === undefined
-            ? {}
-            : await adapter.accountHeaders({ ...scope, accountId });
+        let headers = {};
+        let data;
+        if (accountId !== undefined) {
+            const result = await adapter.accountHeaders({ ...scope, accountId });
+            if (isHeadersResult(result)) {
+                headers = result.headers;
+                data = result.attempt;
+            }
+            else {
+                headers = result;
+            }
+        }
+        const id = ++seq;
         const rec = {
             scope,
             accountId,
             headers,
-            seq: ++seq,
+            seq: id,
+            attempt: accountId === undefined
+                ? undefined
+                : {
+                    ...scope,
+                    accountId,
+                    attemptId: `attempt-${id}`,
+                    transport,
+                    data,
+                },
+            ...(transport === undefined ? {} : { transport }),
+            responded: false,
             outputStarted: false,
         };
         remember(rec);
-        if (accountId !== undefined) {
+        if (rec.attempt) {
             void emit('select', {
                 ...scope,
-                accountId,
+                accountId: rec.attempt.accountId,
                 hook,
                 ...(input.previousAccountId === undefined
                     ? {}
@@ -143,17 +247,40 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 ...(input.rerouteFrom === undefined
                     ? {}
                     : { rerouteFrom: input.rerouteFrom }),
+                handle: rec.attempt,
             });
         }
         return rec;
     };
-    // The transport hooks normally follow `model.request`; choosing here too
-    // keeps a request that skipped it from going out under the host credential.
-    const ensure = async (scope, hook) => records.get(keyOf(scope.sessionID, scope.kind)) ??
-        (await select(scope, hook));
+    // 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));
+        if (!rec || rec.transport !== undefined || rec.ended)
+            return select(scope, hook, transport);
+        rec.transport = transport;
+        if (rec.attempt)
+            rec.attempt.transport = transport;
+        return rec;
+    };
+    // A transport hook that throws stops the send, so its attempt is over.
+    const failing = async (rec, run) => {
+        try {
+            return await run();
+        }
+        catch (error) {
+            finish(rec, { reason: 'failed', message: describe(error) });
+            throw error;
+        }
+    };
+    const liveOn = (rec, transport) => rec?.attempt !== undefined && rec.transport === transport && !rec.ended
+        ? rec
+        : undefined;
     const noteLimit = (rec, signal, via) => {
         const account = accountOf(rec);
-        if (!account || rec.limit)
+        if (!account || !rec.attempt || rec.limit)
             return;
         rec.limit = {
             signal,
@@ -162,22 +289,29 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 via,
                 limit: signal,
                 outputStarted: rec.outputStarted,
+                handle: rec.attempt,
             }),
         };
     };
     const noteQuota = (rec, transport, quota, status) => {
         const account = accountOf(rec);
-        if (!account)
+        if (!account || !rec.attempt)
             return;
         void emit('quota', {
             ...account,
             transport,
             ...(status === undefined ? {} : { status }),
             quota,
+            handle: rec.attempt,
         });
     };
     const inspect = (rec, transport, data, event) => {
-        const verdict = adapter.inspectEvent?.(event === undefined ? { transport, data } : { transport, data, event });
+        const attempt = rec.attempt;
+        if (!attempt)
+            return;
+        const verdict = adapter.inspectEvent?.(event === undefined
+            ? { transport, data, attempt }
+            : { transport, data, event, attempt });
         if (!verdict)
             return;
         if (verdict.quota !== undefined)
@@ -186,6 +320,10 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             rec.outputStarted = true;
         if (verdict.limit)
             noteLimit(rec, verdict.limit, transport);
+        if (verdict.error !== undefined)
+            finish(rec, { reason: 'failed', message: verdict.error });
+        else if (verdict.done)
+            finish(rec);
     };
     const pickForRetry = (sessionID) => {
         let refused;
@@ -204,22 +342,28 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
         return refused ?? primary ?? latest;
     };
     const scoped = { providerID };
-    const registrations = [
-        await ctx.session.hook('model.request', async (draft) => {
-            const rec = await select(scopeOf(draft), 'model.request');
-            if (rec.accountId === undefined)
-                throw noAccount(rec.scope);
-            applyHeaderEdits(draft.headers, rec.headers);
-        }, scoped),
-        await ctx.session.hook('http.request', async (draft) => {
-            const rec = await ensure(scopeOf(draft), 'http.request');
-            const account = accountOf(rec);
-            if (!account)
-                throw noAccount(rec.scope);
+    const registrations = [];
+    registrations.push(await ctx.session.hook('model.request', async (draft) => {
+        const rec = await select(scopeOf(draft), 'model.request');
+        if (rec.accountId === undefined)
+            throw noAccount(rec.scope);
+        applyHeaderEdits(draft.headers, rec.headers);
+    }, scoped));
+    registrations.push(await ctx.session.hook('http.request', async (draft) => {
+        const rec = await bind(scopeOf(draft), 'http.request', 'http');
+        const account = accountOf(rec);
+        const attempt = rec.attempt;
+        if (!account || !attempt)
+            throw noAccount(rec.scope);
+        await failing(rec, async () => {
             let request = draft.request;
             if (adapter.rewriteRequest) {
                 request =
-                    (await adapter.rewriteRequest({ ...account, request })) ?? request;
+                    (await adapter.rewriteRequest({
+                        ...account,
+                        request,
+                        attempt,
+                    })) ?? request;
             }
             const headers = new Headers(request.headers);
             applyHeaderEditsTo(headers, rec.headers);
@@ -227,130 +371,170 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
             const final = new Request(request, { headers });
             byRequest.set(final, rec);
             draft.request = final;
-        }, scoped),
-        await ctx.session.hook('http.response', async (draft) => {
-            const rec = byRequest.get(draft.request) ??
-                records.get(keyOf(draft.sessionID, draft.kind));
-            const account = rec && accountOf(rec);
-            if (!rec || !account)
-                return;
-            const original = draft.response;
-            const quota = adapter.quotaFromHeaders?.(original.headers, original.status);
-            if (quota !== undefined)
-                noteQuota(rec, 'http', quota, original.status);
-            if (!original.ok && adapter.limitFromResponse) {
-                const signal = await adapter.limitFromResponse({
-                    status: original.status,
-                    headers: original.headers,
-                    body: () => original.clone().text(),
-                });
-                if (signal)
-                    noteLimit(rec, signal, 'http');
-            }
-            let response = original;
-            if (original.body && adapter.inspectEvent) {
-                const watch = watchServerSentEvents((event) => inspect(rec, 'http', event.data, event.event), (error) => warn('opencode2 auth event inspection threw', {
+        });
+    }, scoped));
+    registrations.push(await ctx.session.hook('http.response', async (draft) => {
+        const latest = records.get(keyOf(draft.sessionID, draft.kind));
+        const rec = byRequest.get(draft.request) ??
+            (latest && !latest.responded ? liveOn(latest, 'http') : undefined);
+        const account = rec && accountOf(rec);
+        const attempt = rec?.attempt;
+        if (!rec || !account || !attempt)
+            return;
+        const original = draft.response;
+        rec.responded = true;
+        rec.status = original.status;
+        const quota = adapter.quotaFromHeaders?.(original.headers, original.status, attempt);
+        if (quota !== undefined)
+            noteQuota(rec, 'http', quota, original.status);
+        if (!original.ok && adapter.limitFromResponse) {
+            const signal = await adapter.limitFromResponse({
+                status: original.status,
+                headers: original.headers,
+                body: () => original.clone().text(),
+                attempt,
+            });
+            if (signal)
+                noteLimit(rec, signal, 'http');
+        }
+        // An error response carries no output, so its status is the outcome;
+        // ending here keeps the end from depending on whether the host reads
+        // the error body to the end.
+        if (!original.ok || !original.body)
+            finish(rec);
+        let response = original;
+        if (original.body && (adapter.inspectEvent || adapter.onAttemptEnd)) {
+            let body = original.body;
+            if (adapter.inspectEvent) {
+                body = body.pipeThrough(watchServerSentEvents((event) => inspect(rec, 'http', event.data, event.event), (error) => warn('opencode2 auth event inspection threw', {
                     error: describe(error),
-                }));
-                response = new Response(original.body.pipeThrough(watch), {
-                    status: original.status,
-                    statusText: original.statusText,
-                    headers: original.headers,
-                });
+                })));
             }
-            if (adapter.rewriteResponse) {
-                response =
-                    (await adapter.rewriteResponse({
-                        ...account,
-                        request: draft.request,
-                        response,
-                    })) ?? response;
-            }
-            if (response !== original)
-                draft.response = response;
-        }, scoped),
-        await ctx.session.hook('experimental.ws.handshake', async (draft) => {
-            const rec = await ensure(scopeOf(draft), 'experimental.ws.handshake');
-            const account = accountOf(rec);
-            if (!account)
-                throw noAccount(rec.scope);
+            response = new Response(trackBody(body, (error) => finish(rec, error)), {
+                status: original.status,
+                statusText: original.statusText,
+                headers: original.headers,
+            });
+        }
+        if (adapter.rewriteResponse) {
+            response =
+                (await adapter.rewriteResponse({
+                    ...account,
+                    request: draft.request,
+                    response,
+                    attempt,
+                })) ?? response;
+        }
+        if (response !== original)
+            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');
+        const account = accountOf(rec);
+        const attempt = rec.attempt;
+        if (!account || !attempt)
+            throw noAccount(rec.scope);
+        await failing(rec, async () => {
             applyHeaderEdits(draft.headers, rec.headers);
             const url = adapter.rewriteHandshakeURL?.({
                 ...account,
                 url: draft.url,
+                attempt,
             });
             if (url !== undefined)
                 draft.url = url;
             guard(rec.scope, Object.entries(draft.headers));
-        }, scoped),
-        await ctx.session.hook('experimental.ws.receive', (draft) => {
-            const rec = records.get(keyOf(draft.sessionID, draft.kind));
-            if (!rec || rec.accountId === undefined)
-                return;
-            try {
-                inspect(rec, 'ws', draft.frame);
-            }
-            catch (error) {
-                warn('opencode2 auth frame inspection threw', {
-                    error: describe(error),
-                });
-            }
-        }, scoped),
-        await ctx.session.hook('retry', async (draft) => {
-            const rec = pickForRetry(draft.sessionID);
-            if (!rec)
-                return;
-            const hostDecision = draft.decision;
-            let decision = hostDecision;
-            let reason;
-            if (rec.accountId === undefined) {
-                decision = { retry: false };
-                reason = 'no-account';
+        });
+    }, scoped));
+    const rewriteFrame = adapter.rewriteWebSocketFrame?.bind(adapter);
+    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 frame = await rewriteFrame({
+                ...scope,
+                attempt: rec?.attempt,
+                frame: draft.frame,
+            });
+            if (frame !== undefined)
+                draft.frame = frame;
+        }, scoped));
+    }
+    registrations.push(await ctx.session.hook('experimental.ws.receive', (draft) => {
+        const rec = liveOn(records.get(keyOf(draft.sessionID, draft.kind)), 'ws');
+        if (!rec)
+            return;
+        try {
+            inspect(rec, 'ws', draft.frame);
+        }
+        catch (error) {
+            warn('opencode2 auth frame inspection threw', {
+                error: describe(error),
+            });
+        }
+    }, scoped));
+    registrations.push(await ctx.session.hook('retry', async (draft) => {
+        const rec = pickForRetry(draft.sessionID);
+        if (!rec)
+            return;
+        const hostDecision = draft.decision;
+        let decision = hostDecision;
+        let reason;
+        const attempt = rec.attempt;
+        if (rec.accountId === undefined || !attempt) {
+            decision = { retry: false };
+            reason = 'no-account';
+        }
+        else if (rec.outputStarted) {
+            // The user has already seen part of this answer; a retry would
+            // send it again.
+            decision = { retry: false };
+            reason = 'output-started';
+        }
+        else {
+            if (!rec.limit) {
+                const signal = adapter.limitFromError?.(draft.error, attempt);
+                if (signal)
+                    noteLimit(rec, signal, 'error');
             }
-            else if (rec.outputStarted) {
-                // The user has already seen part of this answer; a retry would
-                // send it again.
-                decision = { retry: false };
-                reason = 'output-started';
+            // The next `chooseAccount` should see whatever the plugin learnt
+            // from how this attempt ended.
+            if (rec.ended)
+                await rec.ended;
+            if (rec.limit) {
+                await rec.limit.delivered;
+                rec.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.
+                decision = { retry: true, delay: 0 };
+                reason = 'reroute';
             }
             else {
-                if (!rec.limit) {
-                    const signal = adapter.limitFromError?.(draft.error);
-                    if (signal)
-                        noteLimit(rec, signal, 'error');
-                }
-                if (rec.limit) {
-                    await rec.limit.delivered;
-                    rec.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.
-                    decision = { retry: true, delay: 0 };
-                    reason = 'reroute';
-                }
-                else {
-                    reason = 'host-decides';
-                }
+                reason = 'host-decides';
             }
-            draft.decision = decision;
-            await emit('retry', {
-                sessionID: draft.sessionID,
-                ...(rec.accountId === undefined ? {} : { accountId: rec.accountId }),
-                kind: rec.scope.kind,
-                attempt: draft.attempt,
-                reason,
-                hostDecision,
-                decision,
-            });
-        }, scoped),
-    ];
+        }
+        draft.decision = decision;
+        await emit('retry', {
+            sessionID: draft.sessionID,
+            ...(rec.accountId === undefined ? {} : { accountId: rec.accountId }),
+            kind: rec.scope.kind,
+            attempt: draft.attempt,
+            reason,
+            hostDecision,
+            decision,
+            ...(attempt === undefined ? {} : { handle: attempt }),
+        });
+    }, scoped));
     const forgetSession = (sessionID) => {
         for (const [key, rec] of records) {
-            if (rec.scope.sessionID === sessionID)
-                records.delete(key);
+            if (rec.scope.sessionID !== sessionID)
+                continue;
+            abandon(rec, 'its session was forgotten');
+            records.delete(key);
         }
     };
     const abort = new AbortController();
@@ -398,6 +582,8 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
                 return;
             disposed = true;
             abort.abort();
+            for (const rec of records.values())
+                abandon(rec, 'the installation was disposed');
             records.clear();
             listeners.clear();
             await Promise.all(registrations.map(async (registration) => {

package/dist/opencode2/types.d.ts

@@ -35,6 +35,17 @@ export interface EventVerdict<Q> {
     readonly outputStarted?: boolean;
     readonly quota?: Q;
     readonly limit?: LimitSignal;
+    /**
+     * This is the last event of the response (completed or failed); the
+     * attempt ends here. On WebSocket this is the only way an attempt ends
+     * normally, because the socket stays open between responses.
+     */
+    readonly done?: boolean;
+    /**
+     * The response failed with this message. Ends the attempt with
+     * `error.reason` `failed`; implies `done`.
+     */
+    readonly error?: string;
 }
 /**
  * Header changes for one account. A string sets the header (replacing every
@@ -57,6 +68,65 @@ export interface ChooseAccountInput extends RequestScope {
 export interface AccountRequest extends RequestScope {
     readonly accountId: string;
 }
+/**
+ * One physical send: created when an account is chosen for a request, and
+ * handed back on every hook call and event that belongs to that send, so a
+ * plugin can tie a response, a frame, a limit, a retry decision and the end
+ * of the send to the credential it chose for it.
+ *
+ * `A` is the plugin's own per-attempt value, returned by `accountHeaders`
+ * next to the headers (a served credential receipt, say); the installer
+ * only carries it.
+ */
+export interface Attempt<A = unknown> extends AccountRequest {
+    /** Unique within one installation. */
+    readonly attemptId: string;
+    /**
+     * The transport that carried the send. `undefined` until `http.request` or
+     * `experimental.ws.handshake` has run for it: an account chosen in
+     * `model.request` is chosen before the host has picked the transport.
+     */
+    readonly transport: Transport | undefined;
+    /** What `accountHeaders` returned as `attempt`, if anything. */
+    readonly data: A | undefined;
+}
+/**
+ * Why an attempt ended without completing.
+ *
+ * - `failed`: the response stream errored, or the adapter's `inspectEvent`
+ *   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.
+ */
+export type AttemptEndReason = 'failed' | 'cancelled' | 'abandoned';
+/** How an attempt ended, as `onAttemptEnd` reports it. */
+export interface AttemptOutcome {
+    /** The HTTP status of the response, when an HTTP response was seen. */
+    readonly status?: number;
+    /** Output from this attempt had reached the user. */
+    readonly outputStarted: boolean;
+    /** The account-level refusal recorded for this attempt, if any. */
+    readonly limit?: LimitSignal;
+    /** Absent when the response completed, whatever its status. */
+    readonly error?: {
+        readonly reason: AttemptEndReason;
+        readonly message?: string;
+    };
+}
+/**
+ * `accountHeaders` may return the header edits alone, or the edits together
+ * with a per-attempt value that the installer hands back in
+ * `Attempt.data`.
+ */
+export interface AccountHeadersResult<A = unknown> {
+    readonly headers: HeaderEdits;
+    readonly attempt?: A;
+}
 /** A host-supplied error, as the retry hook reports it. */
 export interface HostError {
     readonly type: string;
@@ -66,8 +136,9 @@ export interface HostError {
 /**
  * Everything provider-specific the installer needs. `Q` is the plugin's own
  * quota reading type; the installer only carries it to the `quota` event.
+ * `A` is the plugin's per-attempt value (see `Attempt`).
  */
-export interface OpenCode2AuthAdapter<Q = unknown> {
+export interface OpenCode2AuthAdapter<Q = unknown, A = unknown> {
     /** Every hook is scoped to this provider; other providers are untouched. */
     readonly providerID: string;
     /**
@@ -81,14 +152,19 @@ export interface OpenCode2AuthAdapter<Q = unknown> {
      * `model.request`, `http.request` and `experimental.ws.handshake`. The last
      * two run after the host has applied its own credential, so these headers
      * win on the wire.
+     *
+     * Called once per attempt, when the account is chosen. Returning
+     * `{headers, attempt}` instead of the bare edits stores `attempt` as the
+     * attempt's `data`, handed back on everything that belongs to the attempt.
      */
-    accountHeaders(input: AccountRequest): Promise<HeaderEdits> | HeaderEdits;
+    accountHeaders(input: AccountRequest): Promise<HeaderEdits | AccountHeadersResult<A>> | HeaderEdits | AccountHeadersResult<A>;
     /**
      * Optional request rewrite (URL, body) before the account headers are
      * applied. Return `undefined` to keep the request.
      */
     rewriteRequest?(input: AccountRequest & {
         readonly request: Request;
+        readonly attempt: Attempt<A>;
     }): Promise<Request | undefined> | Request | undefined;
     /**
      * Optional response rewrite (body stream, status). It receives the
@@ -98,13 +174,35 @@ export interface OpenCode2AuthAdapter<Q = unknown> {
     rewriteResponse?(input: AccountRequest & {
         readonly request: Request;
         readonly response: Response;
+        readonly attempt: Attempt<A>;
     }): Promise<Response | undefined> | Response | undefined;
     /** Optional WebSocket URL rewrite. Return `undefined` to keep the URL. */
     rewriteHandshakeURL?(input: AccountRequest & {
         readonly url: string;
+        readonly attempt: Attempt<A>;
     }): string | undefined;
+    /**
+     * Optional rewrite of each outgoing WebSocket frame of this provider,
+     * from `experimental.ws.send`. Return the frame to send, or `undefined` to
+     * send it unchanged.
+     *
+     * The rewrite must be a deterministic function of the frame (stable for
+     * the session): the host chains turns with `previous_response_id` by
+     * diffing its own request as it was before this hook ran, so the server
+     * only stays in step when every frame is rewritten the same way. Do not
+     * touch `input` or `previous_response_id`. Adding or changing settings
+     * fields uniformly keeps the follow-up turn incremental.
+     *
+     * It runs for every frame, including one no attempt can be tied to
+     * (`attempt` is then `undefined`), so the rewrite never depends on
+     * attribution.
+     */
+    rewriteWebSocketFrame?(input: RequestScope & {
+        readonly attempt: Attempt<A> | undefined;
+        readonly frame: string;
+    }): Promise<string | undefined> | string | undefined;
     /** Quota carried in HTTP response headers. */
-    quotaFromHeaders?(headers: Headers, status: number): Q | undefined;
+    quotaFromHeaders?(headers: Headers, status: number, attempt: Attempt<A>): Q | undefined;
     /**
      * Recognises an account-level refusal from an HTTP response before its
      * body is streamed. `body()` reads a copy, so the host still gets the body.
@@ -113,21 +211,35 @@ export interface OpenCode2AuthAdapter<Q = unknown> {
         readonly status: number;
         readonly headers: Headers;
         readonly body: () => Promise<string>;
+        readonly attempt: Attempt<A>;
     }): Promise<LimitSignal | undefined> | LimitSignal | undefined;
     /**
      * Inspects one server-sent event (`data` payload) or one WebSocket frame.
-     * Detects output, quota and refusals inside the stream.
+     * Detects output, quota, refusals and the end of the response inside the
+     * stream.
      */
     inspectEvent?(input: {
         readonly transport: Transport;
         readonly data: string;
         readonly event?: string;
+        readonly attempt: Attempt<A>;
     }): EventVerdict<Q> | undefined;
     /**
      * Recognises an account-level refusal from the error the host hands the
-     * retry hook, for refusals no other hook saw.
+     * retry hook, for refusals no other hook saw. `attempt` is the attempt
+     * the retry hook judged.
+     */
+    limitFromError?(error: HostError, attempt: Attempt<A>): LimitSignal | undefined;
+    /**
+     * Called once per attempt when it ends: an HTTP response body finished,
+     * errored or was cancelled; an HTTP response with an error status or no
+     * body arrived; an event's verdict said `done` or `error`; or the attempt
+     * was abandoned (see `AttemptEndReason`). Errors are logged and never
+     * reach the host. The retry hook waits for this call to settle before it
+     * decides, so a plugin that records a refusal here has it in place when
+     * `chooseAccount` runs again.
      */
-    limitFromError?(error: HostError): LimitSignal | undefined;
+    onAttemptEnd?(attempt: Attempt<A>, outcome: AttemptOutcome): Promise<void> | void;
 }
 export interface OpenCode2AuthLogger {
     warn(message: string, data?: unknown): void;
@@ -150,18 +262,24 @@ export type RetryReason = 'reroute' | 'output-started' | 'no-account' | 'host-de
  * plugin may want to log as a host change.
  */
 export type SelectingHook = 'model.request' | 'http.request' | 'experimental.ws.handshake';
-export interface OpenCode2AuthEvents<Q> {
+/**
+ * Every event that belongs to one attempt carries it as `handle` (the
+ * `retry` event already uses `attempt` for the host's retry count).
+ */
+export interface OpenCode2AuthEvents<Q, A = unknown> {
     /** An account was picked for a model request. */
     readonly select: AccountRequest & {
         readonly hook: SelectingHook;
         readonly previousAccountId?: string;
         readonly rerouteFrom?: ChooseAccountInput['rerouteFrom'];
+        readonly handle: Attempt<A>;
     };
     /** A quota reading, attributed through this installer's own record. */
     readonly quota: AccountRequest & {
         readonly transport: Transport;
         readonly status?: number;
         readonly quota: Q;
+        readonly handle: Attempt<A>;
     };
     /**
      * An account-level refusal. The retry hook waits for every listener of
@@ -172,6 +290,7 @@ export interface OpenCode2AuthEvents<Q> {
         readonly via: Transport | 'error';
         readonly limit: LimitSignal;
         readonly outputStarted: boolean;
+        readonly handle: Attempt<A>;
     };
     /** The retry hook ran for this provider. */
     readonly retry: {
@@ -182,15 +301,17 @@ export interface OpenCode2AuthEvents<Q> {
         readonly reason: RetryReason;
         readonly hostDecision: SessionRetryDecision;
         readonly decision: SessionRetryDecision;
+        /** The attempt the decision was about, when it had an account. */
+        readonly handle?: Attempt<A>;
     };
 }
 export type OpenCode2AuthEventName = keyof OpenCode2AuthEvents<unknown>;
-export interface OpenCode2AuthInstallation<Q> {
+export interface OpenCode2AuthInstallation<Q, A = unknown> {
     /**
      * Listens to an event. Listener errors are logged and never reach the
      * host. Returns a function that removes the listener.
      */
-    on<E extends OpenCode2AuthEventName>(event: E, listener: (payload: OpenCode2AuthEvents<Q>[E]) => void | Promise<void>): () => void;
+    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. */
     accountFor(sessionID: string, kind: RequestKind): string | undefined;
     /** Drops every record of a session. Session deletion does this itself. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.2.9",
+  "version": "0.3.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": {