@cortexkit/anthropic-auth-core 1.23.0 → 2.0.0

package/dist/internal-types/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ex Machina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/internal-types/commands/builtins.d.ts

@@ -0,0 +1,71 @@
+import type { AddInput, PoolLockSpec, PoolRow, PoolStore, RemoveOptions } from '../store/index.js';
+import type { CommandInvocation, KnobValues, MenuChoice, MenuKnob } from './model.js';
+import { type ResolvedSection } from './seam.js';
+/**
+ * What a plugin's login hands back. `ready` adds the account now. `pending`
+ * means the user must finish somewhere else (a browser, a device code):
+ * `message` tells them how, and the account is added when `completion`
+ * settles, with the result sent to the invocation that started it.
+ */
+export type LoginOutcome = {
+    status: 'ready';
+    account: AddInput;
+} | {
+    status: 'pending';
+    message: string;
+    /** Resolves with the account to add, or undefined when the user gave up. */
+    completion: Promise<AddInput | undefined>;
+} | {
+    status: 'cancelled';
+    message?: string;
+};
+export interface AccountsSectionOptions {
+    /** What to show as an account's identity; defaults to its recorded identity. */
+    describeIdentity?(row: PoolRow): string | undefined;
+    /** The plugin's login; without it the section offers no add action. */
+    login?: {
+        label?: string;
+        knobs?: MenuKnob[];
+        run(values: KnobValues, invocation: CommandInvocation): Promise<LoginOutcome>;
+    };
+    /** Passed to `store.remove`: a reason refuses removing that id. */
+    protect?: RemoveOptions['protect'];
+}
+export interface QuotaSectionOptions {
+    /** The quota scope to show (`all` or a model family); defaults to `all`. */
+    scope?: string;
+    /**
+     * Checks quota now for the named rows. Without it, the menu asks the store
+     * for a reading of each row and waits for the pulls to settle.
+     */
+    check?(ids: readonly string[], invocation: CommandInvocation): Promise<void>;
+}
+export interface RoutingSectionOptions {
+    /**
+     * Further `routing.mode` values the plugin routes as `ordered` with the
+     * former main row moved (`main-first`, `fallback-first`), offered between
+     * `ordered` and `sticky-balanced`.
+     */
+    orderedVariants?: MenuChoice[];
+    formerMainId?: string;
+}
+export interface LimitsSectionOptions {
+    /**
+     * The quota window labels a floor can be set for. Defaults to every label
+     * the pool's quota readings carry, or `primary` when there are none.
+     */
+    labels?: readonly string[];
+}
+export interface BuiltinOptions {
+    store: PoolStore;
+    extraLocks?: readonly PoolLockSpec[];
+    now: () => number;
+    accounts?: AccountsSectionOptions;
+    quota?: QuotaSectionOptions;
+    routing?: RoutingSectionOptions;
+    limits?: LimitsSectionOptions;
+}
+/** `disabledReason` recorded when the user disables an account from the menu. */
+export declare const MENU_DISABLED_REASON = "disabled from the command menu";
+/** The four built-in sections, in their fixed order, from one read of the store. */
+export declare function builtinSections(options: BuiltinOptions): Promise<ResolvedSection[]>;

package/dist/internal-types/commands/index.d.ts

@@ -0,0 +1,10 @@
+export type { AccountsSectionOptions, LimitsSectionOptions, LoginOutcome, QuotaSectionOptions, RoutingSectionOptions, } from './builtins.js';
+export { MENU_DISABLED_REASON } from './builtins.js';
+export type { CommandMenu, CommandMenuOptions, StoreSectionSlot, } from './menu.js';
+export { createCommandMenu, parseApplyRequest } from './menu.js';
+export type { ActionDefinition, ActionInput, ActionOutcome, CommandApplyRequest, CommandApplyResult, CommandDialogPayload, CommandInvocation, CommandMenuModel, ItemDefinition, KnobValue, KnobValues, MenuAccount, MenuAction, MenuChoice, MenuConfirmation, MenuItem, MenuKnob, MenuSection, NotifyKind, PluginExtraSection, PluginSection, SectionContent, SectionSlot, } from './model.js';
+export { SECTION_SLOTS } from './model.js';
+export type { PiMenuOptions, PiMenuUi } from './pi.js';
+export { runPiCommandMenu } from './pi.js';
+export type { ProjectedFailure, SeamLogger, TextRedactor } from './seam.js';
+export { ACTION_FAILED, CommandError, createTextRedactor, DEFAULT_IRREVERSIBLE_CONFIRMATION, projectFailure, } from './seam.js';

package/dist/internal-types/commands/menu.d.ts

@@ -0,0 +1,61 @@
+import { type RedactionOptions } from '../logger/index.js';
+import type { PoolLockSpec, PoolStore } from '../store/index.js';
+import { type AccountsSectionOptions, type LimitsSectionOptions, type QuotaSectionOptions, type RoutingSectionOptions } from './builtins.js';
+import type { CommandApplyRequest, CommandApplyResult, CommandDialogPayload, CommandInvocation, PluginExtraSection, PluginSection } from './model.js';
+import { type SeamLogger } from './seam.js';
+/** The four slots the library can build from a pool store. */
+export type StoreSectionSlot = 'accounts' | 'quota' | 'routing' | 'limits';
+export interface CommandMenuOptions {
+    /** The slash command's name without the slash (`openai`, `claude`). */
+    command: string;
+    /** The dialog title. */
+    title: string;
+    /**
+     * The pool store the built-in Accounts, Quota, Routing and Limits sections
+     * read and write. Required unless `replace` supplies all four.
+     */
+    store?: PoolStore;
+    /**
+     * Plugin sections that take the place of built-in ones, keeping their slot
+     * and the fixed order. For a plugin whose accounts are not pool rows (a
+     * single host login, or rows it must not expose by id), so it renders its
+     * own items and actions without a store. A replaced slot's built-in
+     * options (`accounts`, `quota`, ...) must not be given.
+     */
+    replace?: Partial<Record<StoreSectionSlot, PluginSection>>;
+    /** The plugin's legacy locks, passed to every store write the menu makes. */
+    extraLocks?: readonly PoolLockSpec[];
+    accounts?: AccountsSectionOptions;
+    quota?: QuotaSectionOptions;
+    routing?: RoutingSectionOptions;
+    limits?: LimitsSectionOptions;
+    /** The Cache section; omitted when the plugin has none. */
+    cache?: PluginSection;
+    /** The Diagnostics section (dumps, logging); omitted when the plugin has none. */
+    diagnostics?: PluginSection;
+    /** Provider extras, shown after every fixed section in this order. */
+    extras?: readonly PluginExtraSection[];
+    /** Receives the seam's warnings and failed actions; defaults to the library logger. */
+    logger?: SeamLogger;
+    /**
+     * The provider's secret shapes, added to the redactor every string that
+     * leaves the menu goes through (payloads and notifications). Without a
+     * pattern for its key format, a plugin's API key quoted in an outcome's
+     * text is not recognised.
+     */
+    redaction?: RedactionOptions;
+    now?: () => number;
+}
+export interface CommandMenu {
+    readonly command: string;
+    /** The dialog payload for one invocation of the slash command. */
+    open(invocation: CommandInvocation): Promise<CommandDialogPayload>;
+    /** Applies one action and returns its message and the refreshed menu. */
+    apply(request: CommandApplyRequest, invocation: CommandInvocation): Promise<CommandApplyResult>;
+}
+export declare function createCommandMenu(options: CommandMenuOptions): CommandMenu;
+/**
+ * Checks an apply request that arrived over the loopback RPC; undefined when
+ * it is not one. Only the request's own fields are kept.
+ */
+export declare function parseApplyRequest(value: unknown): CommandApplyRequest | undefined;

package/dist/internal-types/commands/model.d.ts

@@ -0,0 +1,238 @@
+/** The section slots, in the one order every renderer shows them. */
+export declare const SECTION_SLOTS: readonly ['accounts', 'quota', 'routing', 'limits', 'cache', 'diagnostics', 'extra'];
+export type SectionSlot = (typeof SECTION_SLOTS)[number];
+/** One choice of a `choice` input. */
+export interface MenuChoice {
+    value: string;
+    label: string;
+}
+/**
+ * A typed input an action collects before it runs. `value` is the current
+ * setting, shown as the default. A `number` or `text` input that is not
+ * `required` may be left empty, which the action receives as `null`.
+ */
+export type MenuKnob = {
+    kind: 'choice';
+    id: string;
+    label: string;
+    choices: MenuChoice[];
+    value?: string;
+} | {
+    kind: 'toggle';
+    id: string;
+    label: string;
+    value: boolean;
+} | {
+    kind: 'number';
+    id: string;
+    label: string;
+    value?: number;
+    min?: number;
+    max?: number;
+    required?: boolean;
+} | {
+    kind: 'text';
+    id: string;
+    label: string;
+    value?: string;
+    placeholder?: string;
+    /** Hide what is typed (a pasted secret, for example). */
+    masked?: boolean;
+    required?: boolean;
+};
+export type KnobValue = string | number | boolean | null;
+export type KnobValues = Readonly<Record<string, KnobValue>>;
+export interface MenuConfirmation {
+    message: string;
+    /** Irreversible actions always carry a confirmation. */
+    irreversible: boolean;
+}
+export interface MenuAction {
+    id: string;
+    label: string;
+    description?: string;
+    /**
+     * The header a section-level action is listed under (`Actions`). See
+     * `MenuSection` for how renderers draw groups.
+     */
+    group?: string;
+    knobs: MenuKnob[];
+    /** Present when the action must be confirmed before it is applied. */
+    confirm?: MenuConfirmation;
+}
+/**
+ * The account fields a renderer may show, and nothing else: an account is
+ * always projected field by field, never spread, so a credential the store
+ * row carries cannot reach a payload.
+ */
+export interface MenuAccount {
+    id: string;
+    label?: string;
+    enabled: boolean;
+    type: 'oauth' | 'api';
+    /** What the plugin chose to show for the account's identity. */
+    identity?: string;
+}
+export interface MenuItem {
+    id: string;
+    label: string;
+    detail?: string;
+    /** The header the item is listed under (`Accounts`); see `MenuSection`. */
+    group?: string;
+    /**
+     * A short value shown right-aligned beside the label (`enabled`,
+     * `5h 58% left`): an OpenCode dialog option's `footer`.
+     */
+    status?: string;
+    account?: MenuAccount;
+    /**
+     * Extra name/value pairs a drawer may list under the item. Plugin data
+     * passes through here, so it is scrubbed of credential-shaped names.
+     */
+    facts?: Record<string, unknown>;
+    actions: MenuAction[];
+}
+/**
+ * One section of the menu. How every renderer draws it:
+ *
+ * - Every option a renderer shows can be selected and does something: it is
+ *   an item with at least one action, or a section-level action. Text that
+ *   does nothing is never an option; it is a group header or a line.
+ * - `lines` are read-only text. On OpenCode they are drawn as header text
+ *   (a `category`) above the first group; on Pi they are part of the select
+ *   title.
+ * - The options are the items, then the section-level actions, in that
+ *   order. When an option's `group` differs from the previous one's, a
+ *   header naming the group is drawn first. A header is never selectable
+ *   (on OpenCode it is the option's `category`).
+ * - An item's `status` is drawn right-aligned beside its label (on
+ *   OpenCode, `footer`); its `detail` and an action's `description` are
+ *   the secondary text (`description`).
+ *
+ * The built-in sections never emit an item without actions, and a plugin
+ * section should not either. A renderer that meets one must not offer it as
+ * an option: on OpenCode a `disabled` option is hidden altogether, so the
+ * item is written as header text instead, and Pi writes it into the title.
+ */
+export interface MenuSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    /** Read-only text shown above the rows; never a selectable option. */
+    lines: string[];
+    items: MenuItem[];
+    actions: MenuAction[];
+    facts?: Record<string, unknown>;
+}
+export interface CommandMenuModel {
+    /** The slash command's name, without the slash. */
+    command: string;
+    title: string;
+    sections: MenuSection[];
+}
+/** What a host's TUI receives when the slash command opens the dialog. */
+export interface CommandDialogPayload {
+    command: string;
+    menu: CommandMenuModel;
+}
+/**
+ * One applied action, as a renderer sends it back. `itemId` names the item
+ * the action sits on; absent for a section-level action.
+ */
+export interface CommandApplyRequest {
+    command: string;
+    sectionId: string;
+    itemId?: string;
+    actionId: string;
+    values?: KnobValues;
+    /** True once the user confirmed an action that carries a confirmation. */
+    confirmed?: boolean;
+    sessionId?: string;
+}
+/** The outcome of an apply: a message for the user and the refreshed menu. */
+export interface CommandApplyResult {
+    command: string;
+    ok: boolean;
+    text: string;
+    /**
+     * A stable code naming why the apply failed; present on every failure.
+     * The library's own codes are `unavailable`, `needs-confirmation`,
+     * `invalid-input`, `refused`, `action-failed` and `pool-<store failure
+     * kind>`; a plugin's `CommandError` or `ActionOutcome` names its own.
+     */
+    code?: string;
+    /** True when the action was refused only for want of a confirmation. */
+    needsConfirmation?: boolean;
+    menu: CommandMenuModel;
+}
+export type NotifyKind = 'info' | 'warning' | 'error';
+/**
+ * The per-invocation context of one slash-command call. The library reads
+ * both fields once, when the call starts, and keeps that copy for any work
+ * the call leaves running (a login completing later, for example), so a host
+ * that reuses one context object across sessions cannot reroute feedback.
+ */
+export interface CommandInvocation {
+    sessionId?: string;
+    notify(message: string, kind?: NotifyKind): void;
+}
+export interface ActionOutcome {
+    ok: boolean;
+    text: string;
+    /** The failure's stable code; a failure without one is `refused`. */
+    code?: string;
+}
+export interface ActionInput {
+    values: KnobValues;
+    /** The item the action sits on; absent for a section-level action. */
+    itemId?: string;
+    invocation: CommandInvocation;
+}
+type ActionBase = {
+    id: string;
+    label: string;
+    description?: string;
+    /** The header a section-level action is listed under; see `MenuSection`. */
+    group?: string;
+    knobs?: MenuKnob[];
+    run(input: ActionInput): Promise<string | ActionOutcome>;
+};
+/**
+ * An action and its body. An irreversible action must name its
+ * confirmation; a reversible one may.
+ */
+export type ActionDefinition = ActionBase & ({
+    irreversible: true;
+    confirm: string;
+} | {
+    irreversible?: false;
+    confirm?: string;
+});
+export interface ItemDefinition {
+    id: string;
+    label: string;
+    detail?: string;
+    /** The header the item is listed under; see `MenuSection`. */
+    group?: string;
+    /** A short value shown right-aligned beside the label. */
+    status?: string;
+    facts?: Record<string, unknown>;
+    actions?: ActionDefinition[];
+}
+export interface SectionContent {
+    /** Read-only text; renderers never make a line selectable. */
+    lines?: string[];
+    items?: ItemDefinition[];
+    actions?: ActionDefinition[];
+    facts?: Record<string, unknown>;
+}
+/** A section a plugin supplies for one of its slots. */
+export interface PluginSection {
+    title: string;
+    build(invocation: CommandInvocation): SectionContent | Promise<SectionContent>;
+}
+/** A provider extra: a plugin section shown after the fixed slots. */
+export interface PluginExtraSection extends PluginSection {
+    id: string;
+}
+export {};

package/dist/internal-types/commands/pi.d.ts

@@ -0,0 +1,23 @@
+import type { CommandMenu } from './menu.js';
+import type { NotifyKind } from './model.js';
+/**
+ * The part of Pi's `ExtensionUIContext` the renderer uses. `select` and
+ * `input` resolve undefined when the user backs out.
+ */
+export interface PiMenuUi {
+    select(title: string, options: string[]): Promise<string | undefined>;
+    confirm(title: string, message: string): Promise<boolean>;
+    input(title: string, placeholder?: string): Promise<string | undefined>;
+    notify(message: string, type?: NotifyKind): void;
+}
+export interface PiMenuOptions {
+    sessionId?: string;
+}
+/**
+ * Runs one invocation of the slash command on Pi: sections, then an item or
+ * a section action, then the action's inputs and confirmation; after each
+ * apply the user is back in the same section with the refreshed menu. Each
+ * section's list ends with Back, which returns to the section list; backing
+ * out of the section list ends the invocation.
+ */
+export declare function runPiCommandMenu(menu: CommandMenu, ui: PiMenuUi, options?: PiMenuOptions): Promise<void>;

package/dist/internal-types/commands/seam.d.ts

@@ -0,0 +1,72 @@
+import { type RedactionOptions } from '../logger/index.js';
+import type { ActionDefinition, CommandApplyResult, CommandDialogPayload, ItemDefinition, MenuAccount, MenuConfirmation, SectionContent, SectionSlot } from './model.js';
+/** Where a dropped field is reported. Names only, never values. */
+export interface SeamLogger {
+    warn(message: string, data?: unknown): void;
+}
+/** Masks the secret-shaped parts of one string. */
+export type TextRedactor = (text: string) => string;
+/** The string redactor every value crossing the seam goes through. */
+export declare function createTextRedactor(options?: RedactionOptions): TextRedactor;
+/**
+ * A failure whose message was written for the user. An action throws it to
+ * show `message` with the stable `code`; any other thrown value is shown only
+ * as a generic message, because its text may quote a request, a response or
+ * a credential. `code` is lowercase letters, digits and dashes; anything else
+ * is reported as `action-failed`.
+ */
+export declare class CommandError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** What a failed action shows: a stable code and a message safe to display. */
+export interface ProjectedFailure {
+    code: string;
+    text: string;
+}
+/** The code and message shown for an exception the seam cannot vouch for. */
+export declare const ACTION_FAILED: ProjectedFailure;
+/** The code and display text for a thrown value; never its raw text. */
+export declare function projectFailure(error: unknown): ProjectedFailure;
+/** A built-in item may carry the account it shows; plugin items cannot. */
+export interface ResolvedItem extends ItemDefinition {
+    account?: MenuAccount;
+}
+/** A section with its bodies, as the menu holds it between builds. */
+export interface ResolvedSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    content: Omit<SectionContent, 'items'> & {
+        items?: ResolvedItem[];
+    };
+}
+/** The confirmation shown when an irreversible action names none. */
+export declare const DEFAULT_IRREVERSIBLE_CONFIRMATION = "This cannot be undone. Continue?";
+/** What every payload builder needs besides the payload itself. */
+export interface SeamContext {
+    logger: SeamLogger;
+    redact: TextRedactor;
+}
+/**
+ * The confirmation an action must pass before it runs, or undefined. An
+ * irreversible action always has one, even when its definition (built
+ * outside the type checker) names none.
+ */
+export declare function confirmationOf(action: ActionDefinition): MenuConfirmation | undefined;
+/** The account fields a renderer may show; see `MenuAccount`. */
+export declare function projectAccount(account: MenuAccount): MenuAccount;
+/** The payload a host's TUI receives when the slash command opens. */
+export declare function dialogPayload(command: string, title: string, sections: readonly ResolvedSection[], seam: SeamContext): CommandDialogPayload;
+/** How an apply ended, before the seam turns it into a payload. */
+export interface ApplyOutcome {
+    ok: boolean;
+    text: string;
+    /** Present on every failure. */
+    code?: string;
+    needsConfirmation?: boolean;
+}
+/** An apply's result: the message and the refreshed menu. */
+export declare function applyResult(command: string, title: string, sections: readonly ResolvedSection[], outcome: ApplyOutcome, seam: SeamContext): CommandApplyResult;

package/dist/internal-types/fs/refresh-file-lock.d.ts

@@ -0,0 +1,33 @@
+export declare function isLostMarkerRaceError(error: unknown): boolean;
+export interface LockLoss {
+    readonly reason: 'taken-over' | 'expired' | 'unreadable' | 'renewal-failed' | 'marker-lost';
+    readonly expectedOwnerId: string;
+    readonly observedOwnerId?: string;
+    readonly observedExpiresAt?: number;
+}
+export interface RefreshFileLock {
+    readonly ownerId: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+    /** Resolves once on detected loss; remains pending after an owner's release. */
+    whenLost(): Promise<LockLoss>;
+    hasLost(): boolean;
+}
+export declare function acquireRefreshFileLock(options: {
+    name: string;
+    ttlMs: number;
+    /**
+     * File the lock is named after. Required: the lock and the write it guards
+     * must target the same file, and a default resolved in here could only ever
+     * be one host's path.
+     */
+    path: string;
+    now?: () => number;
+    renew?: boolean;
+    renewIntervalMs?: number;
+    /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
+    onContended?: () => void;
+    /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
+    onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+}): Promise<RefreshFileLock | null>;

package/dist/internal-types/logger/capture-sink.d.ts

@@ -0,0 +1,14 @@
+import type { Level } from './engine.js';
+export interface LogTestRecord {
+    channel: string;
+    level: Level;
+    message: string;
+    data?: unknown;
+}
+/** The engine delivers scrubbed records only; this sink never sees raw credentials. */
+export type CaptureSink = (record: LogTestRecord) => void;
+export declare function createCaptureSink(): {
+    records: LogTestRecord[];
+    sink: CaptureSink;
+    clear: () => void;
+};

package/dist/internal-types/logger/engine.d.ts

@@ -0,0 +1,100 @@
+import type { CaptureSink } from './capture-sink.js';
+import { type RedactionOptions } from './redact.js';
+export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** A logger that writes to a file, and to a capture sink when one is given. */
+export interface InitLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed, alongside the file. */
+    captureSink?: CaptureSink;
+    /**
+     * Path of the file lines are appended to, or a function returning it.
+     *
+     * A function is what a host passes when its destination can move while the
+     * process runs — an operator or a test changing the variable that names the
+     * log file expects the next line to land in the new file, and a value
+     * captured once at init would keep writing to the old one.
+     */
+    file: string | (() => string);
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * A logger with no file: the capture sink is its only destination. Nothing
+ * is written to disk or printed, for a host that forwards records to its own
+ * log.
+ */
+export interface SinkOnlyLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed. */
+    captureSink: CaptureSink;
+    file?: undefined;
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * What a logger is configured with: a file (`InitLoggerOptions`, the shape
+ * every release before this one accepted, kept as its own interface so a
+ * caller deriving a type from it with `Pick` or `extends` keeps compiling) or
+ * a capture sink alone.
+ */
+export type LoggerOptions = InitLoggerOptions | SinkOnlyLoggerOptions;
+export interface ChannelLogger {
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    trace(message: string, data?: unknown): void;
+}
+/**
+ * A logger with its own file, level, redaction, capture sink and buffer.
+ * Two instances in one process never touch each other's settings or lines,
+ * so two plugins that load one shared copy of this module each keep their own
+ * log by holding their own instance.
+ */
+export interface LoggerInstance {
+    /** A logger whose lines carry `channel` and go to this instance's file. */
+    createLogger(channel: string): ChannelLogger;
+    /**
+     * Point this instance at a host's file and level. Idempotent: calling it
+     * again replaces both. A runtime level installed by `setLogLevel` is left
+     * alone, because it is the operator's explicit choice and outranks the
+     * floor a host computed at start-up.
+     */
+    configure(options: LoggerOptions): void;
+    /** Operator override of the level floor; undefined removes it. */
+    setLogLevel(level: Level | undefined): void;
+    /**
+     * Write whatever is buffered. Safe to call synchronously from a
+     * process-exit handler, which is how each host drains the buffer on
+     * shutdown.
+     */
+    flushLogs(): void;
+}
+/**
+ * A logger instance of its own, configured with `options`. A plugin whose
+ * copy of this module may be shared with another plugin in the same process
+ * uses this instead of `initLogger`, so neither replaces the other's file,
+ * level, redaction or capture sink.
+ */
+export declare function createLoggerInstance(options: LoggerOptions): LoggerInstance;
+/**
+ * Point the module's default logger at a host's file and level, and return
+ * it. Idempotent: calling it again replaces both. A runtime level installed
+ * by `setLogLevel` is deliberately left alone, because it is the operator's
+ * explicit choice and outranks the floor a host computed at start-up.
+ */
+export declare function initLogger(options: LoggerOptions): LoggerInstance;
+export declare function setLogLevel(l: Level | undefined): void;
+/**
+ * Write whatever the default logger has buffered. Safe to call synchronously
+ * from a process-exit handler, which is how each host drains the buffer on
+ * shutdown.
+ */
+export declare function flushLogs(): void;
+export declare function createLogger(channel: string): ChannelLogger;
+export declare function flushForTest(): Promise<void>;
+/**
+ * Return the default logger to its uninitialised state. Only a test needs
+ * this: a single process runs every test file, so a file path left over from
+ * one test would keep a later "logger was never initialised" case writing
+ * lines.
+ */
+export declare function resetLoggerForTest(): void;

package/dist/internal-types/logger/index.d.ts

@@ -0,0 +1,6 @@
+export type { CaptureSink, LogTestRecord } from './capture-sink.js';
+export { createCaptureSink } from './capture-sink.js';
+export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, LoggerOptions, SinkOnlyLoggerOptions, } from './engine.js';
+export { createLogger, createLoggerInstance, flushForTest, flushLogs, initLogger, resetLoggerForTest, setLogLevel, } from './engine.js';
+export type { RedactionOptions, Redactor } from './redact.js';
+export { createRedactor, redact, redactStrings } from './redact.js';

package/dist/internal-types/logger/redact.d.ts

@@ -0,0 +1,11 @@
+export interface RedactionOptions {
+    extraSecretKeys?: (normalizedKey: string) => boolean;
+    extraValuePatterns?: RegExp[];
+}
+export declare function createRedactor(options?: RedactionOptions): {
+    redact: (value: unknown) => unknown;
+    redactStrings: (value: unknown) => unknown;
+};
+export type Redactor = ReturnType<typeof createRedactor>;
+export declare const redact: (value: unknown) => unknown;
+export declare const redactStrings: (value: unknown) => unknown;