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

package/dist/web-api.d.ts

@@ -1,4 +1,5 @@
 import { type HumanOrigin } from "./human-delivery-receipts.js";
+import { type HumanAuthority, type WebAuthorityResult, type WebPeer } from "./authority/web-authority.js";
 import type { CachedImage } from "./web-images.js";
 import type { SettingsExecution } from "./settings-transaction.js";
 import type { PaneContextSource } from "./pane-context-cache.js";
@@ -10,20 +11,20 @@ import type { WebAppearance } from "./web-appearance.js";
 import type { SendOpts } from "./channel/types.js";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { LifecycleCreateArgs } from "./instance-lifecycle.js";
+import { type Actor as BoardActor, type TaskBoard } from "./scheduler/task-board.js";
 import { type PreviewAvailability } from "./web-preview.js";
-import { type WebChatHistory } from "./web-chat-history.js";
+import { type WebChatHistory, type WebChatMessage } from "./web-chat-history.js";
 import { type WebFileLedger } from "./web-upload.js";
-import type { WebSessionStore } from "./web-session.js";
+import type { WebSessionStore, SessionRecord } from "./web-session.js";
 import { type WebPrefsStore } from "./web-prefs.js";
 import { type WebAccount } from "./web-profile.js";
 import { type MentionNames, type MentionQuery } from "./web-mentions.js";
 import type { ExplicitInstanceRemoval } from "./instance-removal.js";
 /**
- * Push a single SSE frame to every client. If a client throws (closed socket
- * after a network drop, etc.), evict it from the set and continue — without
- * the eviction the dead entry leaks forever, and without the try/catch a
- * single dead client breaks delivery to every client iterated after it.
+ * #1920 §5.2: one event for the guests' streams only, each as projected for it — a message that has just become what
+ * its channel saw (an admin's page already has it, unchanged).
  */
+export declare function broadcastToGuests(clients: Set<ServerResponse>, event: string, data: unknown, onError?: (err: unknown) => void): void;
 export declare function broadcastSseEvent(clients: Set<ServerResponse>, event: string, data: unknown, onError?: (err: unknown) => void, id?: string): void;
 /** One SSE frame; `id` (a chat message's) lets a reconnecting EventSource say what it last saw. */
 export declare function sseFrame(event: string, data: unknown, id?: string): string;
@@ -32,8 +33,20 @@ export declare const SSE_HEARTBEAT_MS = 10000;
 /** Minimal interface — only what web-api needs from FleetManager. */
 export interface WebApiContext {
     readonly webToken: string | null;
+    /** #2072: what this host can run (the published snapshot); absent in a hand-built context. */
+    backendAvailabilityRows?(): import("./backend-availability.js").BackendAvailability[];
+    /** #2072: a backend's cached model catalog, for an instance's own account when one is named; never a probe. */
+    modelCatalogFor?(backend: string, instance: string | null): Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
     /** Absent in a hand-built context: cookies are then simply not a credential, the header token still is. */
     readonly webSessions?: WebSessionStore | null;
+    /** #2233: dashboard-started backend sign-ins (FleetManager); absent in a hand-built context. */
+    readonly webBackendLogins?: import("./web-backend-login.js").WebBackendLogins;
+    /** #2233: Settings → Agents' sign-in list (FleetManager.backendSignInTargets). */
+    backendSignInTargets?(): import("./web-backend-login.js").SignInTarget[];
     readonly dataDir: string;
     readonly sseClients: Set<ServerResponse>;
     readonly fleetConfig: {
@@ -41,11 +54,16 @@ export interface WebApiContext {
             group_id?: number | string;
             mode?: string;
         };
+        health_port?: number;
         web?: {
             echo_to_channel?: boolean;
             usage_panel?: boolean;
+            usage_report_on_public_link?: boolean;
             upload_max_file_mb?: number;
             upload_max_total_mb?: number;
+            search?: {
+                enabled?: boolean;
+            };
         };
         defaults?: {
             backend?: string;
@@ -113,13 +131,20 @@ export interface WebApiContext {
      * many channels were posted to. Never rejects the web send on failure.
      */
     sendClassicWebEcho?(instance: string, text: string, sender?: string): Promise<number>;
+    /** #1920 §5.2: a web message's channel copy was sent — guests of that channel may see it now. */
+    webMessageInChannel?(instance: string, messageId: string): void;
     /** false: definitely not delivered (the instance's IPC is gone, or it was restarted meanwhile). */
-    deliverToInstance(instanceName: string, payload: Record<string, unknown>): Promise<boolean | void>;
-    deliverHumanToInstance?(instanceName: string, payload: Record<string, unknown>, origin: HumanOrigin, originalBody: string): Promise<boolean | void>;
+    deliverToInstance(instanceName: string, payload: Record<string, unknown>, options?: {
+        stillCurrent?: () => boolean;
+    }): Promise<boolean | void>;
+    deliverHumanToInstance?(instanceName: string, payload: Record<string, unknown>, origin: HumanOrigin, originalBody: string, options?: {
+        stillCurrent?: () => boolean;
+    }): Promise<boolean | void>;
     getUiStatus(): unknown;
     /** Current owned pane reader shared with status; absent means context is unavailable. */
     getPaneContextSource?(name: string): PaneContextSource | null;
     /** #1306: which preview origin this /ui load may frame (Host and the TLS signal only); absent: previews off. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
@@ -128,6 +153,10 @@ export interface WebApiContext {
     emitSseEvent(event: string, data: unknown): void;
     /** The web chat's recent messages (history + SSE replay); absent in contexts that have no chat. */
     readonly webChatHistory?: WebChatHistory;
+    /** #2293: the global search index (null or absent: off — web.search.enabled false — or not started). */
+    readonly searchIndex?: Pick<import("./search/search-index.js").SearchIndex, "query" | "context" | "status"> | null;
+    /** #2293: whose cross-instance messages search leaves out now (cross_instance_visibility "hidden"; see searchVisibility). */
+    searchVisibility?(): import("./search/search-docs.js").XmsgVisibility;
     /** Uploads and the files the dashboard may fetch back (web track C2); absent: no file routes. */
     readonly webFiles?: WebFileLedger;
     /** #1630: a cached avatar (an own bot's, or the picture uploaded in View) — never a fetch; null when there is none. */
@@ -177,10 +206,21 @@ export interface WebApiContext {
     needsYouItems?(): unknown[];
     /** #1389: the org chart's structure (fleet.yaml's teams, General, descriptions, thread links); absent: an empty chart. */
     orgChart?(): unknown;
+    /** #1918: in-flight and recently finished cross-instance traffic, bounded (fleet-traffic.ts). */
+    trafficSnapshot?(): {
+        now: string;
+        items: unknown[];
+        delegations?: unknown[];
+    };
     /** #1218: an instance's Log steps, read on demand (null: no such instance; `{ enabled: false }`: the Log is off). */
     logSteps?(name: string, q: import("./log-service.js").LogQuery): Promise<unknown>;
     /** #1468: the prompt-cache expiry analysis for a window ("24h" | "7d" | "30d"); absent: not offered. */
     cacheReport?(window: string): Promise<unknown>;
+    /** #2122: the usage report (Fleet → Usage); absent: not offered. */
+    usageReport?(params: {
+        range: import("./usage-report.js").UsageRange;
+        group: import("./usage-report.js").UsageGroup;
+    }): Promise<unknown>;
     /** #1269: an instance's chat command from the web chat (web-commands.ts); absent: not offered. */
     webCommand?(input: {
         instance: string;
@@ -190,10 +230,41 @@ export interface WebApiContext {
     }, opts: {
         publicLink: boolean;
         person?: WebPerson;
+        authority?: HumanAuthority;
     }): Promise<{
         status: number;
         body: unknown;
     }>;
+    /** #1939 S2b: "Authorize this browser" — the Confirm card in the account's DM; and what the app shows for this browser. */
+    requestSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): Promise<{
+        ok: true;
+        expiresInMs: number;
+    } | {
+        ok: false;
+        refusal: string;
+        retryAfterMs?: number;
+    }>;
+    webSessionAuthorization?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+    }): {
+        state: string;
+        until?: number;
+        expiresInMs?: number;
+        reason?: string;
+    };
+    /** #1939 S1: the design's §3 for one request (`instance` once the body names it); absent: web carries no authority. */
+    webAuthority?(input: {
+        session: SessionRecord | null;
+        gateway: boolean;
+        peer: WebPeer;
+        instance?: string;
+    }): WebAuthorityResult;
     /**
      * #1827: a web person — for the account a session is bound to (none: the operator) — as agents and chats see them.
      * Absent: everyone is "web-user", as before.
@@ -223,6 +294,8 @@ export interface WebApiContext {
         key: string;
         userId: string;
         name: string;
+        guest?: true;
+        authority?: HumanAuthority;
     }): Promise<{
         status: number;
         error?: string;
@@ -267,10 +340,12 @@ export interface WebApiContext {
                 priority?: string;
                 assignee?: string;
                 created_by: string;
-            }): unknown;
-            updateTask(id: string, params: Record<string, unknown>): unknown;
-            claimTask(id: string, assignee: string): unknown;
-            completeTask(id: string, result?: string): unknown;
+            }, by?: BoardActor): unknown;
+            updateTask(id: string, params: Record<string, unknown>, by?: BoardActor): unknown;
+            claimTask(id: string, assignee: string, by?: BoardActor): unknown;
+            completeTask(id: string, result?: string, by?: BoardActor): unknown;
+            /** The task board on the same table (scheduler/task-board.ts); absent in a hand-built context. */
+            board?: TaskBoard;
         };
         list(target?: string): unknown[];
         create(params: unknown): unknown;
@@ -310,10 +385,12 @@ export interface WebPerson {
     /** Their account's name at sign-in, made safe (bound only). */
     readonly platformName?: string;
 }
+export declare function handleWebRequest(req: IncomingMessage, res: ServerResponse, url: URL, ctx: WebApiContext): boolean;
 /**
- * Handle a Web UI request. Returns true if handled, false to pass through.
+ * #2272: the line a web reply's channel copy opens with — the quoted sender and first words when that message reached
+ * the channel (its members saw it); a web-only one is only named, never copied out to the channel.
  */
-export declare function handleWebRequest(req: IncomingMessage, res: ServerResponse, url: URL, ctx: WebApiContext): boolean;
+export declare function webReplyEchoLine(quoted: WebChatMessage): string;
 /**
  * #1723: a public-link page's preview: where it may frame from (`frameSrc` — the quick-tunnel wildcard while its own
  * preview tunnel is starting or up, the exact origin for a configured web.preview_origin, null for none) and, once
@@ -325,6 +402,8 @@ export type PublicPreviewForUi = PreviewAvailability & {
     detail?: string;
 };
 export interface AppShellContext {
+    /** #2118: independent trusted opaque effect document, never HTML-preview consent or listener state. */
+    readonly effectBoot?: string;
     previewForUi?(hostHeader: string | undefined, secure: boolean): (PreviewAvailability & {
         boot: string | null;
     }) | null;
@@ -344,6 +423,11 @@ export interface AppShellContext {
     readonly ownerCss?: OwnerCssStore;
     readonly webToken?: string | null;
     readonly webSessions?: WebApiContext["webSessions"];
+    /** #1920 phase 3: a guest's page says who it is signed in as (its web name and platform), for its "Guest" chip. */
+    guestBadge?(owner: WebAccount): {
+        name: string;
+        platform: string;
+    };
 }
 export type AppShellMode = "full" | "view-only";
 /** The app shell page for one entry, under the panels' CSP; it may frame exactly <preview origin>/frame, and only