@songsid/agend 2.3.0-beta.3 → 2.3.0-beta.5

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";
@@ -89,6 +90,8 @@ 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 SessionRecord } from "./web-session.js";
+import { type HumanAuthority, type WebAuthorityResult, type WebPeer } from "./authority/web-authority.js";
 import { type ReturningDevice } from "./web-returning-device.js";
 import { type PreviewAvailability } from "./web-preview.js";
 import { type ConnectionMetadata, type ConnectionBinding, type BindingProbe, type SecretApplyJob, type ProviderSecretApplyJob } from "./connection-secrets.js";
@@ -465,6 +468,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;
@@ -625,9 +631,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
@@ -1046,6 +1069,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
@@ -1401,6 +1429,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>;
     /**
@@ -1438,6 +1480,77 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         count: number;
         durable: boolean;
     };
+    /**
+     * #1920 phase 3: Settings → Web sign-ins → Guests — the switches, each connection's access mode and the agents named for
+     * an open one, and every guest account (signed in, with a returning device, or narrowed): who, its platform, what it
+     * reaches now, its sessions and devices, and its narrowing. Ids are the accounts' own (an admin's page).
+     */
+    guestOverview(): {
+        enabled: boolean;
+        chat: boolean;
+        instances: string[];
+        connections: Array<{
+            id: string;
+            type: string;
+            mode: "open" | "allowlist";
+            named: string[];
+        }>;
+        guests: Array<{
+            adapterId: string;
+            userId: string;
+            name: string;
+            platform: string;
+            scope: string[];
+            reach: string[];
+            sessions: number;
+            lastSeen: number | null;
+            devices: number;
+            narrow: string[] | null;
+        }>;
+    };
+    /** #1920 phase 3 (the app shell): a guest's chip — its web name, and its connection's platform (discord, telegram). */
+    guestBadge(owner: {
+        adapterId: string;
+        userId: string;
+    }): {
+        name: string;
+        platform: string;
+    };
+    /** #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";
@@ -1463,12 +1576,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;
@@ -1742,6 +1874,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;
@@ -1784,6 +1921,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
@@ -2469,6 +2614,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         key: string;
         userId: string;
         name: string;
+        guest?: true;
+        authority?: HumanAuthority;
     }): Promise<{
         status: 200 | 400 | 403 | 409;
         error?: string;
@@ -2506,6 +2653,16 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private readonly webBackendTokens;
     /** #1269: the web's /clear confirmations — one token per question, used once, for the instance as it was asked about. */
     private readonly webClearTokens;
+    /**
+     * #1939 S1: the design's §3 for one web request (authority/web-authority.ts), with this fleet's admins, policy and
+     * token; `instance` once the body has named it. Observe only: receipts record it, no agent acts on it yet.
+     */
+    webAuthority(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+        instance?: string;
+    }): WebAuthorityResult;
     /** #1269: an instance's chat command from the web chat (web-commands.ts); `publicLink`: a gateway request. */
     webCommand(input: {
         instance: string;
@@ -2515,6 +2672,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     }, opts: {
         publicLink: boolean;
         person?: Pick<WebPersonView, "userId" | "name">;
+        authority?: HumanAuthority;
     }): Promise<WebCommandResult>;
     /** Consume `/clear` Confirm/Cancel exactly once; only Confirm reaches IPC. */
     private handleClearConfirmation;
@@ -3198,8 +3356,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;
     /**
@@ -3244,6 +3425,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. */
@@ -3540,13 +3722,55 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private noteRejectedHost;
     /**
-     * #1920: the instances a guest session may see — derived on every request, never stored. Phase 2 derives it from
-     * the account's chat access (and an admin's naming for an open connection); until then a guest sees nothing.
-     */
-    guestScope(_owner: {
+     * #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 (#2104 review): what an account reaches before an admin's narrowing — its connection's topics (an open one's
+     * named agents), its own Telegram private room, its verified group rooms. Narrowing can only take from this set, so it
+     * is what Settings offers to narrow to. Empty while guest sign-in is off.
+     */
+    private guestReach;
+    /**
+     * #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;