@songsid/agend 2.1.8-beta.1 → 2.1.8-beta.11

package/dist/fleet-manager.d.ts

@@ -1,19 +1,20 @@
 import { type FleetMemory } from "./process-memory.js";
 import { ReplyDeduper } from "./reply-dedup.js";
 import type { FleetConfig, RawFleetConfig, InstanceConfig } from "./types.js";
-import { type DeliveryStatus, type ResolvedStatusEmojis } from "./status-emojis.js";
+import { type DeliveryStatus, type GuildEmoji, type GuildEmojiGroup, type ResolvedStatusEmojis } from "./status-emojis.js";
 import { type RouteTarget } from "./fleet-context.js";
 import { EventLog } from "./event-log.js";
 import { AdapterWorld } from "./adapter-world.js";
 import { CostGuard } from "./cost-guard.js";
 import { IpcClient } from "./channel/ipc-bridge.js";
 import type { AdapterHealthSnapshot, ChannelAdapter, InboundReaction } from "./channel/types.js";
+import { type BackendCliVersionSnapshot } from "./backend/types.js";
 import { type Logger } from "./logger.js";
 import { Scheduler } from "./scheduler/index.js";
 import type { FleetContext } from "./fleet-context.js";
 import { TmuxControlClient } from "./tmux-control.js";
 import { RoutingEngine } from "./routing-engine.js";
-import { InstanceLifecycle, type LifecycleContext } from "./instance-lifecycle.js";
+import { InstanceLifecycle, type TransitionHandle, type LifecycleContext } from "./instance-lifecycle.js";
 import { type ArchiverContext } from "./topic-archiver.js";
 import { type StatuslineWatcherContext } from "./statusline-watcher.js";
 import { type OutboundContext } from "./outbound-handlers.js";
@@ -24,6 +25,9 @@ import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
 import { type ExplicitInstanceRemoval } from "./instance-removal.js";
 import type { InstanceState } from "./backend/types.js";
+import { WakeCoordinator } from "./wake-coordinator.js";
+import { TargetQueueWorker } from "./target-queue-worker.js";
+import { resolveDeliveryWorkerMode } from "./types.js";
 import { type ConnectionMetadata, type ConnectionBinding, type BindingProbe, type SecretApplyJob, type ProviderSecretApplyJob } from "./connection-secrets.js";
 import { type ProviderSecretStatus } from "./provider-secret-registry.js";
 import { ApplyJobStore, type ApplyJob, type ApplyTargetKind, type SelfRestartResult } from "./apply-job.js";
@@ -72,6 +76,12 @@ export interface DeliveryOptions {
     waitForIdle?: boolean;
     /** Test/operational override; normal deliveries use the 60 second backstop. */
     idleTimeoutMs?: number;
+    /**
+     * Phase 2b: never wake inline. Durable dispatch to a `wake_only` target sets
+     * it — the wake coordinator is that target's only waker, so a target that
+     * paused after its row was claimed is handed back instead of woken here.
+     */
+    noInlineWake?: boolean;
 }
 export declare const LOGIN_CALLBACK_PREFIX = "login:";
 /**
@@ -119,6 +129,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     readonly managerBootId: `${string}-${string}-${string}-${string}-${string}`;
     deliveryOutbox: DeliveryOutbox | null;
     private deliveryOutboxRecovered;
+    /** Phase 2b: wakes paused targets for queued durable work (delivery_worker ≠ off). */
+    wakeCoordinator: WakeCoordinator | null;
+    /**
+     * Phase 2c: targets whose durable lane a TargetQueueWorker owns
+     * (delivery_worker: on). Granted and released only in the pump's
+     * synchronous section and only while the lane is empty; the pump skips them.
+     */
+    readonly queueWorkers: Map<string, TargetQueueWorker>;
     private deliveryPumpScheduled;
     private deliveryPumpRunning;
     private deliveryPumpTimer;
@@ -372,6 +390,17 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     sweepReplyObligations(now?: Date): void;
     private scheduleDeliveryOutboxPump;
     private runDeliveryOutboxPump;
+    /**
+     * Phase 2c ownership (design §1.5-A), called synchronously from the pump
+     * before its claim loop, so a grant and the pump's own claims cannot
+     * interleave. A worker is granted a target's lane only when the target is
+     * `on` and its lane is empty: no row in flight in the outbox and no pump
+     * dispatch holding it. It gives the lane back only when it is idle and the
+     * target is no longer `on` (or has nothing pending). A flag change never
+     * takes a lane mid-drain.
+     */
+    private reconcileQueueWorkers;
+    private createQueueWorker;
     private dispatchDurableDelivery;
     private waitForDurableLaneRelease;
     private spawnConcurrency;
@@ -551,8 +580,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /**
      * Ask the daemon to capture the pane before answering, then wait for any state
      * report produced after this request. The ordinary query is intentionally
-     * cache-only (idle gates call it frequently); this opt-in refresh is reserved
-     * for lifecycle decisions where a stale state would strand UI.
+     * cache-only; delivery idle gates opt into their own pane/input proof, and
+     * this refresh serves lifecycle decisions where a stale state would strand UI.
      */
     private refreshInstanceExecutionState;
     private deliverWithIdleGate;
@@ -582,6 +611,40 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: DeliveryOptions): Promise<boolean | void>;
     /** Fleet admin is an explicit config allowlist entry, not merely an open/paired user. */
     isFleetAdmin(userId: string, adapterId?: string): boolean;
+    /** Phase 2: delivery_worker for a target (instance override → fleet default → off). */
+    deliveryWorkerMode(target: string): ReturnType<typeof resolveDeliveryWorkerMode>;
+    /** Active instances mid-restart: they keep their warm slot through the stop → replacement gap. */
+    private restartsHoldingSlot;
+    /**
+     * Instances counted against the wake coordinator's hard cap: running
+     * daemons, plus active instances whose restart is between stopping the old
+     * daemon and publishing the replacement.
+     */
+    private warmInstanceNames;
+    private createWakeCoordinator;
+    /** LifecycleContext: an operator or user wake clears the coordinator's park/backoff for it. */
+    onExternalWake(name: string): void;
+    /**
+     * Phase 2b shared warm-slot admission (design §1.3, §1.6) for every wake
+     * that is not the coordinator's own: an operator's wake, a user's message,
+     * an explicit start or a restart of a paused instance. With delivery_worker
+     * off, or for a target that is not paused (an active restart is already
+     * counted), nothing is reserved. A target already being woken is joined —
+     * its flight holds the slot — rather than reserved twice. Otherwise a slot
+     * is taken under the hard cap, an unleased idle instance is paused to make
+     * one, and if none can be, the wake is refused instead of exceeding the cap.
+     */
+    private acquireWakeSlot;
+    private releaseWakeSlot;
+    /**
+     * An operator's or user's wake (/wake, wake_instance, start_instance on a
+     * paused instance, Settings, a channel message). With delivery_worker off it
+     * is exactly the old lifecycle wake; otherwise it goes through the shared
+     * slot admission and joins any wake already in flight for the target.
+     */
+    explicitWake(name: string, timeoutMs?: number): Promise<void>;
+    /** The least-recently-active idle, unleased, non-general running instance other than `exclude`. */
+    private lruUnleasedIdle;
     changeInstancePauseState(name: string, action: "pause" | "wake"): Promise<"paused" | "awake" | "not_idle">;
     /** Deliver an already-resolved hot snapshot without depending on IPC timing. */
     private applyHotConfigUpdate;
@@ -597,9 +660,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * and reconcile calls leave this false so a persisted pause remains paused
      * across a fleet restart.
      */
-    resumePaused?: boolean): Promise<void>;
+    resumePaused?: boolean, 
+    /** Phase 2a: the caller's transition, for a start made from inside a restart or wake. */
+    transition?: TransitionHandle): Promise<void>;
     /** Recreate a daemon for a marker-only paused instance after an explicit wake/delivery. */
-    startPersistedPausedInstance(name: string): Promise<void>;
+    startPersistedPausedInstance(name: string, transition?: TransitionHandle): Promise<void>;
     /**
      * Start instances with configurable concurrency and stagger delay.
      * Instances sharing the same working_directory are serialized within a group
@@ -692,13 +757,25 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Last-resort completion after RestartProgress could not deliver to its
      * adopted target. It stays bounded and never wakes a not-ready gateway. */
     private sendFleetStartCompletionFallback;
-    stopInstance(name: string): Promise<void>;
+    stopInstance(name: string, transition?: TransitionHandle): Promise<void>;
     /** Restart a single instance, reloading fleet.yaml first to pick up config changes. */
     restartSingleInstance(name: string, opts?: {
         freshStart?: boolean;
+        explicit?: boolean;
     }): Promise<void>;
     isInstanceRestarting(name: string): boolean;
+    /** InstanceLifecycleContext: an explicit wake joins the restart in flight. */
+    restartInFlight(name: string): Promise<void> | undefined;
+    /**
+     * Phase 2a: restarting a paused instance is a wake. The stop leaves the
+     * pause marker in place, and the start used to skip on it ("Persisted
+     * paused instance"), turning a resident pause into a marker-only one that
+     * nothing would wake. Clear it before the start; if the start fails, put it
+     * back so the instance stays wakeable instead of becoming plain stopped.
+     */
+    private startAfterRestart;
     private doRestartSingleInstance;
+    private doRestartWithSlot;
     /**
      * 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
@@ -960,10 +1037,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private refuseTypedIpc;
     private dispatchTypedIpc;
+    /** `list_emojis` / `set_persona_emoji` / `preview_emojis` over IPC; the agent endpoint calls the same methods. */
+    private handlePersonaEmoji;
     private handleScheduleCrud;
     private handleDecisionCrud;
     /** Resolve display name for an instance, fallback to instance name. */
     resolveDisplayName(instanceName: string): string;
+    /** Inherited keys such as __proto__ must never resolve to a mutable instance. */
+    private ownInstanceConfig;
     /** Persist identity to the instance's actual config store. Classic instances
      * are registry rows in classicBot.yaml, not fleet.yaml instance entries. */
     private setInstanceDisplayName;
@@ -987,6 +1068,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     handleDecisionCrudHttp(instance: string, op: string, args: Record<string, unknown>): Promise<unknown>;
     handleTaskCrudHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
     handleSetDisplayNameHttp(instance: string, name: string): Promise<unknown>;
+    handleListEmojisHttp(instance: string, refresh: boolean): Promise<unknown>;
+    handleSetPersonaEmojiHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
+    handlePreviewEmojisHttp(instance: string, args: Record<string, unknown>): Promise<unknown>;
     handleSetDescriptionHttp(instance: string, description: string): Promise<unknown>;
     private summarizeToolCall;
     private handleTaskCrud;
@@ -1077,6 +1161,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private deliveryStatusChains;
     /** #725: in-flight CLI env probes, keyed by backend name. Coalesces concurrent /model requests. */
     private pendingCliEnvProbes;
+    /** Forced vendor catalog refreshes are separate flights, but sysinfo joins either flight. */
+    private pendingVendorCliEnvProbes;
     /**
      * The status emojis for an instance (#1005): its own `status_emojis`, then
      * its channel's `options.status_emojis`, then the platform built-in. An
@@ -1088,27 +1174,67 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     };
     private warnedStatusEmojis;
     /**
-     * A Discord connection's server emojis for the Settings picker (#1005).
-     * Cached per connection — a server's emoji set changes rarely — and one
-     * fetch at a time; `refresh` forces a new one. Uses the running adapter, so
-     * the bot token never leaves the server.
+     * A Discord connection's server emojis for the Settings picker (#1005), from
+     * every server its bot can draw on (#1021): the primary `group_id` server,
+     * then each other server the bot is a member of that ClassicBot's
+     * `allowed_guilds` admits (unset = all, as for classic routing). A bot can
+     * react with a custom emoji from any server it is in. Cached per server — a
+     * server's emoji set changes rarely — and one fetch per server at a time;
+     * `refresh` forces new ones. One server refusing (e.g. Missing Access) is
+     * reported on that server and does not hide the others. Uses the running
+     * adapter, so the bot token never leaves the server.
      */
     listGuildEmojis(channelId: string, refresh?: boolean): Promise<{
         ok: true;
         fetched_at: number;
-        emojis: Array<{
-            id: string;
-            name: string;
-            animated: boolean;
-            available: boolean;
-        }>;
+        emojis: GuildEmoji[];
+        guilds: GuildEmojiGroup[];
     } | {
         ok: false;
         error: string;
     }>;
     private static GUILD_EMOJI_TTL_MS;
+    /** Keyed `<connection>\0<server id>`. */
     private guildEmojiCache;
     private guildEmojiFetches;
+    /**
+     * What `instanceName` may pick as its persona emoji (the `list_emojis`
+     * tool): its current status set with where each value comes from, the
+     * standard emojis its platform takes, and on Discord the server emojis its
+     * bot can draw on — the same lists, and the same resolution, as the
+     * Settings picker (#1005/#1021), so an agent and an operator see one truth.
+     */
+    listEmojisFor(instanceName: string, refresh?: boolean): Promise<Record<string, unknown>>;
+    /**
+     * `preview_emojis` (#1040): download a few Discord server emojis so an agent
+     * can look at them before it picks one — a name and an id say nothing about
+     * what an emoji looks like. The fleet fetches, not the agent (not every
+     * backend can), and returns a local path per emoji to Read, as
+     * download_attachment does for an attachment.
+     *
+     * SSRF-safe by construction: nothing from the caller reaches a URL. The
+     * caller names emojis; each must be an available one in a server this bot
+     * can draw on (the list set_persona_emoji checks), and the CDN URL is built
+     * from that listed emoji's numeric id. Static PNG, size-capped, cached by id.
+     */
+    previewEmojis(instanceName: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private static EMOJI_PREVIEW_MAX;
+    private static EMOJI_PREVIEW_MAX_BYTES;
+    private static EMOJI_PREVIEW_TTL_MS;
+    /** One emoji's static PNG under the inbox, reused while fresh; stale ones are pruned. */
+    private fetchEmojiPreview;
+    /**
+     * `set_persona_emoji`: `instanceName` sets one of its own status emojis —
+     * `delivered` unless it names another — in its per-instance `status_emojis`
+     * override (#1005 addendum 2), so its stamp is told apart from other bots'
+     * on a shared message. The value is judged exactly as Settings and the
+     * react path judge it (statusEmojiProblem on the instance's platform), and
+     * a Discord server emoji must be one its bot can use: an emoji from a
+     * server it is not in would be stored, preview fine, and fail every react.
+     * An empty emoji removes that status's override.
+     */
+    setPersonaEmoji(instanceName: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private personaEmojiMissing;
     /** What the instructions tell `instanceName` not to react with (its own status set). */
     statusEmojiAvoidList(instanceName: string): string[];
     /** The progress bubble's leading emoji, in the form the channel renders. */
@@ -1128,6 +1254,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * own adapter rather than through reactMessageStatus (classic bots).
      */
     private receivedReactionFor;
+    /**
+     * The stamp for an inbound photo / file a classic bot saved (#1080): the
+     * instance's `status_emojis.photo|attachment`, then its connection's, then
+     * the built-in (📸/📎, or 👌/👍 on Telegram — what these paths always stamped).
+     * Anything else a saved attachment can be counts as a file.
+     */
+    private savedAttachmentReactionFor;
     reactMessageStatus(instanceName: string, chatId: string, messageId: string, status: DeliveryStatus, threadId?: string): void;
     /**
      * Apply a terminal delivery verdict. On Telegram the built-in delivered is
@@ -1624,7 +1757,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** `/install-cli cancel` — abort the active install and remove its window. */
     cancelInstallSession(): Promise<string>;
     /** `command -v` on a login shell, so PATH additions from rc files count. */
-    private verifyBinaryOnLoginShell;
+    /**
+     * The absolute path a fresh login shell resolves `binary` to, or null. Only
+     * a real executable file counts: `command -v` also answers with an alias
+     * definition or a function name, neither of which a spawn could run.
+     */
+    private locateBinaryOnLoginShell;
+    /** Put an installed binary's directory on the fleet's PATH (#1059), once. */
+    private adoptBinaryDirectory;
     /** "Sign in now?" button after a successful install. */
     private handleInstallLoginConfirm;
     /** Discord native `/login` slash — shared by every adapter dispatch block. */
@@ -1711,6 +1851,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private cliEnvPath;
     /** Read the cached CLI env for a backend, or null if missing/stale/unparseable. */
     private readCliEnv;
+    /** Return cached CLI versions immediately. Refresh is started after /sysinfo is sent. */
+    getBackendCliVersionSnapshot(): BackendCliVersionSnapshot;
+    /** Called only after the user-visible sysinfo send/respond has settled. */
+    refreshBackendCliVersions(): void;
     /** True when a cached CLI env is old enough that `/model` should re-probe. */
     private cliEnvNeedsRefresh;
     /**
@@ -1719,6 +1863,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * previous list, never stall the command that asked for it.
      */
     private probeBackendBounded;
+    private startCliEnvProbeWorker;
     /**
      * Resolve the effective model for a fleet or ClassicBot instance, plus where it
      * came from. Single source of truth for `/model` and `/ctx` — precedence:
@@ -1745,6 +1890,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * the old list off as fresh.
      */
     private probeBackend;
+    /** Preserve the existing cache merge rules for both in-process and worker probes. */
+    private persistCliEnvProbeResult;
     /** 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. */