@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/self-mcp.js

@@ -0,0 +1,448 @@
+import { FORK_BATCH_MAX, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, } from "./self-mcp-util.js";
+import { MODEL_ARG_DESC, LIST_PROJECTS_DESC, LIST_CHATS_DESC, READ_CHAT_DESC, CREATE_CHAT_DESC, FORK_CHAT_DESC, SEND_MESSAGE_DESC, ARCHIVE_CHAT_DESC, UNARCHIVE_CHAT_DESC, FORK_CHAT_BATCH_DESC, CREATE_PROJECT_DESC, SET_TRIGGER_DESC, REMOVE_TRIGGER_DESC, RUN_TRIGGER_DESC, LIST_TRIGGERS_DESC, } from "./self-mcp-descriptions.js";
+import { listProjectsHandler, listChatsHandler, readChatHandler } from "./self-mcp-read.js";
+import { createChatHandler, forkChatHandler, sendMessageHandler, archiveChatHandler, forkChatBatchHandler, createProjectHandler, } from "./self-mcp-write.js";
+import { PROJECT_STATUSES } from "./project-types.js";
+import { listTriggersHandler, setTriggerHandler, removeTriggerHandler, runTriggerHandler, } from "./self-mcp-triggers.js";
+export { FORK_BATCH_MAX, redactPaths, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, READ_CHAT_MAX_TEXT, clampLimit, truncateText, resolveModelArg, coercePrompts, coerceToolList, coerceBoolean, } from "./self-mcp-util.js";
+const SERVER_NAME = "paddock_manage";
+/** The always-on READ tools (list_projects / list_chats / read_chat). */
+function readTools(context) {
+    return [
+        {
+            name: "list_projects",
+            description: LIST_PROJECTS_DESC,
+            inputSchema: { type: "object", properties: {} },
+            handler: listProjectsHandler(context),
+        },
+        {
+            name: "list_chats",
+            description: LIST_CHATS_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: {
+                        type: "string",
+                        description: "Workspace to filter by: a project slug, or the empty string \"\" for the " +
+                            "ROOT workspace (the instance's own top-level directory — see list_projects' " +
+                            "`root`). Omit entirely to list chats across ALL workspaces, root included.",
+                    },
+                    include_archived: {
+                        type: "boolean",
+                        description: "Include archived chats. Defaults to false, matching the web UI. " +
+                            "Pass true when you need an archived chat's session_id (e.g. to " +
+                            "read or unarchive it) — nothing else surfaces session ids.",
+                    },
+                },
+            },
+            handler: listChatsHandler(context),
+        },
+        {
+            name: "read_chat",
+            description: READ_CHAT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: {
+                        type: "string",
+                        description: "Workspace that owns the chat — a project slug, or the empty string \"\" for " +
+                            "the ROOT workspace. Use the `project` value list_chats reported, verbatim.",
+                    },
+                    session_id: { type: "string", description: "The chat's sessionId (from list_chats)." },
+                    limit: {
+                        type: "number",
+                        description: `How many trailing messages to return (default ${READ_CHAT_DEFAULT_LIMIT}, max ${READ_CHAT_MAX_LIMIT}).`,
+                    },
+                },
+                required: ["project", "session_id"],
+            },
+            handler: readChatHandler(context),
+        },
+    ];
+}
+/** The Phase-2 WRITE tools (create/fork/send/archive/unarchive/fork-batch). */
+function writeTools(write) {
+    return [
+        {
+            name: "create_chat",
+            description: CREATE_CHAT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    prompt: { type: "string", description: "The first turn to send to the new chat." },
+                    project: {
+                        type: "string",
+                        description: "Project slug to create the chat in. Omit to use the current project.",
+                    },
+                    name: {
+                        type: "string",
+                        description: "Concise 3–5 word display name for the new chat (e.g. \"Fix login redirect bug\"). " +
+                            "Strongly recommended: without it the title falls back to a long auto-summary.",
+                    },
+                    preload_context: {
+                        type: "boolean",
+                        description: "Seed the new chat with the project's OVERVIEW.md + CHANGELOG.md.",
+                    },
+                    model: { type: "string", description: MODEL_ARG_DESC },
+                },
+                required: ["prompt"],
+            },
+            handler: createChatHandler(write),
+        },
+        {
+            name: "fork_chat",
+            description: FORK_CHAT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the source chat. Omit to use the current project.",
+                    },
+                    session_id: {
+                        type: "string",
+                        description: "Source chat's sessionId (from list_chats). Omit to fork the CURRENT chat.",
+                    },
+                    prompt: { type: "string", description: "Optional first turn to kick off the fork." },
+                    name: { type: "string", description: "Optional display name for the forked chat." },
+                    model: {
+                        type: "string",
+                        description: `${MODEL_ARG_DESC} Applies to the kickoff turn only (a fork with no \`prompt\` runs no turn).`,
+                    },
+                },
+            },
+            handler: forkChatHandler(write),
+        },
+        {
+            name: "send_message",
+            description: SEND_MESSAGE_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: { type: "string", description: "Target chat's sessionId (from list_chats)." },
+                    prompt: { type: "string", description: "The message to send as a new turn." },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the chat. Omit to use the current project.",
+                    },
+                },
+                required: ["session_id", "prompt"],
+            },
+            handler: sendMessageHandler(write),
+        },
+        {
+            name: "archive_chat",
+            description: ARCHIVE_CHAT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: {
+                        type: "string",
+                        description: "Chat's sessionId (from list_chats). Omit to archive the CURRENT chat (yourself).",
+                    },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the chat. Omit to use the current project.",
+                    },
+                },
+            },
+            handler: archiveChatHandler(write, true),
+        },
+        {
+            name: "unarchive_chat",
+            description: UNARCHIVE_CHAT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    session_id: {
+                        type: "string",
+                        description: "Chat's sessionId (from list_chats). Omit to unarchive the CURRENT chat (yourself).",
+                    },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the chat. Omit to use the current project.",
+                    },
+                },
+            },
+            handler: archiveChatHandler(write, false),
+        },
+        {
+            name: "fork_chat_batch",
+            description: FORK_CHAT_BATCH_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    // Declared as a STRING (not array): the CLI-runtime MCP transport
+                    // reliably carries string args but has dropped array-typed args in
+                    // practice. The handler accepts a JSON array too (coercePrompts), but
+                    // telling the model to emit one directive per line is what works.
+                    prompts: {
+                        type: "string",
+                        description: `The fork directives — ONE per line (1..${FORK_BATCH_MAX} lines), each a non-empty instruction for that fork. A JSON array of strings is also accepted.`,
+                    },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the source chat. Omit to use the current project.",
+                    },
+                    session_id: {
+                        type: "string",
+                        description: "Shared fork source's sessionId. Omit to fork the CURRENT chat.",
+                    },
+                    name_prefix: {
+                        type: "string",
+                        description: 'Optional; each fork is named "<name_prefix> <i>" (1-based).',
+                    },
+                    model: {
+                        type: "string",
+                        description: `${MODEL_ARG_DESC} Applies to EVERY fork's kickoff turn in this fan-out.`,
+                    },
+                },
+                required: ["prompts"],
+            },
+            handler: forkChatBatchHandler(write),
+        },
+    ];
+}
+/**
+ * The PROJECT tools (issue #467 — `create_project`). Appended only when
+ * {@link SelfMcpWriteContext.projectsMcpEnabled} is on: the same coarse binary gate
+ * as the trigger tools (when off the tool is ABSENT, not present-but-refusing). Its
+ * own flag because — unlike every other write tool — this one provisions
+ * instance-level state and clones a caller-supplied git URL.
+ */
+function projectTools(write) {
+    return [
+        {
+            name: "create_project",
+            description: CREATE_PROJECT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Display name for the new project (required)." },
+                    slug: {
+                        type: "string",
+                        description: "Optional kebab-case url slug (a-z, 0-9, single hyphens). Omit to derive it from `name`.",
+                    },
+                    repo: {
+                        type: "string",
+                        description: "Optional git URL (https://, git://, ssh:// or git@host:owner/repo). Supplying it " +
+                            "makes the project REPO-BACKED: the repo is cloned into a nested checkout that " +
+                            "becomes the keeper's working directory. Omit for a notebook project.",
+                    },
+                    summary: { type: "string", description: "Optional one-line description of the project." },
+                    area: {
+                        type: "string",
+                        description: "Optional area/group the project is filed under in the sidebar.",
+                    },
+                    status: {
+                        type: "string",
+                        enum: [...PROJECT_STATUSES],
+                        description: 'Optional initial status (default "active").',
+                    },
+                },
+                required: ["name"],
+            },
+            handler: createProjectHandler(write),
+        },
+    ];
+}
+/**
+ * The Epic T / T3 unified trigger-management tools (list/set/remove/run). Appended
+ * only when {@link SelfMcpWriteContext.triggersMcpEnabled} is on — a coarse binary
+ * gate: when off the tools are ABSENT (not present-but-refusing). These COLLAPSE
+ * what were the separate schedule + hook verbs.
+ */
+function triggerTools(write) {
+    return [
+        {
+            name: "list_triggers",
+            description: LIST_TRIGGERS_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: {
+                        type: "string",
+                        description: "Project slug to list. Omit to use the current project.",
+                    },
+                },
+            },
+            handler: listTriggersHandler(write),
+        },
+        {
+            name: "set_trigger",
+            description: SET_TRIGGER_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The trigger's stable key (create or update)." },
+                    type: {
+                        type: "string",
+                        enum: ["schedule", "event", "webhook"],
+                        description: "WHEN the trigger fires. Omit on an edit to keep the existing WHEN; supply it " +
+                            "(with its fields) to (re)specify the trigger. \"schedule\" needs `cron` or " +
+                            "`interval`; \"event\" needs `event`; \"webhook\" needs `path` (reserved).",
+                    },
+                    cron: {
+                        type: "string",
+                        description: 'For a "schedule" trigger: a 5-field cron expression (e.g. "0 9 * * *"), host-local time. Exactly one of `cron`/`interval`.',
+                    },
+                    interval: {
+                        type: "string",
+                        description: 'For a "schedule" trigger: a duration string (e.g. "30m", "1h"). Exactly one of `cron`/`interval`.',
+                    },
+                    event: {
+                        type: "string",
+                        description: 'For an "event" trigger: the lifecycle trigger (v1: "onArchive").',
+                    },
+                    path: {
+                        type: "string",
+                        description: 'For a "webhook" trigger: the ingress path (reserved — not yet fired).',
+                    },
+                    prompt: {
+                        type: "string",
+                        description: "Inline instruction the fired turn runs. Provide this OR `prompt_file`.",
+                    },
+                    prompt_file: {
+                        type: "string",
+                        description: 'A `.md` file under the project\'s `.paddock/triggers/` dir (e.g. "daily.md"), ' +
+                            "read at fire time. Alternative to `prompt` for long, version-tracked prompts.",
+                    },
+                    session: {
+                        type: "string",
+                        enum: ["new", "resume"],
+                        description: '"new" (default) → a fresh chat each fire; "resume" → accrete into the trigger\'s one owned session.',
+                    },
+                    tools: {
+                        type: "string",
+                        description: "The fired agent's capability = a deny-by-default allow-list — one per line or " +
+                            'comma-separated (e.g. "Bash, Read, Write"). Omit / empty = a tool-less curator. A JSON array is also accepted.',
+                    },
+                    model: { type: "string", description: "Model override for the fired agent." },
+                    permission_mode: {
+                        type: "string",
+                        enum: ["default", "acceptEdits", "bypassPermissions", "plan"],
+                        description: "Permission mode the fired agent's turns run under.",
+                    },
+                    max_spawn_depth: {
+                        type: "number",
+                        description: "Recursion bound for internal spawning (0 = may not spawn).",
+                    },
+                    max_turns: {
+                        type: "number",
+                        description: "Max agent turns bounding a runaway trigger.",
+                    },
+                    enabled: {
+                        type: "boolean",
+                        description: "Whether the trigger is armed. Default FALSE on a NEW trigger; omitted on an " +
+                            "existing trigger leaves it unchanged (so an `enabled`-only call just flips it).",
+                    },
+                    project: {
+                        type: "string",
+                        description: "Project slug to target. Omit to use the current project.",
+                    },
+                },
+                required: ["name"],
+            },
+            handler: setTriggerHandler(write),
+        },
+        {
+            name: "remove_trigger",
+            description: REMOVE_TRIGGER_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The trigger to remove." },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the trigger. Omit to use the current project.",
+                    },
+                },
+                required: ["name"],
+            },
+            handler: removeTriggerHandler(write),
+        },
+        {
+            name: "run_trigger",
+            description: RUN_TRIGGER_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The trigger to fire now." },
+                    project: {
+                        type: "string",
+                        description: "Project slug that owns the trigger. Omit to use the current project.",
+                    },
+                },
+                required: ["name"],
+            },
+            handler: runTriggerHandler(write),
+        },
+    ];
+}
+/**
+ * Build the injected MCP server definition for the self-management tools, bound to
+ * a per-turn context. The READ tools (list_projects/list_chats/read_chat) are
+ * ALWAYS included. When a {@link SelfMcpWriteContext} is provided (the stricter
+ * write flag is on), the WRITE tools (create_chat/fork_chat/send_message/
+ * archive_chat/unarchive_chat/fork_chat_batch) are appended too; omit it for
+ * unchanged read-only behavior. Two further blocks hang off independent gates ON
+ * that write context: {@link SelfMcpWriteContext.projectsMcpEnabled} (issue #467)
+ * appends the project tool (create_project), and
+ * {@link SelfMcpWriteContext.triggersMcpEnabled} (the per-project trigger-MCP
+ * opt-in, Epic T / T3) appends the unified trigger-management tools (list_triggers/
+ * set_trigger/remove_trigger/run_trigger). Inject under
+ * {@link SELF_MCP_SERVER_KEY}.
+ */
+export function selfMcpServerDef(context, write, opts) {
+    const tools = [...readTools(context)];
+    if (write) {
+        tools.push(...writeTools(write));
+        if (write.projectsMcpEnabled) {
+            tools.push(...projectTools(write));
+        }
+        if (write.triggersMcpEnabled) {
+            tools.push(...triggerTools(write));
+        }
+    }
+    // Scope-driven visibility (#312 M1). Absent ⇒ every assembled tool is offered,
+    // which is the in-process keeper path and every pre-#312 caller. An external
+    // principal passes a filter so it is never shown a verb outside its scope.
+    // This is presentation only — the ops layer is what actually refuses a call.
+    const visible = opts?.toolFilter ? tools.filter((t) => opts.toolFilter(t.name)) : tools;
+    return { name: SERVER_NAME, version: "0.1.0", tools: visible };
+}
+/** The record key + the fully-qualified tool names the agent sees. */
+export const SELF_MCP_SERVER_KEY = SERVER_NAME;
+export const SELF_MCP_TOOL_NAMES = {
+    listProjects: `mcp__${SERVER_NAME}__list_projects`,
+    listChats: `mcp__${SERVER_NAME}__list_chats`,
+    readChat: `mcp__${SERVER_NAME}__read_chat`,
+};
+/** The fully-qualified names of the Phase-2 WRITE tools (only present when the write flag is on). */
+export const SELF_MCP_WRITE_TOOL_NAMES = {
+    createChat: `mcp__${SERVER_NAME}__create_chat`,
+    forkChat: `mcp__${SERVER_NAME}__fork_chat`,
+    sendMessage: `mcp__${SERVER_NAME}__send_message`,
+    archiveChat: `mcp__${SERVER_NAME}__archive_chat`,
+    unarchiveChat: `mcp__${SERVER_NAME}__unarchive_chat`,
+    forkChatBatch: `mcp__${SERVER_NAME}__fork_chat_batch`,
+};
+/**
+ * The fully-qualified name of the PROJECT tool (issue #467), present only when a
+ * write context has {@link SelfMcpWriteContext.projectsMcpEnabled} on.
+ */
+export const SELF_MCP_PROJECT_TOOL_NAMES = {
+    createProject: `mcp__${SERVER_NAME}__create_project`,
+};
+/**
+ * The fully-qualified names of the Epic T / T3 unified trigger-management tools
+ * (only present when a write context has {@link SelfMcpWriteContext.triggersMcpEnabled}
+ * on). These collapse the former schedule (set/remove/list_schedule) + hook
+ * (set/remove/list_hook) verbs.
+ */
+export const SELF_MCP_TRIGGER_TOOL_NAMES = {
+    listTriggers: `mcp__${SERVER_NAME}__list_triggers`,
+    setTrigger: `mcp__${SERVER_NAME}__set_trigger`,
+    removeTrigger: `mcp__${SERVER_NAME}__remove_trigger`,
+    runTrigger: `mcp__${SERVER_NAME}__run_trigger`,
+};

package/packages/server/dist/send-file-mcp.d.ts

@@ -0,0 +1,46 @@
+import type { InjectedMcpServerDef } from "@herdctl/core";
+/** The renderer the web side should use for a sent file. */
+export type SentFileKind = "markdown" | "mermaid" | "code" | "text" | "html" | "image" | "video" | "pdf";
+/**
+ * The JSON envelope returned as the tool's result `output`. The web parses this
+ * off the tool call (live + on reload). `paddockSendFile` is a version/discriminator
+ * so the client can be sure a tool output is one of ours before parsing.
+ */
+export interface SentFileEnvelope {
+    paddockSendFile: 1;
+    filename: string;
+    kind: SentFileKind;
+    language?: string;
+    /** "inline" carries `content`; "file" carries `attachmentId` (bytes in the store). */
+    source: "inline" | "file";
+    content?: string;
+    attachmentId?: string;
+    message?: string;
+}
+/**
+ * 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 declare const MAX_ATTACHMENT_BYTES: number;
+/** Per-turn context for the send-file tool. */
+export interface SendFileContext {
+    /** The agent's working directory — resolves a relative `file_path`. */
+    workingDirectory?: string;
+    /**
+     * Copy a real file's bytes into the attachment store, returning its id. Called
+     * once at send time so the shared file is an immutable snapshot and the render
+     * endpoint never serves an arbitrary path. `filenameForExt` supplies the
+     * stored file's extension (for content-type on serve).
+     */
+    saveAttachment: (bytes: Buffer, filenameForExt: string) => Promise<string>;
+}
+/**
+ * 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 declare function sendFileServerDef(context: SendFileContext): InjectedMcpServerDef;
+/** The record key + resulting fully-qualified tool name the agent sees. */
+export declare const SEND_FILE_SERVER_KEY = "paddock";
+export declare const SEND_FILE_TOOL_NAME = "mcp__paddock__send_file";