@songsid/agend 2.3.3 → 2.3.4-beta.10

package/dist/fleet-manager.d.ts

@@ -4,6 +4,7 @@ import { AppIconStore } from "./web-app-icon.js";
 import { type NamedTestResult } from "./tunnel/named-link-test.js";
 import { OfficeShareService } from "./office-share-service.js";
 import { type OfficeShare } from "./office-share.js";
+import type { PageShare } from "./page-share.js";
 import type { LoginCodeOwner } from "./web-login.js";
 import { type ProfileTicket } from "./runtime-cpu-profile.js";
 import type { CpuProfile } from "./cpu-profile.js";
@@ -14,6 +15,7 @@ import type { FleetConfig, RawFleetConfig, InstanceConfig, WebVerifiedAuthorityC
 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 { type TopicDeleteOutcome } from "./instance-topic-delete.js";
 import { BackendAvailabilityStore, type AvailabilityProbes, type BackendAvailability } from "./backend-availability.js";
 import { AdapterWorld } from "./adapter-world.js";
 import { CostGuard } from "./cost-guard.js";
@@ -60,6 +62,7 @@ export declare function applyTaskListCap<T extends {
 } | T[];
 import { type PublicPreviewForUi } from "./web-api.js";
 import { type LogAnswer, type LogQuery } from "./log-service.js";
+import { type ViewHistoryAnswer, type ViewHistoryQuery } from "./view-history.js";
 import { WebChatHistory, type WebChatPost } from "./web-chat-history.js";
 import { type WebEchoCopy } from "./web-reactions.js";
 import { SeenUsers, type MentionNames, type MentionQuery } from "./web-mentions.js";
@@ -86,6 +89,7 @@ import { WebBackendLogins, type SignInTarget } from "./web-backend-login.js";
 import { BrowserBackendSignIns } from "./browser-backend-signins.js";
 import { type RawConfigPatch } from "./settings-api.js";
 import { type AgentEndpointContext } from "./agent-endpoint.js";
+import { AgentCredentials } from "./agent-credentials.js";
 import { ClassicChannelManager } from "./classic-channel-manager.js";
 import { type ExplicitInstanceRemoval } from "./instance-removal.js";
 import { type SessionOomRetry } from "./session-oom-stop.js";
@@ -100,6 +104,7 @@ 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 { WebNotices } from "./web-notices.js";
 import { VERIFIED_SESSION_HOURS, type HumanAuthority, type WebAuthorityRefusal, type WebAuthorityResult, type WebPeer } from "./authority/web-authority.js";
 import { type AuthorityState } from "./authority/authority-state.js";
 import { type SessionAuthorization } from "./authority/session-authorizations.js";
@@ -113,6 +118,7 @@ import { type CarryResult } from "./backend/claude-carry.js";
 import { StormWindow } from "./storm-window.js";
 import { SpawnGate } from "./spawn-gate.js";
 import { BackendOutageTracker } from "./backend-outage.js";
+import { OwnStatusMessages } from "./chat-log-ids.js";
 /** #2348: how a guest sign-in code's issuance ended (issueGuestCode), for Settings → Guests' Send sign-in code. */
 export type GuestCodeOutcome = {
     kind: "sent";
@@ -164,6 +170,11 @@ export interface RestartOpts {
     sessionOomRetry?: SessionOomRetry;
     /** Internal pre-invalidation owner fence for an unclear-OOM action. */
     recoveryCurrent?: () => boolean;
+    /**
+     * #1490 row 27: the lifecycle the caller acts for (lifecyclePin), asked before anything is invalidated. A button or
+     * menu offered for one instance never restarts a later one of the same name, or one restarted since.
+     */
+    ownerCurrent?: () => boolean;
     carry?: {
         backend: string;
         from: string | null;
@@ -268,6 +279,11 @@ export type GuestAuditEntry = {
     name: string;
     outcome: string;
 };
+/** #1490 row 27: a restart asked for one lifecycle of an instance after it was stopped, restarted or replaced. */
+export declare class RestartSupersededError extends Error {
+    /** `shown`: the instance as the chat list names it (shownInstanceName). */
+    constructor(shown: string);
+}
 export declare class FleetManager implements FleetContext, LifecycleContext, ArchiverContext, StatuslineWatcherContext, OutboundContext, AgentEndpointContext {
     dataDir: string;
     private static signalTarget;
@@ -435,6 +451,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private startupRetryNotices;
     /** Unsupported-CLI refusals waiting to go out, grouped by reason (#1109). */
     private unsupportedCliNotices;
+    private kiroCompatibilityHolds;
     private kiroIncompatNotices;
     /** Backoff between automatic startup retries; the last step repeats while the backend is down. */
     static readonly STARTUP_RETRY_BACKOFF_MS: number[];
@@ -462,6 +479,7 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private kiroMigrationRuns;
     /** #1386 "Needs you": the list, its live chat messages and Acknowledge. Started with the fleet (finishStartup). */
     private needsYou;
+    private missedOfflineStore;
     private configHistory;
     private configHistoryTimer;
     private loadedFleetSource;
@@ -570,11 +588,15 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private discordPresenceEagerPending;
     private discordPresenceInFlight;
     private static readonly DISCORD_PRESENCE_REFRESH_MS;
+    /** #3066 §1d: how often a fleet with no Discord bot reads the quota for its history (the user's choice: 30 min). */
+    static readonly QUOTA_BACKGROUND_READ_MS: number;
+    private quotaReadTimer;
     /** Days of event/activity history to keep. */
     private static readonly EVENT_LOG_RETENTION_DAYS;
     private watchdogTimer;
     private startupMemoryDeadline;
     private eventLoopWatch;
+    private stallReporter;
     private startedAt;
     private stormOpenNotifyTimer;
     private memoryLogAt;
@@ -615,6 +637,14 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private readonly webChatRemovals;
     /** #1774: a removal under way — its replies' fate waits for its outcome (success: theirs no more; failure: theirs). */
     private readonly webChatRemovalsPending;
+    /**
+     * #1490 row 27: "still the same lifecycle of `name`" — its lifecycle epoch, moved on synchronously by every stop,
+     * restart and removal (the map is never pruned, so a same-name replacement has a later one). Taken when a button
+     * or menu is claimed or offered, asked after every await before acting by name.
+     */
+    /** #1490 row 27: an instance as the chat list names it — its display name where it has one, else its name. */
+    private shownInstanceName;
+    private lifecyclePin;
     private webChatGeneration;
     /** #1774: who an instance's reply is from, taken when it is sent: the name's generation and its daemon then. */
     private webChatIdentity;
@@ -687,6 +717,10 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * `share` null with `count`: "Revoke all".
      */
     officeShareNotice(event: "created" | "revoked", who: string, share: OfficeShare | null, count: number): void;
+    /** #2911: the open page shares changed — the page hears it; each one handed out that ended is said in its channel. */
+    pageSharesChanged(_list: PageShare[], ended: PageShare[]): void;
+    /** #2911: a page share was made — said in the channel of the instance whose chat it came from (never its URL). */
+    pageShareNotice(who: string, share: PageShare): void;
     /** A share's owner: a person (`person:<adapter>:<user>`) still a fleet admin there; the host's own admin session stays. */
     private officeShareOwnerCurrent;
     private officeActsInstance?;
@@ -857,6 +891,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * startup-only key at startup. See checkStartupSignatureConsistency(). */
     private fleetSignatureMismatch;
     private healthServerListening;
+    private agentCredentialsCache?;
+    get agentCredentials(): AgentCredentials;
     constructor(dataDir: string);
     /** #1266: a reply's buttons — the store (reply-buttons.db) and what a click does. Created on first use. */
     private replyButtonsCtl;
@@ -1187,6 +1223,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Board 003648ac: a web /compact followed to its end, from the transcript the Log reads (none: nothing to follow). */
     private compactWatchService;
     private get compactWatch();
+    /**
+     * Claude history in the View: an instance's earlier conversation for its View, from the transcript the Log reads —
+     * the View's route applied its own access rules first (view-api.ts); the Log's switch plays no part.
+     */
+    viewHistory(name: string, q: ViewHistoryQuery): Promise<ViewHistoryAnswer | null>;
     /** #1218: GET /ui/steps — an instance's steps, read on demand (null: no such instance). */
     logSteps(name: string, q: LogQuery): Promise<LogAnswer | null>;
     /**
@@ -1560,6 +1601,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * first unattended start and every scheduled retry.
      */
     private stopOnUnsupportedCli;
+    /** No pane is needed for a compatibility refusal to remain in Needs you. */
+    setKiroCompatibilityHold(name: string, message: string | null): void;
     /**
      * LifecycleContext: a kiro instance the installed kiro-cli cannot run as
      * configured (#1109) — at start, or at a respawn after kiro-cli replaced
@@ -2017,6 +2060,35 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** Start all instances from fleet config */
     startAll(configPath: string): Promise<void>;
     private startAllWithinDeadline;
+    /**
+     * #3066 §1d (the user: yes, every 30 min): the quota history (usage/quota-history.ts) records only the readings AgEnD
+     * makes. A Discord bot's presence refresh reads every 15 min; without one, nothing reads while nobody looks. So, with no
+     * Discord bot and while some account has a running agent, read every 30 min — the same cached read (its 5-minute TTL
+     * still bounds the vendor calls), recorded like any other.
+     */
+    private startQuotaBackgroundReads;
+    /** #3066 §1: the latest estimates, by `provider\0metric` (what usage-api's lookup reads, synchronously). */
+    private capacityEstimates;
+    private capacityTimer;
+    static readonly CAPACITY_REFRESH_MS: number;
+    /**
+     * #3066 §1: estimate each account's weekly 100% from the quota history (§1d) and the usage ledger's hours — both read
+     * asynchronously, the arithmetic small (usage/capacity.ts). An account is its usage provider id ("claude",
+     * "claude:hsinlin", "codex:yanxianchen"): its hours are the ledger sources of that backend under that credential profile
+     * (Codex's "unrecorded" hours are no account's). A per-model weekly ("Sonnet (weekly)") counts only that model's tokens.
+     *
+     * Prism #3073: no estimate rather than a wrong one —
+     * - a window is measured only where the ledger has its hours: kept (31 days) and scanned (`days.coverage`) for every
+     *   instance of the account's backend, and every instance whose hours count for it; the quota history goes back 12 weeks;
+     * - a profile literally named "default", "unknown" or "unrecorded" (configured, on disk, or in the quota history) makes
+     *   those hours ambiguous: neither the host
+     *   account nor the named one is estimated (each would be credited the other's use, or lose its own);
+     * - only a metric the vendor marks per-model (`scope: "model"`) is filtered by model; another named weekly pool
+     *   ("Luna Reserve (weekly)", Antigravity pools) is no model name and is not estimated.
+     */
+    refreshCapacity(): Promise<number>;
+    /** One background quota read, when nothing else reads (no Discord bot) and an account has a running agent. */
+    backgroundQuotaRead(): Promise<boolean>;
     /** Keep Discord profile activity aligned with the same cached usage source as /usage. */
     private startDiscordUsagePresence;
     /**
@@ -2242,6 +2314,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * copies retain their permissive handling when that identity is unknown.
      */
     private isOwnerCommandCopy;
+    /** File a Telegram update that was too old to inject; Needs you lists it until Acknowledge. */
+    private recordMissedOffline;
     /**
      * #1085: coincident topic numbers must not route across Telegram groups.
      */
@@ -2289,7 +2363,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private handleOutboundFromInstance;
     /** Side effects of a routed reply: cancel-button lifecycle, logs, SSE, chat log. */
     /** No chat platform is configured at all: the web dashboard is the fleet's only surface. */
-    private isWebOnlyFleet;
+    /** #2910: no Discord or Telegram connection at all (src/web-only-fleet.ts). */
+    isWebOnlyFleet(): boolean;
     /** 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. */
@@ -2398,6 +2473,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * of the schedule response on IPC.
      */
     private performScheduleOp;
+    /**
+     * `post_decision` with `supersedes` changes a decision someone else may have recorded (it stops being active): the
+     * same permission as `update_decision`, asked through the same live check (tool set + dashboard switches), on both
+     * create paths. An empty or absent value supersedes nothing and needs nothing; anything else must be an id.
+     */
+    private decisionSupersedes;
     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>;
@@ -2413,7 +2494,41 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     private handleTaskCrud;
     /** Create a forum topic via the adapter. Returns the message_thread_id. */
     createForumTopic(topicName: string, adapterId?: string): Promise<number | string>;
-    deleteForumTopic(topicId: number | string, adapterId?: string): Promise<void>;
+    /**
+     * Delete an agent and, unless asked not to, its own chat topic (user decision: by default). The topic is planned
+     * before the removal (its id and bot go with the fleet.yaml entry) and deleted through the agent's OWN bot after it;
+     * the outcome is the platform's answer (instance-topic-delete.ts). A topic that cannot go never fails the removal.
+     */
+    removeInstanceAndTopic(name: string, authorization: ExplicitInstanceRemoval, opts: {
+        deleteTopic: boolean;
+        execution?: SettingsExecution;
+    }): Promise<TopicDeleteOutcome>;
+    /** #3055: destinations whose platform deletion is running now; a binding to one waits until it is over. */
+    private readonly topicDeletionsInFlight;
+    /** True while a topic with this id is being deleted on any connection (a new binding of it is refused meanwhile). */
+    isTopicDeletionInFlight(topicId: number | string): boolean;
+    /**
+     * #3055 review r2 (Prism P1-3): would this instance config bind a topic whose deletion is running now? Compared by
+     * physical destination, so the same thread number in another Telegram group is not held. Settings asks it at commit.
+     */
+    topicBindingInFlight(inst: {
+        channel_id?: unknown;
+        topic_id?: unknown;
+    }): boolean;
+    /** Any topic deletion running now (a connection's group or General may not be re-pointed meanwhile). */
+    topicDeletionPending(): boolean;
+    /** The physical destination of `topicId` on the bot `adapterId`. */
+    private destinationFor;
+    /** The adapter of the bot `adapterId` names — never a substitute for a bot that is not there. */
+    private instanceTopicAdapter;
+    /**
+     * Topic ownership by physical destination (#3055 review, Prism P1): an instance's topic is where its bot's platform
+     * puts it (a Telegram group + thread, a Discord channel), so two bots in one group, or two instances on one
+     * channel, are seen to share it; and every connection's own General is protected, with or without a General agent.
+     */
+    private topicOwnership;
+    /** What deleting `name`'s topic would act on: its own bot only — a bot that is not there is never substituted. */
+    private planInstanceTopicDelete;
     getForumTopicDeleter(adapterId?: string): ((topicId: number | string) => Promise<void>) | null;
     private topicCleanupTimer;
     private sessionPruneTimer;
@@ -2852,6 +2967,16 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     notifyFleetError(text: string, opts?: {
         throttle?: boolean;
     }): boolean;
+    private webNotices;
+    /** #2910 D2 (web-api): the Notices on a web-only fleet; null on any other (its General says them). */
+    webNoticesFeed(): WebNotices | null;
+    /** #2910 D2: the web-only fleet's Notices (web-notices.json), read on first use. */
+    webNoticeStore(): WebNotices | null;
+    /**
+     * #2910 D2: on a web-only fleet (no chat connection at all), keep what General or an agent's topic would have been
+     * told as a Notice, and push it to the dashboard. False on any other fleet (its chat says it; nothing is kept).
+     */
+    private recordWebNotice;
     private static readonly FLEET_ERROR_THROTTLE_MS;
     private fleetErrorNotices;
     /**
@@ -3144,6 +3269,13 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
         ok: false;
         refusal: WebAuthorityRefusal;
     };
+    /**
+     * #2910 D1 (auth-api, at sign-in): a web-only fleet's host session — signed in with the host's own code (`agend web
+     * --code`) on this computer — is the host operator, authorized from now for max_session_hours (as an account's
+     * Confirm would be), under the current epoch: a revocation ends it, and only a new sign-in on this computer gives it
+     * again. A fleet with a chat connection, another session, or another peer: nothing (§3 as before).
+     */
+    authorizeHostSession(session: SessionRecord, peer: WebPeer): void;
     private authorityStateStore;
     /**
      * #1939 §10: the switch, "Only this computer can authorize" and the revocation epoch in force for the configuration as
@@ -3382,9 +3514,11 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * Make a tool summary safe to paste into a channel message.
      *
      * The text is agent-controlled (it is built from tool inputs — file paths,
-     * shell commands), so it gets flattened to one line, capped, and stripped of
-     * the two Discord mass-mention triggers. Neither channel renders it with a
-     * parse mode, so no markup escaping is needed beyond that.
+     * shell commands), so it gets flattened to one line, secrets masked, capped,
+     * and stripped of the two Discord mass-mention triggers. Masking comes BEFORE
+     * the cap: a cap can cut a mask's context but must never be what hides (or
+     * fails to hide) a secret. Neither channel renders it with a parse mode, so no
+     * markup escaping is needed beyond that.
      */
     private static sanitizeActivity;
     /**
@@ -3424,6 +3558,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     /** Configured threshold before elapsed time appears, in ms. */
     progressMinElapsedMs(): number;
+    /** M-2391: when the instance's live (not retiring) bubble started — the current turn's start — or undefined. */
+    private liveButtonStart;
     private startProgressTicker;
     /**
      * After a reply: give the instance REPLY_RETIRE_GRACE_MS to resume working; if
@@ -3614,6 +3750,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     /** "Resend token" button (web login): only the requester may press it; the token never enters the channel. */
     private handleLoginTokenResend;
     private activeInstall;
+    /** M-2281: how long `/login`'s install window may run (a field so a smoke can shorten it). */
+    installTimeoutMs: number;
     /** An install that succeeded, between its success line and the sign-in it hands over to (#1131). */
     private installHandoff;
     /** Start a CLI install session. Caller enforces admin. */
@@ -3628,6 +3766,8 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
     }): Promise<string>;
     /** Whether this backend's CLI is on the fleet's PATH (what `/login` installs when it is not). */
     isCliInstalled(backend: string): boolean;
+    /** M-2281: isCliInstalled without holding the fleet loop (a chat click's path: `which` on a slow PATH can take seconds). */
+    isCliInstalledOffLoop(backend: string): Promise<boolean>;
     /** Abort the active install (`/login cancel`) and remove its window. */
     cancelInstallSession(): Promise<string>;
     /** `command -v` on a login shell, so PATH additions from rc files count. */
@@ -3639,12 +3779,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      */
     private locateBinaryOnLoginShell;
     /**
-     * #1092: the binary in one of the directories its own installer installs to,
-     * when no login shell can see it (the installer recorded its PATH in an
-     * interactive-only rc file). The same executable-file check as the login
-     * shell lookup; a symlink to an executable counts, as codex's launcher is one.
+     * #1092: the binary in one of the directories its own installer installs to, when no login shell can see it (the
+     * installer recorded its PATH in an interactive-only rc file) — only those directories (#1092). #3009: through
+     * backend-availability's install-directory check (the one resolveBackendBinary uses): one killable child, never
+     * accessSync/statSync on the fleet's thread. An executable file counts, a symlink to one too (codex's launcher is one).
      */
-    private locateInInstallerBinDirs;
+    private locateInstalledBackend;
     /** Put an installed binary's directory on the fleet's PATH (#1059), once. */
     private adoptBinaryDirectory;
     /** Discord native `/login` slash — shared by every adapter dispatch block. */
@@ -3759,6 +3899,22 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * text is its command path — and other sources pass through untouched.
      */
     private replyDiscordNotACommand;
+    /** #2940: this fleet's own status bubbles and the messages the platform said were deleted (ids, never text). */
+    readonly ownStatusMessages: OwnStatusMessages;
+    /**
+     * #2940: a status bubble of ours was posted: never logged, and a line already logged for it (by a sibling bot) goes.
+     * Discord only (#2943 review: the only platform where our bots see each other's posts), keyed by channel and id.
+     */
+    private noteOwnStatusMessage;
+    /** #2940: Discord says a message was deleted — its chat-log line goes, and it is never logged after this. */
+    onPlatformMessageDeleted(e: {
+        messageId?: string;
+        channelId?: string;
+    } | undefined): void;
+    /** #2940: the key a Discord message's chat-log line is kept under (none for another platform: nothing is tracked). */
+    private chatLogKey;
+    /** #2940: whether `msg` must not enter the chat log (only its key is looked at; the debug trail names keys, not text). */
+    private chatLogExcludes;
     /** Handle a message in a classic channel: log it, forward only /chat messages */
     private handleClassicChannelMessage;
     /** Download photo or document attachment to classic instance workspace inbox. Returns { path, kind } or undefined. */
@@ -3961,8 +4117,12 @@ export declare class FleetManager implements FleetContext, LifecycleContext, Arc
      * restart backends only read it at launch, so it is persisted and the
      * instance respawns.
      */
-    applyEffort(instanceName: string, requested: string): Promise<string>;
-    applyModel(instanceName: string, model: string): Promise<string>;
+    applyEffort(instanceName: string, requested: string, opts?: {
+        current?: () => boolean;
+    }): Promise<string>;
+    applyModel(instanceName: string, model: string, opts?: {
+        current?: () => boolean;
+    }): Promise<string>;
     /** Save an instance's model (fleet.yaml, or its ClassicBot channel). False when neither holds it. */
     private persistInstanceModel;
     /**