@songsid/agend 2.1.0-beta.8 → 2.1.0

package/dist/fleet-manager.d.ts

@@ -1,4 +1,4 @@
-import type { FleetConfig, InstanceConfig } from "./types.js";
+import type { FleetConfig, RawFleetConfig, InstanceConfig } from "./types.js";
 import { type RouteTarget } from "./fleet-context.js";
 import { EventLog } from "./event-log.js";
 import { AdapterWorld } from "./adapter-world.js";
@@ -14,10 +14,34 @@ import { InstanceLifecycle, type LifecycleContext } from "./instance-lifecycle.j
 import { type ArchiverContext } from "./topic-archiver.js";
 import { type StatuslineWatcherContext } from "./statusline-watcher.js";
 import { type OutboundContext } from "./outbound-handlers.js";
+import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
 import type { InstanceState } from "./backend/types.js";
 export declare function resolveReplyThreadId(argsThreadId: unknown, instanceConfig?: InstanceConfig): string | undefined;
+/**
+ * Pure warm-cap victim selection (extracted for testability). Given the current
+ * warm (running) instance names and a cap, return the LRU idle instances to evict
+ * so the running count returns to the cap. Skips: the `exclude` instance, any
+ * already-evicting, general instances (never evicted), and non-idle instances
+ * (working/stuck can't be evicted). Oldest last-inbound is evicted first; a
+ * missing timestamp (0) sorts oldest. cap <= 0 (or non-integer) = unlimited → [].
+ */
+export declare function selectLruEvictions(warm: string[], cap: number, opts: {
+    exclude?: string;
+    isEvicting: (name: string) => boolean;
+    isGeneral: (name: string) => boolean;
+    isIdle: (name: string) => boolean;
+    lastInboundAt: (name: string) => number;
+}): string[];
+export interface DeliveryOptions {
+    /** Explicitly identify agent-to-agent delivery when metadata is unavailable. */
+    isCrossInstance?: boolean;
+    /** Force or bypass the idle gate. Schedules set this explicitly. */
+    waitForIdle?: boolean;
+    /** Test/operational override; normal deliveries use the 60 second backstop. */
+    idleTimeoutMs?: number;
+}
 export declare class FleetManager implements FleetContext, LifecycleContext, ArchiverContext, StatuslineWatcherContext, OutboundContext, AgentEndpointContext {
     dataDir: string;
     private children;
@@ -25,6 +49,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** @deprecated Use lifecycle.daemons — kept for backward compat */
     get daemons(): Map<string, import("./daemon.js").Daemon>;
     fleetConfig: FleetConfig | null;
+    private rawFleetConfig;
+    private rawFleetDocument;
+    private savedFleetConfigSnapshot;
     adapter: ChannelAdapter | null;
     readonly worlds: Map<string, AdapterWorld>;
     readonly adapters: Map<string, ChannelAdapter>;
@@ -51,12 +78,25 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private lastActivity;
     /** Latest pane-derived execution snapshot reported by each daemon. */
     private instanceStateCache;
+    /** CLI pane status overrides; daemon.pid alone only proves FleetManager lives. */
+    private instanceProcessStatus;
+    /** Instances currently being auto-paused by warm_cap, so concurrent checks don't double-evict. */
+    private warmCapEvicting;
+    /** Per-instance tail keeps cross-instance and scheduled deliveries FIFO. */
+    private idleGatedDeliveryTails;
+    /** Non-user work must observe a fresh idle snapshot after the latest delivery. */
+    private lastDeliveryAt;
+    /** State-cache updates wake event-driven idle waiters without busy polling. */
+    private instanceIdleWaiters;
     private lastInboundUser;
     private cancelButtons;
     private lastInboundMsg;
     private topicArchiver;
     controlClient: TmuxControlClient | null;
     classicChannels: ClassicChannelManager | null;
+    private pendingClassicStarts;
+    /** In-flight /model selections, keyed by nonce (see handleModelSelection). */
+    private pendingModelSelects;
     private failoverActive;
     readonly ipcStoppingInstances: Set<string>;
     private adapterRestarting;
@@ -79,6 +119,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     getSysInfo(): import("./fleet-context.js").SysInfo;
     /** Load fleet.yaml and build routing table */
     loadConfig(configPath: string): FleetConfig;
+    /** User-authored fleet.yaml, before defaults are merged into instances. */
+    getRawFleetConfig(): RawFleetConfig;
     /** Build topic routing table: { topicId -> RouteTarget } */
     buildRoutingTable(): Map<string, RouteTarget>;
     /**
@@ -100,6 +142,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * /cancel). Classic-only commands (/chat, /load) must NOT use this.
      */
     private resolveSlashTarget;
+    /**
+     * Model switching is privileged. Fleet allowlisted admins retain authority in
+     * ClassicBot channels, while ClassicBot's own admin_users may also switch the
+     * model of the channel they administer.
+     */
+    private isModelAdmin;
+    private handlePauseWakeSlash;
     /** Get the adapter bound to an instance, falling back to primary adapter */
     getAdapterForInstance(name: string): ChannelAdapter | null;
     /** Get the world for an instance */
@@ -118,10 +167,31 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     bindInstanceAdapter(name: string, adapterId: string, fromInbound?: boolean): void;
     getInstanceStatus(name: string): "running" | "paused" | "stopped" | "crashed";
     getInstanceExecutionState(name: string): InstanceState | null;
+    isClassicInstance(name: string): boolean;
     private cacheInstanceExecutionState;
-    /** Single delivery facade: wake an auto-paused CLI before sending to daemon IPC. */
-    deliverToInstance(instanceName: string, payload: Record<string, unknown>): Promise<void>;
+    private cacheInstanceProcessStatus;
+    /**
+     * Fleet-wide warm cap: if more than `defaults.warm_cap` instances are running,
+     * auto-pause the least-recently-active idle instances until back at the cap.
+     * Never evicts general instances (must stay warm) or working/stuck instances
+     * (only idle). 0/unset = unlimited. wake-before-deliver re-warms any evicted
+     * instance when a message next arrives.
+     *
+     * @param exclude instance to spare (e.g. one just woken to receive a delivery).
+     */
+    private enforceWarmCap;
+    private waitForInstanceIdle;
+    private deliverWithIdleGate;
+    /** Single delivery facade: wake paused CLIs and serialize non-user work behind idle. */
+    deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: DeliveryOptions): Promise<void>;
+    /** Fleet admin is an explicit config allowlist entry, not merely an open/paired user. */
+    isFleetAdmin(userId: string, adapterId?: string): boolean;
+    changeInstancePauseState(name: string, action: "pause" | "wake"): Promise<"paused" | "awake" | "not_idle">;
+    /** Apply a Settings edit to a ClassicBot channel without waiting for the poller. */
+    restartClassicInstanceFromSettings(instanceName: string): Promise<void>;
     startInstance(name: string, config: InstanceConfig, topicMode: boolean): Promise<void>;
+    /** Recreate a daemon for a marker-only paused instance after an explicit wake/delivery. */
+    startPersistedPausedInstance(name: string): Promise<void>;
     /**
      * Start instances with configurable concurrency and stagger delay.
      * Instances sharing the same working_directory are serialized within a group
@@ -131,7 +201,16 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startInstancesWithConcurrency;
     stopInstance(name: string): Promise<void>;
     /** Restart a single instance, reloading fleet.yaml first to pick up config changes. */
-    restartSingleInstance(name: string): Promise<void>;
+    restartSingleInstance(name: string, opts?: {
+        freshStart?: boolean;
+    }): Promise<void>;
+    /**
+     * Mark an instance so its next daemon start skips session resume. Written AFTER
+     * stop (survives the old daemon's cleanup) and BEFORE start so the respawn reads
+     * it — reuses the crash-state → resumeDisabled path from crash-loop recovery.
+     * One-shot: the daemon deletes it on startup.
+     */
+    private writeFreshStartMarker;
     /** Load .env file from data dir into process.env */
     private loadEnvFile;
     /** Start all instances from fleet config */
@@ -203,8 +282,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private botUserId;
     /** Periodically check if bound topics still exist */
     private startTopicCleanupPoller;
-    /** Save fleet config back to fleet.yaml */
-    saveFleetConfig(): void;
+    /**
+     * Patch only values changed in the effective config into the original YAML
+     * document. Unknown keys, explicit overrides and comments remain untouched.
+     */
+    saveFleetConfig(explicitPatches?: RawConfigPatch[]): void;
+    private patchFleetDocument;
     removeInstance(name: string): Promise<void>;
     startStatuslineWatcher(name: string): void;
     stopStatuslineWatcher(name: string): void;
@@ -266,7 +349,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         id: string;
         title: string;
     }>;
-    sendHangNotification(instanceName: string): Promise<void>;
+    sendHangNotification(instanceName: string, unchangedForMs?: number): Promise<void>;
     private static INSTRUCTIONS_FILENAME;
     private static GENERAL_INSTRUCTIONS;
     /** Ensure the general instance has its project instructions file + knowledge */
@@ -289,12 +372,50 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private forwardToClassicInstance;
     /** Paste raw text directly to a classic instance's CLI (no [user:] wrapping) */
     private pasteRawToClassicInstance;
+    /** Resolve the backend name configured for an instance (fleet or classic). */
+    private backendNameForInstance;
+    private cliEnvPath;
+    /** Read the cached CLI env for a backend, or null if missing/stale/unparseable. */
+    private readCliEnv;
+    /** Resolve the model currently configured for a fleet or ClassicBot instance. */
+    private currentModelForInstance;
+    private modelChoiceLabel;
+    /** Probe one backend's CLI env and cache it. Best-effort; never throws. */
+    private probeBackend;
+    /** Background-probe every distinct backend in use at startup (non-blocking). */
+    private probeCliEnvs;
+    /** Best-effort model list for `/model`: cached CLI env first, else live probe. Never throws. */
+    private getModelOptions;
+    /** `/model` slash handler (admin only). No arg → DC menu; `/model <name>` → apply directly. */
+    private handleModelSlash;
+    /**
+     * Show a TG inline-keyboard model-selection menu. Reuses the same
+     * pendingModelSelects coordinator as the DC Select Menu path.
+     * Returns null on success (menu shown), or a fallback string to send.
+     */
+    promptModelMenu(instanceName: string, userId: string, channelId: string, adapter: ChannelAdapter, chatId: string, threadId?: string): Promise<string | null>;
+    /** Consume a `/model` selection callback. Returns true for all model-select ids (incl. stale). */
+    private handleModelSelection;
+    /** Apply a model to an instance: runtime paste (claude-code) or persist + restart (others). */
+    applyModel(instanceName: string, model: string): Promise<string>;
     /** Read recent chat log for agent context */
     private getRecentChatLog;
+    /** Return a user-facing blocker without mutating ClassicBot state. */
+    private validateClassicStart;
+    private isBackendInstalled;
+    private getMissingBackendWarning;
+    /** Handle Discord's required static slash choice, warning before a likely startup failure. */
+    private handleClassicStartSlash;
+    /** Present platform-native backend choices, then start on selection or timeout. */
+    private beginClassicBackendSelection;
+    /** Consume a selection callback. Returns true for all ClassicBot callback IDs, including stale ones. */
+    private handleClassicBackendSelection;
+    /** Atomically claim one pending request so timeout/click races create at most one instance. */
+    private finishClassicBackendSelection;
     /** Start a classic channel instance with lightweight config */
     private startClassicInstance;
     /** Handle /start slash command — register classic channel */
-    handleClassicStart(channelId: string, channelName: string, userId: string, guildId?: string, adapterId?: string): Promise<string>;
+    handleClassicStart(channelId: string, channelName: string, userId: string, guildId?: string, adapterId?: string, backend?: string): Promise<string>;
     /** Handle /stop slash command — unregister classic channel */
     handleClassicStop(channelId: string, adapterId?: string): Promise<string>;
     stopAll(): Promise<void>;