@harness-fe/mcp-server 4.0.0-next.2 → 4.0.0-next.4

package/dist/bridge.d.ts

@@ -1,323 +0,0 @@
-/**
- * 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 Principal } from './identity.js';
-import { type ConsentPolicy, 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, principal?: Principal): Promise<Task | undefined>;
-    resolveTask(id: string, note?: string, principal?: Principal): 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;
-    /**
-     * Browser-consent policy for control commands (4.0 · P2). When omitted it
-     * defaults to `session` while auth is enabled (non-loopback / exposed) and
-     * `off` on loopback — so solo dev keeps its zero-friction flow and any
-     * exposed daemon prompts the user before an agent drives the page.
-     */
-    consent?: ConsentPolicy;
-    /**
-     * 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;
-    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
-    private readonly consentPolicy;
-    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;
-    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
-    private connToPrincipal;
-    /**
-     * Identity attributed to MCP-driven writes (task claim/resolve). The MCP
-     * tool layer is a daemon-wide singleton today with no per-call caller
-     * context, so stdio/HTTP agents collapse to one principal. P4 (per-session
-     * MCP transport) replaces this with the real per-call principal.
-     */
-    private readonly defaultPrincipal;
-    /** 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;
-    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
-    getAuthOptions(): AuthOptions;
-    /**
-     * 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, principal?: Principal): Promise<Task | undefined>;
-    getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
-    resolveTask(id: string, note?: string, principal?: Principal): 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;
-}