dsh-keys-manager 0.0.0 → 0.1.0

package/lib/host-types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Minimal Host service contracts used by the plugin.
+ *
+ * These interfaces name only the methods Keys Manager calls. The real
+ * implementations are the shipped DSH services; keeping the contract local
+ * avoids coupling the plugin to adapter internals while still type-checking
+ * every call site.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { KeyRecord, ManagerSettings, ModelRecord } from './domain.js';
+/** One provider route from `llm.listConfigurableProviders()`. */
+export interface DirectoryEntry {
+    provider: string;
+    displayName: string;
+    settingsNs: string;
+    settingsPath: readonly string[];
+    declared?: boolean;
+    defaultBaseURL?: string;
+    baseURLEnv?: readonly string[];
+    nativeAuth?: {
+        env: readonly string[];
+        oauth: boolean;
+    };
+    error?: string;
+}
+/** One model an endpoint disclosed during discovery. */
+export interface DiscoveredModel {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    inputModalities?: ReadonlyArray<'text' | 'image'>;
+}
+/** Request sent to the adapter's model-discovery operation. */
+export interface DiscoveryRequest {
+    provider?: string;
+    baseURL?: string;
+    api?: string;
+    apiKey?: string;
+}
+/** The LLM runtime methods Keys Manager uses. */
+export interface LlmRuntimeLike {
+    listConfigurableProviders(): DirectoryEntry[];
+    listProviders(): Array<{
+        id: string;
+        name: string;
+    }>;
+    discoverModels(settingsNs: string, request: DiscoveryRequest, signal: AbortSignal): Promise<DiscoveredModel[]>;
+}
+/** Credential value/source facts returned by the credential seam. */
+export interface CredentialHit {
+    value: string;
+    source: string;
+}
+/** Credential presence facts returned by the credential seam. */
+export interface CredentialDescription {
+    configured: boolean;
+    source?: string;
+    writable: boolean;
+}
+/** The credential provider methods the broker wraps. */
+export interface CredentialsLike {
+    resolve(ref: string): Promise<CredentialHit | undefined>;
+    describe(ref: string): Promise<CredentialDescription>;
+    set(ref: string, value: string): Promise<void>;
+    unset(ref: string): Promise<void>;
+}
+/** One path-addressed settings edit. */
+export type SettingsPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+/** One live settings namespace descriptor. */
+export interface SettingsDescriptorLike {
+    ns: string;
+    value: unknown;
+    revision: number;
+}
+/** The settings service methods Keys Manager uses. */
+export interface SettingsLike {
+    readonly writable: boolean;
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): SettingsDescriptorLike[];
+    mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>;
+}
+/** The Typert registry method Keys Manager uses. */
+export interface TypertLike {
+    register(contribution: unknown): () => void;
+}
+/** Host context surface this plugin requires. */
+export type HostContext = Context & {
+    llm: LlmRuntimeLike;
+    credentials: CredentialsLike;
+    settings?: SettingsLike;
+    typert: TypertLike;
+};
+/** Serializable provider failure facts relevant to key health. */
+export interface LlmFailureLike {
+    code: string;
+    message?: string;
+    providerRetryAfterMs?: number;
+}
+/** One stream chunk; only `finish` is inspected by the broker. */
+export interface StreamChunkLike {
+    type: string;
+    reason?: {
+        kind: string;
+        failure?: LlmFailureLike;
+    };
+}
+/** Minimal `GenerateOptions` surface observed by the stream listener. */
+export interface GenerateOptionsLike {
+    provider: string;
+    model: string;
+    sessionId?: string;
+    /** Host-side bypass purposes; any value opts the stream out of retry pins. */
+    purpose?: 'compaction' | 'session-title';
+    messages: readonly unknown[];
+}
+/** Payload of the `agent/request` waterfall (subset used here). */
+export interface AgentRequestPayload {
+    agent?: {
+        session?: {
+            id?: string;
+        };
+    };
+    turn: number;
+    step: number;
+}
+/** Payload of the `agent/request-error` waterfall. */
+export interface RequestErrorPayload {
+    agent: {
+        session: {
+            id: string;
+        };
+    };
+    turn: number;
+    step: number;
+    provider: string;
+    failure: LlmFailureLike;
+    retryPolicy?: unknown;
+    signal: AbortSignal;
+}
+/** Return value of the request-error waterfall. */
+export type RequestErrorAction = {
+    kind: 'retry';
+} | undefined;
+/** Selection result for one request. */
+export interface KeySelection {
+    key: KeyRecord | undefined;
+    value: string | undefined;
+}
+/** Attempt bookkeeping for retry/failover decisions. */
+export interface AttemptState {
+    keyId: string | undefined;
+    retries: number;
+    failure?: LlmFailureLike;
+    at: number;
+    turn?: number;
+    step?: number;
+    /** Whether the request actually resolved a managed key through the broker. */
+    usedManagedKey?: boolean;
+    /** Monotonic stream-sequence attribution for this step. */
+    lastSequence?: number;
+    /** Retry budget consumed per selected key. */
+    keyRetries?: Record<string, number>;
+}
+/** Provider support verdict used by the UI. */
+export interface ProviderSupport {
+    supported: boolean;
+    reason?: string;
+}
+export type { ManagerSettings, ModelRecord };

package/lib/host-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-types.js.map

package/lib/host-types.js.map

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

package/lib/index.d.ts

@@ -0,0 +1,181 @@
+import type { StateView } from './domain.js';
+import type { CredentialsLike, GenerateOptionsLike, HostContext, KeySelection, RequestErrorAction, AgentRequestPayload, RequestErrorPayload, SettingsLike, StreamChunkLike } from './host-types.js';
+import { KeysManagerStore } from './store.js';
+export declare const name = "keys-manager";
+export declare const inject: string[];
+export declare const provide: string[];
+/** Service keybinding consumed by the Typert Gateway. */
+interface TypertRemoteBinding {
+    service: KeysManagerService;
+    serviceKey: string;
+    namespace: string;
+}
+export declare class KeysManagerService {
+    readonly ctx: HostContext;
+    readonly store: KeysManagerStore;
+    private readonly als;
+    private readonly attempts;
+    private readonly stepAttempts;
+    private readonly streamAttempts;
+    private readonly linkedAttempts;
+    private readonly retryBindings;
+    private readonly requestSteps;
+    private attemptSequence;
+    private readonly switches;
+    private warnings;
+    settings: SettingsLike | undefined;
+    private rawCredentials;
+    private readonly credentialOriginals;
+    private readonly credentialWrappers;
+    private brokerOwners;
+    private readonly bindingCache;
+    private lastBindingPruneAt;
+    private readonly selectionQueues;
+    private queue;
+    private closing;
+    readonly typertRemote: TypertRemoteBinding;
+    constructor(ctx: HostContext, store: KeysManagerStore);
+    /** Log without ever echoing secret material. */
+    warn(message: string): void;
+    /** Rebuild the broker-reference → provider index. */
+    private rebuildBrokerMap;
+    /** Serialize mutations, rejecting submissions that arrive during shutdown. */
+    private run;
+    /**
+     * Periodically drop expired transient state: retry pins after `PIN_TTL_MS`,
+     * the remaining attempt/step records after `ATTEMPT_TTL_MS`.
+     */
+    pruneTransient(now?: number): void;
+    /** Stop accepting mutations, drain the queue, then persist the final snapshot. */
+    close(): Promise<void>;
+    /** Push a user-facing warning that rides the next state response. */
+    private pushWarning;
+    private takeWarnings;
+    /** Current settings service, if the composition mounted one. */
+    private settingsService;
+    /** Current raw credential provider. */
+    private credentialsRaw;
+    /** Install the broker layer on one credential provider instance. */
+    attachCredentials(credentials: CredentialsLike): void;
+    /** Restore the credential provider methods when our fiber unloads. */
+    detachCredentials(credentials: CredentialsLike): void;
+    /** Resolve a credential through the unwrapped provider. */
+    private resolveOriginal;
+    /**
+     * Probe one credential reference while distinguishing absence from a
+     * transient credential-store failure. Selection must never persist a
+     * permanent `valueMissing` marker for an error.
+     */
+    private probeKey;
+    /** Write one key literal through the unwrapped provider. */
+    private setOriginal;
+    /**
+     * Remove one key literal through the unwrapped provider. A rejected unset is
+     * only ignored when the credential is confirmed absent; a transient or
+     * permission failure must keep the metadata so a later retry can finish.
+     */
+    private unsetOriginal;
+    /** All settings descriptors, with an explicit unreadable state. */
+    private describeSettings;
+    /** Find one live settings descriptor by entry id. */
+    private namespace;
+    /** Apply one path-addressed settings write through the live revision. */
+    private mutateSettings;
+    /** Prune expired bindings at most once a minute, without a restart. */
+    private pruneBindings;
+    /** Build the complete UI state. */
+    buildState(): StateView;
+    /** Remote: complete manager state. */
+    getState(): StateView;
+    /** Find one directory entry by route id. */
+    private directoryEntry;
+    /**
+     * Classify the live binding. An unreadable settings snapshot is `unknown`,
+     * not a confirmed mismatch: transient settings failures must not disable
+     * key-pool recovery for a provider that is still managed.
+     */
+    private bindingState;
+    /** Candidate credential refs from which an existing key can be imported. */
+    private importRefs;
+    /** Create and store one key record without adding it to a provider. */
+    private createKeyRecord;
+    /** Find the first existing key value worth importing. */
+    private findImport;
+    /** Remote: take over one existing provider route. */
+    adoptProvider(provider: string): Promise<StateView>;
+    /** Discover models for a new extra provider, falling back to the seed catalog. */
+    private discoverModels;
+    /** Remote: install and adopt one extra built-in provider. */
+    addExtraProvider(extraId: string, alias: string, value: string): Promise<StateView>;
+    /** Add one key; caller already owns the mutation queue. */
+    private addKeyLocked;
+    /** Remote: add one key to a managed provider. */
+    addKey(provider: string, alias: string, value: string): Promise<StateView>;
+    /** Remote: rename or pause/resume one key. */
+    updateKey(provider: string, keyId: string, patch: unknown): Promise<StateView>;
+    /** Remote: delete one key, releasing the provider when it was the last one. */
+    deleteKey(provider: string, keyId: string): Promise<StateView>;
+    /** Read one live profile for release-time cleanup decisions. */
+    private profileAt;
+    /** Restore the exact live profile captured before release mutated it. */
+    private restoreProfileSnapshot;
+    /** Remove every managed credential, recording progress before a retry. */
+    private deleteManagedCredentials;
+    /** Restore the provider profile and drop management; caller owns the queue. */
+    private releaseLocked;
+    /** Remote: stop managing a provider and restore its original key reference. */
+    releaseProvider(provider: string): Promise<StateView>;
+    /** Remote: update manager policy. */
+    setSettings(patch: unknown): Promise<StateView>;
+    /**
+     * Serialize the first selection for a sticky session/provider pair so two
+     * concurrent requests cannot advance the cursor and bind different keys.
+     */
+    selectKey(providerId: string, sessionId: string | undefined, step?: {
+        turn: number;
+        step: number;
+    }): Promise<KeySelection>;
+    /** Pin the key a retry must use, scoped to the failing step. */
+    private pinRetry;
+    /** Record the turn/step the agent loop is about to request for one provider. */
+    noteRequestStep(payload: AgentRequestPayload, providerId: string): void;
+    /** Drop one step's retry pin once its attempt settles. */
+    private clearRetry;
+    /** Selection body; callers reach it through {@link selectKey}. */
+    private doSelectKey;
+    /** Record a terminal failure without deciding policy yet. */
+    private recordFailure;
+    /** Record a successful terminal finish. */
+    private recordSuccess;
+    /** Mark one key cooling, preserving escalation across recovery windows. */
+    private markFailure;
+    /** Prune stale attempt records. */
+    private pruneAttempts;
+    /** Waterfall listener: bind a key to the request and observe its terminal chunk. */
+    streamListener(options: GenerateOptionsLike, next: () => AsyncIterable<StreamChunkLike>): AsyncIterable<StreamChunkLike>;
+    /** Wrap one managed stream so credential resolution sees this key. */
+    private wrapStream;
+    /**
+     * Delegate recovery to the next agent/request-error listener. Preserve the
+     * current key only when that listener actually requests a retry; a declined
+     * (undefined) recovery is terminal and must still cool the exhausted key.
+     */
+    private delegateAndMaybeCool;
+    /** Record one failed stream attempt for turn/step attribution. */
+    private recordStreamAttempt;
+    /** Consume the stream record linked to this exact failure object. */
+    private takeLinkedAttempt;
+    /** Claim the next unclaimed stream attempt after a step's last sequence. */
+    private claimStreamAttempt;
+    /**
+     * Find a metadata-selectable alternate whose credential actually resolves.
+     * A key whose credential was removed outside the manager must not cause the
+     * current, working key to be cooled and the session rebound.
+     */
+    private findVerifiedAlternate;
+    /** Waterfall listener: bounded retry, then key switch and cool-down. */
+    requestErrorListener(payload: RequestErrorPayload, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>;
+}
+/** Host entry. */
+export declare function apply(ctx: HostContext): void;
+export {};