@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/send-file-mcp.js

@@ -0,0 +1,281 @@
+/**
+ * Paddock-native "send file" MCP tool.
+ *
+ * Exposes a single `paddock_send_file` tool to keeper agents via
+ * herdctl's `injectedMcpServers` mechanism. herdctl carries the def to the agent
+ * differently per runtime, and both auto-allowlist the server's `mcp__<name>__*`
+ * tools:
+ *   - SDK runtime (chats, the `session` drive-mode default) — the def becomes an
+ *     IN-PROCESS SDK MCP server via `createSdkMcpServer`; no bridge, no socket.
+ *   - CLI runtime (the sweeper, triggers, and `driveMode: batch` chats) — the
+ *     agent is a separate `claude -p` process that can't reach an in-process SDK
+ *     server, so herdctl stands up a localhost HTTP MCP bridge per injected
+ *     server instead.
+ * Either way this tool's handler runs inside the Paddock server process.
+ *
+ * ── How the rendered file reaches (and persists in) the chat ────────────────
+ * The tool returns a small JSON ENVELOPE as its result `output`. That output is
+ * the one representation that survives everywhere:
+ *   - live: `@herdctl/chat`'s translator forwards it verbatim on the
+ *     `chat:tool_call` event;
+ *   - reload: `@herdctl/core`'s history parser preserves tool `output` verbatim
+ *     (it only summarizes tool *input*).
+ * So the web renders from the tool call itself — no separate WS event, and a
+ * refresh shows exactly what was there live. See ChatPane's `sentFileFromToolCall`.
+ *
+ * Two ways to send a file:
+ *   - Inline / virtual: `content` + `filename` (a real-looking but possibly
+ *     fictional name). The content rides IN the envelope, so it stays in the
+ *     transcript and in the agent's context (the agent authored it and can
+ *     revise it on a later turn). Nothing needs to exist on disk.
+ *   - Real file: `file_path` (relative to the agent's working directory). Only
+ *     the PATH goes in the envelope — never the bytes — so the transcript stays
+ *     lean and Paddock loads the bytes on demand (sandboxed) when rendering.
+ *
+ * The optional `kind` selects the renderer; when omitted it's inferred from the
+ * filename extension.
+ */
+import { basename, extname, resolve } from "node:path";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+/**
+ * Reject a runaway send; a chat attachment shouldn't be huge. Sized generously
+ * for video: a short screen recording (e.g. a Playwright `recordVideo`) routinely
+ * exceeds the old 25 MB image ceiling, so we allow up to 100 MB.
+ */
+export const MAX_ATTACHMENT_BYTES = 100 * 1024 * 1024;
+const MARKDOWN_EXT = new Set([".md", ".mdx", ".markdown"]);
+const MERMAID_EXT = new Set([".mmd", ".mermaid"]);
+const HTML_EXT = new Set([".html", ".htm"]);
+const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg"]);
+// Video extensions render inline as a <video> player. Note `.webm` (video) is
+// distinct from `.webp` (image); the IMAGE check runs first so they never collide.
+const VIDEO_EXT = new Set([".mp4", ".webm", ".mov", ".m4v"]);
+const PDF_EXT = new Set([".pdf"]);
+/** Extension -> language label for the code-block filename chrome. */
+const LANGUAGE_BY_EXT = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".cs": "csharp",
+    ".php": "php",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".sh": "bash",
+    ".bash": "bash",
+    ".zsh": "bash",
+    ".sql": "sql",
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".css": "css",
+    ".scss": "scss",
+    ".xml": "xml",
+};
+function inferKind(filename) {
+    const ext = extname(filename).toLowerCase();
+    if (MARKDOWN_EXT.has(ext))
+        return "markdown";
+    if (MERMAID_EXT.has(ext))
+        return "mermaid";
+    if (HTML_EXT.has(ext))
+        return "html";
+    // IMAGE before VIDEO so `.webp` (image) is never confused with `.webm` (video).
+    if (IMAGE_EXT.has(ext))
+        return "image";
+    if (VIDEO_EXT.has(ext))
+        return "video";
+    if (PDF_EXT.has(ext))
+        return "pdf";
+    if (ext in LANGUAGE_BY_EXT)
+        return "code";
+    return "text";
+}
+function inferLanguage(filename) {
+    return LANGUAGE_BY_EXT[extname(filename).toLowerCase()];
+}
+function ok(envelope) {
+    return { content: [{ type: "text", text: JSON.stringify(envelope) }] };
+}
+/**
+ * A short listing of a directory's top-level entries, to append to a
+ * file-not-found / escape error so the agent can immediately see the right
+ * filename instead of shelling out to `ls`/`find` to hunt for it (the main
+ * source of friction observed with screenshot flows). Files first, then dirs;
+ * capped so a large dir doesn't flood the tool result.
+ */
+async function describeDir(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+        const dirs = entries.filter((e) => e.isDirectory()).map((e) => `${e.name}/`);
+        const shown = [...files, ...dirs].slice(0, 40);
+        if (shown.length === 0)
+            return "It is currently empty.";
+        const more = files.length + dirs.length > shown.length ? ", …" : "";
+        return `Entries in it: ${shown.join(", ")}${more}.`;
+    }
+    catch {
+        return "";
+    }
+}
+function fail(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+const TOOL_NAME = "send_file";
+const SERVER_NAME = "paddock";
+const TOOL_DESCRIPTION = "Render a file inline in the Paddock chat so the user sees it nicely formatted. " +
+    "Use this to share a document, code snippet, or diagram. Two modes: (1) pass `content` " +
+    "with a `filename` to render inline/virtual content that need not exist on disk (great " +
+    "for a code snippet or a Markdown/Mermaid block — the filename can be illustrative, e.g. " +
+    "`example.tsx` or `architecture.mmd`); or (2) pass `file_path` to render a real file from " +
+    "your working directory. Markdown renders formatted, ```mermaid``` blocks (or a .mmd file / " +
+    "kind:'mermaid') render as diagrams, and code renders with a filename header. Videos " +
+    "(mp4/webm) sent via a real `file_path` render as an inline player with controls — keep them " +
+    "short. A real .pdf (via `file_path`) renders inline in a scrollable PDF viewer. Prefer " +
+    "this over pasting long content into your text reply.";
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        content: {
+            type: "string",
+            description: "Inline file contents to render (for a virtual/illustrative file). Provide this OR file_path.",
+        },
+        file_path: {
+            type: "string",
+            description: "Path to a real file to render, relative to (or absolute within) your working directory. Provide this OR content.",
+        },
+        filename: {
+            type: "string",
+            description: "Display filename shown in the file header (e.g. `example.tsx`, `README.md`, `flow.mmd`). Required with `content`; defaults to the basename of `file_path`.",
+        },
+        kind: {
+            type: "string",
+            enum: ["markdown", "mermaid", "code", "text", "html", "image", "video", "pdf"],
+            description: "Renderer to use. Optional — inferred from the filename extension when omitted.",
+        },
+        language: {
+            type: "string",
+            description: "Language hint for the `code` kind (e.g. `python`). Optional.",
+        },
+        message: {
+            type: "string",
+            description: "Optional note to show alongside the file.",
+        },
+    },
+    required: ["filename"],
+};
+function createHandler(context) {
+    return async (args) => {
+        try {
+            const rawContent = typeof args.content === "string" ? args.content : undefined;
+            const filePath = typeof args.file_path === "string" ? args.file_path : undefined;
+            const filenameArg = typeof args.filename === "string" ? args.filename : undefined;
+            const kindArg = typeof args.kind === "string" ? args.kind : undefined;
+            const languageArg = typeof args.language === "string" ? args.language : undefined;
+            const message = typeof args.message === "string" ? args.message : undefined;
+            if (rawContent === undefined && filePath === undefined) {
+                return fail("Error: provide either `content` (inline) or `file_path` (a real file).");
+            }
+            if (rawContent !== undefined) {
+                // Inline / virtual file — content rides in the envelope.
+                const filename = filenameArg ?? "snippet.txt";
+                const kind = kindArg ?? inferKind(filename);
+                if (kind === "image") {
+                    return fail("Error: inline `content` cannot be an image; use `file_path` for images.");
+                }
+                if (kind === "video") {
+                    return fail("Error: inline `content` cannot be a video; use `file_path` for videos.");
+                }
+                if (kind === "pdf") {
+                    return fail("Error: inline `content` cannot be a PDF; use `file_path` for PDFs.");
+                }
+                return ok({
+                    paddockSendFile: 1,
+                    filename,
+                    kind,
+                    language: kind === "code" ? (languageArg ?? inferLanguage(filename)) : undefined,
+                    source: "inline",
+                    content: rawContent,
+                    message,
+                });
+            }
+            // Real file — copy its bytes into the attachment store NOW, so the shared
+            // file is an immutable snapshot (renders forever, even if the original is
+            // later edited/deleted) and the render endpoint only ever serves files that
+            // were explicitly sent — never an arbitrary on-box path. Because we copy
+            // rather than reference, there's no sandbox: a relative path resolves
+            // against the working dir, an absolute path is used as-is.
+            const wd = context.workingDirectory;
+            const resolved = wd ? resolve(wd, filePath) : resolve(filePath);
+            let realPath;
+            try {
+                realPath = await realpath(resolved);
+            }
+            catch {
+                const where = wd ? ` Your working directory is ${wd}. ${await describeDir(wd)}` : "";
+                return fail(`Error: file not found: ${filePath} (looked for ${resolved}).${where} ` +
+                    `Pass a path to a file that exists (screenshots from the browser tools are ` +
+                    `saved in your working directory).`);
+            }
+            const info = await stat(realPath);
+            if (!info.isFile()) {
+                return fail(`Error: not a regular file: ${filePath}`);
+            }
+            if (info.size > MAX_ATTACHMENT_BYTES) {
+                return fail(`Error: file too large to send: ${info.size} bytes (limit ${MAX_ATTACHMENT_BYTES}).`);
+            }
+            const bytes = await readFile(realPath);
+            const filename = filenameArg ?? basename(resolved);
+            const kind = kindArg ?? inferKind(filename);
+            const attachmentId = await context.saveAttachment(bytes, filename);
+            return ok({
+                paddockSendFile: 1,
+                filename,
+                kind,
+                language: kind === "code" ? (languageArg ?? inferLanguage(filename)) : undefined,
+                source: "file",
+                attachmentId,
+                message,
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return fail(`Error sending file: ${msg}`);
+        }
+    };
+}
+/**
+ * Build the injected MCP server definition for the send-file tool, bound to a
+ * per-turn context. Pass the returned value under a stable server key (`paddock`)
+ * so the tool surfaces to the agent as `mcp__paddock__send_file`.
+ */
+export function sendFileServerDef(context) {
+    return {
+        name: SERVER_NAME,
+        version: "0.1.0",
+        tools: [
+            {
+                name: TOOL_NAME,
+                description: TOOL_DESCRIPTION,
+                inputSchema: TOOL_INPUT_SCHEMA,
+                handler: createHandler(context),
+            },
+        ],
+    };
+}
+/** The record key + resulting fully-qualified tool name the agent sees. */
+export const SEND_FILE_SERVER_KEY = SERVER_NAME;
+export const SEND_FILE_TOOL_NAME = `mcp__${SERVER_NAME}__${TOOL_NAME}`;

package/packages/server/dist/session-hub.d.ts

@@ -0,0 +1,186 @@
+/**
+ * SessionHub — session-scoped fan-out + re-attach for in-flight chat turns.
+ *
+ * The problem it solves (issue #54): a turn's stream used to be bound to the ONE
+ * socket that sent `chat:send`. Frames were written straight to that socket and
+ * silently dropped whenever it wasn't OPEN. So if the socket died mid-turn (idle
+ * half-open drop, laptop sleep, wifi change, the client's own auto-reconnect
+ * swapping sockets), every remaining frame of the running turn was lost — the
+ * live stream stalled and only a full page reload (which re-hydrates from the
+ * persisted transcript) recovered it.
+ *
+ * The hub decouples a turn from any single socket:
+ *
+ *  - Every emitted frame is buffered on the turn and stamped with a per-turn,
+ *    monotonic `seq`.
+ *  - Frames fan out to the turn's ORIGIN socket PLUS every socket currently
+ *    subscribed to the turn's session (dead sockets are skipped, not dropped-
+ *    on-the-floor-permanently — a live one still gets the frame).
+ *  - A reconnecting client re-`attach`es to the session and replays exactly the
+ *    frames it missed (everything with `seq` greater than the last it applied),
+ *    so the stream resumes seamlessly with no gap and no duplication.
+ *
+ * A just-completed turn's buffer is retained briefly ({@link COMPLETED_TTL_MS})
+ * so a client that reconnects right at the end still receives the tail frames
+ * (including the terminal `chat:complete`) rather than hanging "streaming"
+ * forever.
+ *
+ * The hub is transport-shaped but transport-agnostic: it only needs a socket it
+ * can check `readyState` on and `send` a JSON string to (the `HubSocket`
+ * minimal interface), so it is unit-testable without a real WebSocket.
+ */
+/** The slice of a WebSocket the hub needs — real `ws` sockets satisfy this. */
+export interface HubSocket {
+    readyState: number;
+    /** WebSocket.OPEN (1) — read off the instance so tests can fake it. */
+    readonly OPEN: number;
+    send(data: string): void;
+}
+/** A server→client frame the hub buffers and fans out. `payload.seq` is stamped by the hub. */
+export interface HubMessage {
+    type: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * The frame shape `emit` accepts. `payload` is any object (the caller's typed
+ * routing payloads are interfaces without a string index signature, so they
+ * don't satisfy `Record<string, unknown>` directly); the hub treats it opaquely
+ * and only adds `seq`.
+ */
+export interface HubMessageInput {
+    type: string;
+    payload: object;
+}
+interface BufferedFrame {
+    seq: number;
+    msg: HubMessage;
+}
+interface Turn {
+    projectSlug: string;
+    /** Null until the turn's session id is known (a brand-new chat resolves it mid-stream). */
+    sessionId: string | null;
+    jobId: string | null;
+    /**
+     * The socket that started the turn; always a fan-out target while OPEN. `null`
+     * for a server-initiated turn with no client watching (a scheduler-fired
+     * wake — Paddock#111): frames are still buffered for replay so a client that
+     * attaches mid-turn (or opens the chat afterward) sees the woken work.
+     */
+    origin: HubSocket | null;
+    frames: BufferedFrame[];
+    /** `seq` of `frames[0]` after any trim — replays older than this need a resync. */
+    baseSeq: number;
+    nextSeq: number;
+    running: boolean;
+    evictTimer: ReturnType<typeof setTimeout> | null;
+}
+/** How long a completed turn's buffer lingers so an end-of-turn reconnect still gets the tail. */
+export declare const COMPLETED_TTL_MS = 60000;
+/** The outcome of an {@link SessionHub.attach}. */
+export type AttachResult = {
+    status: "none";
+} | {
+    status: "replayed";
+    frames: number;
+} | {
+    status: "resync";
+    projectSlug: string;
+};
+/**
+ * A session's live-turn status, surfaced so the UI can restore the Stop button
+ * and streaming indicators (issues #52/#53). Emitted on start/stop transitions
+ * via {@link SessionHub.onActive} and readable via {@link SessionHub.activeInfo}.
+ */
+export interface ActiveInfo {
+    sessionId: string;
+    projectSlug: string;
+    /** The running turn's cancellable job id, if known yet (null early in a turn). */
+    jobId: string | null;
+    running: boolean;
+}
+export declare class SessionHub {
+    /** sessionId → the current (running or recently-completed) turn for that session. */
+    private bySession;
+    /** sessionId → sockets attached to it (fan-out targets beyond the origin). */
+    private subscribers;
+    /**
+     * Notified on every running-state transition (turn start / stop) so the WS
+     * layer can broadcast a `chat:active` signal to clients — powering the Stop
+     * button restore (#52) and streaming indicators (#53). Set by the WS layer.
+     */
+    onActive: ((info: ActiveInfo) => void) | null;
+    /**
+     * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
+     * chat / a slash command) so the turn is re-attachable from its very first
+     * frame; omit it for a brand-new chat and call {@link TurnHandle.setSession}
+     * once the id arrives on the stream.
+     */
+    startTurn(projectSlug: string, origin: HubSocket | null, sessionId?: string | null): TurnHandle;
+    /** Add a socket to a session's fan-out set (idempotent). */
+    subscribe(sessionId: string, socket: HubSocket): void;
+    /**
+     * Attach a (re)connecting socket to a session and, when `wantReplay`, catch it
+     * up on a still-live turn by replaying every buffered frame after `afterSeq`.
+     *
+     * `wantReplay` MUST be false for a fresh mount (one that also hydrates the
+     * transcript over REST) so buffered frames don't duplicate the transcript; it
+     * is true only for a genuine reconnect of a socket that was mid-turn, where
+     * `afterSeq` is the last seq the client applied and the replay is exactly the
+     * gap. Replays are written straight to `socket` (not the whole fan-out).
+     */
+    attach(sessionId: string, socket: HubSocket, opts: {
+        wantReplay: boolean;
+        afterSeq: number;
+    }): AttachResult;
+    /** Drop a socket from every session's fan-out set (call on socket close). */
+    unsubscribeSocket(socket: HubSocket): void;
+    /** Whether a session currently has a RUNNING turn (used by the active-turns signal). */
+    isRunning(sessionId: string): boolean;
+    /**
+     * Send a one-off control frame to every socket attached to a session — its
+     * (recently-)tracked turn's origin plus every subscribed socket (#245). Unlike
+     * {@link emit} this is not seq-stamped or buffered; it's for out-of-band signals
+     * like `chat:queued_flushed` that must reach a client that reconnected on a new
+     * socket after the origin died.
+     */
+    broadcast(sessionId: string, msg: HubMessage): void;
+    /** Whether a session currently has a RUNNING turn plus its job id, or null. */
+    activeInfo(sessionId: string): ActiveInfo | null;
+    /** Snapshot of every session with a running turn (for a newly-connected client). */
+    runningSessions(): ActiveInfo[];
+    /** Register a turn under its resolved session id, evicting any prior turn there. */
+    register(turn: Turn, sessionId: string): void;
+    /** Stamp `seq`, buffer (with trim), and fan out to origin + subscribers. */
+    emit(turn: Turn, base: HubMessageInput): void;
+    /** Mark a turn finished; retain its buffer briefly for an end-of-turn reconnect. */
+    end(turn: Turn): void;
+    /**
+     * Re-broadcast a running turn's active state once its jobId becomes known, so
+     * clients can arm the Stop button before the first content frame (Paddock#111).
+     * No-op if the turn isn't running or its session id isn't resolved yet (a new
+     * chat learns the jobId together with its session id on the first frame).
+     */
+    jobIdResolved(turn: Turn): void;
+    private fireActive;
+    private recipients;
+    private evict;
+    private static write;
+}
+/**
+ * A per-turn handle the WS layer drives: stamp/fan-out frames via {@link emit},
+ * learn the session id via {@link setSession}, and finish via {@link end}.
+ */
+export declare class TurnHandle {
+    private readonly hub;
+    private readonly turn;
+    constructor(hub: SessionHub, turn: Turn);
+    get jobId(): string | null;
+    setJobId(id: string): void;
+    /** Register (or move) this turn under its now-known session id. Idempotent. */
+    setSession(sessionId: string): void;
+    /** Buffer + fan out one frame to every live socket attached to this turn's session. */
+    emit(base: HubMessageInput): void;
+    /** Finish the turn (buffer retained briefly for a late reconnect). */
+    end(): void;
+}
+export {};