@songsid/agend 2.1.6-beta.1 → 2.1.6-beta.10

package/dist/fleet-manager.d.ts

@@ -21,6 +21,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 { 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";
 import { StormWindow } from "./storm-window.js";
 import { SpawnGate } from "./spawn-gate.js";
 import { BackendOutageTracker } from "./backend-outage.js";
@@ -242,6 +245,40 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private ipcReconnectInFlight;
     private adapterRestarting;
     private adapterState;
+    /** Web Settings secret rotation is deliberately separate from reconnect
+     * recovery: a rotation must build a fresh provider client with the new token,
+     * and stale callbacks from the old client must not win. */
+    private connectionSecretChallenges;
+    private connectionSecretChallengesByKey;
+    private connectionSecretJobs;
+    private connectionSecretJobSession;
+    private connectionSecretInFlight;
+    private connectionSecretGenerations;
+    /** Local epoch that fences a challenge across adapter replacement and
+     * provider reconnect generations. The adapter's own generation can reset
+     * when a new adapter object is constructed, so keep an independent epoch. */
+    private connectionSecretAdapterRefs;
+    private connectionSecretHealthGenerations;
+    /** Generic API-key verifier/apply state.  The challenge scope contains the
+     * resolved spec/env key, so a request can never retarget another provider. */
+    private providerSecretChallenges;
+    private providerSecretChallengesByKey;
+    private providerSecretJobs;
+    private providerSecretJobSession;
+    private providerSecretInFlight;
+    private providerSecretGenerations;
+    /** Test seam only; production always uses the fixed HTTPS client. */
+    private providerSecretHttpClient?;
+    /** Code-owned activation hooks; never populated from a request. */
+    private providerSecretReloadHooks;
+    /** In-memory snapshots for narrow hot consumers (currently Groq voice). */
+    private providerSecretHotSnapshots;
+    /** Web Settings connection-binding step-up challenges and apply jobs. */
+    private connectionBindingChallenges;
+    private connectionBindingChallengesByKey;
+    private connectionBindingJobs;
+    private connectionBindingJobSession;
+    private connectionBindingInFlight;
     private collabInstances;
     private healthServer;
     private healthPortRetried;
@@ -254,6 +291,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private fullRestartLauncher;
     private eventLogPruneTimer;
     private logRotateTimer;
+    private discordPresenceTimer;
+    private discordPresenceInFlight;
+    private static readonly DISCORD_PRESENCE_REFRESH_MS;
     /** Days of event/activity history to keep. */
     private static readonly EVENT_LOG_RETENTION_DAYS;
     private watchdogTimer;
@@ -262,7 +302,29 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private mirrorBuffer;
     private mirrorTimer;
     private sseClients;
-    private webToken;
+    /**
+     * Read from disk on every access rather than cached at startup: `agend
+     * web-token rotate` runs in a separate process, and a cached copy would keep
+     * authorizing revoked links and cookies until the fleet restarted.
+     */
+    private get webToken();
+    /**
+     * Set while a Settings apply job is driving the reconcile. The reconcile
+     * stays the single doer; it just says out loud what it is doing to whom, so
+     * the job's rows are the work rather than a prediction of it.
+     */
+    private applyJobStoreCache;
+    /** The apply that currently owns the reconcile slot, reserved synchronously
+     * so a second request cannot slip in before the first one starts working. */
+    private activeApplyJobId;
+    /** The fleet-level signature this process actually came up on. */
+    private appliedFleetLevel;
+    /** The config behind that signature, kept so a "needs restart" log can name
+     * which keys moved rather than just asserting that something did. */
+    private startupFleetConfig;
+    /** Set when the file on disk and the in-memory config disagree on a
+     * startup-only key at startup. See checkStartupSignatureConsistency(). */
+    private fleetSignatureMismatch;
     private viewToken;
     private healthServerListening;
     constructor(dataDir: string);
@@ -273,6 +335,18 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     stormSuppressed(kind: string): boolean;
     private handleSighup;
     private scheduleReconcile;
+    /**
+     * Take the reconcile slot, or refuse.
+     *
+     * Only one reconcile may touch lifecycle and config at a time — two of them
+     * stop and start the same instance in parallel. SIGHUP and a Settings apply
+     * are the same operation from two entrances, so they share the one slot: the
+     * signal coalesces into a pending replay, the apply is told the fleet is busy.
+     *
+     * The returned promise is the caller's to handle; the stored one is already
+     * handled, so a rejection never escapes as an unhandled rejection.
+     */
+    private startExclusiveReconcile;
     /**
      * Is the fleet going down (or coming back up) on purpose?
      *
@@ -309,6 +383,13 @@ 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;
+    /**
+     * A channel's configurable bot_token_env is an env-key writer too.  Refuse
+     * an overlap with a registry API key (or a process-reserved key) before the
+     * config becomes live; otherwise a Discord token could be written into
+     * GROQ_API_KEY by a perfectly valid-looking rotation request.
+     */
+    private assertProviderSecretEnvKeys;
     /** User-authored fleet.yaml, before defaults are merged into instances. */
     getRawFleetConfig(): RawFleetConfig;
     /** Build topic routing table: { topicId -> RouteTarget } */
@@ -398,6 +479,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Classic channels use their effective backend merge chain, not the raw row.
      */
     getActiveUsageProviderIds(): ReadonlySet<string>;
+    /** Subscription providers used by the running/paused instances owned by one adapter. */
+    getUsageProviderIdsForAdapter(adapterId: string): ReadonlySet<string>;
+    /** `[instance, effective backend, credential profile]` for everything that is
+     * running or paused — the one place both usage views agree on who is live. */
+    private activeBackendBindings;
     /** Effective backends with a running or persisted-paused fleet/Classic instance. */
     getActiveBackendIds(): ReadonlySet<string>;
     isClassicInstance(name: string): boolean;
@@ -535,6 +621,15 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * from restarting the same process twice; backendNameOf defines ownership.
      */
     private configuredBackendInstanceNames;
+    /**
+     * Probe the same executable set exposed by the web backend catalog.
+     *
+     * This deliberately has no cache: an `/install-cli` completion can add a
+     * binary to PATH while the fleet process remains alive, and the next bare
+     * `/login` must see it without requiring a restart or an explicit cache
+     * invalidation call.
+     */
+    private probeInstalledBackends;
     /**
      * One fleet-level notice per burst, not one per instance: a post-update herd
      * fails many instances within the same second. Two notices per incident at
@@ -584,6 +679,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startUpdateProgressMonitor;
     /** Start all instances from fleet config */
     startAll(configPath: string): Promise<void>;
+    /** Keep Discord profile activity aligned with the same cached usage source as /usage. */
+    private startDiscordUsagePresence;
+    private refreshDiscordUsagePresence;
     /**
      * Delete inbox files older than retentionDays (by mtime). Cleans the shared
      * inbox (`<dataDir>/inbox`) and every workspace inbox
@@ -719,12 +817,43 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Pure: callers rely on being able to ask before claiming the dedup key.
      */
     private botMessageDropReason;
+    /**
+     * Say so when an adapter's access mode is coming from its state file rather
+     * than from fleet.yaml. The state file wins by design — a pairing done at
+     * runtime has to survive a restart — but that also means an edit to
+     * `access.mode` silently does nothing, which is indistinguishable from the
+     * fleet not having reloaded. Naming the file is what makes it fixable.
+     */
+    private warnIfAccessModeOverridden;
     private handleInboundMessage;
     /** Handle outbound tool calls from a daemon instance */
     /** Warn (but don't block) when rate limits are high. 30-min debounce per instance. */
     private rateLimitWarnedAt;
     private warnIfRateLimited;
     /** Handle outbound tool calls from a daemon instance */
+    /**
+     * Would this instance be allowed to use this tool?
+     *
+     * Stage 1 asks and records; nothing is refused yet. The recording is not only
+     * an observation window: `logActivity("tool_call")` sits on the outbound path
+     * only, so today the fleet has no idea what the agent endpoint or the typed
+     * IPC handlers are being asked to do — the one face with no authorization is
+     * also the one face with no telemetry.
+     *
+     * The profile comes from the instance the socket belongs to. Deliberately not
+     * `senderSessionName`, which arrives inside the message: a caller that fills
+     * in its own identity has not been identified.
+     */
+    /**
+     * Say once, at startup, what the new default means for this fleet.
+     *
+     * Nothing is rewritten: an explicit `tool_set: full` is a choice somebody
+     * made, and marking an instance as a coordinator is a judgement about how
+     * their fleet is organised. Both stay theirs — this only makes sure they are
+     * not discovered by an agent failing at three in the morning.
+     */
+    private announceToolPermissionsChange;
+    private checkToolPermission;
     private handleOutboundFromInstance;
     /** Side effects of a routed reply: cancel-button lifecycle, logs, SSE, chat log. */
     private afterReplyRouted;
@@ -760,6 +889,24 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private scheduleSourceAdapter;
     private notifySourceTopic;
     private notifyScheduleFailure;
+    /**
+     * The typed IPC messages, all through one door.
+     *
+     * They used to be five sibling branches on the dispatch, which is why the
+     * permission question had five places to be forgotten. Routing them together
+     * means the check above happens once and cannot be skipped by adding a
+     * sixth — a new type has to appear in `IPC_TYPE_TOOLS` to be dispatched at
+     * all.
+     */
+    /**
+     * Answer a refused typed message the way its handler would have.
+     *
+     * These are request/response over IPC: dropping the message silently leaves
+     * the caller waiting for a reply that never comes, and a hung agent is a
+     * worse failure than a refused one.
+     */
+    private refuseTypedIpc;
+    private dispatchTypedIpc;
     private handleScheduleCrud;
     private handleDecisionCrud;
     /** Resolve display name for an instance, fallback to instance name. */
@@ -771,6 +918,19 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private handleSetDisplayName;
     private handleSetDescription;
     handleScheduleCrudHttp(instance: string, op: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * The only place an agent's request creates, changes or removes a schedule
+     * (#895). The IPC handler (MCP calls, direct channel.sock writes) and the
+     * agent endpoint (agent-cli, HTTP agent mode) are adapters over this, so the
+     * target check cannot be present on one face and missing on the other — the
+     * shape #804 had to close twice.
+     *
+     * `caller` is the instance the server resolved for the request; any
+     * `source` in `args` is ignored, and a schedule's source is always its caller.
+     * A refusal is a ToolNotPermittedError: 403 on the agent endpoint, the error
+     * of the schedule response on IPC.
+     */
+    private performScheduleOp;
     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>;
@@ -1005,6 +1165,21 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * (or an assist for one they stopped) must not stay clickable for the rest
      * of its 15 minutes.
      */
+    /**
+     * Collapse every still-armed button prompt, for a fleet that is going away.
+     *
+     * The map is in memory; the buttons are in the chat for up to 24 hours. A
+     * restart therefore leaves them looking live — pressing one takes the stale
+     * branch, which acknowledges the click and drops the dismissal without
+     * saying so. Retiring them here means the user meets a spent prompt instead
+     * of a live-looking dead one.
+     *
+     * Best effort and bounded. Each collapse is a platform call, a day of tips
+     * can be many of them, and shutdown still has instances to stop. Whatever
+     * has not finished by the deadline is abandoned — that is exactly today's
+     * behaviour, so the budget can only leave things no worse than before.
+     */
+    private retirePendingNoncePrompts;
     clearNoncePromptsForInstance(instanceName: string): void;
     /** A clean exit is intentional from the CLI's perspective, but often not from
      * the operator's. Keep the instance notice passive and put the action in the
@@ -1438,12 +1613,35 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Human-readable effective model, e.g. `auto (default)`. Used by /ctx. */
     modelDisplayForInstance(instanceName: string): string;
     private modelChoiceLabel;
-    /** Probe one backend's CLI env and cache it. Best-effort; never throws. */
+    /**
+     * Probe one backend's CLI env and cache it. Best-effort; never throws.
+     *
+     * `refreshVendorCatalog` is the "🔄 Refresh models" path only (#886): first
+     * ask the CLI to refetch its own catalog, for backends whose probe merely
+     * reads a file the CLI maintains. Every other caller leaves it off, so the
+     * startup and /model probes behave exactly as before. A failed vendor
+     * refresh fails the probe (null), which the menu reports instead of passing
+     * the old list off as fresh.
+     */
     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;
+    /**
+     * The model list plus where it came from. `source` is "live" only when a probe
+     * actually ran and answered; a refresh that failed or ran out of time reports
+     * "cache" with the previous list, so a menu can say "could not refresh"
+     * instead of presenting an old list as a fresh one.
+     */
+    private getModelOptionsWithSource;
+    /**
+     * The /model menu's choices, in the one order all three pickers share:
+     * 🔄 Refresh first, then models, then (claude) "More models…". Refresh takes
+     * a slot inside Discord's 25-option select cap, so it is paid for from the
+     * model rows, never from "More models…".
+     */
+    private modelMenuChoices;
     /**
      * Model catalog behind the `list_models` tool.
      *
@@ -1493,6 +1691,18 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private claudeApiModelOptions;
     /** Replace a consumed "/model" menu with the full account catalog tier. */
     private expandClaudeModelMenu;
+    /**
+     * "🔄 Refresh models" (#886): probe live past both caches and redraw the menu.
+     *
+     * Past AgEnD's cli-env cache (refresh=true) and, where the backend supports
+     * it, past the CLI's own catalog cache too (codex: `codex debug models`).
+     * Without the second half, a codex refresh re-read the same models_cache.json
+     * and showed the old list as new.
+     *
+     * A failed refresh keeps the previous list and says so. It never blanks the
+     * menu, because a picker with no rows cannot even offer another refresh.
+     */
+    private refreshModelMenu;
     /** 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). */
@@ -1584,6 +1794,211 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * fields, plus cold fleet-level settings, retain restart semantics.
      */
     private reconcileInstances;
+    /**
+     * `{channel, cold defaults}` as one comparable string — the part of the config
+     * a running fleet process cannot adopt without restarting.
+     */
+    private fleetLevelSignature;
+    /**
+     * The config a reconcile is about to load, not the one held in memory.
+     *
+     * Settings mutates the in-memory object and writes the file; only the file
+     * goes back through defaults expansion. Forecasting from memory therefore
+     * misses every instance that a changed fleet default will restart — the user
+     * is told "restart AgEnD" and not told that five agents are about to go down.
+     */
+    private nextFleetConfig;
+    /**
+     * Does the config this process is running match the one a reconcile would
+     * load off disk?
+     *
+     * If not, every apply reports a fleet-level change that a restart cannot
+     * clear — restart, recompute, disagree again — a self-sustaining loop that
+     * the rate limit can only slow to three naggings an hour. Startup rewrites
+     * the file in three places before this point (slimFleetConfigAtStartup, the
+     * general auto-create, the general fixup), so the two can genuinely diverge.
+     *
+     * An offer to restart that cannot possibly succeed is worse than no offer, so
+     * the panel shows the mismatch instead of a button.
+     */
+    private checkStartupSignatureConsistency;
+    /**
+     * Is a live adapter already long-polling this bot token?
+     *
+     * Telegram's `getUpdates` has exactly one consumer: a second poller takes
+     * turns with the first and both miss messages. The setup wizard's "post in
+     * the group and I'll detect it" step is a second poller, so it has to know
+     * when the answer is "not against this token, not while I'm running".
+     */
+    isBotTokenInUse(token: string): boolean;
+    /** Non-null when startup found the running config and fleet.yaml disagreeing. */
+    fleetSignatureMismatchKeys(): string[] | null;
+    /**
+     * Restart AgEnD itself on behalf of a Settings apply.
+     *
+     * Deliberately a separate action from Apply: the panel is reachable from
+     * outside the LAN, and "restart the whole fleet" must never be something a
+     * single Apply click can carry along with it.
+     *
+     * The order below is the safety envelope, and the order matters:
+     * concurrency and consistency first (cheap, and a restart during a reconcile
+     * is the dangerous one), then the state checks, then the rate limit, then the
+     * audit notice — and only once all of that holds is the attempt written to
+     * disk and fsynced, before anything spawns.
+     */
+    requestSettingsSelfRestart(jobId: string, key: string): Promise<SelfRestartResult>;
+    /** The audit notice, and the message the restart progress will edit. */
+    private postSelfRestartNotice;
+    /** Jobs outlive this process on purpose; see apply-job.ts. */
+    get applyJobs(): ApplyJobStore;
+    /** The only channel metadata exposed to the Settings secret UI. */
+    listSecureConnections(): ConnectionMetadata[];
+    private secureConnectionChannel;
+    private secureConnectionGeneration;
+    /** Provider API-key rows exposed to Settings (never the env key or secret). */
+    providerSecretsEnabled(): boolean;
+    listProviderSecrets(): ProviderSecretStatus[];
+    private providerSecretStaleConsumers;
+    private providerSecretGeneration;
+    private providerSecretEnvAllowed;
+    verifyProviderSecret(input: {
+        specId: string;
+        secret: string;
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): Promise<{
+        ok: true;
+        verification_id: string;
+        expires_at: number;
+        spec_id: string;
+        activation: "next_use" | "reload_hook";
+    } | {
+        ok: false;
+        status: "unsupported_verifier" | "provider_rejected" | "provider_unavailable" | "invalid";
+        error: string;
+    }>;
+    /** Naming aliases used by integrations that call this an API-key operation. */
+    verifyProviderApiKey(input: Parameters<FleetManager["verifyProviderSecret"]>[0]): ReturnType<FleetManager["verifyProviderSecret"]>;
+    startProviderSecretApply(input: {
+        specId: string;
+        verificationId: string;
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): {
+        job: ProviderSecretApplyJob;
+        reused: boolean;
+    } | {
+        busy: ProviderSecretApplyJob | null;
+    } | {
+        error: string;
+    };
+    startProviderApiKeyApply(input: Parameters<FleetManager["startProviderSecretApply"]>[0]): ReturnType<FleetManager["startProviderSecretApply"]>;
+    getProviderSecretApply(jobId: string, sessionBinding: string): ProviderSecretApplyJob | null;
+    getProviderApiKeyApply(jobId: string, sessionBinding: string): ProviderSecretApplyJob | null;
+    private runProviderSecretApply;
+    /** Groq is currently read from process.env per voice request, so the hook is
+     * intentionally a no-op. Keeping it as a named code-owned hook makes the
+     * hot activation contract explicit and gives tests a failure seam; no generic
+     * SIGHUP or caller-provided hook is ever executed. */
+    private runProviderSecretReloadHook;
+    private normalizeConnectionBinding;
+    private connectionBindingChannelConfig;
+    /** Verify a prospective group/guild binding without mutating fleet state. */
+    verifyConnectionBinding(input: {
+        connectionId: string;
+        binding: {
+            group_id?: unknown;
+            general_channel_id?: unknown;
+        };
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): Promise<{
+        ok: true;
+        verification_id: string;
+        expires_at: number;
+        binding: ConnectionBinding;
+        probe: BindingProbe;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    startConnectionBindingApply(input: {
+        connectionId: string;
+        verificationId: string;
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): {
+        job: SecretApplyJob;
+        reused: boolean;
+    } | {
+        busy: SecretApplyJob | null;
+    } | {
+        error: string;
+    };
+    getConnectionBindingApply(jobId: string, sessionBinding: string): SecretApplyJob | null;
+    private runConnectionBindingApply;
+    /** Stop, rebuild and wait for a new adapter before committing YAML binding. */
+    private rebuildAdapterForBinding;
+    verifyConnectionSecret(input: {
+        connectionId: string;
+        secret: string;
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): Promise<{
+        ok: true;
+        verification_id: string;
+        expires_at: number;
+        identity?: {
+            id: string | null;
+            username: string | null;
+        };
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    startConnectionSecretApply(input: {
+        connectionId: string;
+        verificationId: string;
+        sessionBinding: string;
+        idempotencyKey: string;
+    }): {
+        job: SecretApplyJob;
+        reused: boolean;
+    } | {
+        busy: SecretApplyJob | null;
+    } | {
+        error: string;
+    };
+    getConnectionSecretApply(jobId: string, sessionBinding: string): SecretApplyJob | null;
+    private runConnectionSecretApply;
+    /** Stop the old provider client and construct a new one from process.env. */
+    private rebuildAdapterForSecret;
+    /**
+     * What a reconcile is about to do, per target.
+     *
+     * A forecast, not the record: it is built from the same `classifyInstanceChange`
+     * the reconcile decides with, but the rows that end up in the job are the ones
+     * the reconcile reports as it works. A target the forecast missed (a Classic
+     * instance inheriting a changed default) is added when it is first touched.
+     */
+    planConfigApply(): Array<{
+        target: string;
+        kind: ApplyTargetKind;
+    }>;
+    /**
+     * Start (or re-join) a Settings apply.
+     *
+     * The key is the client's. Handing back the existing job for a repeated key is
+     * the whole point: the retry after a lost response must not apply everything a
+     * second time.
+     */
+    startSettingsApply(key: string): {
+        job: ApplyJob;
+        reused: boolean;
+    } | {
+        busy: ApplyJob | null;
+    };
+    private runSettingsApply;
     restartInstances(): Promise<void>;
     private checkForUpdates;
     /**