@edspencer/paddock 0.0.1 → 0.56.0

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

@@ -0,0 +1,215 @@
+import { ok, fail, errText, truncateText, redactPaths, resolveModelArg, coercePrompts, FORK_BATCH_MAX, } from "./self-mcp-util.js";
+// The SAME shape validators `ProjectStore.create` uses, so the tool's up-front
+// checks can't drift from the store's (issue #467). `project-paths.ts` is pure
+// (node:path only), so importing it keeps these handlers fleet-free/unit-testable.
+import { SLUG_RE, isValidRepoUrl } from "./project-paths.js";
+import { PROJECT_STATUSES } from "./project-types.js";
+export function createChatHandler(write) {
+    return async (args) => {
+        try {
+            const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+            if (!prompt)
+                return fail("Error: `prompt` is required (the first turn for the new chat).");
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const name = typeof args.name === "string" && args.name.trim().length > 0 ? args.name.trim() : undefined;
+            const preloadContext = typeof args.preload_context === "boolean" ? args.preload_context : undefined;
+            // Per-chat model override (#336): validated against the picker allow-list; a
+            // non-blank unknown id is rejected with an actionable error instead of being
+            // silently ignored.
+            const modelResult = resolveModelArg(args.model);
+            if (typeof modelResult === "string")
+                return fail(modelResult);
+            const model = modelResult.model;
+            const { sessionId } = await write.createChat(project, prompt, { name, preloadContext, model });
+            // Echo the human-readable name + kickoff prompt so the chat renders with its
+            // real title (not just a link) both live and on reload (#253). When no name
+            // was given the web derives a title from the prompt (matching the sidebar's
+            // auto-name). Prompt is capped to bound the tool-result payload. `model` is
+            // echoed (when overridden) so the tool result records which model the spawned
+            // chat runs on (#336).
+            return ok({ created: true, project, sessionId, name, model, prompt: truncateText(prompt) });
+        }
+        catch (error) {
+            return fail(`Error creating chat: ${errText(error)}`);
+        }
+    };
+}
+export function forkChatHandler(write) {
+    return async (args) => {
+        try {
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const explicit = typeof args.session_id === "string" ? args.session_id.trim() : "";
+            const sourceSessionId = explicit.length > 0 ? explicit : write.currentSessionId();
+            if (!sourceSessionId) {
+                return fail("no chat to fork (current chat id not yet known — pass session_id)");
+            }
+            const prompt = typeof args.prompt === "string" && args.prompt.trim().length > 0 ? args.prompt.trim() : undefined;
+            const name = typeof args.name === "string" && args.name.trim().length > 0 ? args.name.trim() : undefined;
+            // Per-chat model override (#336): validated against the picker allow-list.
+            // Only applies to a kickoff turn — a fork without `prompt` runs no turn.
+            const modelResult = resolveModelArg(args.model);
+            if (typeof modelResult === "string")
+                return fail(modelResult);
+            const model = modelResult.model;
+            const { sessionId } = await write.forkChat({ projectSlug: project, sourceSessionId, prompt, name, model });
+            return ok({
+                forked: true,
+                project,
+                sessionId,
+                from: sourceSessionId,
+                name,
+                model,
+                prompt: prompt ? truncateText(prompt) : undefined,
+            });
+        }
+        catch (error) {
+            return fail(`Error forking chat: ${errText(error)}`);
+        }
+    };
+}
+export function sendMessageHandler(write) {
+    return async (args) => {
+        try {
+            const sessionId = typeof args.session_id === "string" ? args.session_id.trim() : "";
+            const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+            if (!sessionId)
+                return fail("Error: `session_id` is required (get it from list_chats).");
+            if (!prompt)
+                return fail("Error: `prompt` is required (the message to send).");
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            await write.sendMessage(project, sessionId, prompt);
+            // Echo the sent message so the tool renders the actual message text (#253).
+            return ok({ sent: true, project, sessionId, prompt: truncateText(prompt) });
+        }
+        catch (error) {
+            return fail(`Error sending message: ${errText(error)}`);
+        }
+    };
+}
+/**
+ * Handler factory for archive_chat / unarchive_chat. Both resolve the target the
+ * same way — `session_id` OPTIONAL, defaulting to the CURRENT chat so an agent can
+ * archive ITSELF without knowing its own id (mirrors fork_chat's self-default) —
+ * and differ only in the boolean they set. `archived` selects which tool this is.
+ */
+export function archiveChatHandler(write, archived) {
+    const verb = archived ? "archiving" : "unarchiving";
+    return async (args) => {
+        try {
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const explicit = typeof args.session_id === "string" ? args.session_id.trim() : "";
+            const sessionId = explicit.length > 0 ? explicit : write.currentSessionId();
+            if (!sessionId) {
+                return fail("no chat to archive (current chat id not yet known — pass session_id)");
+            }
+            await write.setArchived(project, sessionId, archived);
+            return ok({ archived, project, sessionId });
+        }
+        catch (error) {
+            return fail(`Error ${verb} chat: ${errText(error)}`);
+        }
+    };
+}
+/**
+ * `create_project` (issue #467) — provision a whole new project. The one write tool
+ * that does NOT act inside an existing project, which is why it sits behind its own
+ * `projectsMcpEnabled` gate.
+ *
+ * Pure, like its siblings: it trims + SHAPE-validates the args (using the very same
+ * `SLUG_RE` / `isValidRepoUrl` / `PROJECT_STATUSES` the store and DTO use, so there
+ * is no second definition of "valid") and delegates to `write.createProject`, which
+ * runs `ProjectStore.create` + `ensureProjectAgent` — literally the REST create path.
+ * The up-front checks are a fast, actionable-error convenience, NOT a replacement for
+ * the store's own validation: the store still rejects a duplicate slug, a bad URL and
+ * an unclonable repo, and still rolls the whole project dir back on a clone failure.
+ */
+export function createProjectHandler(write) {
+    return async (args) => {
+        try {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name)
+                return fail("Error: `name` is required (the project's display name).");
+            const slugArg = typeof args.slug === "string" ? args.slug.trim() : "";
+            // Only validate a slug the caller actually SUPPLIED — an omitted slug is
+            // derived from `name` by the store (slugify), which can't produce a bad one.
+            if (slugArg && !SLUG_RE.test(slugArg)) {
+                return fail(`Error: invalid slug "${slugArg}" — must be kebab-case (lowercase a-z, 0-9 and ` +
+                    "single hyphens, e.g. \"my-new-project\"). Omit `slug` to derive it from `name`.");
+            }
+            const repoArg = typeof args.repo === "string" ? args.repo.trim() : "";
+            if (repoArg && !isValidRepoUrl(repoArg)) {
+                return fail(`Error: invalid repo URL "${repoArg}" — expected an https://, git://, ssh:// or ` +
+                    "git@host:owner/repo url. Omit `repo` to create a notebook project.");
+            }
+            const statusArg = typeof args.status === "string" ? args.status.trim().toLowerCase() : "";
+            if (statusArg && !PROJECT_STATUSES.includes(statusArg)) {
+                return fail(`Error: unknown status "${statusArg}". Valid statuses: ${PROJECT_STATUSES.join(", ")}.`);
+            }
+            const summary = typeof args.summary === "string" ? args.summary.trim() : "";
+            const area = typeof args.area === "string" ? args.area.trim() : "";
+            const input = {
+                name,
+                ...(slugArg ? { slug: slugArg } : {}),
+                ...(repoArg ? { repo: repoArg } : {}),
+                ...(summary ? { summary } : {}),
+                ...(area ? { group: area } : {}),
+                ...(statusArg ? { status: statusArg } : {}),
+            };
+            const project = await write.createProject(input);
+            return ok({ created: true, ...project });
+        }
+        catch (error) {
+            // Redact server filesystem paths: a clone failure arrives as git's whole argv
+            // (`Command failed: git clone -- <url> <dest>`), and the agent needs the repo
+            // URL + git's reason, not our on-disk layout. Capped so a verbose git failure
+            // can't flood the tool result.
+            return fail(`Error creating project: ${truncateText(redactPaths(errText(error)))}`);
+        }
+    };
+}
+export function forkChatBatchHandler(write) {
+    return async (args) => {
+        try {
+            const prompts = coercePrompts(args.prompts);
+            if (prompts.length === 0) {
+                return fail("Error: `prompts` is required — a non-empty list of directive strings " +
+                    "(a JSON array, or one directive per line).");
+            }
+            if (prompts.length > FORK_BATCH_MAX) {
+                return fail(`Error: too many prompts (${prompts.length}); max ${FORK_BATCH_MAX} forks per call.`);
+            }
+            if (prompts.some((p) => p.length === 0)) {
+                return fail("Error: every entry in `prompts` must be a non-empty string.");
+            }
+            const clean = prompts;
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const project = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const explicit = typeof args.session_id === "string" ? args.session_id.trim() : "";
+            const sourceSessionId = explicit.length > 0 ? explicit : write.currentSessionId();
+            if (!sourceSessionId) {
+                return fail("no chat to fork (current chat id not yet known — pass session_id)");
+            }
+            const namePrefix = typeof args.name_prefix === "string" && args.name_prefix.trim().length > 0 ? args.name_prefix.trim() : undefined;
+            // Per-chat model override (#336): one model for the WHOLE fan-out (each fork's
+            // kickoff turn runs on it), validated against the picker allow-list.
+            const modelResult = resolveModelArg(args.model);
+            if (typeof modelResult === "string")
+                return fail(modelResult);
+            const model = modelResult.model;
+            // Concurrent fan-out; herdctl enforces the real concurrency cap downstream.
+            const forks = await Promise.all(clean.map(async (prompt, i) => {
+                const name = namePrefix ? `${namePrefix} ${i + 1}` : undefined;
+                const { sessionId } = await write.forkChat({ projectSlug: project, sourceSessionId, prompt, name, model });
+                return { sessionId, prompt };
+            }));
+            return ok({ count: forks.length, source: sourceSessionId, model, forks });
+        }
+        catch (error) {
+            return fail(`Error forking chat batch: ${errText(error)}`);
+        }
+    };
+}

package/packages/server/dist/self-mcp.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Paddock self-management MCP — assembly root (issue #214).
+ *
+ * Exposes the `paddock_manage` tools that let a keeper agent inspect and drive
+ * Paddock itself: enumerate projects/chats + read transcripts (READ, always on),
+ * create/fork/message/archive chats (WRITE, Phase 2), and manage a project's
+ * unified triggers (Epic T / T3). This module is the thin assembly layer — it
+ * wires the extracted pieces into one {@link InjectedMcpServerDef}, conditionally
+ * by capability tier, and owns the public name-map exports. The actual logic lives
+ * in siblings, all re-exported here so existing importers keep one import path:
+ *   - `self-mcp-types.ts`        — the DTOs + the two per-turn context bags
+ *   - `self-mcp-util.ts`         — result envelopes, clamps, arg coercion + caps
+ *   - `self-mcp-descriptions.ts` — the agent-facing `*_DESC` prose
+ *   - `self-mcp-read.ts`         — list_projects / list_chats / read_chat handlers
+ *   - `self-mcp-write.ts`        — create/fork/send/archive/fork-batch + create_project handlers
+ *   - `self-mcp-triggers.ts`     — list/set/remove/run trigger handlers
+ *
+ * ── How it reaches the keeper ───────────────────────────────────────────────
+ * Injected via herdctl's `injectedMcpServers` mechanism, exactly like the
+ * send_file tool (see send-file-mcp.ts, which documents both routes): on the SDK
+ * runtime — how chats run by default — the def becomes an in-process SDK MCP
+ * server; on the CLI runtime (the sweeper, triggers, `driveMode: batch`) the
+ * agent is a separate `claude -p` process that can't reach one, so herdctl stands
+ * up a localhost HTTP MCP bridge instead. Either way herdctl auto-allowlists the
+ * server's `mcp__<name>__*` tools. The tools
+ * surface to the agent as `mcp__paddock_manage__{list_projects,list_chats,…}`.
+ *
+ * The module stays pure: it takes narrow bags of async callbacks (wired to
+ * ProjectStore/HerdctlService by the caller) so the trimming/validation logic is
+ * unit-testable without the fleet. Tool outputs are plain JSON text for the AGENT
+ * to read (not a render envelope like send_file).
+ */
+import type { InjectedMcpServerDef } from "@herdctl/core";
+import type { SelfMcpContext, SelfMcpWriteContext } from "./self-mcp-types.js";
+export type { SelfMcpProject, SelfMcpChat, SelfMcpMessage, SelfMcpTrigger, SelfMcpContext, SelfMcpWriteContext, SelfMcpCreateProjectInput, SelfMcpCreatedProject, } from "./self-mcp-types.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";
+/** Assembly-time options for {@link selfMcpServerDef}. */
+export interface SelfMcpServerDefOptions {
+    /**
+     * Which tools to OFFER, by bare tool name (`"read_chat"`, not the
+     * `mcp__paddock_manage__` form). Used by the Management API (#312) to hide
+     * out-of-scope verbs from an external principal. Omit to offer everything.
+     */
+    toolFilter?: (toolName: string) => boolean;
+}
+/**
+ * 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 declare function selfMcpServerDef(context: SelfMcpContext, write?: SelfMcpWriteContext, opts?: SelfMcpServerDefOptions): InjectedMcpServerDef;
+/** The record key + the fully-qualified tool names the agent sees. */
+export declare const SELF_MCP_SERVER_KEY = "paddock_manage";
+export declare const SELF_MCP_TOOL_NAMES: {
+    readonly listProjects: "mcp__paddock_manage__list_projects";
+    readonly listChats: "mcp__paddock_manage__list_chats";
+    readonly readChat: "mcp__paddock_manage__read_chat";
+};
+/** The fully-qualified names of the Phase-2 WRITE tools (only present when the write flag is on). */
+export declare const SELF_MCP_WRITE_TOOL_NAMES: {
+    readonly createChat: "mcp__paddock_manage__create_chat";
+    readonly forkChat: "mcp__paddock_manage__fork_chat";
+    readonly sendMessage: "mcp__paddock_manage__send_message";
+    readonly archiveChat: "mcp__paddock_manage__archive_chat";
+    readonly unarchiveChat: "mcp__paddock_manage__unarchive_chat";
+    readonly forkChatBatch: "mcp__paddock_manage__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 declare const SELF_MCP_PROJECT_TOOL_NAMES: {
+    readonly createProject: "mcp__paddock_manage__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 declare const SELF_MCP_TRIGGER_TOOL_NAMES: {
+    readonly listTriggers: "mcp__paddock_manage__list_triggers";
+    readonly setTrigger: "mcp__paddock_manage__set_trigger";
+    readonly removeTrigger: "mcp__paddock_manage__remove_trigger";
+    readonly runTrigger: "mcp__paddock_manage__run_trigger";
+};