@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.11

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";
@@ -13,17 +14,16 @@ import type { LifecycleCreateArgs } from "./instance-lifecycle.js";
 import { type PreviewAvailability } from "./web-preview.js";
 import { type WebChatHistory } 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,6 +32,14 @@ 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;
     readonly dataDir: string;
@@ -41,9 +49,11 @@ 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;
         };
@@ -113,6 +123,8 @@ 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>;
@@ -120,6 +132,7 @@ export interface WebApiContext {
     /** 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;
     };
@@ -177,10 +190,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 +214,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 +278,8 @@ export interface WebApiContext {
         key: string;
         userId: string;
         name: string;
+        guest?: true;
+        authority?: HumanAuthority;
     }): Promise<{
         status: number;
         error?: string;
@@ -325,6 +382,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 +403,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