@wrongstack/webui 0.255.0 → 0.256.1

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 import { WebSocket } from 'ws';
-import { Agent, EventBus, SessionWriter, ToolRegistry, ModelsRegistry, ConfigStore, SecretVault, MemoryStore, ProviderConfig, ProviderApiKey, Context, Logger } from '@wrongstack/core';
+import { Agent, EventBus, SessionStore, ToolRegistry, ModelsRegistry, ConfigStore, SecretVault, JournalEntry, Logger, MemoryStore, ProviderConfig, ProviderApiKey, Context } from '@wrongstack/core';
 import * as http from 'node:http';
 
 interface WSServerMessage {
@@ -13,11 +13,50 @@ interface WSClientMessage {
 interface WebUIOptions {
     port?: number | undefined;
     webuiPort?: number | undefined;
+    /**
+     * Pre-built backend services. When provided, `startWebUI` skips its
+     * default agent/event-bus/session/store construction and wires the
+     * supplied instances into the WS message router and HTTP API
+     * handlers instead.
+     *
+     * Intended for callers (most notably `cli/webui-server.ts`) that
+     * already own the agent lifecycle — the CLI's `runWebUI` constructs
+     * the Agent, EventBus, SessionStore, and friends so it can run an
+     * eternal iteration against them, then hands the lot to the webui
+     * for the human-facing surface.
+     *
+     * `session` is typed as `SessionStore` (read + write) rather than
+     * the narrower `SessionWriter` because `startWebUI` needs to
+     * `load()` existing session history to project the chat view, and
+     * `list()` past sessions to populate the sessions dashboard. A
+     * `SessionWriter`-only field would force `startWebUI` to take a
+     * separate `sessionStore` for reads, which is a worse API for the
+     * CLI caller (`runWebUI` already has one store, not two).
+     *
+     * When `services` is omitted, `startWebUI` retains its existing
+     * behavior (builds the defaults in-place). This keeps the standalone
+     * `node dist/index.js webui` flow fully back-compatible.
+     */
+    services?: BackendServices | undefined;
+    /**
+     * Subscribe to live per-iteration events from the eternal-autonomy
+     * engine. When provided, `startWebUI` wires a WS broadcast that
+     * pushes each `JournalEntry` to every connected client. Observability
+     * only — starting the loop still goes through REPL/TUI or `--eternal`,
+     * since the webui has no slash-command dispatch surface yet.
+     *
+     * The argument is a *function* the caller supplies that performs the
+     * actual subscription; the returned disposer is invoked on
+     * `shutdown()`. This indirection lets the caller (most commonly
+     * `cli/webui-server.ts`) own the engine lifecycle and merely hand the
+     * webui an observer slot.
+     */
+    subscribeEternalIteration?: ((fn: (entry: JournalEntry) => void) => () => void) | undefined;
 }
 interface BackendServices {
     agent: Agent;
     events: EventBus;
-    session: SessionWriter;
+    session: SessionStore;
     toolRegistry: ToolRegistry;
     modelsRegistry: ModelsRegistry;
     configStore: ConfigStore;
@@ -49,6 +88,20 @@ interface CreateHttpServerOptions {
      * cross-process SessionRegistry.
      */
     globalRoot?: string | undefined;
+    /**
+     * Shared auth token for `/api/*` endpoints. Required for non-loopback
+     * binds (LAN exposure). Loopback binds accept any local origin without
+     * a token (the WS path's loopback-bootstrap policy — see ws-auth.ts).
+     */
+    apiToken?: string | undefined;
+    /**
+     * If true, the `/ws-auth` endpoint exchanges a `?token=` query param (or
+     * `X-WS-Token` header) for an `HttpOnly` auth cookie. The cookie is then
+     * sent automatically on the WS upgrade, closing the C-598 query-string
+     * token exposure class. Default: true. Set to false to keep the legacy
+     * URL-token-only flow (e.g. in tests that don't want cookie state).
+     */
+    enableWsCookie?: boolean | undefined;
 }
 /**
  * Inject the live WS port into the served HTML so the frontend connects to
@@ -116,6 +169,49 @@ declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): {
  *  process so it survives kill/killAll. Never throws. */
 declare function openBrowser(url: string, platform?: NodeJS.Platform): void;
 
+/**
+ * Per-section context-window token estimate for the `context.debug` command.
+ *
+ * Uses the simple 4-chars-per-token heuristic — not exact, but close enough to
+ * spot which section (system prompt, tool schemas, or message history) is
+ * eating the context window. Tool schemas in particular are easy to overlook:
+ * each tool ships its full JSON schema to the model every turn, so 20+ builtins
+ * can cost 10-20k tokens on their own.
+ *
+ * Extracted from `index.ts` as a pure function so the breakdown maths can be
+ * unit tested without standing up a Context/ToolRegistry.
+ */
+/** 4-chars-per-token heuristic estimate for a string. */
+declare function estimateTokens(s: string): number;
+/** Stringify arbitrary content for length estimation (JSON, with fallbacks). */
+declare function stringifyContent(c: unknown): string;
+interface ToolTokenEntry {
+    name: string;
+    tokens: number;
+}
+interface MessageTokenEntry {
+    index: number;
+    role: string;
+    tokens: number;
+    preview: string;
+}
+interface ContextBreakdown {
+    total: number;
+    systemPrompt: number;
+    tools: {
+        total: number;
+        count: number;
+        breakdown: ToolTokenEntry[];
+    };
+    messages: {
+        total: number;
+        count: number;
+        breakdown: MessageTokenEntry[];
+    };
+}
+declare function messageTokens(content: unknown): number;
+declare function messagePreview(content: unknown): string;
+
 /**
  * Running-instance registry for the standalone WebUI server.
  *
@@ -172,6 +268,25 @@ declare function listInstances(baseDir?: string): Promise<WebUIInstanceRecord[]>
 /** Human-readable table of running instances for `webui --list`. */
 declare function formatInstances(instances: WebUIInstanceRecord[]): string;
 
+type EternalSubscribe = (fn: (entry: JournalEntry) => void) => () => void;
+type EternalBroadcast<C> = (clients: Map<WebSocket, C>, msg: WSServerMessage) => void;
+interface EternalSubscription {
+    /** Tear down the underlying engine subscription. Idempotent. */
+    dispose: () => void;
+}
+declare function createEternalSubscription<C>(subscribe: EternalSubscribe, broadcast: EternalBroadcast<C>, clientsRef: () => Map<WebSocket, C>): EternalSubscription;
+
+type ShellOpenTarget = 'terminal' | 'file-manager';
+interface ShellOpenRequest {
+    path: string;
+    target: ShellOpenTarget;
+}
+interface ShellOpenResult {
+    success: boolean;
+    message: string;
+}
+declare function handleShellOpen(req: ShellOpenRequest, logger: Logger): Promise<ShellOpenResult>;
+
 /**
  * Send a JSON message to a single WebSocket client.
  * No-op when the socket is not in OPEN state (disconnected / closing).
@@ -342,6 +457,9 @@ interface VerifyClientInput {
     hostHeader?: string | undefined;
     /** Peer address (`req.socket.remoteAddress`). */
     remoteAddress?: string | undefined;
+    /** `Cookie` header (`req.headers.cookie`). Carries `ws_token=…` when the
+     *  browser went through `/ws-auth` to set the HttpOnly auth cookie. */
+    cookieHeader?: string | string[] | undefined;
     /** Host/interface the WS server is bound to. */
     wsHost: string;
     /** The server's generated auth token. */
@@ -351,6 +469,15 @@ interface VerifyClientInput {
  * Decide whether to accept an incoming WebSocket handshake. Pure mirror of the
  * closure previously inlined in `index.ts`; see the module doc for the layered
  * policy. Returns `true` to accept, `false` to reject.
+ *
+ * Token sources, in priority order:
+ *  1. `Cookie: ws_token=…` (browser clients that went through `/ws-auth`)
+ *  2. `?token=…` URL query param (non-browser clients: curl, scripts)
+ *
+ * Browser clients (with an `Origin` header) are restricted to the cookie path —
+ * URL token is rejected for them, closing the C-598 query-string token
+ * exposure class. Non-browser clients keep the URL-token fallback so curl
+ * and tests continue to work.
  */
 declare function verifyClient(input: VerifyClientInput): boolean;
 
@@ -480,10 +607,10 @@ declare class AutoPhaseWebSocketHandler {
     private send;
 }
 
-declare function startWebUI(opts?: {
+declare function startWebUI(opts?: WebUIOptions & {
     wsPort?: number | undefined;
     wsHost?: string | undefined;
     open?: boolean | undefined;
 }): Promise<void>;
 
-export { AutoPhaseWebSocketHandler, type BackendServices, type ConnectedClient, type CustomContextMode, type CustomModeStore, type KeyOpResult, type ProvidersRecord, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, addProvider, broadcast, browserOpenCommand, buildCspHeader, createCustomModeStore, createHttpServer, createProviderConfigIO, defaultBaseDir, deleteKey, errMessage, extractToken, findFreePort, formatInstances, generateAuthToken, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleMemoryForget, handleMemoryList, handleMemoryRemember, hostHeaderOk, injectWsPort, isLoopbackBind, isLoopbackHostname, isPortFree, listInstances, loadSavedProviders, maskedKey, normalizeKeys, openBrowser, registerInstance, registryPath, removeProvider, saveProviders, send, sendResult, setActiveKey, startWebUI, tokenMatches, unregisterInstance, upsertKey, verifyClient, writeKeysBack };
+export { AutoPhaseWebSocketHandler, type BackendServices, type ConnectedClient, type ContextBreakdown, type CreateHttpServerOptions, type CustomContextMode, type CustomModeStore, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, type KeyOpResult, type MessageTokenEntry, type ProvidersRecord, type ShellOpenRequest, type ShellOpenResult, type ShellOpenTarget, type ToolTokenEntry, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, addProvider, broadcast, browserOpenCommand, buildCspHeader, createCustomModeStore, createEternalSubscription, createHttpServer, createProviderConfigIO, defaultBaseDir, deleteKey, errMessage, estimateTokens, extractToken, findFreePort, formatInstances, generateAuthToken, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleMemoryForget, handleMemoryList, handleMemoryRemember, handleShellOpen, hostHeaderOk, injectWsPort, isLoopbackBind, isLoopbackHostname, isPortFree, listInstances, loadSavedProviders, maskedKey, messagePreview, messageTokens, normalizeKeys, openBrowser, registerInstance, registryPath, removeProvider, saveProviders, send, sendResult, setActiveKey, startWebUI, stringifyContent, tokenMatches, unregisterInstance, upsertKey, verifyClient, writeKeysBack };