@cjhyy/code-shell-server 0.9.48 → 0.9.50

package/dist/panels/background-services.d.ts

@@ -0,0 +1,193 @@
+import { type PanelExecutionScope, type PanelExecutionGate } from "./execution-gate.js";
+import { type CommitBoundary, type ServiceProcessIdentity, type ServiceIdentityInspector } from "./background-service-store.js";
+import { spawnServiceProcess } from "./background-service-process.js";
+export declare const panelBackgroundServiceMethods: readonly ["services.get", "services.setDesired", "services.configure", "services.attach", "services.detach", "services.read", "services.control"];
+export declare const backgroundServiceLimits: {
+    maxRunning: number;
+    maxPerApp: number;
+    maxPerScope: number;
+    healthyResetMs: number;
+    maxRetainedScopes: number;
+    maxChannels: number;
+    maxChannelBytes: number;
+    maxConfigBytes: number;
+    minCommitIntervalMs: number;
+    drainTimeoutMs: number;
+    maxLifetimeMs: number;
+    maxConsecutiveFailures: number;
+    maxServices: number;
+};
+export interface BackgroundServiceDefinition {
+    entry: string;
+    channels: Record<string, {
+        maxBytes: number;
+    }>;
+    maxLifetimeMs: number;
+    idleGraceMs: number;
+}
+export interface BackgroundServiceScope {
+    appId: string;
+    projectPath: string;
+    name: string;
+}
+type Desired = "off" | "on-demand" | "always";
+type Phase = "stopped" | "starting" | "running" | "draining" | "backoff" | "failed" | "paused" | "revoked" | "stop-unconfirmed" | "needs-consent";
+interface Channel {
+    generation: number;
+    seq: number;
+    committedAt: number;
+    value: unknown;
+}
+interface Control {
+    requestKey: string;
+    action: string;
+    result: string;
+    at: number;
+}
+export interface BackgroundServiceState {
+    desired: Desired;
+    desiredRevision: number;
+    configRevision: number;
+    phase: Phase;
+    generation: number;
+    revision: string;
+    startedAt: number | null;
+    restarts: number;
+    lastError: string | null;
+    controls: Control[];
+}
+export interface BackgroundServiceDescription {
+    revision: string;
+    definition: BackgroundServiceDefinition;
+    /** Resolve verified Host runtimes only at launch, never during read-only discovery. */
+    executable: string | (() => Promise<string>);
+    entry: string;
+    sha256: string;
+    packageRoot: string;
+    cwd: string;
+}
+export interface BackgroundServiceOptions {
+    rootDir: string;
+    describe(scope: BackgroundServiceScope): Promise<BackgroundServiceDescription>;
+    onEvent?(scope: BackgroundServiceScope, event: {
+        name: string;
+        state: BackgroundServiceState;
+        generation: number;
+        channel?: string;
+        seq?: number;
+    }): void;
+    gate?: PanelExecutionGate;
+    now?: () => number;
+    fault?: (boundary: CommitBoundary) => void;
+    identities?: ServiceIdentityInspector;
+    groupStatus?: (identity: ServiceProcessIdentity) => "alive" | "dead" | "unknown";
+    spawn?: typeof spawnServiceProcess;
+    /** Tests can block exactly at the authoritative publication boundary. */
+    beforePublish?: () => Promise<void>;
+    afterSpawnBeforeIdentity?: (identity: ServiceProcessIdentity) => Promise<void>;
+}
+/** Host-only coordinator. Package code never receives the authoritative storage path. */
+export declare class PanelBackgroundService {
+    private readonly options;
+    private readonly store;
+    private readonly records;
+    private readonly processes;
+    private readonly attachments;
+    private readonly pending;
+    private readonly failedCommits;
+    private emergency?;
+    private storageRetryAt;
+    private readonly publishTimers;
+    private readonly idleSince;
+    private readonly heldForUpdate;
+    private tail;
+    private timer?;
+    private initialized;
+    private initialization?;
+    private initializationRetryAt;
+    private initializationFailures;
+    private initializationError;
+    private recoveringStorage;
+    private lastAvailability;
+    private availabilityRevision;
+    private readonly availabilityListeners;
+    private stopping;
+    private ticking;
+    private unregister?;
+    private unregisterMutation?;
+    private unregisterDrain?;
+    private readonly now;
+    constructor(options: BackgroundServiceOptions);
+    private exclusive;
+    isAvailable(): boolean;
+    /** Subscribe to transitions; callers read isAvailable() for the initial snapshot. */
+    subscribeAvailability(listener: (available: boolean) => void): () => void;
+    private notifyAvailability;
+    private groupStatus;
+    private legacyLocalityDiagnostic;
+    private markStopUnconfirmed;
+    private startTimer;
+    initialize(): Promise<void>;
+    private commit;
+    private beginEmergencyStop;
+    private recoverStorage;
+    private emit;
+    private ensure;
+    private emptyRecord;
+    private compactInactive;
+    private inspect;
+    private receipt;
+    private remember;
+    get(scope: BackgroundServiceScope): Promise<BackgroundServiceState>;
+    read(scope: BackgroundServiceScope, channel: string, afterSeq?: number): Promise<Channel | {
+        generation: number;
+        seq: number;
+        committedAt: null;
+        value: null;
+        unchanged?: undefined;
+    } | {
+        unchanged: true;
+        generation?: undefined;
+        seq?: undefined;
+        committedAt?: undefined;
+        value?: undefined;
+    }>;
+    setDesired(scope: BackgroundServiceScope, input: {
+        desired: Desired;
+        expectedRevision: number;
+        requestKey: string;
+    }): Promise<BackgroundServiceState>;
+    configure(scope: BackgroundServiceScope, input: {
+        config: unknown;
+        expectedConfigRevision: number;
+        requestKey: string;
+    }): Promise<{
+        configRevision: number;
+    }>;
+    attach(scope: BackgroundServiceScope, guestId: number): Promise<{
+        attachId: string;
+        state: BackgroundServiceState;
+    }>;
+    detach(attachId: string, guestId: number): Promise<{
+        detached: boolean;
+    }>;
+    detachGuest(guestId: number): void;
+    control(scope: BackgroundServiceScope, input: {
+        action: "poke" | "pause" | "resume" | "stop" | "restart";
+        requestKey: string;
+    }): Promise<BackgroundServiceState>;
+    private stop;
+    private assertCapacity;
+    private exitedPhase;
+    private reconcile;
+    private failAttempt;
+    private onLine;
+    private onExit;
+    tick(): Promise<void>;
+    drain(matches: (scope: PanelExecutionScope) => boolean): Promise<void>;
+    /** Called after the catalog mutation releases its admission barrier, success or rollback. */
+    resumeAfterUpdate(): void;
+    revoke(appId: string): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};