@cortexkit/common-auth 0.2.9 → 0.4.0

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,54 @@ 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. Never
+     * alter, drop or reorder the `input` items the host put in the frame, and
+     * never touch `previous_response_id`: the host's next frame assumes the
+     * server holds exactly what it sent. Adding items to `input`, or adding or
+     * changing settings fields, keeps the host's order and continuation when
+     * done the same way for every frame: the added items become part of the
+     * server's history and the follow-up turn stays incremental.
+     *
+     * What inserting `input` items into every frame does not keep is the
+     * equivalence of the two ways a history reaches the server (settings
+     * fields carry no history, so they are not affected). Incrementally, each
+     * frame carries only
+     * the new items, so an item the rewrite inserts into every frame lands at
+     * every network boundary of the accumulated history. After a reconnect the
+     * host replays the whole history in one frame, and the same rewrite
+     * inserts that item once. The two server-side histories, and their cache
+     * prefixes, then differ. A rewrite that only adds or changes settings
+     * fields is unaffected. An adapter that inserts `input` items must show,
+     * for its own insertion, that the accumulated incremental history equals
+     * the rewritten full replay (including across tool loops), or accept the
+     * divergence and name what it costs (a cache miss and a different prompt
+     * after every reconnect).
+     *
+     * 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 +230,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 +281,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 +309,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 +320,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/dist/quota/projection.d.ts

@@ -33,10 +33,17 @@ export interface ProjectedQuota {
 }
 /**
  * Resolves `map` for a request in `scope` (`all` or a model family). A family
- * request sees only its own family's keys and the `all` keys. Per label, a
- * family reading shadows the `all` entry; a family tombstone or absence
- * record says only that no family-specific limit exists, so it does not hide
- * an `all` entry for the same label and is used only when there is none.
+ * request sees only its own family's keys and the `all` keys.
+ *
+ * The label decides how a family limit relates to a general one. Under the
+ * same label, the family reading replaces the `all` reading: use this only
+ * when the provider's family figure is a more specific view of the same cap.
+ * Under different labels both limits are projected and every consumer judges
+ * both, so a family cap that applies on top of a general cap must be stored
+ * under its own label; otherwise the general cap is hidden from a family
+ * request. A family tombstone or absence record says only that no
+ * family-specific limit exists, so it does not hide an `all` entry for the
+ * same label and is used only when there is none.
  */
 export declare function projectQuota(map: QuotaMap | undefined, scope?: string): ProjectedQuota;
 export interface ExhaustionReset {

package/dist/quota/projection.js

@@ -61,10 +61,17 @@ function projectBudget(budget) {
 }
 /**
  * Resolves `map` for a request in `scope` (`all` or a model family). A family
- * request sees only its own family's keys and the `all` keys. Per label, a
- * family reading shadows the `all` entry; a family tombstone or absence
- * record says only that no family-specific limit exists, so it does not hide
- * an `all` entry for the same label and is used only when there is none.
+ * request sees only its own family's keys and the `all` keys.
+ *
+ * The label decides how a family limit relates to a general one. Under the
+ * same label, the family reading replaces the `all` reading: use this only
+ * when the provider's family figure is a more specific view of the same cap.
+ * Under different labels both limits are projected and every consumer judges
+ * both, so a family cap that applies on top of a general cap must be stored
+ * under its own label; otherwise the general cap is hidden from a family
+ * request. A family tombstone or absence record says only that no
+ * family-specific limit exists, so it does not hide an `all` entry for the
+ * same label and is used only when there is none.
  */
 export function projectQuota(map, scope = ALL_SCOPE) {
     const byLabel = new Map();

package/dist/routing/admission.js

@@ -6,7 +6,9 @@
 //
 // A marked or backed-off row is excluded before the gates. Stage 1 then
 // judges each remaining row alone, in gate order:
-//   1. an API-key row is admitted without consulting quota;
+//   1. an API-key row is admitted without consulting quota (a provider that
+//      offers paid rows only after its OAuth rows are spent leaves them out
+//      of `rows` until then);
 //   2. an OAuth row whose projection resolves no entry for the scope needs a
 //      first reading: refused, pull requested;
 //   3. a required label with no entry is unknown: refused, pull requested;

package/dist/routing/index.d.ts

@@ -4,5 +4,5 @@ export type { OrderedAttempt, OrderedPlacement, OrderedRoute, OrderedRouteInput,
 export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
 export type { StickyPin } from './pins.js';
 export { isPinValid, pendingBytesForPins } from './pins.js';
-export type { PinAction, StickyBreakDecision, StickyRoute, StickyRouteInput, StickySelection, StickySelectionCandidate, StickySelectionInput, } from './sticky.js';
-export { decideStickyBreak, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, STICKY_WINDOW_SLOTS, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';
+export type { PinAction, StickyBreakDecision, StickyRoute, StickyRouteInput, StickySelection, StickySelectionCandidate, StickySelectionInput, StickyStatusClass, StickyStatusClassifier, } from './sticky.js';
+export { decideStickyBreak, defaultStickyStatusClass, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/routing/index.js

@@ -1,4 +1,4 @@
 export { admit, exclusionFor } from './admission.js';
 export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
 export { isPinValid, pendingBytesForPins } from './pins.js';
-export { decideStickyBreak, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, STICKY_WINDOW_SLOTS, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';
+export { decideStickyBreak, defaultStickyStatusClass, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/routing/sticky.d.ts

@@ -4,12 +4,6 @@ import { type StickyPin } from './pins.js';
 export declare const QUOTA_STALENESS_MS: number;
 export declare const MIN_RESET_HOURS: number;
 export declare const MIN_WEIGHT = 0.000001;
-/**
- * How many window readings the selection primitives judge, as openai-auth's
- * primary and secondary slots did. The projection's first readings in its
- * order fill the slots; any further window is judged by admission only.
- */
-export declare const STICKY_WINDOW_SLOTS = 2;
 /** The projection's time, else the caller's cache-entry time. */
 export declare function snapshotCheckedAt(quota: ProjectedQuota | null | undefined, entryCheckedAt?: number): number | undefined;
 export type StickyBreakDecision = {
@@ -22,6 +16,23 @@ export type StickyBreakDecision = {
     window?: WindowRef;
     resetsAt?: string;
 };
+/**
+ * How the adapter reads a failed response's HTTP status for the break
+ * decision. `permanent` moves the session off its row before any quota is
+ * consulted; `transient` and `healthy` keep it unless the quota says the row
+ * is spent. A missing status means the request failed without a response.
+ */
+export type StickyStatusClass = 'permanent' | 'transient' | 'healthy';
+export type StickyStatusClassifier = (status: number | undefined) => StickyStatusClass;
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export declare function defaultStickyStatusClass(status: number | undefined): StickyStatusClass;
 /** Classifies whether a pinned session should leave its row after a failure. */
 export declare function decideStickyBreak(input: {
     quota: ProjectedQuota | null | undefined;
@@ -29,6 +40,8 @@ export declare function decideStickyBreak(input: {
     status?: number;
     now: number;
     killswitchPasses?: boolean;
+    /** Defaults to `defaultStickyStatusClass`. */
+    classifyStatus?: StickyStatusClassifier;
 }): StickyBreakDecision;
 export declare function sustainableWindowWeight(window: {
     remainingPercent: number;

package/dist/routing/sticky.js

@@ -7,12 +7,6 @@ import { isPinValid } from './pins.js';
 export const QUOTA_STALENESS_MS = 15 * 60_000;
 export const MIN_RESET_HOURS = 1 / 60;
 export const MIN_WEIGHT = 1e-6;
-/**
- * How many window readings the selection primitives judge, as openai-auth's
- * primary and secondary slots did. The projection's first readings in its
- * order fill the slots; any further window is judged by admission only.
- */
-export const STICKY_WINDOW_SLOTS = 2;
 /** The projection's time, else the caller's cache-entry time. */
 export function snapshotCheckedAt(quota, entryCheckedAt) {
     for (const checkedAt of [quota?.checkedAt, entryCheckedAt]) {
@@ -22,10 +16,33 @@ export function snapshotCheckedAt(quota, entryCheckedAt) {
     }
     return undefined;
 }
-function slotReadings(quota) {
-    // Longest known window first, unknown lengths last, as openai-auth sorts.
-    // Tombstones and absence records carry no capacity figure, so they occupy
-    // no slot.
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export function defaultStickyStatusClass(status) {
+    if (status === 401 || status === 403)
+        return 'permanent';
+    if (status === undefined ||
+        status === 0 ||
+        !Number.isFinite(status) ||
+        (status >= 500 && status <= 599) ||
+        status === 429) {
+        return 'transient';
+    }
+    return 'healthy';
+}
+function windowReadings(quota) {
+    // Every reading is an independent constraint, so all of them are judged:
+    // a third window (for example a short window beside two weekly ones) can
+    // be the one that is nearly spent. Longest known window first, unknown
+    // lengths last, as openai-auth sorts, so a break decision with several
+    // spent windows names the longest. Tombstones and absence records carry no
+    // capacity figure and are left out.
     return quota.limits
         .filter((limit) => limit.kind === 'reading')
         .sort((left, right) => {
@@ -37,12 +54,12 @@ function slotReadings(quota) {
             return (right.windowMinutes ?? 0) - (left.windowMinutes ?? 0);
         }
         return 0;
-    })
-        .slice(0, STICKY_WINDOW_SLOTS);
+    });
 }
 /** Classifies whether a pinned session should leave its row after a failure. */
 export function decideStickyBreak(input) {
-    if (input.status === 401 || input.status === 403) {
+    const statusClass = (input.classifyStatus ?? defaultStickyStatusClass)(input.status);
+    if (statusClass === 'permanent') {
         return { action: 'migrate', reason: 'permanent' };
     }
     if (!input.quota)
@@ -58,7 +75,7 @@ export function decideStickyBreak(input) {
     if (input.killswitchPasses === false) {
         return { action: 'migrate', reason: 'killswitch' };
     }
-    for (const limit of slotReadings(input.quota)) {
+    for (const limit of windowReadings(input.quota)) {
         const remaining = limit.remainingPercent;
         if (typeof remaining === 'number' &&
             Number.isFinite(remaining) &&
@@ -83,14 +100,7 @@ export function decideStickyBreak(input) {
             resetsAt: budgetReset.resetsAt,
         };
     }
-    if (input.status === undefined ||
-        input.status === 0 ||
-        !Number.isFinite(input.status) ||
-        (input.status >= 500 && input.status <= 599) ||
-        input.status === 429) {
-        return { action: 'retain', reason: 'transient' };
-    }
-    return { action: 'retain', reason: 'healthy' };
+    return { action: 'retain', reason: statusClass };
 }
 export function sustainableWindowWeight(window, reservePercent, now) {
     const spendable = Math.max(0, window.remainingPercent - reservePercent);
@@ -124,7 +134,8 @@ function candidateWeight(candidate, now) {
     }
     // Missing reserve data must leave a window usable rather than silently
     // excluding its account.
-    const weights = slotReadings(candidate.quota).map((limit) => sustainableWindowWeight({
+    // The account is as constrained as its tightest window, whichever it is.
+    const weights = windowReadings(candidate.quota).map((limit) => sustainableWindowWeight({
         remainingPercent: limit.remainingPercent ?? Number.NaN,
         ...(limit.resetsAt === undefined ? {} : { resetsAt: limit.resetsAt }),
     }, candidate.reservePercent[limit.label] ?? 0, now));

package/dist/rpc/notifications.d.ts

@@ -22,7 +22,27 @@ export interface NotificationScope {
     rpcRoot: string;
     directoryPrefix: string;
     registrationSessionId: string;
+    /**
+     * Strict session isolation. When true, `pushNotification` and
+     * `drainNotifications` refuse an absent or empty session id (throwing
+     * `RpcSessionRequiredError`) and a drain returns only that session's own
+     * notifications: no notification reaches every session. A strict scope is
+     * a separate queue from the same scope without the flag, so a lenient
+     * caller cannot push into it or drain it.
+     *
+     * Off by default: without it, a drain with no session returns every
+     * session's notifications and a push with no session reaches every
+     * session, which plugins that drain from one process-wide TUI rely on.
+     */
+    requireSession?: boolean;
 }
+/** A strict notification scope was used without a session id. */
+export declare class RpcSessionRequiredError extends Error {
+    readonly operation: 'push' | 'drain';
+    constructor(operation: 'push' | 'drain');
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export declare function isSessionId(value: unknown): value is string;
 export declare function pushNotification(scope: NotificationScope, payload: OpenDialogPayload, sessionId?: string): void;
 export declare function drainNotifications(scope: NotificationScope, lastReceivedId?: number, sessionId?: string): RpcNotification[];
 export declare function isTuiConnected(scope: NotificationScope, sessionId: string): boolean;

package/dist/rpc/notifications.js

@@ -1,9 +1,23 @@
+/** A strict notification scope was used without a session id. */
+export class RpcSessionRequiredError extends Error {
+    operation;
+    constructor(operation) {
+        super(`a ${operation} on a strict notification scope needs a session id`);
+        this.name = 'RpcSessionRequiredError';
+        this.operation = operation;
+    }
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export function isSessionId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 const queues = new Map();
 function state(scope) {
     const key = JSON.stringify([
         scope.rpcRoot,
         scope.directoryPrefix,
         scope.registrationSessionId,
+        ...(scope.requireSession === true ? ['strict'] : []),
     ]);
     let value = queues.get(key);
     if (!value) {
@@ -15,6 +29,8 @@ function state(scope) {
 const QUEUE_CAP = 100;
 const TUI_CONNECTED_WINDOW_MS = 3_000;
 export function pushNotification(scope, payload, sessionId) {
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('push');
     const value = state(scope);
     value.queue.push({
         id: value.nextId++,
@@ -26,6 +42,11 @@ export function pushNotification(scope, payload, sessionId) {
         value.queue = value.queue.slice(-QUEUE_CAP);
 }
 export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
+    // A strict queue holds only session-scoped notifications (its push refuses
+    // the rest), so the ordinary match below already gives a strict drain
+    // nothing but its own session's notifications.
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('drain');
     const value = state(scope);
     const now = Date.now();
     if (sessionId !== undefined)

package/dist/rpc/rpc-server.d.ts

@@ -1,5 +1,5 @@
 import type { RpcLogChannel } from './index.js';
-import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
+import { type ApplyRequest, type ApplyResult, type RpcNotification } from './notifications.js';
 export interface RpcServerHandle {
     port: number;
     token: string;
@@ -13,6 +13,14 @@ export interface RpcServerOptions {
     sweepRoot?: string;
     drain: (lastReceivedId: number, sessionId?: string) => RpcNotification[];
     apply: (request: ApplyRequest) => Promise<ApplyResult>;
+    /**
+     * Refuse a `pending-notifications` drain whose `sessionId` is absent, not a
+     * string or empty, with 400 and without calling `drain`. Pair it with a
+     * strict notification scope (`requireSession`) so neither the wire nor
+     * the queue can hand one session's notifications to another. Off by
+     * default, when a session-less drain is passed to `drain` as undefined.
+     */
+    requireSession?: boolean;
     timeoutMs?: number;
     receiptTimeoutMs?: number;
 }

package/dist/rpc/rpc-server.js

@@ -2,6 +2,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { readFile, unlink } from 'node:fs/promises';
 import { createServer, } from 'node:http';
 import { join } from 'node:path';
+import { isSessionId, } from './notifications.js';
 import { sweepRpcState, writePortFile } from './port-file.js';
 function readBody(req) {
     return new Promise((resolve, reject) => {
@@ -64,6 +65,8 @@ export async function startRpcServer(options) {
             const body = await readBody(req);
             const params = JSON.parse(body || '{}');
             if (method === 'pending-notifications') {
+                if (options.requireSession === true && !isSessionId(params.sessionId))
+                    return json(400, { error: 'session required' });
                 const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
                 if (sessionId === undefined && !warnedMissingNotificationSession) {
                     warnedMissingNotificationSession = true;
@@ -81,9 +84,13 @@ export async function startRpcServer(options) {
             return json(404, { error: 'unknown method' });
         }
         catch (error) {
-            json(500, {
+            // A handler's exception can quote a request or a credential, so its
+            // text goes to the plugin's log channel only; the wire gets a fixed code.
+            log.warn('rpc request failed', {
+                pid: process.pid,
                 error: error instanceof Error ? error.message : String(error),
             });
+            json(500, { error: 'internal error' });
         }
     }
     const port = await new Promise((resolve, reject) => {

package/dist/sidebar-file/index.d.ts

@@ -1,2 +1,2 @@
-export type { SidebarFile, SidebarFileHooks, SidebarFileOptions, } from './sidebar-file.js';
+export type { SidebarFile, SidebarFileHooks, SidebarFileOptions, SidebarRepair, SidebarWriteOptions, SidebarWriteResult, } from './sidebar-file.js';
 export { createSidebarFile } from './sidebar-file.js';