@wrongstack/webui-server 0.308.0 → 0.308.1

package/dist/server/frontend-static-serve.d.ts

@@ -73,6 +73,12 @@ export interface StaticServeOptions {
      * listening and the WebSocketServer being attached.
      */
     deferListen?: boolean | undefined;
+    /**
+     * Fail-fast port binding (no auto-advance on EADDRINUSE). Mirrors
+     * `WEBUI_STRICT_PORT` semantics for hosts that resolved the port without
+     * probing.
+     */
+    strictPort?: boolean | undefined;
     /** Package-resolution/build seams supplied by the owning host. */
     ensureDistDeps?: EnsureDistDeps | undefined;
     /**

package/dist/server/http-server/api-router.d.ts

@@ -24,6 +24,13 @@ export interface ApiRouterDeps {
     getVectorMemoryStore?: (() => VectorMemoryStore | undefined) | undefined;
     /** Model cache directory for the vector memory provider. */
     vectorMemoryModelCacheDir?: string | undefined;
+    /**
+     * Optional SAGE memory store. When provided, the
+     * `GET /api/memory/search?q=…&explain=1` route becomes active. Same
+     * strict opt-in contract as the vector memory store — non-CLI hosts
+     * that don't wire a memory store stay on their existing surface.
+     */
+    getMemoryStore?: (() => import('@wrongstack/core/types').MemoryPort | undefined) | undefined;
 }
 export declare function handleApiRoutes(req: http.IncomingMessage, res: http.ServerResponse, url: URL, deps: ApiRouterDeps, requireAccessToken: boolean, accessTokenOk: boolean, getTechStackRuntime: () => Promise<{
     store: import('@wrongstack/techstack').TechStackStore;

package/dist/server/http-server/vector-memory-handlers.d.ts

@@ -7,6 +7,7 @@
  */
 import type * as http from 'node:http';
 import type { VectorMemoryStore } from '@wrongstack/vector-memory';
+import type { MemoryPort } from '@wrongstack/core/types';
 export interface VectorMemoryStatusResponse {
     enabled: boolean;
     storePath?: string | undefined;
@@ -17,6 +18,12 @@ export interface VectorMemoryStatusResponse {
     entries?: number | undefined;
     vectors?: number | undefined;
     providers?: string[] | undefined;
+    cache?: {
+        entries: number;
+        providers: number;
+        totalUseCount: number;
+        oldestLastUsedAt: string | null;
+    } | undefined;
 }
 export interface VectorMemorySearchHit {
     id: string;
@@ -28,6 +35,14 @@ export interface VectorMemorySearchHit {
 export interface VectorMemorySearchResponse {
     hits: VectorMemorySearchHit[];
     count: number;
+    /**
+     * Pairwise cosine similarity matrix between returned hits, in hit order.
+     * Cell [i][j] is the similarity between hits[i] and hits[j]. Optional —
+     * the route only computes it when `?similarity=1` is set, to keep the
+     * default response cheap. Used by the WebUI's heatmap view to surface
+     * whether the top-K results form coherent clusters.
+     */
+    similarity?: number[][] | undefined;
 }
 /** Shape the store exposes. Kept narrow so we don't leak the full class. */
 export interface VectorMemorySnapshot {
@@ -52,4 +67,42 @@ export declare function handleVectorMemorySearch(res: http.ServerResponse, url:
 export declare function handleVectorMemoryStore(res: http.ServerResponse, req: http.IncomingMessage, getStore: () => VectorMemoryStore | undefined): Promise<void>;
 /** Handle `DELETE /api/vector-memory/store/:id`. */
 export declare function handleVectorMemoryForget(res: http.ServerResponse, url: URL, getStore: () => VectorMemoryStore | undefined): Promise<void>;
+export interface MemorySearchHit {
+    id: string;
+    text: string;
+    kind: string;
+    status: string;
+    tags: string[];
+    /** Per-channel score breakdown — null on the side that didn't contribute. */
+    lexicalScore: number | null;
+    vectorScore: number | null;
+    /** RRF-style combined score, monotonically higher = better. */
+    finalScore: number;
+    /** Which channel(s) produced this hit. */
+    source: 'lexical' | 'vector' | 'both';
+}
+export interface MemorySearchResponse {
+    hits: MemorySearchHit[];
+    count: number;
+    /**
+     * Where the score breakdown came from. `breakdown` means the rich
+     * variant was used (vector channel was wired); `lexical` means the
+     * fallback synthesized a position-derived score because the surface
+     * doesn't ship `searchSageWithBreakdown`. The UI branches on this to
+     * decide whether to show a dual-column score card or a single column.
+     */
+    channel: 'breakdown' | 'lexical';
+}
+/**
+ * Handle `GET /api/memory/search?q=…&limit=…&explain=1`.
+ *
+ * Returns SAGE search hits. When `explain=1` is set and the underlying
+ * memory store exposes `searchSageWithBreakdown`, each hit carries a
+ * per-channel score breakdown (lexical, vector, RRF final, `source`
+ * attribution). Without the flag — or when the rich variant isn't
+ * available — the response degrades to lexical-only hits with
+ * `vectorScore: null` and `source: 'lexical'`, plus a top-level
+ * `channel: 'lexical'` so the caller can branch.
+ */
+export declare function handleMemorySearch(res: http.ServerResponse, url: URL, getStore: () => MemoryPort | undefined): Promise<void>;
 //# sourceMappingURL=vector-memory-handlers.d.ts.map

package/dist/server/index.d.ts

@@ -69,7 +69,7 @@ export { browserOpenCommand, openBrowser } from './open-browser.js';
 export { isPathInside, resolveWorkingDirInsideProject } from './path-containment.js';
 export type { ConfirmDecision, PendingConfirm } from './pending-confirms.js';
 export { isDestructivePendingConfirm, resolveAllPendingConfirms, resolveYoloEligiblePendingConfirms, } from './pending-confirms.js';
-export { findFreePort, getSurfaceDefaultPorts, isPortFree, SURFACE_DEFAULT_PORTS, type SurfaceKind, surfaceLabel, } from './port-utils.js';
+export { findFreePort, getSurfaceDefaultPorts, isPortFree, isStrictPort, listenWithRetry, SURFACE_DEFAULT_PORTS, type SurfaceKind, surfaceLabel, } from './port-utils.js';
 export { ensureDistDir, resolveDistDir, startStaticServe, type EnsureDistDeps, type ResolveDistOptions, type StaticServeDeps, type StaticServeHandle, type StaticServeOptions, } from './frontend-static-serve.js';
 export { announceWebuiReady, createWebuiShutdown, registerWebuiInstance, registerWebuiSignalHandlers, type AnnounceWebuiReadyParams, type RegisterWebuiInstanceDeps, type RegisterWebuiInstanceParams, type WebuiShutdownResources, } from './embedded-lifecycle.js';
 export { createStreamCoalescer, type StreamCoalescer, type StreamCoalescerDeps, type ToolProgressPayload, } from './stream-coalescer.js';

package/dist/server/memory-handlers.d.ts

@@ -40,6 +40,25 @@ export declare function handleSageList(ws: WebSocket, memoryStore: MemoryPort):
  * a full `listSage()` for stores that predate `listSagePage`.
  */
 export declare function handleSageListPage(ws: WebSocket, msg: unknown, memoryStore: MemoryPort): Promise<void>;
+/**
+ * Run a search and return the per-channel score breakdown
+ * (lexical / vector / final + `source` attribution). Used by the
+ * WebUI's Memory panel so the operator can see WHY a memory is in
+ * the result list.
+ *
+ * Request:  { type: 'memory.sage.searchBreakdown', payload: { query, limit?, includeStale? } }
+ * Response: { type: 'memory.sage.searchBreakdown', payload: { hits, source } }
+ *
+ * `source` is one of:
+ *  - `breakdown`: the underlying surface returned a `VectorAugmentHit[]`
+ *    with both lexical and vector scores populated per hit.
+ *  - `lexical`: the surface only has the flat `searchSage` — we wrap
+ *    the results with a position-derived score and `source: 'lexical'`.
+ *
+ * Clients branch on `source` to decide whether to render the dual
+ * score panel or a single lexical column.
+ */
+export declare function handleSageSearchBreakdown(ws: WebSocket, msg: unknown, memoryStore: MemoryPort): Promise<void>;
 /**
  * Get a single Sage entry by ID.
  * Request:  { type: 'memory.sage.get', payload: { id } }

package/dist/server/port-utils.d.ts

@@ -9,14 +9,15 @@
  *   starts at 3456, SimpleUI at 3466. Set `WEBUI_STRICT_PORT=1` to disable.
  * - **TOCTOU window.** The probe in `findFreePort` binds a throwaway
  *   `net.Server` then closes it, so there is a tiny race between "found free"
- *   and "real server binds". For local multi-instance use that race is
- *   negligible; if it ever loses, the real bind fails loudly with EADDRINUSE
- *   exactly as before.
+ *   and "real server binds". When that race is lost the real bind fails with
+ *   EADDRINUSE; `listenWithRetry` is the safety net — it advances past the
+ *   competitor (bounded) instead of crashing or hanging.
  * - **Instance registry.** Every live process records itself in
  *   `~/.wrongstack/webui-instances.json` with its PID, surface, port, and
  *   project root. A crashed instance is pruned on the next registry read
  *   (`process.kill(pid, 0)` probe), so ghosts don't accumulate.
  */
+import * as net from 'node:net';
 /**
  * Surface-specific default single port.
  *
@@ -37,6 +38,12 @@ export declare const SURFACE_DEFAULT_PORTS: {
 export type SurfaceKind = keyof typeof SURFACE_DEFAULT_PORTS;
 /** Human-readable label for surfaces. */
 export declare function surfaceLabel(surface: SurfaceKind): string;
+/**
+ * True when `WEBUI_STRICT_PORT` requests fail-fast port binding (no
+ * auto-advance). Single source of truth for both `resolvePorts` (probe-time)
+ * and `startWebUI`'s bind-time retry — the two must not drift apart.
+ */
+export declare function isStrictPort(): boolean;
 /**
  * Return the surface-specific default HTTP port.
  */
@@ -56,4 +63,17 @@ export interface FindFreePortOptions {
  * `exclude`. Throws if nothing is free within `maxTries` steps.
  */
 export declare function findFreePort(host: string, startPort: number, opts?: FindFreePortOptions): Promise<number>;
+export interface ListenWithRetryOptions {
+    /** Bind attempts before giving up on EADDRINUSE. Default 10. */
+    maxTries?: number | undefined;
+}
+/**
+ * Listen `server` on `host` starting at `port`, advancing one port on each
+ * EADDRINUSE — the bind-time safety net for the `findFreePort` TOCTOU window
+ * (probe closes, competitor binds, real listen loses the race). Any other
+ * error (EACCES, EAFNOSUPPORT, …) rejects immediately; EADDRINUSE past the
+ * final attempt rejects with the last error. Resolves with the port the
+ * server actually bound, which exceeds the request when a retry advanced.
+ */
+export declare function listenWithRetry(server: net.Server, host: string, port: number, opts?: ListenWithRetryOptions): Promise<number>;
 //# sourceMappingURL=port-utils.d.ts.map

package/dist/server/start-webui-companion.d.ts

@@ -12,5 +12,13 @@ import * as http from 'node:http';
  * fallback for systems where `::` does not accept IPv4-mapped
  * connections (net.ipv6.bindv6only=1, some Windows configs).
  */
-export declare function setupCompanionServer(httpServer: http.Server, wsHost: string | undefined, httpPort: number): http.Server | null;
+export declare function setupCompanionServer(httpServer: http.Server, wsHost: string | undefined, 
+/**
+ * The port the PRIMARY server actually bound — not the originally
+ * requested port. The companion must mirror it exactly: advertised URLs
+ * point at the primary's port, so a companion bound elsewhere would be
+ * unreachable dead weight. A single bind attempt; EADDRINUSE here means
+ * the mirror is impossible, so the companion degrades to null.
+ */
+httpPort: number): Promise<http.Server | null>;
 //# sourceMappingURL=start-webui-companion.d.ts.map

package/dist/server/start-webui-shutdown.d.ts

@@ -38,6 +38,11 @@ export declare function setupWebuiShutdown(options: {
     clearEternalSubscription: () => void;
     codebaseIndexing: any;
     memoryStore: any;
+    /** Vector memory store (mirrors CLI's teardown). `undefined` when the
+     *  standalone WebUI host failed to construct one (read-only FS, etc.). */
+    vectorMemoryStore: {
+        close(): void;
+    } | undefined;
     globalConfigPath: string;
 }): () => void;
 //# sourceMappingURL=start-webui-shutdown.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/webui-server",
-  "version": "0.308.0",
+  "version": "0.308.1",
   "license": "MIT",
   "description": "WrongStack WebUI HTTP/WebSocket server module — extracted from @wrongstack/webui in PR #243/244 to remove the CLI -> @wrongstack/webui/server cross-package edge (audit §3.1.1). Pure backend: HTTP routes, WebSocket handlers, MCP tool wrappers, HTML serving. The web frontend lives in @wrongstack/webui; this package is the standalone server it can run on.",
   "keywords": [
@@ -40,17 +40,17 @@
   ],
   "dependencies": {
     "ws": "^8.21.3",
-    "@wrongstack/runtime": "0.308.0",
-    "@wrongstack/kanban": "0.308.0",
-    "@wrongstack/core": "0.308.0",
-    "@wrongstack/sdd": "0.308.0",
-    "@wrongstack/providers": "0.308.0",
-    "@wrongstack/sage": "0.308.0",
-    "@wrongstack/mcp": "0.308.0",
-    "@wrongstack/techstack": "0.308.0",
-    "@wrongstack/tools": "0.308.0",
-    "@wrongstack/vector-memory": "0.308.0",
-    "@wrongstack/requirement-intake": "0.308.0"
+    "@wrongstack/core": "0.308.1",
+    "@wrongstack/requirement-intake": "0.308.1",
+    "@wrongstack/kanban": "0.308.1",
+    "@wrongstack/sdd": "0.308.1",
+    "@wrongstack/mcp": "0.308.1",
+    "@wrongstack/providers": "0.308.1",
+    "@wrongstack/runtime": "0.308.1",
+    "@wrongstack/techstack": "0.308.1",
+    "@wrongstack/sage": "0.308.1",
+    "@wrongstack/tools": "0.308.1",
+    "@wrongstack/vector-memory": "0.308.1"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
@@ -63,6 +63,7 @@
   "scripts": {
     "build": "node ../../scripts/build-package.mjs",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   }
 }