@songsid/agend 2.3.0-beta.2 → 2.3.0-beta.4

package/dist/fleet-manager.d.ts

@@ -10,6 +10,7 @@ import type { FleetConfig, RawFleetConfig, InstanceConfig } from "./types.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 { BackendAvailabilityStore, type AvailabilityProbes, type BackendAvailability } from "./backend-availability.js";
 import { AdapterWorld } from "./adapter-world.js";
 import { CostGuard } from "./cost-guard.js";
 import { IpcClient } from "./channel/ipc-bridge.js";
@@ -73,6 +74,8 @@ import { AppearanceTools } from "./web-appearance-tools.js";
 import { ModStore } from "./web-mod-store.js";
 import { AgentMods } from "./web-mod-agent.js";
 import { type CachedImage } from "./web-images.js";
+import { WebSettingsTools } from "./web-settings-tools.js";
+import { type TrafficItem } from "./fleet-traffic.js";
 import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
@@ -84,6 +87,7 @@ import { TargetQueueWorker } from "./target-queue-worker.js";
 import { resolveDeliveryWorkerMode } from "./types.js";
 import { type WebNeedsItem } from "./needs-you-hub.js";
 import { type OrgChart } from "./web-org.js";
+import { type MemoryHog } from "./memory-hogs.js";
 import { type CacheReport } from "./cache-service.js";
 import { type WebCommandResult } from "./web-commands.js";
 import { type ReturningDevice } from "./web-returning-device.js";
@@ -442,6 +446,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** #1306: the preview listener (health_port + 1 by default), and whether it is listening. */
     private previewListener;
     private previewListening;
+    /** The preview listener could not open its port: "<port>: <error code>", for the page (#2061 follow-up); null otherwise. */
+    private previewListenError;
     /** The ports the preview listener was started for, and the inputs it was built from (a reload compares them). */
     private previewPorts;
     private previewInputs;
@@ -460,6 +466,9 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Injectable only to keep the chat→CLI reload hand-off deterministic in tests. */
     private fullRestartLauncher;
     private eventLogPruneTimer;
+    /** #1920 §3.2: the background reads of guests' ClassicBot room membership (a minute's tick; reads only what is due). */
+    private guestRoomsTimer;
+    private guestRoomMembership;
     private outboxPruneTimer;
     private logRotateTimer;
     private discordPresenceTimer;
@@ -474,6 +483,17 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startedAt;
     private stormOpenNotifyTimer;
     private memoryLogAt;
+    /**
+     * #2015: while host memory is elevated or critical, the processes holding the most in the fleet's service and whose
+     * they are (an instance, the fleet, tmux), for the pressure log, /health and the dashboard — never chat (#1712).
+     * Rescanned at most once a minute (async, one at a time); cleared when pressure ends.
+     */
+    private memoryTop;
+    private memoryTopScan;
+    /** The scan (a seam for tests: they give it a fake /proc). */
+    private memoryHogScan;
+    /** The fleet's own tmux session exists (only then are its panes read: a fleet that never started has none). */
+    private tmuxSessionEnsured;
     private memoryDebugAt;
     private memoryLogLevel;
     /** #1685: the host_memory value the last status frame carried, so a change re-sends the frame. */
@@ -574,6 +594,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private ownerCssStore?;
     /** #1629 r4 §3: each person's own CSS; which version is in force is their `css.active` in the web preferences. */
     get ownerCss(): OwnerCssStore;
+    private webSettingsToolsService?;
+    /**
+     * #2056: Settings → Web appearance for a tool (General, a coordinator, full) — the page's own stores and checks, and the
+     * page's announcement after a change (web-settings-tools.ts).
+     */
+    get webSettings(): WebSettingsTools;
     get webPrefs(): WebPrefsStore;
     /**
      * Read from disk on every access rather than cached at startup: `agend
@@ -603,9 +629,26 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     sseHeartbeatMs: number;
     /** The dashboard's login codes. Memory only: a code that outlives the process is a code nobody can prove was not copied. */
     private webLoginCodes;
+    /**
+     * #1920 step 4: guests' codes, apart from the admins' — one per account, so no guest's `/web` withdraws another's or
+     * an admin's code (#2093 review), at most 32 at once. Local sign-in only for now (audience "local").
+     */
+    private webGuestLoginCodes;
+    /** #1920 step 4: when each account last got a guest code (monotonic) — one a minute, so `/web` is no DM flood. */
+    private readonly guestCodeAskedAt;
+    /** #2093 review: an account's guest /web in progress — one at a time, so two at once cannot both pass the minute. */
+    private readonly guestCodeInFlight;
+    /**
+     * #2093 review: revokes a guest /web in progress must see — every web session's (`/web revoke` from an admin) bumps
+     * the global count, an account's own bumps its entry — checked before the code is issued and while it is delivered.
+     */
+    private guestRevokes;
+    private readonly guestAccountRevokes;
     /** #1570: browsers that may ask the sign-in page for a fresh code, and how often they may. */
     private returningDevices;
     private readonly codeRequestLimiter;
+    /** #1920 step 4b: guests' device code requests, limited apart — guests never use up the admins' fleet-wide budget. */
+    private readonly guestCodeRequestLimiter;
     /**
      * 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
@@ -651,6 +694,20 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** #1266: the choice, delivered as an ordinary inbound message from whoever made it, and shown in the web chat. */
     private deliverReplyButtonChoice;
     private ensureDeliveryOutbox;
+    /** #1918: cross-instance traffic, as the org canvas draws it (fleet-traffic.ts). */
+    private readonly trafficLog;
+    private trafficMemo;
+    /** One delivery row's traffic item, kept for the snapshot and sent to the open pages when it is news. */
+    private publishTraffic;
+    /**
+     * GET /ui/traffic: what is in flight now (the outbox's pending rows) and what finished in the last two minutes, at
+     * most TRAFFIC_SNAPSHOT_MAX items. Worked out at most once every two seconds, so the public link's polling (or any
+     * number of pages) costs one indexed read per two seconds. Visibility is applied as of now.
+     */
+    trafficSnapshot(): {
+        now: string;
+        items: TrafficItem[];
+    };
     /** Synchronous SQLite admission; the caller may acknowledge only after this returns. */
     admitDurableDelivery(input: {
         operationId: string;
@@ -704,6 +761,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private hostMemoryIndicator;
     /** Separate cooldown: changing measurements must not create new text-throttle keys. */
     private reportMemoryPressure;
+    /**
+     * #2015: rescan the largest processes (at most once a minute, one at a time). The first result of an episode, and
+     * then at most every 10 minutes, is logged with the pressure; /health and the dashboard read the latest. Never chat.
+     */
+    private refreshMemoryTop;
     /** Wire the one fleet-wide storm into notification and recovery surfaces. */
     private bindStormWindowEvents;
     /** What the gate allows while any storm window is open (see SpawnGate.pump). */
@@ -993,7 +1055,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * for `instance` (#1320 part B). Per entry: the channel's own adapter, no
      * thread, mention suppression on. Returns the number of channels posted
      * to. Failures are per-entry warn-and-continue — a failed echo never fails
-     * the web send. Entries without `web_echo: true` are never touched.
+     * the web send. Only entries classicWebEchoOn admits are touched (#2054: unset follows web.echo_to_channel; an explicit
+     * `web_echo: false` never echoes).
      *
      * Every copy is fenced at start time: an entry whose explicit world is
      * gone is skipped (only legacy adapterId-less entries fall back to the
@@ -1004,6 +1067,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * already in flight may still land late — the contract permits that.
      */
     /** `sender` (#1827): the web person's name, as the room log records them ("web-user" when none). */
+    /**
+     * #1920 §5.2: a web message's channel copy was sent — it is now what the channel saw. Kept so (and on disk), and sent
+     * to the guests' streams only: an admin's page already has it, and nothing about it changed for them.
+     */
+    webMessageInChannel(instance: string, messageId: string): void;
     sendClassicWebEcho(instance: string, text: string, sender?: string): Promise<number>;
     /**
      * #1666: a delivered web chat message starts the same cancel/progress lifecycle in the instance's topic as a platform
@@ -1359,6 +1427,20 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         handle: string;
         owner: LoginCodeOwner;
     }, current: () => boolean): Promise<void>;
+    /**
+     * #1920 §5.5 (step 4b): a guest signing in through the public link — said in the General of the admin who opened it
+     * (who, how many agents), awaited as an admin's public sign-in is, while that link is the open one, its opener still
+     * current, and the account still an admitted guest. A failure refuses the sign-in.
+     */
+    confirmGuestPublicWebLogin(info: {
+        label: string;
+        handle: string;
+        account: {
+            adapterId: string;
+            userId: string;
+        };
+        exposureId: string;
+    }, current: () => boolean): Promise<void>;
     /** Telegram's typed command enters through the same strict owner and nonce path as Discord. */
     dashboardMenu(msg: InboundMessage): Promise<void>;
     /**
@@ -1396,6 +1478,41 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         count: number;
         durable: boolean;
     };
+    /** #1920 step 4: whether a `/web` is a guest's — guest sign-in on, and not from a fleet admin (theirs runs as before). */
+    isGuestWebAsk(adapterId: string | undefined, userId: string): boolean;
+    /** #1920 step 4 (auth-api): a guest code's account may still sign in — guests on, and something in its scope now. */
+    guestSignInAllowed(account: {
+        adapterId: string;
+        userId: string;
+    }): boolean;
+    /**
+     * #1920 §5.4: a guest's own `/web revoke` — its sessions and its outstanding code; nobody else's (an admin's revokes
+     * everyone's, as before).
+     */
+    revokeGuestWebSessions(owner: {
+        adapterId: string;
+        userId: string;
+    }): {
+        count: number;
+        durable: boolean;
+    };
+    /**
+     * #1920 §2.3 (step 4): `/web` from someone who is not a fleet admin, while guest sign-in is on. `revoke` ends their
+     * own guest sessions. Otherwise a guest code (tier guest, bound to this account) goes privately — a DM, else the
+     * slash command's ephemeral answer (`replyPrivately`) — once a minute at most, and only when their scope (from what
+     * they may already use in chat, rooms read at sign-in) holds something. The code itself is never posted where asked.
+     * Callers ask isGuestWebAsk first (synchronously); false here too when it is not a guest's.
+     */
+    guestWebCommand(ask: {
+        adapterId: string;
+        userId: string;
+        username?: string;
+        arg: string;
+        replyHere: (text: string) => Promise<unknown>;
+        replyPrivately?: (text: string) => Promise<unknown>;
+    }): Promise<boolean>;
+    /** guestWebCommand's issuance, one per account at a time; a revoke made meanwhile (either kind) ends it unissued. */
+    private issueGuestCode;
     /** #1570 (auth-api): this browser becomes a returning device of the code's owner. The cookie value, or null. */
     rememberReturningDevice(owner: LoginCodeOwner, input: {
         surface: "local" | "gateway";
@@ -1421,12 +1538,31 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     } | {
         kind: "refused";
     }>;
+    /**
+     * #1920 step 4b: a guest's returning device asks for a code — a guest code for that account, by DM only, under the
+     * same rules as its /web (guests on, not an admin, something in scope now; one per account and the cap; one flow per
+     * account at a time; a revoke meanwhile ends it), its own limiter, and the guests' breaker. Asked through the public
+     * link: only while that exposure is the open one (its code then works through it alone), as an admin's device.
+     */
+    private requestGuestDeviceCode;
+    /** #1920 step 4b (auth-api): this browser becomes a guest's returning device. The cookie value, or null. */
+    rememberGuestDevice(account: {
+        adapterId: string;
+        userId: string;
+    }, input: {
+        surface: "local" | "gateway";
+        label: string;
+    }): string | null;
     /** Called by the sign-in endpoint: a login the operator did not make should be visible to them. */
     onWebLogin(info: {
         label: string;
         surface: "local" | "gateway";
         tier: string;
         handle: string;
+        owner?: {
+            adapterId: string;
+            userId: string;
+        };
     }): void;
     getDashboardAccess(): {
         ready: boolean;
@@ -1545,7 +1681,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
          *  reported separately because they differ by ~60x and only one of them can
          *  show a fleet-manager leak. */
         memory: FleetMemory;
-        hostMemory: MemoryPressureSnapshot;
+        hostMemory: MemoryPressureSnapshot & {
+            topProcesses?: MemoryHog[];
+            topProcessesAt?: string;
+        };
         problems: string[];
     };
     /** Start the primary adapter (backward-compatible, sets this.adapter) */
@@ -1697,6 +1836,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private inboundNoticeAdapter;
     private handleInboundMessageCore;
+    /**
+     * A person's platform message as the web chat shows it — the user's own words, as a user (#1306), in the instance's
+     * history (#1565). #1920 §5.2: said in the instance's topic, General or room, so it is that channel's, by that account.
+     */
+    private emitPlatformInbound;
     /** 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;
@@ -1739,6 +1883,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** On a fleet with no chat platform, the dashboard is where an instance-health prompt is posted (#1307 item 6). */
     private webOnlyPromptPlace;
     /** Resolves when the reply is in the web chat (#1770: after its files are copied); the caller need not wait. */
+    /**
+     * #1920 §5.2: whether a platform send landed in the instance's own place — its ClassicBot room, or its topic in its
+     * connection's group — so its channel's members saw it. Anything else (another chat, a DM, a context left from General,
+     * an answer without the chat it went to) is not the channel's.
+     */
+    private landedInOwnChannel;
+    /** #1920 §5.2 (#2085 review): a platform click's buttons are in the instance's own place — else not its channel's. */
+    private clickInOwnChannel;
     private afterReplyRouted;
     /**
      * #1770: a reply's files as the web chat shows them. Each is copied into the instance's web-files/ and served from
@@ -2424,6 +2576,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         key: string;
         userId: string;
         name: string;
+        guest?: true;
     }): Promise<{
         status: 200 | 400 | 403 | 409;
         error?: string;
@@ -2937,8 +3090,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private pasteRawToClassicInstance;
     /** Resolve the backend name configured for an instance (fleet or classic). */
     private backendNameForInstance;
+    /**
+     * #2072: a catalog is the account's, so a credential profile has its own. Only claude-code's probe reads an account
+     * catalog through a profile's login (its `GET /v1/models` with the profile's token); other backends' probes read the
+     * process environment, so their catalog stays the backend's own.
+     */
+    private catalogProfile;
     private cliEnvPath;
-    /** Read the cached CLI env for a backend, or null if missing/stale/unparseable. */
+    /** Read the cached CLI env for a backend (a credential profile's own, when given), or null if missing/stale/unparseable. */
     private readCliEnv;
     /** Return cached CLI versions immediately. Refresh is started after /sysinfo is sent. */
     getBackendCliVersionSnapshot(): BackendCliVersionSnapshot;
@@ -2969,6 +3128,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     };
     /** Human-readable effective model, e.g. `auto (default)`. Used by /ctx. */
     modelDisplayForInstance(instanceName: string): string;
+    /**
+     * #2072: the model an instance runs is always among its choices — one its CLI's catalog does not list (an older
+     * name, a custom provider's, a typed one) is shown first, marked, so the menu never hides what is running.
+     */
+    private withCurrentModel;
     private modelChoiceLabel;
     /** Preserve the existing cache merge rules for worker probes. */
     private persistCliEnvProbeResult;
@@ -3142,8 +3306,31 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private prospectiveCodexModel;
     /** #1811: whether a launch of `backend` here would pass a level: the same gate its builder applies. */
     private launchEffortGate;
-    /** Installed the way the launch finds a CLI (resolveBinary): on PATH or in a known install directory. */
-    private backendInstalledHere;
+    /**
+     * #2072: what this host can run, from the published availability snapshot (backend-availability.ts). Read only: a
+     * handler never starts a probe, not even in the background — launch, the timer, and /login install or sign-in do.
+     */
+    backendAvailabilityRows(): BackendAvailability[];
+    /**
+     * #2072 part 3: the models a Settings field offers for `backend` — the cached catalog (an instance's own credential
+     * profile's, when it is named and has one), claude's account catalog included. Read only: never a probe.
+     */
+    modelCatalogFor(backend: string, instance: string | null): import("./backend/types.js").ModelOption[];
+    /**
+     * #2072 (#2078 review): the snapshot as THIS instance would see it. Its sign-in on a backend is its own credential
+     * profile's when it has one there — the host's default login says nothing about it. A profile's login is a file check
+     * (credentialProfileLogin), no process.
+     */
+    backendAvailabilityFor(instanceName: string): BackendAvailability[];
+    /** The probes the snapshot runs (tests replace them: no CLI, no account, no network). */
+    availabilityProbes: AvailabilityProbes;
+    private availabilityStore;
+    private availabilityTimer;
+    get backendAvailability(): BackendAvailabilityStore;
+    /** A launch need not look the binary up again (a synchronous `which` on the loop) when the snapshot found it. */
+    private noteAvailabilityPaths;
+    /** Probe now and then every AVAILABILITY_STALE_MS; a pass that finds nothing changed starts no CLI. */
+    private startAvailabilityRefresh;
     /** The models `/model` would offer on a backend: the cached CLI env, else (live) a bounded probe. Never throws. */
     private backendModelOptions;
     /**
@@ -3188,6 +3375,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private findClassicApprovalGeneral;
     /** Return a user-facing blocker without mutating ClassicBot state. */
     private validateClassicStart;
+    /** #2072: from the published snapshot (no `which` on the loop); not checked yet counts as installed (no false alarm). */
     private isBackendInstalled;
     private getMissingBackendWarning;
     /** Handle Discord's required static slash choice, warning before a likely startup failure. */
@@ -3483,6 +3671,50 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Only the parsed host name is logged, never the raw header.
      */
     private noteRejectedHost;
+    /**
+     * #1920 §3: the instances a guest session may see — derived on every request from the account's chat access, never
+     * stored; nothing while `web.guests.enabled` is not true.
+     * - Its connection's fleet topics and General (what it may talk to in chat): when that connection's access lets the
+     *   account in (AccessManager.isAllowed — allowed_users or paired). An `open` connection lets everyone in, so it gives
+     *   only the instances an admin named for its guests (`web.guests.open_instances`; the user's decision: least
+     *   privilege, as an open group has no list of people).
+     * - A Telegram private ClassicBot room that is the account's own (its chat id is the user id).
+     * - A ClassicBot group or guild room on its connection: only while its membership is verified (§3.2 — a "member"
+     *   answer read in the background, at most 15 minutes old; unknown, failed or stale hides it).
+     * - Then an admin's narrowing (`web.guests.narrow`), which only takes away.
+     * A fleet admin is not a guest: an admin outside the connection's access gets nothing here (admins sign in as admins).
+     */
+    guestScope(owner: {
+        readonly adapterId: string;
+        readonly userId: string;
+    } | undefined): ReadonlySet<string>;
+    /**
+     * #1920 §3.5: a guest session still admitted — current, with something in scope. A scope that became empty (guest
+     * sign-in off, the account removed from the connection's access, everything narrowed away) ends the session here,
+     * so the next request and the open stream find it gone.
+     */
+    private guestStillAdmitted;
+    /**
+     * The same, with a third answer (§3.2): "pending" — nothing in scope now, but a room's membership is not read yet
+     * (a restart, a room just created). The request is refused and the session kept; its read starts in the background.
+     */
+    private guestAdmission;
+    /** #1920 §3.2: the membership answers; the read goes to the room's own connection, never waits past its deadline. */
+    private guestRooms;
+    /** #1920 §3.2: read this guest's rooms that are due (GuestRoomMembership.refresh says when each mode reads). */
+    private refreshGuestRooms;
+    /** Every account with a live guest session, one after another (the guest caps bound them); one pass at a time. */
+    private refreshAllGuestRooms;
+    private guestRoomsPass;
+    /**
+     * #1920 §3.5: guest sign-in turned off ends every guest session — checked when the configuration is read or saved
+     * and when the sessions are opened, so turning it back on never revives one.
+     */
+    private enforceGuestSwitch;
+    /** #1920 §5.2: whether this instance is the account's own Telegram private ClassicBot room (its chat id is the user id). */
+    private guestOwnRoom;
+    /** A private room's chat id is its one user's id (a group's is negative, so never equal); Telegram only. */
+    private isOwnPrivateRoom;
     /** Shared handler dispatcher; gateway admission is enforced by its separate listener. */
     private dispatchWebHttp;
     private startHealthServer;
@@ -3504,6 +3736,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     previewForUi(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
+    private previewNotListening;
     /**
      * #1723: for one page of the public link (exposure `exposureId`, at `dashboardOrigin`): its own preview tunnel's
      * origin once up, "starting" until then, why it failed if it did — or a configured web.preview_origin, used instead.