@wrongstack/webui 0.273.1 → 0.274.0

package/dist/server/index.d.ts

@@ -13,8 +13,23 @@ interface WSClientMessage {
     payload?: unknown | undefined;
 }
 interface WebUIOptions {
+    /** HTTP frontend port. Prefer `httpPort`; `port` is kept for compatibility. */
     port?: number | undefined;
+    /** HTTP frontend port. */
+    httpPort?: number | undefined;
     webuiPort?: number | undefined;
+    /** WebSocket backend port. */
+    wsPort?: number | undefined;
+    /** Host/interface to bind. */
+    wsHost?: string | undefined;
+    /** Fixed access token/password. Defaults to WEBUI_TOKEN or random per process. */
+    accessToken?: string | undefined;
+    /** Browser-facing HTTP URL, used in startup output and instance registry. */
+    publicUrl?: string | undefined;
+    /** Browser-facing WebSocket URL, injected into the frontend for tunnels/proxies. */
+    publicWsUrl?: string | undefined;
+    /** Force token/password protection even on loopback binds. */
+    requireToken?: boolean | undefined;
     /**
      * Pre-built backend services. When provided, `startWebUI` skips its
      * default agent/event-bus/session/store construction and wires the
@@ -103,6 +118,11 @@ interface CreateHttpServerOptions {
      * is allowed to open a WebSocket back to the local server.
      */
     wsPort: number;
+    /**
+     * Public WebSocket URL injected into the frontend. Use this behind tunnels or
+     * reverse proxies where the browser-facing WS URL differs from host:wsPort.
+     */
+    publicWsUrl?: string | undefined;
     /**
      * Path to the global WrongStack root (~/.wrongstack). Used by the
      * /api/sessions and /api/sessions/:id/agents endpoints to read the
@@ -110,11 +130,13 @@ interface CreateHttpServerOptions {
      */
     globalRoot?: string | undefined;
     /**
-     * Shared auth token for `/api/*` endpoints. Required for non-loopback
-     * binds (LAN exposure). Loopback binds accept any local origin without
+     * Shared auth token for HTTP and WS access. Required for non-loopback
+     * binds (LAN exposure). Loopback binds accept local browser access without
      * a token (the WS path's loopback-bootstrap policy — see ws-auth.ts).
      */
     apiToken?: string | undefined;
+    /** Force HTTP token auth even on loopback binds, useful behind public tunnels. */
+    requireToken?: boolean | 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
@@ -149,7 +171,7 @@ interface CreateHttpServerOptions {
  */
 declare function injectWsPort(html: string, wsPort: number): string;
 /** Build the Content-Security-Policy value for the given WS port. */
-declare function buildCspHeader(wsPort: number): string;
+declare function buildCspHeader(wsPort: number, requestHost?: string | undefined, publicWsUrl?: string | undefined): string;
 /**
  * Create the static-file HTTP server. Returns the `http.Server` (not
  * listening yet) so the caller can attach to a `shutdown()` hook and
@@ -277,7 +299,7 @@ declare function messagePreview(content: unknown): string;
 /**
  * Running-instance registry for the standalone WebUI server.
  *
- * Every live `webui` process records itself in a single JSON file under the
+ * Every live `wstackui` process records itself in a single JSON file under the
  * wstack home dir (`~/.wrongstack/webui-instances.json`) so a user running
  * several instances (one per project, or several per project on different
  * ports) can see at a glance which ports are open for which path.
@@ -327,7 +349,7 @@ declare function registerInstance(record: WebUIInstanceRecord, baseDir?: string)
 declare function unregisterInstance(pid: number, baseDir?: string): Promise<void>;
 /** List live instances, pruning any dead entries encountered. */
 declare function listInstances(baseDir?: string): Promise<WebUIInstanceRecord[]>;
-/** Human-readable table of running instances for `webui --list`. */
+/** Human-readable table of running instances for `wstackui --list`. */
 declare function formatInstances(instances: WebUIInstanceRecord[]): string;
 
 type EternalSubscribe = (fn: (entry: JournalEntry) => void) => () => void;
@@ -374,6 +396,16 @@ declare function errMessage(err: unknown): string;
  * Shared between standalone and CLI-embedded WebUI servers.
  */
 declare function generateAuthToken(): string;
+declare function resolveAuthToken(explicit?: string | undefined): string;
+declare function hostForBrowserUrl(bindHost: string): string;
+declare function buildWebUIAccessUrl(opts: {
+    host: string;
+    port: number;
+    token?: string | undefined;
+    protocol?: 'http' | 'https' | undefined;
+    publicUrl?: string | undefined;
+}): string;
+declare function envFlag(name: string): boolean;
 
 /**
  * Shared file-operation WebSocket handlers for both the standalone WebUI
@@ -525,7 +557,7 @@ declare function handleMemoryForget(ws: WebSocket, msg: unknown, memoryStore: Me
 
 /**
  * MCP management handlers for the WebUI server (both the standalone
- * `wrongstack webui` server and the CLI's embedded `--webui` server).
+ * `wstackui` server and the CLI's embedded `--webui` server).
  *
  * These are thin WebSocket translators over the shared, surface-agnostic
  * management core in `@wrongstack/mcp` (`manage.ts`) — the SAME core the REPL
@@ -620,6 +652,7 @@ declare function extractToken(url: string): string | undefined;
 declare function hostHeaderOk(input: {
     hostHeader: string | undefined;
     wsHost: string;
+    allowedHostnames?: readonly string[] | undefined;
 }): boolean;
 interface VerifyClientInput {
     /** Browser `Origin` header, or undefined for non-browser clients. */
@@ -637,6 +670,12 @@ interface VerifyClientInput {
     wsHost: string;
     /** The server's generated auth token. */
     expectedToken: string;
+    /** Force token auth even for loopback binds, useful behind public tunnels. */
+    requireToken?: boolean | undefined;
+    /** Extra Host header names allowed on loopback binds, e.g. a tunnel hostname. */
+    allowedHostnames?: readonly string[] | undefined;
+    /** Allow browser WS URL tokens for explicit public WS URLs where cookies cannot cross hostnames. */
+    allowBrowserUrlToken?: boolean | undefined;
 }
 /**
  * Decide whether to accept an incoming WebSocket handshake. Pure mirror of the
@@ -759,19 +798,49 @@ declare class AutoPhaseWebSocketHandler {
     private store;
     private clients;
     private broadcastInterval;
-    /** Aborts in-flight task agents when the run is stopped. */
+    /** Aborts in-flight task agents AND the planning turn when the run is stopped. */
     private abort;
+    /** Set the instant a stop/clear/revert is requested, so a planning turn that
+     *  resolves afterwards never launches the orchestrator (the abort alone can't
+     *  cover the window between the LLM call resolving and the orchestrator start). */
+    private stopping;
     /** Optional per-phase git-worktree isolation (lazily created at start). */
     private worktrees;
+    /** Base branch + tip SHA captured at run start so a revert can git-revert the
+     *  run's squash commits (history-preserving) instead of a destructive reset. */
+    private runBase;
     /** Per-run worker identities so the board can show "who is on what". */
     private usedNicknames;
     constructor(agent: Agent, context: Context, logger: Logger, storeDir: string, events?: EventBus | undefined, projectRoot?: string | undefined);
     addClient(ws: WebSocket): void;
     handleMessage(msg: AutoPhaseWSMessage): Promise<void>;
     private handleStart;
+    /**
+     * Halt the run NOW — at any phase. Sets `stopping` (so a planning turn that
+     * resolves afterwards bails), aborts in-flight agents, stops the orchestrator
+     * tick, and ends the live broadcast. The board is kept for review; use
+     * `autophase.clear` to reset or `autophase.revert` to undo the changes.
+     */
+    private handleStop;
+    /**
+     * Stop + wipe: tear down phase worktrees and reset to an empty board so the UI
+     * returns to the start screen ("new one"). Does NOT touch already-merged commits
+     * on the base branch — that is `autophase.revert`.
+     */
+    private handleClear;
+    /**
+     * Stop + undo: remove phase worktrees, then history-preservingly `git revert`
+     * every commit this run landed on the base branch (captured `runBase`..HEAD),
+     * then reset to an empty board. Refuses (reports a reason) on a dirty tree or a
+     * conflicting revert rather than leaving the tree half-reverted.
+     */
+    private handleRevert;
     /** Generic fallback phases when the LLM planner produces nothing usable. */
     private defaultPhases;
-    /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure. */
+    /** Plan phases+todos for the goal via the LLM; fall back to defaults on failure.
+     *  The caller passes the run's abort signal so a stop during planning cancels
+     *  the LLM turn (the previous fresh, never-aborted controller made planning
+     *  uninterruptible). */
     private planPhases;
     private executeTaskWithAgent;
     /** Persist + broadcast after an interactive board mutation. */
@@ -883,6 +952,8 @@ interface SddWizardDeps {
         defaultModel?: string | undefined;
         defaultProvider?: string | undefined;
         fallbackModels?: string[] | undefined;
+        /** Per-run worktree-isolation override; undefined → env default. */
+        worktrees?: boolean | undefined;
     }) => Promise<{
         runId: string;
     }>;
@@ -937,12 +1008,6 @@ interface SddWizardWiringOptions {
         projectDir: string;
     };
 }
-/**
- * Build the {@link SddWizardDeps} shared by both webui servers from a single
- * per-task `subagentFactory`. The factory drives BOTH the interview agent (an
- * isolated turn off the main chat bus) and the real multi-agent run, so each
- * server only has to supply the right factory for its process.
- */
 declare function buildSddWizardDeps(opts: SddWizardWiringOptions): SddWizardDeps;
 
 /**
@@ -1013,7 +1078,12 @@ declare function handleSkillsExport(ws: WebSocket, ctx: SkillsContext): Promise<
 declare function startWebUI(opts?: WebUIOptions & {
     wsPort?: number | undefined;
     wsHost?: string | undefined;
+    httpPort?: number | undefined;
+    accessToken?: string | undefined;
+    publicUrl?: string | undefined;
+    publicWsUrl?: string | undefined;
+    requireToken?: boolean | undefined;
     open?: boolean | undefined;
 }): Promise<void>;
 
-export { AutoPhaseWebSocketHandler, type BackendServices, type CompletionHandlerOptions, type CompletionItemKind, type CompletionSuggestion, type ConnectedClient, type ContextBreakdown, type CreateHttpServerOptions, type CustomContextMode, type CustomModeStore, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, type KeyOpResult, type LspCompletionSource, type LspCompletionSourceRequest, type MessageTokenEntry, type ProvidersRecord, SddBoardWebSocketHandler, type SddWizardDeps, SddWizardWebSocketHandler, type SddWizardWiringOptions, type ShellOpenRequest, type ShellOpenResult, type ShellOpenTarget, type SkillsContext, SpecsWebSocketHandler, type ToolTokenEntry, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, WorktreeWebSocketHandler, addProvider, broadcast, browserOpenCommand, buildCspHeader, buildSddWizardDeps, createCustomModeStore, createEternalSubscription, createHttpServer, createProviderConfigIO, createToolLspCompletionSource, defaultBaseDir, deleteKey, errMessage, estimateTokens, extractToken, findFreePort, formatInstances, generateAuthToken, handleCompletionRequest, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleGitChanges, handleGitDiff, handleGitInfo, handleMcpAdd, handleMcpDisable, handleMcpDiscover, handleMcpEnable, handleMcpList, handleMcpRemove, handleMcpRestart, handleMcpSleep, handleMcpUpdate, handleMcpWake, handleMemoryForget, handleMemoryList, handleMemoryRemember, handleShellOpen, handleSkillsContent, handleSkillsCreate, handleSkillsEdit, handleSkillsExport, handleSkillsInstall, handleSkillsUninstall, handleSkillsUpdate, 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 };
+export { AutoPhaseWebSocketHandler, type BackendServices, type CompletionHandlerOptions, type CompletionItemKind, type CompletionSuggestion, type ConnectedClient, type ContextBreakdown, type CreateHttpServerOptions, type CustomContextMode, type CustomModeStore, type EternalBroadcast, type EternalSubscribe, type EternalSubscription, type KeyOpResult, type LspCompletionSource, type LspCompletionSourceRequest, type MessageTokenEntry, type ProvidersRecord, SddBoardWebSocketHandler, type SddWizardDeps, SddWizardWebSocketHandler, type SddWizardWiringOptions, type ShellOpenRequest, type ShellOpenResult, type ShellOpenTarget, type SkillsContext, SpecsWebSocketHandler, type ToolTokenEntry, type VerifyClientInput, type WSClientMessage, type WSServerMessage, type WebUIInstanceRecord, type WebUIOptions, WorktreeWebSocketHandler, addProvider, broadcast, browserOpenCommand, buildCspHeader, buildSddWizardDeps, buildWebUIAccessUrl, createCustomModeStore, createEternalSubscription, createHttpServer, createProviderConfigIO, createToolLspCompletionSource, defaultBaseDir, deleteKey, envFlag, errMessage, estimateTokens, extractToken, findFreePort, formatInstances, generateAuthToken, handleCompletionRequest, handleFilesList, handleFilesRead, handleFilesTree, handleFilesWrite, handleGitChanges, handleGitDiff, handleGitInfo, handleMcpAdd, handleMcpDisable, handleMcpDiscover, handleMcpEnable, handleMcpList, handleMcpRemove, handleMcpRestart, handleMcpSleep, handleMcpUpdate, handleMcpWake, handleMemoryForget, handleMemoryList, handleMemoryRemember, handleShellOpen, handleSkillsContent, handleSkillsCreate, handleSkillsEdit, handleSkillsExport, handleSkillsInstall, handleSkillsUninstall, handleSkillsUpdate, hostForBrowserUrl, hostHeaderOk, injectWsPort, isLoopbackBind, isLoopbackHostname, isPortFree, listInstances, loadSavedProviders, maskedKey, messagePreview, messageTokens, normalizeKeys, openBrowser, registerInstance, registryPath, removeProvider, resolveAuthToken, saveProviders, send, sendResult, setActiveKey, startWebUI, stringifyContent, tokenMatches, unregisterInstance, upsertKey, verifyClient, writeKeysBack };