@getpaseo/server 0.1.59 → 0.1.61

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

@@ -1,19 +1,23 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { ensureValidJson } from "../json-utils.js";
-import { AgentPermissionRequestPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, } from "../messages.js";
-import { buildStoredAgentPayload, toAgentPayload } from "./agent-projections.js";
+import { AgentPermissionRequestPayloadSchema, AgentListItemPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, } from "../messages.js";
+import { buildStoredAgentPayload, toAgentListItemPayload, toAgentPayload, } from "./agent-projections.js";
 import { curateAgentActivity } from "./activity-curator.js";
 import { ensureAgentLoaded } from "./agent-loading.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./timeline-append.js";
+import { getPaseoWorktreesRoot } from "../../utils/worktree.js";
+import { archivePaseoWorktree, killTerminalsUnderPath, } from "../paseo-worktree-archive-service.js";
 import { WaitForAgentTracker } from "./wait-for-agent-tracker.js";
 import { scheduleAgentMetadataGeneration } from "./agent-metadata-generator.js";
-import { expandUserPath, resolvePathFromBase } from "../path-utils.js";
+import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../path-utils.js";
 import { captureTerminalLines } from "../../terminal/terminal.js";
-import { createAgentWorktree, runAsyncWorktreeBootstrap } from "../worktree-bootstrap.js";
+import { runAsyncWorktreeBootstrap } from "../worktree-bootstrap.js";
 import { ScheduleSummarySchema, StoredScheduleSchema } from "../schedule/types.js";
-import { deletePaseoWorktree, listPaseoWorktrees } from "../../utils/worktree.js";
-import { AgentModelSchema, AgentProviderEnum, AgentStatusEnum, ProviderSummarySchema, parseDurationString, resolveProviderAndModel, sanitizePermissionRequest, sendPromptToAgent, setupFinishNotification, serializeSnapshotWithMetadata, startAgentRun, toScheduleSummary, waitForAgentWithTimeout, } from "./mcp-shared.js";
+import { resolveSnapshotCwd } from "./provider-snapshot-manager.js";
+import { AgentModelSchema, AgentProviderEnum, AgentStatusEnum, ProviderSummarySchema, parseDurationString, resolveRequiredProviderModel, sanitizePermissionRequest, sendPromptToAgent, setupFinishNotification, serializeSnapshotWithMetadata, startAgentRun, toScheduleSummary, waitForAgentWithTimeout, } from "./mcp-shared.js";
+import { toWorktreeRequestError } from "../worktree-errors.js";
+import { join } from "node:path";
 const CLAUDE_TO_CODEX_MODE = {
     plan: "read-only",
     default: "auto",
@@ -45,6 +49,50 @@ function mapModeAcrossProviders(sourceMode, sourceProvider, targetProvider) {
     }
     return sourceMode;
 }
+function parseTimestamp(value) {
+    if (!value) {
+        return 0;
+    }
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function resolveAgentListActivityTime(agent) {
+    return Math.max(parseTimestamp(agent.updatedAt), parseTimestamp(agent.lastUserMessageAt), parseTimestamp(agent.attentionTimestamp), parseTimestamp(agent.archivedAt), parseTimestamp(agent.createdAt));
+}
+function compareAgentListItems(a, b) {
+    const attentionDelta = Number(b.requiresAttention ?? false) - Number(a.requiresAttention ?? false);
+    if (attentionDelta !== 0) {
+        return attentionDelta;
+    }
+    const statusOrder = {
+        running: 0,
+        initializing: 1,
+        idle: 2,
+        error: 3,
+        closed: 4,
+    };
+    const statusDelta = (statusOrder[a.status] ?? 999) - (statusOrder[b.status] ?? 999);
+    if (statusDelta !== 0) {
+        return statusDelta;
+    }
+    return resolveAgentListActivityTime(b) - resolveAgentListActivityTime(a);
+}
+function resolveScheduleProviderAndModel(params) {
+    const providerInput = params.provider?.trim() || params.defaultProvider;
+    const slashIndex = providerInput.indexOf("/");
+    if (slashIndex === -1) {
+        return { provider: providerInput };
+    }
+    const provider = providerInput.slice(0, slashIndex).trim();
+    const model = providerInput.slice(slashIndex + 1).trim();
+    if (!provider || !model) {
+        throw new Error("provider must be <provider> or <provider>/<model>");
+    }
+    return {
+        provider: provider,
+        model,
+    };
+}
 function resolveChildAgentCwd(params) {
     const lockedCwd = params.lockedCwd?.trim();
     if (lockedCwd) {
@@ -147,7 +195,7 @@ export async function createAgentMcpServer(options) {
         if (callerAgent) {
             const hasProviderOverride = params?.provider !== undefined;
             const resolvedProviderModel = hasProviderOverride
-                ? resolveProviderAndModel({
+                ? resolveScheduleProviderAndModel({
                     provider: params?.provider,
                     defaultProvider: callerAgent.provider,
                 })
@@ -192,21 +240,32 @@ export async function createAgentMcpServer(options) {
                 },
             };
         }
+        const resolvedProviderModel = resolveScheduleProviderAndModel({
+            provider: params?.provider,
+            defaultProvider: "claude",
+        });
         return {
             type: "new-agent",
-            config: (() => {
-                const resolvedProviderModel = resolveProviderAndModel({
-                    provider: params?.provider,
-                    defaultProvider: "claude",
-                });
-                return {
-                    provider: resolvedProviderModel.provider,
-                    cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : process.cwd(),
-                    ...(resolvedProviderModel.model ? { model: resolvedProviderModel.model } : {}),
-                };
-            })(),
+            config: {
+                provider: resolvedProviderModel.provider,
+                cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : process.cwd(),
+                ...(resolvedProviderModel.model ? { model: resolvedProviderModel.model } : {}),
+            },
         };
     };
+    const ProviderModelInputSchema = AgentProviderEnum.trim()
+        .refine((value) => value.includes("/"), {
+        message: "provider must be provider/model, for example codex/gpt-5.4",
+    })
+        .refine((value) => {
+        try {
+            resolveRequiredProviderModel(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "provider must be provider/model, for example codex/gpt-5.4" });
     const agentToAgentInputSchema = {
         cwd: z
             .string()
@@ -218,8 +277,7 @@ export async function createAgentMcpServer(options) {
             .min(1, "Title is required")
             .max(60, "Title must be 60 characters or fewer")
             .describe("Short descriptive title (<= 60 chars) summarizing the agent's focus."),
-        provider: AgentProviderEnum.optional().describe("Optional agent implementation to spawn. Defaults to 'claude'."),
-        model: z.string().optional().describe("Model to use (e.g. claude-sonnet-4-20250514)"),
+        provider: ProviderModelInputSchema.describe("Required provider/model pair, for example codex/gpt-5.4."),
         thinking: z.string().optional().describe("Thinking option ID"),
         labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
         initialPrompt: z
@@ -248,8 +306,7 @@ export async function createAgentMcpServer(options) {
             .min(1, "Title is required")
             .max(60, "Title must be 60 characters or fewer")
             .describe("Short descriptive title (<= 60 chars) summarizing the agent's focus."),
-        provider: AgentProviderEnum.optional().describe("Optional agent implementation to spawn. Defaults to 'claude'."),
-        model: z.string().optional().describe("Model to use (e.g. claude-sonnet-4-20250514)"),
+        provider: ProviderModelInputSchema.describe("Required provider/model pair, for example codex/gpt-5.4."),
         thinking: z.string().optional().describe("Thinking option ID"),
         labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
         initialPrompt: z
@@ -269,6 +326,17 @@ export async function createAgentMcpServer(options) {
             .string()
             .optional()
             .describe("Required when worktreeName is set: the base branch to diff/merge against."),
+        refName: z.string().min(1).optional().describe("Optional source ref for worktree creation."),
+        action: z
+            .enum(["branch-off", "checkout"])
+            .optional()
+            .describe("Optional worktree creation action."),
+        githubPrNumber: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional GitHub pull request number to checkout."),
         background: z
             .boolean()
             .optional()
@@ -281,8 +349,8 @@ export async function createAgentMcpServer(options) {
             .describe("Send a notification prompt to the caller agent when this agent finishes, errors, or needs permission. Requires a caller agent context."),
     };
     const createAgentInputSchema = callerAgentId ? agentToAgentInputSchema : topLevelInputSchema;
-    const agentToAgentCreateAgentArgsSchema = z.object(agentToAgentInputSchema);
-    const topLevelCreateAgentArgsSchema = z.object(topLevelInputSchema);
+    const agentToAgentCreateAgentArgsSchema = z.object(agentToAgentInputSchema).strict();
+    const topLevelCreateAgentArgsSchema = z.object(topLevelInputSchema).strict();
     if (options.voiceOnly || options.enableVoiceTools || callerContext?.enableVoiceTools) {
         server.registerTool("speak", {
             title: "Speak",
@@ -321,7 +389,7 @@ export async function createAgentMcpServer(options) {
     }
     server.registerTool("create_agent", {
         title: "Create agent",
-        description: "Create a new Claude or Codex agent tied to a working directory. Optionally run an initial prompt immediately or create a git worktree for the agent.",
+        description: "Create an agent tied to a working directory. Requires provider/model, for example codex/gpt-5.4. Optionally run an initial prompt immediately or create a git worktree for the agent.",
         inputSchema: createAgentInputSchema,
         outputSchema: {
             agentId: z.string(),
@@ -349,13 +417,15 @@ export async function createAgentMcpServer(options) {
         let resolvedCwd;
         let resolvedMode;
         let worktreeConfig;
+        let shouldBootstrapWorktree;
         if (callerAgentId) {
             const callerArgs = agentToAgentCreateAgentArgsSchema.parse(args);
-            provider = callerArgs.provider ?? "claude";
+            const resolvedProviderModel = resolveRequiredProviderModel(callerArgs.provider);
+            provider = resolvedProviderModel.provider;
+            model = resolvedProviderModel.model;
             initialPrompt = callerArgs.initialPrompt;
             background = callerArgs.background ?? false;
             normalizedTitle = callerArgs.title.trim();
-            model = callerArgs.model;
             thinking = callerArgs.thinking;
             labels = callerArgs.labels;
             notifyOnFinish = callerArgs.notifyOnFinish ?? false;
@@ -376,29 +446,39 @@ export async function createAgentMcpServer(options) {
         }
         else {
             const topLevelArgs = topLevelCreateAgentArgsSchema.parse(args);
-            provider = topLevelArgs.provider ?? "claude";
+            const resolvedProviderModel = resolveRequiredProviderModel(topLevelArgs.provider);
+            provider = resolvedProviderModel.provider;
+            model = resolvedProviderModel.model;
             initialPrompt = topLevelArgs.initialPrompt;
             background = topLevelArgs.background ?? false;
             normalizedTitle = topLevelArgs.title.trim();
-            model = topLevelArgs.model;
             thinking = topLevelArgs.thinking;
             labels = topLevelArgs.labels;
             notifyOnFinish = topLevelArgs.notifyOnFinish ?? false;
-            const { cwd, mode, worktreeName, baseBranch } = topLevelArgs;
+            const { cwd, mode, worktreeName, baseBranch, refName, action, githubPrNumber } = topLevelArgs;
             resolvedCwd = expandUserPath(cwd);
             if (worktreeName) {
-                if (!baseBranch) {
+                if (!baseBranch && !refName && !action && githubPrNumber === undefined) {
                     throw new Error("baseBranch is required when creating a worktree");
                 }
-                const worktree = await createAgentWorktree({
-                    branchName: worktreeName,
-                    cwd: resolvedCwd,
-                    baseBranch,
-                    worktreeSlug: worktreeName,
-                    paseoHome: options.paseoHome,
+                const createdWorktree = await createMcpWorktree({
+                    input: {
+                        cwd: resolvedCwd,
+                        worktreeSlug: worktreeName,
+                        refName,
+                        action,
+                        githubPrNumber,
+                        runSetup: false,
+                        paseoHome: options.paseoHome,
+                    },
+                    createPaseoWorktree: options.createPaseoWorktree,
+                    resolveDefaultBranch: baseBranch ? async () => baseBranch : undefined,
+                    workspaceGitService: options.workspaceGitService,
+                    logger: options.logger,
                 });
-                resolvedCwd = worktree.worktreePath;
-                worktreeConfig = worktree;
+                resolvedCwd = createdWorktree.worktree.worktreePath;
+                worktreeConfig = createdWorktree.worktree;
+                shouldBootstrapWorktree = createdWorktree.created;
             }
             resolvedMode = mode;
         }
@@ -420,6 +500,7 @@ export async function createAgentMcpServer(options) {
             void runAsyncWorktreeBootstrap({
                 agentId: snapshot.id,
                 worktree: worktreeConfig,
+                shouldBootstrap: shouldBootstrapWorktree,
                 terminalManager: terminalManager ?? null,
                 appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
                     agentManager,
@@ -443,6 +524,11 @@ export async function createAgentMcpServer(options) {
             explicitTitle: snapshot.config.title,
             paseoHome: options.paseoHome,
             logger: childLogger,
+            deps: options.workspaceGitService
+                ? {
+                    workspaceGitService: options.workspaceGitService,
+                }
+                : undefined,
         });
         try {
             agentManager.recordUserMessage(snapshot.id, trimmedPrompt, {
@@ -692,14 +778,28 @@ export async function createAgentMcpServer(options) {
     });
     server.registerTool("list_agents", {
         title: "List agents",
-        description: "List all live agents managed by the server.",
+        description: "List recent agents as compact metadata.",
         inputSchema: {
             includeArchived: z.boolean().optional().default(false),
+            cwd: z.string().optional(),
+            sinceHours: z
+                .number()
+                .int()
+                .positive()
+                .max(24 * 30)
+                .optional()
+                .default(48),
+            statuses: z.array(AgentStatusEnum).optional(),
+            limit: z.number().int().positive().max(200).optional().default(50),
         },
         outputSchema: {
-            agents: z.array(AgentSnapshotPayloadSchema),
+            agents: z.array(AgentListItemPayloadSchema),
         },
-    }, async ({ includeArchived }) => {
+    }, async ({ includeArchived = false, cwd, sinceHours = 48, statuses, limit = 50 }) => {
+        const callerCwd = callerAgentId ? resolveCallerAgent()?.cwd : undefined;
+        const requestedCwd = cwd?.trim() ? expandUserPath(cwd) : callerCwd;
+        const statusFilter = statuses && statuses.length > 0 ? new Set(statuses) : null;
+        const sinceMs = Date.now() - sinceHours * 60 * 60 * 1000;
         const liveSnapshots = agentManager.listAgents();
         const liveAgents = await Promise.all(liveSnapshots.map((snapshot) => serializeSnapshotWithMetadata(agentStorage, snapshot, childLogger)));
         const liveIds = new Set(liveSnapshots.map((snapshot) => snapshot.id));
@@ -708,9 +808,16 @@ export async function createAgentMcpServer(options) {
             .filter((record) => !record.internal && !liveIds.has(record.id))
             .filter((record) => includeArchived || !record.archivedAt)
             .map((record) => buildStoredAgentPayload(record, requireProviderRegistry(), childLogger));
+        const agents = [...liveAgents, ...storedAgents]
+            .map(toAgentListItemPayload)
+            .filter((agent) => !requestedCwd || isSameOrDescendantPath(requestedCwd, agent.cwd))
+            .filter((agent) => !statusFilter || statusFilter.has(agent.status))
+            .filter((agent) => !agent.archivedAt || resolveAgentListActivityTime(agent) >= sinceMs)
+            .sort(compareAgentListItems)
+            .slice(0, limit);
         return {
             content: [],
-            structuredContent: ensureValidJson({ agents: [...liveAgents, ...storedAgents] }),
+            structuredContent: ensureValidJson({ agents }),
         };
     });
     server.registerTool("cancel_agent", {
@@ -973,15 +1080,29 @@ export async function createAgentMcpServer(options) {
         }
         const scheduleTarget = target === "self"
             ? (() => {
-                if (!callerAgentId) {
+                const callerAgent = resolveCallerAgent();
+                if (!callerAgentId || !callerAgent) {
                     throw new Error("target=self requires a caller agent");
                 }
-                if (provider !== undefined || cwd !== undefined) {
-                    throw new Error("provider and cwd can only be used with target=new-agent");
+                const trimmedCwd = cwd?.trim();
+                if (trimmedCwd && expandUserPath(trimmedCwd) !== callerAgent.cwd) {
+                    throw new Error("cwd can only differ from the caller agent when target=new-agent");
+                }
+                if (provider !== undefined) {
+                    const resolved = resolveScheduleProviderAndModel({
+                        provider,
+                        defaultProvider: callerAgent.provider,
+                    });
+                    if (resolved.provider !== callerAgent.provider ||
+                        (resolved.model !== undefined && resolved.model !== callerAgent.config.model)) {
+                        throw new Error("provider can only differ from the caller agent when target=new-agent");
+                    }
                 }
                 return { type: "agent", agentId: callerAgentId };
             })()
-            : resolveNewAgentScheduleTarget({ provider, cwd });
+            : (() => {
+                return resolveNewAgentScheduleTarget({ provider, cwd });
+            })();
         const schedule = await scheduleService.create({
             prompt: prompt.trim(),
             cadence: every
@@ -1129,7 +1250,7 @@ export async function createAgentMcpServer(options) {
         if (!definition) {
             throw new Error(`Provider ${provider} is not configured`);
         }
-        const models = await definition.fetchModels();
+        const models = await definition.fetchModels({ cwd: resolveSnapshotCwd(), force: false });
         return {
             content: [],
             structuredContent: ensureValidJson({
@@ -1152,9 +1273,11 @@ export async function createAgentMcpServer(options) {
         },
     }, async ({ cwd }) => {
         const resolvedCwd = resolveScopedCwd(cwd, { required: true });
-        const worktrees = await listPaseoWorktrees({
-            cwd: resolvedCwd,
-            paseoHome: options.paseoHome,
+        if (!options.workspaceGitService) {
+            throw new Error("WorkspaceGitService is required to list worktrees");
+        }
+        const worktrees = await options.workspaceGitService.listWorktrees(resolvedCwd, {
+            reason: "mcp:list-worktrees",
         });
         return {
             content: [],
@@ -1169,25 +1292,41 @@ export async function createAgentMcpServer(options) {
                 .string()
                 .optional()
                 .describe("Optional repository cwd. Defaults to the caller agent cwd."),
-            branchName: z.string(),
-            baseBranch: z.string(),
+            branchName: z.string().optional(),
+            baseBranch: z.string().optional(),
+            refName: z.string().min(1).optional(),
+            action: z.enum(["branch-off", "checkout"]).optional(),
+            githubPrNumber: z.number().int().positive().optional(),
         },
         outputSchema: {
             branchName: z.string(),
             worktreePath: z.string(),
         },
-    }, async ({ cwd, branchName, baseBranch }) => {
-        const worktree = await createAgentWorktree({
-            branchName,
-            cwd: resolveScopedCwd(cwd, { required: true }),
-            baseBranch,
-            worktreeSlug: branchName,
-            paseoHome: options.paseoHome,
+    }, async ({ cwd, branchName, baseBranch, refName, action, githubPrNumber }) => {
+        if (!branchName && !refName && githubPrNumber === undefined) {
+            throw new Error("create_worktree requires branchName, refName, or githubPrNumber");
+        }
+        const repoRoot = resolveScopedCwd(cwd, { required: true });
+        const createdWorktree = await createMcpWorktree({
+            input: {
+                cwd: repoRoot,
+                worktreeSlug: branchName,
+                refName,
+                action,
+                githubPrNumber,
+                runSetup: false,
+                paseoHome: options.paseoHome,
+            },
+            createPaseoWorktree: options.createPaseoWorktree,
+            resolveDefaultBranch: baseBranch ? async () => baseBranch : undefined,
+            workspaceGitService: options.workspaceGitService,
+            logger: options.logger,
         });
+        const { worktree } = createdWorktree;
         return {
             content: [],
             structuredContent: ensureValidJson({
-                branchName,
+                branchName: worktree.branchName,
                 worktreePath: worktree.worktreePath,
             }),
         };
@@ -1207,11 +1346,48 @@ export async function createAgentMcpServer(options) {
             success: z.boolean(),
         },
     }, async ({ cwd, worktreePath, worktreeSlug }) => {
-        await deletePaseoWorktree({
-            cwd: resolveScopedCwd(cwd, { required: true }),
-            worktreePath,
-            worktreeSlug,
+        const repoRoot = resolveScopedCwd(cwd, { required: true });
+        if (!worktreePath && !worktreeSlug) {
+            throw new Error("worktreePath or worktreeSlug is required");
+        }
+        if (!options.github) {
+            throw new Error("GitHub service is required to archive worktrees");
+        }
+        if (!options.workspaceGitService) {
+            throw new Error("WorkspaceGitService is required to archive worktrees");
+        }
+        if (!options.archiveWorkspaceRecord) {
+            throw new Error("Workspace registry archiver is required to archive worktrees");
+        }
+        if (!options.emitWorkspaceUpdatesForCwds) {
+            throw new Error("Workspace update emitter is required to archive worktrees");
+        }
+        if (!options.emitSessionMessage) {
+            throw new Error("Session message emitter is required to archive worktrees");
+        }
+        const targetPath = worktreePath ??
+            join(await getPaseoWorktreesRoot(repoRoot, options.paseoHome), worktreeSlug);
+        await archivePaseoWorktree({
             paseoHome: options.paseoHome,
+            github: options.github,
+            workspaceGitService: options.workspaceGitService,
+            agentManager,
+            agentStorage,
+            archiveWorkspaceRecord: options.archiveWorkspaceRecord,
+            emit: options.emitSessionMessage,
+            emitWorkspaceUpdatesForCwds: options.emitWorkspaceUpdatesForCwds,
+            isPathWithinRoot: isSameOrDescendantPath,
+            killTerminalsUnderPath: (rootPath) => killTerminalsUnderPath({
+                terminalManager: terminalManager ?? null,
+                isPathWithinRoot: isSameOrDescendantPath,
+                killTrackedTerminal: () => { },
+                sessionLogger: childLogger,
+            }, rootPath),
+            sessionLogger: childLogger,
+        }, {
+            targetPath,
+            repoRoot,
+            requestId: "mcp:archive_worktree",
         });
         return {
             content: [],
@@ -1327,4 +1503,39 @@ export async function createAgentMcpServer(options) {
     });
     return server;
 }
+async function createMcpWorktree(options) {
+    try {
+        if (!options.createPaseoWorktree) {
+            throw new Error("Paseo worktree service is not configured");
+        }
+        const result = await options.createPaseoWorktree(options.input, {
+            resolveDefaultBranch: options.resolveDefaultBranch,
+        });
+        if (options.workspaceGitService) {
+            const refreshResults = await Promise.allSettled([
+                options.workspaceGitService.getSnapshot(options.input.cwd, {
+                    force: true,
+                    reason: "create-worktree",
+                }),
+                options.workspaceGitService.getSnapshot(result.worktree.worktreePath, {
+                    force: true,
+                    reason: "create-worktree",
+                }),
+            ]);
+            for (const [index, refreshResult] of refreshResults.entries()) {
+                if (refreshResult.status === "fulfilled") {
+                    continue;
+                }
+                options.logger.warn({
+                    err: refreshResult.reason,
+                    cwd: index === 0 ? options.input.cwd : result.worktree.worktreePath,
+                }, "Failed to force-refresh workspace git snapshot after creating worktree");
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        throw toWorktreeRequestError(error);
+    }
+}
 //# sourceMappingURL=mcp-server.js.map