dsh-keys-manager 0.0.0 → 0.1.0

package/lib/core.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Pure key-selection and cooldown policy for the Keys Manager.
+ *
+ * Nothing here touches Cordis, the filesystem, or a secret. The Host passes
+ * plain provider records in and gets the same records back, which keeps the
+ * round-robin, sticky-session, cooldown-escalation, and retry decisions
+ * unit-testable without a running Harness.
+ */
+import type { KeyRecord, KeyStatus, ManagerSettings, ProviderRecord, ProviderStatus } from './domain.js';
+import type { LlmFailureLike } from './host-types.js';
+/** Defaults also exposed in the manager's policy card. */
+export declare const DEFAULT_SETTINGS: ManagerSettings;
+/** Normalize one persisted settings object. */
+export declare function normalizeSettings(value: unknown): ManagerSettings;
+/** Apply and validate a settings patch from the UI; throws on nonsense. */
+export declare function patchSettings(current: ManagerSettings, patch: unknown): ManagerSettings;
+/** Clamp an untyped numeric setting. */
+export declare function clampInteger(value: unknown, min: number, max: number, fallback: number): number;
+/** Whether a key may serve a request now. */
+export declare function isSelectable(key: KeyRecord | undefined, now: number): key is KeyRecord;
+/** Pick the next healthy key for a provider in creation order, advancing the cursor. */
+export declare function pickRoundRobin(provider: ProviderRecord, now: number, exclude?: ReadonlySet<string>): KeyRecord | undefined;
+/** Pick the next healthy key other than `excludeKeyId`, advancing the cursor. */
+export declare function pickHealthyExcluding(provider: ProviderRecord, excludeKeyId: string, now: number): KeyRecord | undefined;
+/** Coerce a persisted cursor into range without mutating it. */
+export declare function normalizeCursor(cursor: number, length: number): number;
+/** Result of marking one key failure. */
+export interface CooldownResult {
+    cooldownMs: number;
+    level: number;
+    cooldownUntil: number;
+}
+/**
+ * Record one failed key use and start (or extend) its cooldown.
+ *
+ * First failure: base cooldown. A failure while cooling, or within the
+ * recovery grace window after the previous cooldown expired, doubles the
+ * level. A long healthy gap resets the level, so an occasional failure does
+ * not inherit ancient escalation. The result is always capped at seven days.
+ */
+export declare function applyFailureCooldown(key: KeyRecord, settings: ManagerSettings, now: number, failure: LlmFailureLike | undefined): CooldownResult;
+/**
+ * Record one successful use: clear the failure streak, but keep the previous
+ * cooldown timestamp/level until the recovery grace window has elapsed. A
+ * failure shortly after recovery must still escalate.
+ */
+export declare function markKeySuccess(key: KeyRecord, now: number): void;
+/** Record that a request used a key, without changing health. */
+export declare function markKeyUsed(key: KeyRecord, now: number): void;
+/** Status a key row renders. */
+export declare function statusOfKey(key: KeyRecord | undefined, now: number): KeyStatus;
+/** Status a provider row renders. */
+export declare function statusOfProvider(keys: readonly KeyRecord[], now: number): ProviderStatus;
+/** Whether a model-request failure should affect key health at all. */
+export declare function shouldFailover(code: string | undefined): boolean;
+/** Session/provider binding key. */
+export declare function bindingKey(sessionId: string, provider: string): string;
+/** Validate a new key input before it reaches the credential store. */
+export declare function validateKeyInput(alias: unknown, value: unknown): {
+    alias: string;
+    value: string;
+};
+/** Validate a rename/enable patch. */
+export declare function validateKeyPatch(patch: unknown): {
+    alias?: string;
+    enabled?: boolean;
+};
+/** Maximum keys per provider (also used by the Host). */
+export declare const KEY_LIMIT = 32;
+/** Re-export the shared update type for callers that only import core. */
+export type { ManagerSettings };

package/lib/core.js

@@ -0,0 +1,238 @@
+/** Defaults also exposed in the manager's policy card. */
+export const DEFAULT_SETTINGS = {
+    retryCount: 2,
+    baseCooldownMs: 5 * 60 * 1000,
+    recoveryGraceMs: 10 * 60 * 1000,
+    maxCooldownMs: 7 * 24 * 60 * 60 * 1000,
+    stickySession: true,
+    autoSwitch: true,
+};
+const MIN_COOLDOWN_MS = 30 * 1000;
+const MAX_KEYS_PER_PROVIDER = 32;
+const MAX_ALIAS_LENGTH = 80;
+const MAX_KEY_LENGTH = 16 * 1024;
+/** Failure codes that describe the request or configuration, not the key. */
+const NON_KEY_FAILURE_CODES = new Set([
+    'ABORTED',
+    'CANCELLED',
+    'CONTEXT_WINDOW_EXCEEDED',
+    'EMPTY_RESPONSE_REQUEST',
+    'IMAGE_OFFLOAD_REQUIRED',
+    'INVALID_PREPARED_CALL',
+    'INVALID_REQUEST',
+    'NO_ADAPTER',
+    'REGISTRATION_DISPOSED',
+    'UNKNOWN_MODEL',
+    'UNSUPPORTED_OPTION',
+]);
+/** Normalize one persisted settings object. */
+export function normalizeSettings(value) {
+    const source = value !== null && typeof value === 'object' ? value : {};
+    return {
+        retryCount: clampInteger(source.retryCount, 1, 3, DEFAULT_SETTINGS.retryCount),
+        baseCooldownMs: clampInteger(source.baseCooldownMs, MIN_COOLDOWN_MS, DEFAULT_SETTINGS.maxCooldownMs, DEFAULT_SETTINGS.baseCooldownMs),
+        recoveryGraceMs: clampInteger(source.recoveryGraceMs, 0, DEFAULT_SETTINGS.maxCooldownMs, DEFAULT_SETTINGS.recoveryGraceMs),
+        maxCooldownMs: DEFAULT_SETTINGS.maxCooldownMs,
+        stickySession: source.stickySession !== false,
+        autoSwitch: source.autoSwitch !== false,
+    };
+}
+/** Apply and validate a settings patch from the UI; throws on nonsense. */
+export function patchSettings(current, patch) {
+    const source = patch !== null && typeof patch === 'object' ? patch : {};
+    if (source.retryCount !== undefined) {
+        if (!Number.isInteger(source.retryCount) || source.retryCount < 1 || source.retryCount > 3) {
+            throw new TypeError('retryCount must be an integer from 1 to 3');
+        }
+    }
+    if (source.baseCooldownMs !== undefined) {
+        if (!Number.isFinite(source.baseCooldownMs) || source.baseCooldownMs < MIN_COOLDOWN_MS) {
+            throw new TypeError('baseCooldownMs must be at least 30 seconds');
+        }
+    }
+    if (source.recoveryGraceMs !== undefined) {
+        if (!Number.isFinite(source.recoveryGraceMs) || source.recoveryGraceMs < 0) {
+            throw new TypeError('recoveryGraceMs must be zero or positive');
+        }
+    }
+    return normalizeSettings({ ...current, ...source });
+}
+/** Clamp an untyped numeric setting. */
+export function clampInteger(value, min, max, fallback) {
+    const number = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+    return Math.min(max, Math.max(min, Math.round(number)));
+}
+/** Whether a key may serve a request now. */
+export function isSelectable(key, now) {
+    if (key === undefined)
+        return false;
+    if (key.enabled === false || key.valueMissing === true)
+        return false;
+    return !(Number(key.cooldownUntil) > now);
+}
+/** Pick the next healthy key for a provider in creation order, advancing the cursor. */
+export function pickRoundRobin(provider, now, exclude) {
+    const keys = Array.isArray(provider.keys) ? provider.keys : [];
+    if (keys.length === 0)
+        return undefined;
+    const start = normalizeCursor(provider.cursor, keys.length);
+    for (let offset = 0; offset < keys.length; offset += 1) {
+        const index = (start + offset) % keys.length;
+        const key = keys[index];
+        if (exclude?.has(key.id))
+            continue;
+        if (isSelectable(key, now)) {
+            provider.cursor = (index + 1) % keys.length;
+            return key;
+        }
+    }
+    return undefined;
+}
+/** Pick the next healthy key other than `excludeKeyId`, advancing the cursor. */
+export function pickHealthyExcluding(provider, excludeKeyId, now) {
+    const keys = Array.isArray(provider.keys) ? provider.keys : [];
+    if (keys.length === 0)
+        return undefined;
+    const start = normalizeCursor(provider.cursor, keys.length);
+    for (let offset = 0; offset < keys.length; offset += 1) {
+        const index = (start + offset) % keys.length;
+        const key = keys[index];
+        if (key.id === excludeKeyId)
+            continue;
+        if (isSelectable(key, now)) {
+            provider.cursor = (index + 1) % keys.length;
+            return key;
+        }
+    }
+    return undefined;
+}
+/** Coerce a persisted cursor into range without mutating it. */
+export function normalizeCursor(cursor, length) {
+    if (!Number.isInteger(cursor) || length <= 0)
+        return 0;
+    return ((cursor % length) + length) % length;
+}
+/**
+ * Record one failed key use and start (or extend) its cooldown.
+ *
+ * First failure: base cooldown. A failure while cooling, or within the
+ * recovery grace window after the previous cooldown expired, doubles the
+ * level. A long healthy gap resets the level, so an occasional failure does
+ * not inherit ancient escalation. The result is always capped at seven days.
+ */
+export function applyFailureCooldown(key, settings, now, failure) {
+    const normalized = normalizeSettings(settings);
+    const previousLevel = Number.isInteger(key.failureLevel) ? key.failureLevel : 0;
+    const previousUntil = Number(key.cooldownUntil) || 0;
+    let level = 0;
+    if (previousUntil > 0) {
+        if (now <= previousUntil)
+            level = previousLevel + 1;
+        else if (now - previousUntil <= normalized.recoveryGraceMs)
+            level = previousLevel + 1;
+        else
+            level = 0;
+    }
+    const providerDelay = Number(failure?.providerRetryAfterMs);
+    const base = Math.max(MIN_COOLDOWN_MS, normalized.baseCooldownMs);
+    const exponential = Math.min(normalized.maxCooldownMs, base * 2 ** Math.min(level, 30));
+    const requested = Number.isFinite(providerDelay) && providerDelay > 0 ? Math.max(exponential, providerDelay) : exponential;
+    const cooldownMs = Math.max(1, Math.min(normalized.maxCooldownMs, requested));
+    key.failureLevel = level;
+    key.cooldownUntil = now + cooldownMs;
+    key.lastFailureAt = now;
+    key.lastFailureCode = typeof failure?.code === 'string' ? failure.code : '';
+    key.consecutiveFailures = (Number(key.consecutiveFailures) || 0) + 1;
+    key.totalFailures = (Number(key.totalFailures) || 0) + 1;
+    return { cooldownMs, level, cooldownUntil: key.cooldownUntil };
+}
+/**
+ * Record one successful use: clear the failure streak, but keep the previous
+ * cooldown timestamp/level until the recovery grace window has elapsed. A
+ * failure shortly after recovery must still escalate.
+ */
+export function markKeySuccess(key, now) {
+    key.lastUsedAt = now;
+    key.consecutiveFailures = 0;
+    key.lastFailureCode = '';
+    key.totalUses = (Number(key.totalUses) || 0) + 1;
+}
+/** Record that a request used a key, without changing health. */
+export function markKeyUsed(key, now) {
+    key.lastUsedAt = now;
+}
+/** Status a key row renders. */
+export function statusOfKey(key, now) {
+    if (key === undefined)
+        return 'missing';
+    if (key.enabled === false)
+        return 'paused';
+    if (key.valueMissing === true)
+        return 'missing';
+    if (Number(key.cooldownUntil) > now)
+        return 'cooling';
+    return 'active';
+}
+/** Status a provider row renders. */
+export function statusOfProvider(keys, now) {
+    if (keys.length === 0)
+        return 'empty';
+    const statuses = keys.map(key => statusOfKey(key, now));
+    if (statuses.includes('active'))
+        return 'active';
+    if (statuses.includes('cooling'))
+        return 'cooling';
+    if (statuses.includes('paused'))
+        return 'paused';
+    return 'missing';
+}
+/** Whether a model-request failure should affect key health at all. */
+export function shouldFailover(code) {
+    return typeof code === 'string' && code.length > 0 && !NON_KEY_FAILURE_CODES.has(code);
+}
+/** Session/provider binding key. */
+export function bindingKey(sessionId, provider) {
+    return `${sessionId}\u0000${provider}`;
+}
+/** Validate a new key input before it reaches the credential store. */
+export function validateKeyInput(alias, value) {
+    const cleanAlias = typeof alias === 'string' ? alias.trim() : '';
+    if (cleanAlias.length === 0)
+        throw new TypeError('alias is required');
+    if (cleanAlias.length > MAX_ALIAS_LENGTH)
+        throw new TypeError(`alias must be at most ${MAX_ALIAS_LENGTH} characters`);
+    if (typeof value !== 'string')
+        throw new TypeError('key value is required');
+    const cleanValue = value.trim();
+    if (cleanValue.length === 0)
+        throw new TypeError('key value is required');
+    if (cleanValue.length > MAX_KEY_LENGTH)
+        throw new TypeError('key value is too long');
+    return { alias: cleanAlias, value: cleanValue };
+}
+/** Validate a rename/enable patch. */
+export function validateKeyPatch(patch) {
+    if (patch === null || typeof patch !== 'object' || Array.isArray(patch))
+        throw new TypeError('patch is required');
+    const source = patch;
+    const result = {};
+    if (source.alias !== undefined) {
+        const alias = typeof source.alias === 'string' ? source.alias.trim() : '';
+        if (alias.length === 0)
+            throw new TypeError('alias is required');
+        if (alias.length > MAX_ALIAS_LENGTH)
+            throw new TypeError(`alias must be at most ${MAX_ALIAS_LENGTH} characters`);
+        result.alias = alias;
+    }
+    if (source.enabled !== undefined) {
+        if (typeof source.enabled !== 'boolean')
+            throw new TypeError('enabled must be a boolean');
+        result.enabled = source.enabled;
+    }
+    if (Object.keys(result).length === 0)
+        throw new TypeError('patch has no supported fields');
+    return result;
+}
+/** Maximum keys per provider (also used by the Host). */
+export const KEY_LIMIT = MAX_KEYS_PER_PROVIDER;
+//# sourceMappingURL=core.js.map

package/lib/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/lib/domain.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared, transport-safe domain shapes for the Keys Manager.
+ *
+ * The Host and the Web Client both compile against these declarations. They
+ * deliberately contain no Cordis, Node, or React types so the client bundle
+ * can import them type-only without pulling Host code into the browser.
+ */
+/** Health state a key row renders. */
+export type KeyStatus = 'active' | 'cooling' | 'paused' | 'missing';
+/** Health state a provider row renders. */
+export type ProviderStatus = KeyStatus | 'empty' | 'unmanaged';
+/** Manager policy shared by the Host selection engine and the UI form. */
+export interface ManagerSettings {
+    /** Retries on the same key before switching to another key. */
+    retryCount: number;
+    /** First cooldown after a key starts failing. */
+    baseCooldownMs: number;
+    /** A failure within this window after recovery escalates the cooldown. */
+    recoveryGraceMs: number;
+    /** Hard ceiling for any cooldown. */
+    maxCooldownMs: number;
+    /** Keep one key for one session instead of rotating every request. */
+    stickySession: boolean;
+    /** Automatically mark and switch away from a failing key. */
+    autoSwitch: boolean;
+}
+/** Reserved OAuth2 account payload; unset for API-key rows. */
+export type OAuthRecord = Record<string, unknown>;
+/** One persisted key. Key literals live only in the credential store. */
+export interface KeyRecord {
+    id: string;
+    alias: string;
+    /** Credential reference holding this key's literal. */
+    ref: string;
+    kind: 'api-key' | 'oauth';
+    enabled: boolean;
+    createdAt: number;
+    lastUsedAt: number;
+    cooldownUntil: number;
+    lastFailureAt: number;
+    lastFailureCode: string;
+    failureLevel: number;
+    consecutiveFailures: number;
+    totalUses: number;
+    totalFailures: number;
+    valueMissing: boolean;
+    importedFrom: string | null;
+    /** Reserved for subscription OAuth2 accounts. */
+    oauth: OAuthRecord | null;
+}
+/** One model entry installed into a pi-ai route profile. */
+export interface ModelRecord {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    input?: Array<'text' | 'image'>;
+    reasoningEfforts?: Record<string, unknown>;
+    compat?: Record<string, unknown>;
+}
+/** One managed provider and its adoption facts. */
+export interface ProviderRecord {
+    provider: string;
+    displayName: string;
+    source: 'dsh' | 'extra';
+    settingsNs: string;
+    settingsPath: string[];
+    adapter: 'pi-ai' | 'deepseek';
+    /** Broker reference written into the provider profile's `apiKeyEnv`. */
+    brokerRef: string;
+    /** The profile's reference before adoption, restored on release. */
+    originalApiKeyEnv: string | null;
+    /** True when the profile itself was created by adding an extra provider. */
+    createdProfile: boolean;
+    /** True when a profile existed before adoption. */
+    hadProfile: boolean;
+    extraId: string | null;
+    api: string | null;
+    baseURL: string | null;
+    models: ModelRecord[];
+    adoptedAt: number;
+    /** Next round-robin position in `keys`. */
+    cursor: number;
+    keys: KeyRecord[];
+}
+/** Durable, secret-free manager document. */
+export interface StateDocument {
+    version: 1;
+    settings: ManagerSettings;
+    providers: Record<string, ProviderRecord>;
+    sessionBindings: Record<string, {
+        keyId: string;
+        boundAt: number;
+    }>;
+}
+/** Public key row returned to the UI (no credential reference or value). */
+export interface KeyView {
+    id: string;
+    alias: string;
+    status: KeyStatus;
+    enabled: boolean;
+    createdAt: number;
+    lastUsedAt: number;
+    cooldownUntil: number;
+    failureLevel: number;
+    consecutiveFailures: number;
+    totalUses: number;
+    totalFailures: number;
+    importedFrom: string | null;
+    valueMissing: boolean;
+    kind: 'api-key' | 'oauth';
+}
+/** Public provider row returned to the UI. */
+export interface ProviderView {
+    provider: string;
+    displayName: string;
+    source: 'dsh' | 'extra';
+    /** Where the route came from: DSH catalog, this plugin's catalog, or a hand-declared profile. */
+    origin?: 'dsh' | 'plugin' | 'custom';
+    /** True when this plugin created the route profile and release removes it. */
+    createdProfile?: boolean;
+    managed: boolean;
+    configured: boolean;
+    active: boolean;
+    supported: boolean;
+    reason?: string;
+    settingsNs: string;
+    settingsPath: string[];
+    apiKeyEnv: string | null;
+    brokerRef: string | null;
+    bindingHealthy?: boolean;
+    extra: boolean;
+    extraId: string | null;
+    api: string | null;
+    baseURL: string | null;
+    env: string[];
+    defaultBaseURL: string | null;
+    nativeAuth: {
+        env: string[];
+        oauth: boolean;
+    } | null;
+    models: ModelRecord[];
+    keyCount: number;
+    healthyKeyCount: number;
+    status: ProviderStatus;
+    keys: KeyView[];
+    warning?: string;
+}
+/** Complete manager snapshot the UI renders. */
+export interface StateView {
+    now: number;
+    writable: boolean;
+    settings: ManagerSettings;
+    providers: ProviderView[];
+    managedCount: number;
+    keyCount: number;
+    healthyKeyCount: number;
+    coolingKeyCount: number;
+    pausedKeyCount: number;
+    bindingsCount: number;
+    warnings: string[];
+}
+/** One curated extra built-in provider. */
+export interface ExtraProvider {
+    id: string;
+    name: string;
+    api: string;
+    baseURL: string;
+    env: string[];
+    models: ModelRecord[];
+}

package/lib/domain.js

@@ -0,0 +1,9 @@
+/**
+ * Shared, transport-safe domain shapes for the Keys Manager.
+ *
+ * The Host and the Web Client both compile against these declarations. They
+ * deliberately contain no Cordis, Node, or React types so the client bundle
+ * can import them type-only without pulling Host code into the browser.
+ */
+export {};
+//# sourceMappingURL=domain.js.map

package/lib/domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.js","sourceRoot":"","sources":["../src/domain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}