@harness-fe/mcp-server 3.0.1

package/dist/bridge.d.ts

@@ -0,0 +1,302 @@
+/**
+ * WS bridge — accepts connections from vite-plugin and runtime-client.
+ *
+ * Protocol: see @harness-fe/protocol.
+ *
+ * Responsibilities:
+ *   - Handshake: `hello` frame → register peer in SessionRouter, reply `hello.ack`
+ *   - sendCommand(): forward a CommandFrame to the target tab, return a
+ *     Promise that resolves when the matching ResponseFrame arrives
+ *   - onEvent(): broadcast event frames to subscribers (mcp tools / future
+ *     recorder)
+ */
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type AuthOptions } from './auth.js';
+import { type EventFrame, type HttpBatch, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
+import { SessionRouter, type PeerSession } from './sessionRouter.js';
+import { type IStore, type ITaskStore, type IMemoryStore, type RetentionPolicy } from './store/index.js';
+/**
+ * Surface used by the stdio MCP layer. Same shape whether the underlying
+ * implementation is an in-process `Bridge` (leader) or a `RemoteBridge`
+ * proxying over WS to another daemon (follower).
+ *
+ * All methods are async so the same call site works in both modes.
+ */
+export interface IBridge {
+    sendCommand(command: string, args: unknown, opts?: SendCommandOptions): Promise<unknown>;
+    listTabs(): Promise<TabInfo[]>;
+    listTasks(filter?: {
+        status?: TaskStatus | 'all';
+        limit?: number;
+    }): Promise<Task[]>;
+    claimTask(id: string): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    getMemoryStore(): IMemoryStore;
+    /**
+     * Base URL (e.g. http://127.0.0.1:47729) where the replay viewer is reachable.
+     * Returns undefined when the bridge does not serve HTTP (e.g. follower mode).
+     */
+    getViewerBaseUrl(): string | undefined;
+    /**
+     * The configured auth token, or undefined if auth is disabled. Used to
+     * compose URLs that the user (or agent) can hit without an extra
+     * authentication step.
+     */
+    getAuthToken(): string | undefined;
+    /**
+     * Read an attachment PNG for a task. Returns base64-encoded PNG or null.
+     * The task must exist in the in-memory map so we can look up its projectId.
+     */
+    getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
+}
+export interface SendCommandOptions {
+    tabId?: string;
+    timeoutMs?: number;
+    target?: 'runtime-client' | 'vite-plugin';
+    projectId?: string;
+}
+/**
+ * Default data directory for all persistence stores, keyed by the port the
+ * daemon listens on. Identity of a daemon = its listening address; same
+ * port → same on-disk store; different ports → independent stores.
+ *
+ * This lets users opt into isolation simply by configuring a different
+ * `--port` in their `mcp.json`, and lets multiple IDEs targeting the same
+ * port automatically share state through the existing leader/follower
+ * mechanism in `cli.ts`. No cwd / project-root detection involved.
+ */
+export declare function defaultDataDir(port: number): string;
+export interface BridgeOptions {
+    port?: number;
+    /** Bind address. Default 127.0.0.1 (no remote exposure). */
+    host?: string;
+    /**
+     * Token-based auth applied to every HTTP route and WS upgrade. Empty
+     * token disables auth (only valid when bound to a loopback host).
+     */
+    auth?: AuthOptions;
+    /**
+     * Override the host used when building outbound URLs (dashboard links,
+     * replay viewer URLs). When omitted and `host` is `0.0.0.0` / `::`, the
+     * first non-internal IPv4 address from the OS network interfaces is
+     * used so other LAN devices can follow the links. For loopback binds the
+     * literal `host` is reused.
+     */
+    publicHost?: string;
+    /**
+     * Store instance for JSONL persistence. If omitted, a default JsonlStore
+     * is created at `dataDir` (or `defaultDataDir(port)` when `dataDir` is
+     * also omitted). Pass null to disable persistence.
+     */
+    store?: IStore | null;
+    /**
+     * Task store instance for JSON task persistence. If omitted, a default
+     * JsonTaskStore is created at `dataDir`. Pass null to disable task
+     * persistence (useful in tests).
+     */
+    taskStore?: ITaskStore | null;
+    /**
+     * Memory store instance for agent memory persistence. If omitted, a default
+     * JsonMemoryStore is created at `dataDir`. Pass null to disable memory
+     * persistence (useful in tests).
+     */
+    memoryStore?: IMemoryStore | null;
+    /**
+     * Root data directory for task attachment binaries. Defaults to the same
+     * `~/.harness/data` directory used by the stores. Override in tests.
+     */
+    attachmentsDataDir?: string;
+    /**
+     * Root data directory for the default stores (when `store` / `taskStore`
+     * / `memoryStore` are not supplied). When omitted, computed from `port`
+     * via `defaultDataDir(port)`. Set explicitly to point all stores at a
+     * non-default location (useful for tests or migration).
+     */
+    dataDir?: string;
+    /**
+     * Optional friendly label surfaced in the startup banner and (later) the
+     * dashboard title. Purely cosmetic — has no effect on data isolation,
+     * routing, or auth. Identity is always the listening port.
+     */
+    label?: string;
+    /**
+     * Automatic retention policy enforcement.
+     *
+     * Without this, manual `session.purge` MCP calls are the only thing that
+     * trims the on-disk store — so a long-running daemon will eventually fill
+     * the user's disk. Default: run `store.purge()` once shortly after start
+     * and every hour thereafter. Set `enabled: false` for tests / one-shot runs.
+     */
+    autoPurge?: {
+        enabled?: boolean;
+        /** Period between purges in ms. Default 1 hour. */
+        intervalMs?: number;
+        /** Override the retention policy. Default uses store's built-in defaults. */
+        policy?: RetentionPolicy;
+        /** Skip the startup purge (still runs the periodic timer). Default false. */
+        skipInitial?: boolean;
+    };
+}
+export type EventListener = (event: EventFrame, session: PeerSession) => void;
+export declare class Bridge implements IBridge {
+    readonly router: SessionRouter;
+    readonly store: IStore | null;
+    readonly taskStore: ITaskStore | null;
+    readonly memoryStore: IMemoryStore;
+    private wss?;
+    private httpServer?;
+    /**
+     * Optional HTTP handler invoked for non-WebSocket requests. Set via
+     * `setHttpHandler()`. Allows higher layers (e.g. replay viewer) to serve
+     * routes on the same port as the WS bridge without coupling Bridge to them.
+     */
+    private httpHandler?;
+    private sockets;
+    private pending;
+    private eventListeners;
+    private tasks;
+    private opts;
+    private auth;
+    private publicHostOverride;
+    private readonly attachDataDir;
+    private autoPurgeOpts;
+    /** Set by start() when auto-purge is enabled; cleared by stop(). */
+    private autoPurgeTimer?;
+    /**
+     * Map from connectionId → buildId (for build-plugin connections)
+     * or sessionId (for runtime-client connections).
+     */
+    private connToStoreId;
+    /** Connections that already logged a "no store session" warning. */
+    private warnedNoSession;
+    /**
+     * Grace period timers: projectId → timer handle.
+     * When a build plugin disconnects, a 30-second timer is started.
+     * If the same project reconnects within that window, the timer is cancelled.
+     */
+    private graceTimers;
+    /**
+     * Pending build end info: projectId → { buildId, closedAt }.
+     * Tracks builds waiting for the grace period to expire.
+     */
+    private pendingEndBuild;
+    /**
+     * Dashboard SPA subscribers — connections that sent `hello` with
+     * role: 'dashboard-client'. Receive `dashboard.update` frames whenever
+     * session state changes; never receive commands and never send events.
+     */
+    private dashboardSubscribers;
+    /** Debounce per-session 'session.update' broadcasts so chatty rrweb chunks don't spam subscribers. */
+    private dashboardDebounceTimers;
+    /** Optional friendly label (HARNESS_FE_LABEL). Cosmetic only. */
+    readonly label: string | undefined;
+    constructor(opts?: BridgeOptions);
+    /**
+     * Returns the memory store instance for use by mcp.ts and other callers.
+     */
+    getMemoryStore(): IMemoryStore;
+    private loadTasks;
+    private persistTasks;
+    /**
+     * Load tasks for a specific project from the task store into the in-memory map.
+     * Called when a project connects so its tasks are available immediately.
+     */
+    private loadTasksForProject;
+    private taskDedupKey;
+    /**
+     * Register an HTTP request handler that runs for non-WebSocket requests on
+     * the same port. Only one handler is supported; later calls replace prior
+     * ones. WS upgrades bypass this handler.
+     */
+    setHttpHandler(handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>): void;
+    /**
+     * Insert a handler that runs *before* the main HTTP handler. Return `true`
+     * if the request was consumed (no further processing); return `false` to
+     * fall through to the existing handler. Allows mcpHttp.ts to mount on
+     * `/mcp` without owning the whole HTTP surface.
+     */
+    prependHttpHandler(handler: (req: IncomingMessage, res: ServerResponse) => Promise<boolean> | boolean): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Run `store.purge()` defensively. Errors are logged but never bubble out
+     * — the daemon must continue serving even if disk is full or files are
+     * locked.
+     */
+    private runAutoPurge;
+    /** Expose the bound port (useful when port:0 was passed for tests). */
+    getBoundPort(): number | undefined;
+    getViewerBaseUrl(): string | undefined;
+    getAuthToken(): string | undefined;
+    /**
+     * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
+     *
+     * `kind: 'session.update'` is debounced per-sessionId (200ms) so chatty
+     * rrweb chunk appends don't spam every subscriber. Other kinds fire
+     * immediately because they represent rare state transitions (new
+     * session, session closed, export created).
+     */
+    notifyDashboard(payload: {
+        kind: 'session.new' | 'session.update' | 'session.closed' | 'project.update' | 'export.new';
+        sessionId?: string;
+        projectId?: string;
+    }): void;
+    private flushDashboardUpdate;
+    /**
+     * Host string used when handing out URLs that other machines need to
+     * reach. Loopback binds keep the literal address; wildcard binds
+     * (0.0.0.0 / ::) prefer the first non-internal IPv4. Explicit
+     * `publicHost` always wins.
+     */
+    private getPublicHost;
+    onEvent(listener: EventListener): () => void;
+    /**
+     * Handle an HTTP-batch POST /events request (Edge Runtime path).
+     *
+     * Stateless: each call is a self-contained hello+events sequence.
+     * The hello is used to register the peer (or look up the existing session)
+     * and the events are persisted to the session timeline — same paths as the
+     * WS handler.
+     */
+    handleHttpBatch(hello: HttpBatch['hello'], events: HttpBatch['events']): void;
+    listTabs(): Promise<TabInfo[]>;
+    listTasks(filter?: {
+        status?: TaskStatus | 'all';
+        limit?: number;
+    }): Promise<Task[]>;
+    claimTask(id: string): Promise<Task | undefined>;
+    getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
+    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    private persistTaskEvent;
+    private recordTask;
+    /**
+     * Write attachment data to disk and return persisted pointer objects.
+     * Drops attachments if the total decoded size exceeds 4 MB.
+     */
+    private writeTaskAttachments;
+    /**
+     * Read an attachment from disk for a given task.
+     * Returns the base64 data if found, null otherwise.
+     */
+    readTaskAttachment(projectId: string, taskId: string, attachmentId: string): string | null;
+    /**
+     * Send a command to a specific tab and await its response.
+     * `tabId` falls back to the most-recent active tab if omitted.
+     */
+    sendCommand(command: string, args: unknown, opts?: SendCommandOptions): Promise<unknown>;
+    /**
+     * Returns true if there is an active build for the given projectId.
+     * Checks both in-memory grace period builds and the store.
+     */
+    private hasActiveBuild;
+    private onConnection;
+    private handleFrame;
+    /**
+     * Runtime → daemon query dispatcher (0.5+). Whitelisted methods only.
+     * Owner check: tasks.update / tasks.get / tasks.delete refuse to touch
+     * tasks whose `visitorId` doesn't match the caller's `peer.visitorId`.
+     */
+    private handleQuery;
+    private handleMcpCall;
+    private invokeMcpMethod;
+}