@songsid/agend 2.2.0-beta.2 → 2.2.0-beta.20

package/dist/web-api.d.ts

@@ -1,3 +1,4 @@
+import { type HumanOrigin } from "./human-delivery-receipts.js";
 import type { CachedImage } from "./web-images.js";
 import type { SettingsExecution } from "./settings-transaction.js";
 import type { PaneContextSource } from "./pane-context-cache.js";
@@ -8,6 +9,9 @@ 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 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
@@ -35,6 +39,8 @@ export interface WebApiContext {
         web?: {
             echo_to_channel?: boolean;
             usage_panel?: boolean;
+            upload_max_file_mb?: number;
+            upload_max_total_mb?: number;
         };
         defaults?: {
             backend?: string;
@@ -65,7 +71,11 @@ export interface WebApiContext {
     } | null;
     getGroupIdForInstance?(name: string): string;
     /** Reserve display ordering before IPC handoff, then settle delivery without waiting for the echo. */
-    reserveWebChannelEcho?(name: string, sendEcho: () => Promise<unknown>): (accepted: boolean) => void;
+    reserveWebChannelEcho?(name: string, sendEcho: () => Promise<unknown>, opts?: {
+        copy?: boolean;
+    }): (accepted: boolean) => void;
+    /** #1666: the cancel/progress bubble a platform inbound starts, posted in the instance's topic. */
+    startWebChatProgress?(name: string): Promise<void>;
     readonly daemons: Map<string, unknown>;
     readonly eventLog: {
         logActivity(event: string, sender: string, summary: string, receiver?: string, detail?: string): void;
@@ -97,9 +107,10 @@ export interface WebApiContext {
      * (#1320 part B). Resolves the entries and adapters itself; returns how
      * many channels were posted to. Never rejects the web send on failure.
      */
-    sendClassicWebEcho?(instance: string, text: string): Promise<number>;
+    sendClassicWebEcho?(instance: string, text: string, sender?: string): Promise<number>;
     /** 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>;
     getUiStatus(): unknown;
     /** Current owned pane reader shared with status; absent means context is unavailable. */
     getPaneContextSource?(name: string): PaneContextSource | null;
@@ -107,6 +118,8 @@ export interface WebApiContext {
     previewForUi?(hostHeader: string | undefined, secure: boolean): PreviewAvailability & {
         boot: string | null;
     };
+    /** #1723: the same for a page of the public link (exposure `exposureId`, at `dashboardOrigin`); absent: none there. */
+    publicPreviewForUi?(exposureId: string, dashboardOrigin: string): PublicPreviewForUi;
     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;
@@ -116,6 +129,8 @@ export interface WebApiContext {
     webImage?(kind: "bot" | "avatar", key: string): CachedImage | null;
     /** #1630: one Discord server emoji of the fleet's bots, from the host cache (fetched once); null for any other id. */
     webEmoji?(id: string): Promise<CachedImage | null>;
+    /** #1682: names for mention ids (only those asked; from memory, never a request); absent: no names. */
+    webMentionNames?(query: MentionQuery): MentionNames;
     /** #1630: the custom emoji of the servers the fleet's Discord bots are in. */
     webEmojiList?(): Promise<Array<{
         id: string;
@@ -124,14 +139,20 @@ export interface WebApiContext {
     }>>;
     /** Absent means SSE_HEARTBEAT_MS; a test shortens it. */
     readonly sseHeartbeatMs?: number;
+    /** #1665: the web preferences kept on the host (one bucket: the operator's); absent: /ui/prefs is not offered. */
+    readonly webPrefs?: WebPrefsStore;
     startInstance(name: string, config: unknown, topicMode: boolean): Promise<void>;
-    stopInstance(name: string): Promise<void>;
+    stopInstance(name: string): Promise<{
+        backgroundWorkEnded: boolean;
+    }>;
     /** The fleet prompts open on the dashboard (web track C4); absent: none are offered. */
     listWebPrompts?(): unknown[];
     /** #1386: everything waiting on the person, every world (the web is global). */
     needsYouItems?(): unknown[];
     /** #1389: the org chart's structure (fleet.yaml's teams, General, descriptions, thread links); absent: an empty chart. */
     orgChart?(): 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>;
     /** #1269: an instance's chat command from the web chat (web-commands.ts); absent: not offered. */
@@ -142,10 +163,25 @@ export interface WebApiContext {
         confirm?: string;
     }, opts: {
         publicLink: boolean;
+        person?: WebPerson;
     }): Promise<{
         status: number;
         body: unknown;
     }>;
+    /**
+     * #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.
+     */
+    webPerson?(owner?: WebAccount): WebPerson;
+    /** #1827: set (or, with null, clear) a person's own name; refused with a reason. */
+    setWebPersonName?(owner: WebAccount | undefined, raw: unknown): {
+        ok: true;
+        person: WebPerson;
+    } | {
+        ok: false;
+        status: number;
+        error: string;
+    };
     /** #1386: the web's Acknowledge of a delivery item; `principal` is "web:<session handle>" or "cli". */
     acknowledgeNeedsItem?(id: string, principal: string): {
         status: number;
@@ -157,9 +193,14 @@ export interface WebApiContext {
         error?: string;
     }>;
     /** #1266: a click on an agent reply's button. */
-    clickWebReplyButton?(instance: string, id: string, index: number): Promise<{
+    clickWebReplyButton?(instance: string, id: string, index: number, voter?: {
+        key: string;
+        userId: string;
+        name: string;
+    }): Promise<{
         status: number;
         error?: string;
+        options?: number[];
     }>;
     /** Interrupt the current reply and drop what was queued for it; false when the instance is not running. */
     cancelInstance?(name: string): boolean;
@@ -207,23 +248,60 @@ export interface WebApiContext {
         };
         list(target?: string): unknown[];
         create(params: unknown): unknown;
+        /** #1724: the update MCP update_schedule makes (cron and at clear each other). */
+        update?(id: string, params: Record<string, unknown>): unknown;
+        /** #1426: a pending retry of a schedule's occurrence, for the row's "retrying". */
+        getRetry?(id: string): unknown;
         delete(id: string): void;
     } | null;
 }
+/** #1827: a web person as the web chat shows them to agents and chats. */
+export interface WebPerson {
+    /** Their key in the web preferences (web-profile.ts webPersonKey): never shown. */
+    readonly key: string;
+    /** Signed in as an account (a sign-in code DMed to it), or the operator. */
+    readonly bound: boolean;
+    /** What agents see as the id: the bound account's user id on its platform (still `via web`), or "web-user". */
+    readonly userId: string;
+    /** Their poll ballot's key: the account's `<connection>:<user id>` (as on the platform), or the operator's. */
+    readonly voterKey: string;
+    /** The name in use: the one they chose, else their account's name at sign-in, else "web-user". */
+    readonly name: string;
+    /** Whether the name in use is one they chose. */
+    readonly set: boolean;
+    /** Their account's name at sign-in, made safe (bound only). */
+    readonly platformName?: string;
+}
 /**
  * Handle a Web UI request. Returns true if handled, false to pass through.
  */
 export declare function handleWebRequest(req: IncomingMessage, res: ServerResponse, url: URL, ctx: WebApiContext): boolean;
+/**
+ * #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
+ * the preview tunnel failed, why (`detail`, a fixed reason the page words).
+ */
+export type PublicPreviewForUi = PreviewAvailability & {
+    boot: string | null;
+    frameSrc: string | null;
+    detail?: string;
+};
 export interface AppShellContext {
     previewForUi?(hostHeader: string | undefined, secure: boolean): (PreviewAvailability & {
         boot: string | null;
     }) | null;
+    publicPreviewForUi?(exposureId: string, dashboardOrigin: string): PublicPreviewForUi;
     /** #1523 N3: `web.usage_panel` — the header's ◔ is offered unless it is false (the page needs no probe read for it). */
     readonly fleetConfig?: {
         web?: {
             usage_panel?: boolean;
+            log_tab?: boolean;
+            upload_max_file_mb?: number;
+            upload_max_total_mb?: number;
         };
     } | null;
+    /** #1665: the host's theme and language go into the page itself, so a device paints them before any script reads. */
+    readonly webPrefs?: WebPrefsStore;
 }
 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