@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/agent/mcp-server.js

@@ -0,0 +1,544 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WorkflowNotFoundError } from "../workflow/workflow-manager.js";
+import { WorkflowSnapshotSchema, WorkflowStatusSchema, WorkflowTaskGraphSchema, SessionDigestSchema, } from "../messages.js";
+import { AgentStatusEnum } from "./mcp-shared.js";
+import { expandUserPath } from "../path-utils.js";
+import { ensureValidJson } from "../json-utils.js";
+import { createPaseoToolCatalog } from "./tools/paseo-tools.js";
+// --- Workflow tool input schemas (Story 1.4) --------------------------------
+// The task-graph shape mirrors the TS interfaces ported in Story 1.2
+// (`workflow/workflow-manager.ts` — TaskNode/TaskGraphMetadata/TaskGraph). The
+// Zod surface is single-sourced as `WorkflowTaskGraphSchema` in the protocol
+// (Epic 3, Story 3.3) and reused here AND by the client-facing `workflow.start`
+// RPC — one parse boundary, no divergent copy. The inferred shape stays
+// assignable to `CreateWorkflowInput.graph`.
+const workflowStartArgsSchema = z.object({
+    graph: WorkflowTaskGraphSchema.describe("Decomposed task graph that drives child-agent spawning"),
+    provider: z
+        .string()
+        .describe("Agent provider each spawned child runs, for example codex or claude"),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Working directory all child agents inherit; defaults to the caller agent's cwd"),
+    model: z.string().optional().describe("Optional provider model each child is spawned with"),
+    title: z.string().optional().describe("Optional workflow display title; defaults to the goal"),
+    labels: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Optional labels copied onto every spawned child alongside the workflow id"),
+});
+const workflowIdArgsSchema = z.object({
+    workflowId: z.string().describe("Workflow id returned by workflow_start"),
+});
+function isZodSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.safeParseAsync === "function");
+}
+function relaxMcpOutputSchema(outputSchema) {
+    if (!outputSchema) {
+        return outputSchema;
+    }
+    if (isZodSchema(outputSchema)) {
+        return outputSchema instanceof z.ZodObject ? outputSchema.passthrough() : outputSchema;
+    }
+    return z.object(outputSchema).passthrough();
+}
+function relaxMcpToolOutputSchema(config) {
+    if (config.outputSchema === undefined) {
+        return config;
+    }
+    return {
+        ...config,
+        outputSchema: relaxMcpOutputSchema(config.outputSchema),
+    };
+}
+function formatStructuredContentForModel(structuredContent) {
+    if (!structuredContent ||
+        typeof structuredContent !== "object" ||
+        Array.isArray(structuredContent)) {
+        return JSON.stringify(structuredContent, null, 2);
+    }
+    const record = structuredContent;
+    const summary = [];
+    for (const [key, value] of Object.entries(record)) {
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        summary.push(`${key}_count=${value.length}`);
+        const ids = value
+            .map((item) => item && typeof item === "object" && !Array.isArray(item)
+            ? item.id
+            : null)
+            .filter((id) => typeof id === "string" && id.length > 0);
+        if (ids.length === value.length && ids.length > 0) {
+            summary.push(`${key}_ids=${ids.join(",")}`);
+        }
+    }
+    const json = JSON.stringify(structuredContent, null, 2);
+    return summary.length > 0 ? `${summary.join("\n")}\n\n${json}` : json;
+}
+function addModelVisibleStructuredContent(result) {
+    if (result.structuredContent === undefined || result.content.length > 0) {
+        return result;
+    }
+    return {
+        ...result,
+        content: [
+            {
+                type: "text",
+                text: formatStructuredContentForModel(result.structuredContent),
+            },
+        ],
+    };
+}
+function toMcpToolResult(result) {
+    return addModelVisibleStructuredContent({
+        content: result.content,
+        ...(result.structuredContent !== undefined
+            ? { structuredContent: result.structuredContent }
+            : {}),
+        ...(result.isError !== undefined ? { isError: result.isError } : {}),
+    });
+}
+export async function createAgentMcpServer(options) {
+    const { agentManager, callerAgentId, workflowManager, broadcastToClients } = options;
+    const catalog = await createPaseoToolCatalog(options);
+    const server = new McpServer({
+        name: "agent-mcp",
+        version: "2.0.0",
+    });
+    const registerRawTool = server.registerTool.bind(server);
+    // Loose typing on `config`/`handler` here is deliberate: zod 3's MCP-SDK
+    // ZodRawShape generic chain produces TS2589 "type instantiation excessively
+    // deep" through the McpServer["registerTool"] signature at every call site
+    // once the schemas grow past trivial shape. Typing the handler params as
+    // `any` keeps inference shallow AND prevents TS7031 implicit-any errors at
+    // every tool's `async (args, extra) =>` arrow. Runtime shape unchanged — we
+    // still hand off to the raw bound method.
+    const registerTool = (name, config, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const relaxed = relaxMcpToolOutputSchema(config);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const wrappedHandler = (async (args, extra) => 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        addModelVisibleStructuredContent((await handler(args, extra))));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        registerRawTool(name, relaxed, wrappedHandler);
+    };
+    for (const tool of catalog.tools.values()) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+        }, async (args, context) => toMcpToolResult(await catalog.executeTool(tool.name, args, { signal: context?.signal })));
+    }
+    if (options.voiceOnly) {
+        return server;
+    }
+    const resolveScopedCwd = (requestedCwd) => {
+        const trimmed = requestedCwd?.trim();
+        if (trimmed) {
+            return expandUserPath(trimmed);
+        }
+        const caller = callerAgentId ? agentManager.getAgent(callerAgentId) : null;
+        if (caller?.cwd) {
+            return caller.cwd;
+        }
+        throw new Error("cwd is required outside an agent-scoped session");
+    };
+    // --- Open URL on the user's client (API-389) ------------------------------
+    // Ask the user's paired client(s) (phone/desktop/web) to open an https URL in
+    // THEIR own browser, not the host machine. The daemon keeps no
+    // agentId→socket map, so this broadcasts to every connected client; each
+    // client re-validates https and confirms with the user before opening.
+    registerTool("open_url", {
+        title: "Open a URL in the user's client browser",
+        description: "Ask the user's paired Paseo client(s) (phone/desktop/web) to open an https URL in their OWN browser (not the host machine). The client asks the user to confirm before opening. Use for links the user should see on their device, like dashboards, deploy previews, or tenant URLs. Only https URLs are allowed.",
+        inputSchema: { url: z.string() },
+        outputSchema: { requested: z.boolean(), url: z.string() },
+    }, async ({ url }) => {
+        if (!broadcastToClients) {
+            throw new Error("Opening URLs on the client is not supported by this daemon");
+        }
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error(`Invalid URL: ${url}`);
+        }
+        if (parsed.protocol !== "https:") {
+            throw new Error(`Only https URLs may be opened on the client (got "${parsed.protocol}")`);
+        }
+        broadcastToClients({
+            type: "open_url",
+            payload: { url, ...(callerAgentId ? { agentId: callerAgentId } : {}) },
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ requested: true, url }),
+        };
+    });
+    // --- Workflow tools (Story 1.4) -------------------------------------------
+    // Purely additive: these register only when a `workflowManager` is wired in,
+    // and they leave every existing agent tool untouched. Child agents spawned by a
+    // workflow connect to this same MCP server and inherit create_agent/wait_for_agent
+    // /etc. for free. The handlers delegate straight to the daemon-owned manager —
+    // no workflow logic lives here.
+    if (workflowManager) {
+        registerTool("workflow_list", {
+            title: "List workflows",
+            description: "List every known workflow (live and persisted) with its current status, phases, and child agent ids.",
+            inputSchema: {},
+            outputSchema: {
+                workflows: z.array(WorkflowSnapshotSchema),
+            },
+        }, async () => {
+            const workflows = await workflowManager.listWorkflows();
+            return {
+                content: [],
+                structuredContent: ensureValidJson({ workflows }),
+            };
+        });
+        registerTool("workflow_start", {
+            title: "Start workflow",
+            description: "Launch a task-graph workflow. Each task node becomes a child agent spawned through the normal agent lifecycle (inheriting MCP tools, supervision, and persistence). Returns the workflow id and the ids of the spawned child agents.",
+            inputSchema: workflowStartArgsSchema.shape,
+            outputSchema: {
+                workflowId: z.string(),
+                childAgentIds: z.array(z.string()),
+                status: WorkflowStatusSchema,
+            },
+        }, async (rawArgs) => {
+            const args = workflowStartArgsSchema.parse(rawArgs);
+            const cwd = resolveScopedCwd(args.cwd);
+            const baseConfig = {
+                provider: args.provider,
+                cwd,
+                ...(args.model ? { model: args.model } : {}),
+            };
+            const workflow = await workflowManager.createWorkflow({
+                cwd,
+                graph: args.graph,
+                baseConfig,
+                ...(args.title ? { title: args.title } : {}),
+                ...(args.labels ? { labels: args.labels } : {}),
+                ...(callerAgentId ? { parentAgentId: callerAgentId } : {}),
+            });
+            const started = await workflowManager.startWorkflow(workflow.id);
+            return {
+                content: [],
+                structuredContent: ensureValidJson({
+                    workflowId: started.id,
+                    childAgentIds: started.childAgentIds,
+                    status: started.status,
+                }),
+            };
+        });
+        registerTool("workflow_get", {
+            title: "Get workflow",
+            description: "Fetch a single workflow snapshot by id. Returns null when the id is unknown (absence is a valid result, not an error).",
+            inputSchema: workflowIdArgsSchema.shape,
+            outputSchema: {
+                workflow: WorkflowSnapshotSchema.nullable(),
+            },
+        }, async (rawArgs) => {
+            const { workflowId } = workflowIdArgsSchema.parse(rawArgs);
+            try {
+                const workflow = await workflowManager.getWorkflow(workflowId);
+                return {
+                    content: [],
+                    structuredContent: ensureValidJson({ workflow }),
+                };
+            }
+            catch (error) {
+                if (error instanceof WorkflowNotFoundError) {
+                    return {
+                        content: [],
+                        structuredContent: ensureValidJson({ workflow: null }),
+                    };
+                }
+                throw error;
+            }
+        });
+        registerTool("workflow_status", {
+            title: "Get workflow status",
+            description: "Read a workflow's status plus the live lifecycle status of each child agent (read fresh from the agent manager, not the value recorded at spawn time). Throws when the workflow id is unknown.",
+            inputSchema: workflowIdArgsSchema.shape,
+            outputSchema: {
+                workflowId: z.string(),
+                status: WorkflowStatusSchema,
+                children: z.array(z.object({
+                    agentId: z.string(),
+                    status: AgentStatusEnum.nullable(),
+                })),
+            },
+        }, async (rawArgs) => {
+            const { workflowId } = workflowIdArgsSchema.parse(rawArgs);
+            // Throws WorkflowNotFoundError on an unknown id -> MCP error result (AC #4).
+            const workflow = await workflowManager.getWorkflow(workflowId);
+            const children = workflow.childAgentIds.map((agentId) => {
+                const liveAgent = agentManager.getAgent(agentId);
+                return { agentId, status: liveAgent?.lifecycle ?? null };
+            });
+            return {
+                content: [],
+                structuredContent: ensureValidJson({
+                    workflowId: workflow.id,
+                    status: workflow.status,
+                    children,
+                }),
+            };
+        });
+        registerTool("workflow_cancel", {
+            title: "Cancel workflow",
+            description: "Cancel a workflow, flipping it to the terminal cancelled status. Throws when the id is unknown or the workflow has already reached a terminal state.",
+            inputSchema: workflowIdArgsSchema.shape,
+            outputSchema: {
+                workflowId: z.string(),
+                status: WorkflowStatusSchema,
+            },
+        }, async (rawArgs) => {
+            const { workflowId } = workflowIdArgsSchema.parse(rawArgs);
+            // Throws on unknown / already-terminal -> MCP error result (AC #7).
+            const cancelled = await workflowManager.cancelWorkflow(workflowId);
+            return {
+                content: [],
+                structuredContent: ensureValidJson({
+                    workflowId: cancelled.id,
+                    status: cancelled.status,
+                }),
+            };
+        });
+    }
+    // Session tag tools — let Claude (running inside an agent-scoped MCP
+    // session) read and set user-defined tags on its own session. Tags live on
+    // Agent.labels with a `tag:` key prefix (same convention the workspace
+    // right-click "Tag session…" UI uses), so anything Claude sets shows up in
+    // the tab strip + sidebar filters immediately.
+    //
+    // Auto-tagging policy is encoded in a separate Claude Code skill
+    // (skills/paseo-auto-tag/SKILL.md) — these tools are pure infrastructure.
+    const TAG_LABEL_PREFIX = "tag:";
+    function readSessionTags(agentId) {
+        const agent = agentManager.getAgent(agentId);
+        const labels = agent?.labels ?? {};
+        const tags = [];
+        for (const [key, value] of Object.entries(labels)) {
+            if (key.startsWith(TAG_LABEL_PREFIX) && value !== "false") {
+                tags.push(key.slice(TAG_LABEL_PREFIX.length));
+            }
+        }
+        return tags.sort();
+    }
+    server.registerTool("get_session_tags", {
+        title: "Get session tags",
+        description: "Return the list of user-defined tags currently assigned to this session. Use this before calling set_session_tags to avoid duplicating tags or overwriting work the user did manually.",
+        inputSchema: {},
+        outputSchema: {
+            tags: z.array(z.string()),
+        },
+    }, async () => {
+        if (!callerAgentId) {
+            throw new Error("get_session_tags is only available to agent-scoped MCP sessions");
+        }
+        const tags = readSessionTags(callerAgentId);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ tags }),
+        };
+    });
+    server.registerTool("set_session_tags", {
+        title: "Set session tags",
+        description: "Assign user-defined tags to this session. Tags appear in the tab strip and sidebar filters. " +
+            "Default mode 'add' merges into the existing tag set; mode 'replace' wipes existing tags and sets only the new ones; mode 'remove' deletes the named tags. " +
+            "Use sparingly — over-tagging trains the user to ignore tags. Prefer a small set of meaningful tags (client name, project area, urgency). " +
+            "Tag names are case-sensitive, free-form, max 64 chars each, max 20 tags per session.",
+        inputSchema: {
+            tags: z
+                .array(z.string().trim().min(1).max(64))
+                .min(1)
+                .max(20)
+                .describe("Tag names to apply. Free-form strings; no leading/trailing whitespace; max 64 chars each."),
+            mode: z
+                .enum(["add", "replace", "remove"])
+                .optional()
+                .describe("add: merge with existing (default). replace: discard existing tag-prefixed labels, keep only `tags`. remove: delete the named tags from the existing set."),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            appliedTags: z.array(z.string()),
+        },
+    }, async ({ tags, mode }) => {
+        if (!callerAgentId) {
+            throw new Error("set_session_tags is only available to agent-scoped MCP sessions");
+        }
+        const agent = agentManager.getAgent(callerAgentId);
+        const existingLabels = agent?.labels ?? {};
+        const resolvedMode = mode ?? "add";
+        // Partition existing labels into tag-prefixed (managed) vs other (preserved).
+        const preservedLabels = {};
+        const existingTagSet = new Set();
+        for (const [key, value] of Object.entries(existingLabels)) {
+            if (key.startsWith(TAG_LABEL_PREFIX)) {
+                if (value !== "false")
+                    existingTagSet.add(key.slice(TAG_LABEL_PREFIX.length));
+            }
+            else {
+                preservedLabels[key] = value;
+            }
+        }
+        // Normalize incoming tags (trim + dedupe).
+        const incoming = [];
+        const incomingSet = new Set();
+        for (const raw of tags) {
+            const normalized = raw.trim();
+            if (!normalized || incomingSet.has(normalized))
+                continue;
+            incomingSet.add(normalized);
+            incoming.push(normalized);
+        }
+        let nextTagSet;
+        switch (resolvedMode) {
+            case "replace":
+                nextTagSet = incomingSet;
+                break;
+            case "remove":
+                nextTagSet = new Set(existingTagSet);
+                for (const tag of incoming)
+                    nextTagSet.delete(tag);
+                break;
+            default: // "add"
+                nextTagSet = new Set(existingTagSet);
+                for (const tag of incoming)
+                    nextTagSet.add(tag);
+                break;
+        }
+        const nextLabels = { ...preservedLabels };
+        for (const tag of nextTagSet) {
+            nextLabels[`${TAG_LABEL_PREFIX}${tag}`] = "true";
+        }
+        await agentManager.updateAgentMetadata(callerAgentId, { labels: nextLabels });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                ok: true,
+                appliedTags: Array.from(nextTagSet).sort(),
+            }),
+        };
+    });
+    // ── Session digest ───────────────────────────────────────────────────────
+    // Structured per-session metadata so an orchestrator can triage a fleet
+    // without replaying transcripts. Self-reported fields here; keyFiles/summary/
+    // accomplishments are daemon-derived on idle. See docs/session-digest.md.
+    server.registerTool("get_session_digest", {
+        title: "Get session digest",
+        description: "Return this session's digest — goal, nextStep, blockers, links (self-reported) plus keyFiles, summary, accomplishments (daemon-derived) and live status — so you can understand the session without reading its transcript.",
+        inputSchema: {},
+        outputSchema: {
+            digest: SessionDigestSchema.nullable(),
+            status: AgentStatusEnum,
+            requiresAttention: z.boolean(),
+            attentionReason: z.enum(["finished", "error", "permission"]).nullable(),
+        },
+    }, async () => {
+        if (!callerAgentId) {
+            throw new Error("get_session_digest is only available to agent-scoped MCP sessions");
+        }
+        const agent = agentManager.getAgent(callerAgentId);
+        const attention = agent?.attention;
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                digest: agent?.digest ?? null,
+                status: agent?.lifecycle ?? "closed",
+                requiresAttention: attention?.requiresAttention ?? false,
+                attentionReason: attention?.requiresAttention ? attention.attentionReason : null,
+            }),
+        };
+    });
+    server.registerTool("set_session_digest", {
+        title: "Set session digest",
+        description: "Set this session's self-reported digest so an orchestrator can triage it without the transcript. " +
+            "goal: why this session exists (one line). nextStep: where you left off / what's next. " +
+            "blockers: what's stopping progress. links: PR/MR/preview/deploy URLs. " +
+            "Daemon-owned fields (keyFiles, summary, accomplishments) cannot be set here — they're derived automatically on idle. " +
+            "Default mode 'merge' updates only the fields you pass (unioning blockers/links); 'replace' overwrites the fields you pass.",
+        inputSchema: {
+            goal: z.string().max(280).optional(),
+            nextStep: z.string().max(280).optional(),
+            blockers: z.array(z.string().min(1).max(200)).max(10).optional(),
+            links: z
+                .array(z.object({
+                kind: z.enum(["pr", "mr", "issue", "deploy", "preview", "doc", "other"]),
+                url: z.string().min(1).max(500),
+                label: z.string().max(80).optional(),
+            }))
+                .max(20)
+                .optional(),
+            mode: z.enum(["merge", "replace"]).optional(),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            digest: SessionDigestSchema,
+        },
+    }, async ({ goal, nextStep, blockers, links, mode }) => {
+        if (!callerAgentId) {
+            throw new Error("set_session_digest is only available to agent-scoped MCP sessions");
+        }
+        const existing = agentManager.getAgent(callerAgentId)?.digest;
+        const resolvedMode = mode ?? "merge";
+        // Preserve daemon-owned fields (keyFiles/summary/accomplishments/generatedAt)
+        // — they're never settable here, only carried forward.
+        const next = { ...existing };
+        if (goal !== undefined) {
+            next.goal = goal;
+        }
+        if (nextStep !== undefined) {
+            next.nextStep = nextStep;
+        }
+        if (blockers !== undefined) {
+            next.blockers =
+                resolvedMode === "replace" ? blockers : unionStrings(existing?.blockers, blockers);
+        }
+        if (links !== undefined) {
+            next.links = resolvedMode === "replace" ? links : unionLinksByUrl(existing?.links, links);
+        }
+        next.selfReportedAt = new Date().toISOString();
+        await agentManager.updateAgentMetadata(callerAgentId, { digest: next });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ ok: true, digest: next }),
+        };
+    });
+    return server;
+}
+function unionStrings(existing, incoming) {
+    const out = [...(existing ?? [])];
+    for (const value of incoming) {
+        if (!out.includes(value)) {
+            out.push(value);
+        }
+    }
+    return out;
+}
+function unionLinksByUrl(existing, incoming) {
+    const out = [...(existing ?? [])];
+    for (const link of incoming) {
+        const idx = out.findIndex((candidate) => candidate.url === link.url);
+        if (idx >= 0) {
+            out[idx] = link;
+        }
+        else {
+            out.push(link);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=mcp-server.js.map