@cortexkit/common-auth 0.2.9 → 0.4.0

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,33 @@ 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 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.
  */
 export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     const { providerID } = adapter;
@@ -51,6 +112,7 @@ export async function installOpenCode2Auth(ctx, adapter, options = {}) {
     const forbidden = (options.hostCredentials ?? [placeholderSecret(providerID)]).filter((value) => value !== '');
     const records = new Map();
     const byRequest = new WeakMap();
+    let warnedUnprovenResponse = false;
     const listeners = new Map();
     let seq = 0;
     const warn = (message, data) => {
@@ -76,15 +138,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 +196,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 +210,41 @@ 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 }),
             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 +252,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 +294,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 +325,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 +347,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 +376,174 @@ 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');
+        });
+    }, scoped));
+    registrations.push(await ctx.session.hook('http.response', async (draft) => {
+        const rec = byRequest.get(draft.request);
+        if (!rec) {
+            if (!warnedUnprovenResponse) {
+                warnedUnprovenResponse = true;
+                warn('opencode2 auth dropped an http.response whose request it did not produce', { sessionID: draft.sessionID, kind: draft.kind });
             }
-            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', {
+            return;
+        }
+        const account = accountOf(rec);
+        const attempt = rec?.attempt;
+        if (!rec || !account || !attempt)
+            return;
+        const original = draft.response;
+        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 +591,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) => {