@getpaseo/server 0.1.62 → 0.1.65

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

@@ -4,7 +4,9 @@ import { ensureValidJson } from "../json-utils.js";
 import { AgentPermissionRequestPayloadSchema, AgentListItemPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, } from "../messages.js";
 import { buildStoredAgentPayload, toAgentListItemPayload, toAgentPayload, } from "./agent-projections.js";
 import { curateAgentActivity } from "./activity-curator.js";
+import { selectItemsByProjectedLimit } from "./timeline-projection.js";
 import { ensureAgentLoaded } from "./agent-loading.js";
+import { isStoredAgentProviderAvailable } from "../persistence-hooks.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./timeline-append.js";
 import { getPaseoWorktreesRoot } from "../../utils/worktree.js";
 import { archivePaseoWorktree, killTerminalsUnderPath, } from "../paseo-worktree-archive-service.js";
@@ -12,7 +14,6 @@ import { WaitForAgentTracker } from "./wait-for-agent-tracker.js";
 import { scheduleAgentMetadataGeneration } from "./agent-metadata-generator.js";
 import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../path-utils.js";
 import { captureTerminalLines } from "../../terminal/terminal.js";
-import { runAsyncWorktreeBootstrap } from "../worktree-bootstrap.js";
 import { ScheduleSummarySchema, StoredScheduleSchema } from "../schedule/types.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";
@@ -59,6 +60,34 @@ function parseTimestamp(value) {
 function resolveAgentListActivityTime(agent) {
     return Math.max(parseTimestamp(agent.updatedAt), parseTimestamp(agent.lastUserMessageAt), parseTimestamp(agent.attentionTimestamp), parseTimestamp(agent.archivedAt), parseTimestamp(agent.createdAt));
 }
+function resolveRegisteredProviderIds(agentManager, providerRegistry) {
+    return providerRegistry
+        ? Object.keys(providerRegistry)
+        : agentManager.getRegisteredProviderIds();
+}
+async function resolveProviderSummary(provider, logger) {
+    const base = {
+        id: provider.id,
+        label: provider.label,
+        description: provider.description,
+        modes: provider.modes,
+    };
+    if (!provider.enabled) {
+        return { ...base, enabled: false, status: "unavailable" };
+    }
+    try {
+        const available = await provider.createClient(logger).isAvailable();
+        return { ...base, enabled: true, status: available ? "available" : "unavailable" };
+    }
+    catch (availabilityError) {
+        return {
+            ...base,
+            enabled: true,
+            status: "unavailable",
+            error: availabilityError instanceof Error ? availabilityError.message : String(availabilityError),
+        };
+    }
+}
 function compareAgentListItems(a, b) {
     const attentionDelta = Number(b.requiresAttention ?? false) - Number(a.requiresAttention ?? false);
     if (attentionDelta !== 0) {
@@ -155,12 +184,6 @@ export async function createAgentMcpServer(options) {
         name: "agent-mcp",
         version: "2.0.0",
     });
-    const requireProviderRegistry = () => {
-        if (!providerRegistry) {
-            throw new Error("Provider registry is required to load stored agent records");
-        }
-        return providerRegistry;
-    };
     const resolveCallerAgent = () => {
         if (!callerAgentId) {
             return null;
@@ -171,7 +194,7 @@ export async function createAgentMcpServer(options) {
         }
         return parentAgent;
     };
-    const resolveScopedCwd = (requestedCwd, options) => {
+    const resolveScopedCwd = (requestedCwd, opts) => {
         const callerAgent = resolveCallerAgent();
         if (callerAgent) {
             return resolveChildAgentCwd({
@@ -183,66 +206,76 @@ export async function createAgentMcpServer(options) {
         }
         const trimmedCwd = requestedCwd?.trim();
         if (!trimmedCwd) {
-            if (options?.required) {
+            if (opts?.required) {
                 throw new Error("cwd is required");
             }
             throw new Error("cwd is required when no caller agent is available");
         }
         return expandUserPath(trimmedCwd);
     };
+    const buildCallerAgentScheduleConfigExtras = (callerAgent) => {
+        return {
+            ...(callerAgent.config.thinkingOptionId
+                ? { thinkingOptionId: callerAgent.config.thinkingOptionId }
+                : {}),
+            ...(callerAgent.config.approvalPolicy
+                ? { approvalPolicy: callerAgent.config.approvalPolicy }
+                : {}),
+            ...(callerAgent.config.sandboxMode ? { sandboxMode: callerAgent.config.sandboxMode } : {}),
+            ...(typeof callerAgent.config.networkAccess === "boolean"
+                ? { networkAccess: callerAgent.config.networkAccess }
+                : {}),
+            ...(typeof callerAgent.config.webSearch === "boolean"
+                ? { webSearch: callerAgent.config.webSearch }
+                : {}),
+            ...(callerAgent.config.title ? { title: callerAgent.config.title } : {}),
+            ...(callerAgent.config.extra ? { extra: callerAgent.config.extra } : {}),
+            ...(callerAgent.config.systemPrompt ? { systemPrompt: callerAgent.config.systemPrompt } : {}),
+            ...(callerAgent.config.mcpServers ? { mcpServers: callerAgent.config.mcpServers } : {}),
+        };
+    };
+    const buildCallerAgentScheduleConfig = (callerAgent, params) => {
+        const hasProviderOverride = params?.provider !== undefined;
+        const resolvedProviderModel = hasProviderOverride
+            ? resolveScheduleProviderAndModel({
+                provider: params?.provider,
+                defaultProvider: callerAgent.provider,
+            })
+            : null;
+        const resolvedProvider = resolvedProviderModel?.provider ?? callerAgent.provider;
+        let resolvedModel;
+        if (resolvedProviderModel?.model) {
+            resolvedModel = resolvedProviderModel.model;
+        }
+        else if (!hasProviderOverride && callerAgent.config.model) {
+            resolvedModel = callerAgent.config.model;
+        }
+        return {
+            provider: resolvedProvider,
+            cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : callerAgent.cwd,
+            ...(callerAgent.currentModeId
+                ? {
+                    modeId: mapModeAcrossProviders(callerAgent.currentModeId, callerAgent.provider, resolvedProvider),
+                }
+                : {}),
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+            ...buildCallerAgentScheduleConfigExtras(callerAgent),
+        };
+    };
     const resolveNewAgentScheduleTarget = (params) => {
+        if (!params?.provider?.trim()) {
+            throw new Error("provider is required when target is new-agent");
+        }
         const callerAgent = resolveCallerAgent();
         if (callerAgent) {
-            const hasProviderOverride = params?.provider !== undefined;
-            const resolvedProviderModel = hasProviderOverride
-                ? resolveScheduleProviderAndModel({
-                    provider: params?.provider,
-                    defaultProvider: callerAgent.provider,
-                })
-                : null;
-            const resolvedProvider = resolvedProviderModel?.provider ?? callerAgent.provider;
             return {
                 type: "new-agent",
-                config: {
-                    provider: resolvedProvider,
-                    cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : callerAgent.cwd,
-                    ...(callerAgent.currentModeId
-                        ? {
-                            modeId: mapModeAcrossProviders(callerAgent.currentModeId, callerAgent.provider, resolvedProvider),
-                        }
-                        : {}),
-                    ...(resolvedProviderModel?.model
-                        ? { model: resolvedProviderModel.model }
-                        : !hasProviderOverride && callerAgent.config.model
-                            ? { model: callerAgent.config.model }
-                            : {}),
-                    ...(callerAgent.config.thinkingOptionId
-                        ? { thinkingOptionId: callerAgent.config.thinkingOptionId }
-                        : {}),
-                    ...(callerAgent.config.approvalPolicy
-                        ? { approvalPolicy: callerAgent.config.approvalPolicy }
-                        : {}),
-                    ...(callerAgent.config.sandboxMode
-                        ? { sandboxMode: callerAgent.config.sandboxMode }
-                        : {}),
-                    ...(typeof callerAgent.config.networkAccess === "boolean"
-                        ? { networkAccess: callerAgent.config.networkAccess }
-                        : {}),
-                    ...(typeof callerAgent.config.webSearch === "boolean"
-                        ? { webSearch: callerAgent.config.webSearch }
-                        : {}),
-                    ...(callerAgent.config.title ? { title: callerAgent.config.title } : {}),
-                    ...(callerAgent.config.extra ? { extra: callerAgent.config.extra } : {}),
-                    ...(callerAgent.config.systemPrompt
-                        ? { systemPrompt: callerAgent.config.systemPrompt }
-                        : {}),
-                    ...(callerAgent.config.mcpServers ? { mcpServers: callerAgent.config.mcpServers } : {}),
-                },
+                config: buildCallerAgentScheduleConfig(callerAgent, params),
             };
         }
         const resolvedProviderModel = resolveScheduleProviderAndModel({
             provider: params?.provider,
-            defaultProvider: "claude",
+            defaultProvider: params.provider,
         });
         return {
             type: "new-agent",
@@ -387,9 +420,100 @@ export async function createAgentMcpServer(options) {
     if (options.voiceOnly) {
         return server;
     }
+    const resolveCallerCreateAgentArgs = (args, parentAgentId) => {
+        const callerArgs = agentToAgentCreateAgentArgsSchema.parse(args);
+        const resolvedProviderModel = resolveRequiredProviderModel(callerArgs.provider);
+        const parentAgent = agentManager.getAgent(parentAgentId);
+        if (!parentAgent) {
+            throw new Error(`Parent agent ${parentAgentId} not found`);
+        }
+        const provider = resolvedProviderModel.provider;
+        const resolvedCwd = resolveChildAgentCwd({
+            parentCwd: parentAgent.cwd,
+            requestedCwd: callerArgs.cwd,
+            lockedCwd: callerContext?.lockedCwd,
+            allowCustomCwd: callerContext?.allowCustomCwd ?? true,
+        });
+        const parentMode = parentAgent.currentModeId;
+        const resolvedMode = parentMode
+            ? mapModeAcrossProviders(parentMode, parentAgent.provider, provider)
+            : undefined;
+        return {
+            provider,
+            initialPrompt: callerArgs.initialPrompt,
+            background: callerArgs.background ?? false,
+            normalizedTitle: callerArgs.title.trim(),
+            model: resolvedProviderModel.model,
+            thinking: callerArgs.thinking,
+            labels: callerArgs.labels,
+            notifyOnFinish: callerArgs.notifyOnFinish ?? false,
+            resolvedCwd,
+            resolvedMode,
+            setupContinuation: undefined,
+        };
+    };
+    const resolveTopLevelCreateAgentArgs = async (args) => {
+        const topLevelArgs = topLevelCreateAgentArgsSchema.parse(args);
+        const resolvedProviderModel = resolveRequiredProviderModel(topLevelArgs.provider);
+        const { cwd, mode, worktreeName, baseBranch, refName, action, githubPrNumber } = topLevelArgs;
+        let resolvedCwd = expandUserPath(cwd);
+        let setupContinuation;
+        const shouldCreateWorktree = Boolean(worktreeName || refName || action || githubPrNumber);
+        if (shouldCreateWorktree) {
+            if (worktreeName && !baseBranch && !refName && !action && githubPrNumber === undefined) {
+                throw new Error("baseBranch is required when creating a worktree");
+            }
+            const createdWorktree = await createMcpWorktree({
+                input: {
+                    cwd: resolvedCwd,
+                    worktreeSlug: worktreeName,
+                    refName,
+                    action,
+                    githubPrNumber,
+                    ...(topLevelArgs.initialPrompt
+                        ? { firstAgentContext: { prompt: topLevelArgs.initialPrompt } }
+                        : {}),
+                    runSetup: false,
+                    paseoHome: options.paseoHome,
+                },
+                createPaseoWorktree: options.createPaseoWorktree,
+                resolveDefaultBranch: baseBranch ? async () => baseBranch : undefined,
+                setupContinuation: {
+                    kind: "agent",
+                    terminalManager: terminalManager ?? null,
+                    appendTimelineItem: ({ agentId, item }) => appendTimelineItemIfAgentKnown({
+                        agentManager,
+                        agentId,
+                        item,
+                    }),
+                    emitLiveTimelineItem: ({ agentId, item }) => emitLiveTimelineItemIfAgentKnown({
+                        agentManager,
+                        agentId,
+                        item,
+                    }),
+                    logger: childLogger,
+                },
+            });
+            resolvedCwd = createdWorktree.worktree.worktreePath;
+            setupContinuation = createdWorktree.setupContinuation;
+        }
+        return {
+            provider: resolvedProviderModel.provider,
+            initialPrompt: topLevelArgs.initialPrompt,
+            background: topLevelArgs.background ?? false,
+            normalizedTitle: topLevelArgs.title.trim(),
+            model: resolvedProviderModel.model,
+            thinking: topLevelArgs.thinking,
+            labels: topLevelArgs.labels,
+            notifyOnFinish: topLevelArgs.notifyOnFinish ?? false,
+            resolvedCwd,
+            resolvedMode: mode,
+            setupContinuation,
+        };
+    };
     server.registerTool("create_agent", {
         title: "Create 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.",
+        description: "Create an agent tied to a working directory. Requires provider/model, for example codex/gpt-5.4. Do not guess; call list_providers and list_models first if uncertain. Optionally run an initial prompt immediately or create a git worktree for the agent.",
         inputSchema: createAgentInputSchema,
         outputSchema: {
             agentId: z.string(),
@@ -406,87 +530,15 @@ export async function createAgentMcpServer(options) {
             permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
         },
     }, async (args) => {
-        let provider;
-        let initialPrompt;
-        let background = false;
-        let normalizedTitle;
-        let model;
-        let thinking;
-        let labels;
-        let notifyOnFinish = false;
-        let resolvedCwd;
-        let resolvedMode;
-        let worktreeConfig;
-        let shouldBootstrapWorktree;
-        if (callerAgentId) {
-            const callerArgs = agentToAgentCreateAgentArgsSchema.parse(args);
-            const resolvedProviderModel = resolveRequiredProviderModel(callerArgs.provider);
-            provider = resolvedProviderModel.provider;
-            model = resolvedProviderModel.model;
-            initialPrompt = callerArgs.initialPrompt;
-            background = callerArgs.background ?? false;
-            normalizedTitle = callerArgs.title.trim();
-            thinking = callerArgs.thinking;
-            labels = callerArgs.labels;
-            notifyOnFinish = callerArgs.notifyOnFinish ?? false;
-            const parentAgent = agentManager.getAgent(callerAgentId);
-            if (!parentAgent) {
-                throw new Error(`Parent agent ${callerAgentId} not found`);
-            }
-            resolvedCwd = resolveChildAgentCwd({
-                parentCwd: parentAgent.cwd,
-                requestedCwd: callerArgs.cwd,
-                lockedCwd: callerContext?.lockedCwd,
-                allowCustomCwd: callerContext?.allowCustomCwd ?? true,
-            });
-            const parentMode = parentAgent.currentModeId;
-            if (parentMode) {
-                resolvedMode = mapModeAcrossProviders(parentMode, parentAgent.provider, provider);
-            }
-        }
-        else {
-            const topLevelArgs = topLevelCreateAgentArgsSchema.parse(args);
-            const resolvedProviderModel = resolveRequiredProviderModel(topLevelArgs.provider);
-            provider = resolvedProviderModel.provider;
-            model = resolvedProviderModel.model;
-            initialPrompt = topLevelArgs.initialPrompt;
-            background = topLevelArgs.background ?? false;
-            normalizedTitle = topLevelArgs.title.trim();
-            thinking = topLevelArgs.thinking;
-            labels = topLevelArgs.labels;
-            notifyOnFinish = topLevelArgs.notifyOnFinish ?? false;
-            const { cwd, mode, worktreeName, baseBranch, refName, action, githubPrNumber } = topLevelArgs;
-            resolvedCwd = expandUserPath(cwd);
-            if (worktreeName) {
-                if (!baseBranch && !refName && !action && githubPrNumber === undefined) {
-                    throw new Error("baseBranch is required when creating a worktree");
-                }
-                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 = createdWorktree.worktree.worktreePath;
-                worktreeConfig = createdWorktree.worktree;
-                shouldBootstrapWorktree = createdWorktree.created;
-            }
-            resolvedMode = mode;
-        }
+        const resolved = callerAgentId
+            ? resolveCallerCreateAgentArgs(args, callerAgentId)
+            : await resolveTopLevelCreateAgentArgs(args);
+        const { provider, initialPrompt, background, normalizedTitle, model, thinking, labels, notifyOnFinish, resolvedCwd, resolvedMode, setupContinuation, } = resolved;
         const childAgentDefaultLabels = callerContext?.childAgentDefaultLabels;
         const mergedLabels = {
             ...(callerAgentId ? { "paseo.parent-agent-id": callerAgentId } : {}),
-            ...(childAgentDefaultLabels ?? {}),
-            ...(labels ?? {}),
+            ...childAgentDefaultLabels,
+            ...labels,
         };
         const snapshot = await agentManager.createAgent({
             provider,
@@ -496,25 +548,9 @@ export async function createAgentMcpServer(options) {
             model,
             thinkingOptionId: thinking,
         }, undefined, Object.keys(mergedLabels).length > 0 ? { labels: mergedLabels } : undefined);
-        if (worktreeConfig) {
-            void runAsyncWorktreeBootstrap({
-                agentId: snapshot.id,
-                worktree: worktreeConfig,
-                shouldBootstrap: shouldBootstrapWorktree,
-                terminalManager: terminalManager ?? null,
-                appendTimelineItem: (item) => appendTimelineItemIfAgentKnown({
-                    agentManager,
-                    agentId: snapshot.id,
-                    item,
-                }),
-                emitLiveTimelineItem: (item) => emitLiveTimelineItemIfAgentKnown({
-                    agentManager,
-                    agentId: snapshot.id,
-                    item,
-                }),
-                logger: childLogger,
-            });
-        }
+        setupContinuation?.startAfterAgentCreate({
+            agentId: snapshot.id,
+        });
         const trimmedPrompt = initialPrompt.trim();
         scheduleAgentMetadataGeneration({
             agentManager,
@@ -524,11 +560,6 @@ 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, {
@@ -767,7 +798,7 @@ export async function createAgentMcpServer(options) {
         if (!record || record.internal) {
             throw new Error(`Agent ${agentId} not found`);
         }
-        const structuredSnapshot = buildStoredAgentPayload(record, requireProviderRegistry(), childLogger);
+        const structuredSnapshot = buildStoredAgentPayload(record, resolveRegisteredProviderIds(agentManager, providerRegistry));
         return {
             content: [],
             structuredContent: ensureValidJson({
@@ -804,10 +835,12 @@ export async function createAgentMcpServer(options) {
         const liveAgents = await Promise.all(liveSnapshots.map((snapshot) => serializeSnapshotWithMetadata(agentStorage, snapshot, childLogger)));
         const liveIds = new Set(liveSnapshots.map((snapshot) => snapshot.id));
         const storedRecords = await agentStorage.list();
+        const registeredProviderIds = resolveRegisteredProviderIds(agentManager, providerRegistry);
         const storedAgents = storedRecords
             .filter((record) => !record.internal && !liveIds.has(record.id))
             .filter((record) => includeArchived || !record.archivedAt)
-            .map((record) => buildStoredAgentPayload(record, requireProviderRegistry(), childLogger));
+            .filter((record) => includeArchived || isStoredAgentProviderAvailable(record, registeredProviderIds))
+            .map((record) => buildStoredAgentPayload(record, registeredProviderIds));
         const agents = [...liveAgents, ...storedAgents]
             .map(toAgentListItemPayload)
             .filter((agent) => !requestedCwd || isSameOrDescendantPath(requestedCwd, agent.cwd))
@@ -1213,25 +1246,18 @@ export async function createAgentMcpServer(options) {
     });
     server.registerTool("list_providers", {
         title: "List providers",
-        description: "List available agent providers and their modes.",
+        description: "List configured agent providers, availability, and their modes.",
         inputSchema: {},
         outputSchema: {
             providers: z.array(ProviderSummarySchema),
         },
-    }, async () => ({
-        content: [],
-        structuredContent: ensureValidJson({
-            providers: Object.values(providerRegistry ?? {}).map((provider) => ({
-                id: provider.id,
-                label: provider.label,
-                modes: provider.modes.map((mode) => ({
-                    id: mode.id,
-                    label: mode.label,
-                    ...(mode.description ? { description: mode.description } : {}),
-                })),
-            })),
-        }),
-    }));
+    }, async () => {
+        const providers = await Promise.all(Object.values(providerRegistry ?? {}).map((provider) => resolveProviderSummary(provider, childLogger)));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ providers }),
+        };
+    });
     server.registerTool("list_models", {
         title: "List models",
         description: "List models for an agent provider.",
@@ -1250,6 +1276,9 @@ export async function createAgentMcpServer(options) {
         if (!definition) {
             throw new Error(`Provider ${provider} is not configured`);
         }
+        if (!definition.enabled) {
+            throw new Error(`Provider '${provider}' is disabled`);
+        }
         const models = await definition.fetchModels({ cwd: resolveSnapshotCwd(), force: false });
         return {
             content: [],
@@ -1286,41 +1315,48 @@ export async function createAgentMcpServer(options) {
     });
     server.registerTool("create_worktree", {
         title: "Create worktree",
-        description: "Create a Paseo-managed git worktree.",
+        description: "Create a Paseo-managed git worktree. Branch off a new branch, check out an existing branch, or check out a GitHub PR.",
         inputSchema: {
-            cwd: z
-                .string()
-                .optional()
-                .describe("Optional repository cwd. Defaults to the caller agent cwd."),
-            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(),
+            cwd: z.string().optional().describe("Repository directory. Defaults to the agent's cwd."),
+            target: z
+                .discriminatedUnion("mode", [
+                z
+                    .object({
+                    mode: z.literal("branch-off"),
+                    newBranch: z.string().min(1).describe("Name for the new branch."),
+                    base: z
+                        .string()
+                        .min(1)
+                        .optional()
+                        .describe("Base ref. Defaults to the repo's default branch."),
+                })
+                    .describe("Create a new branch off a base."),
+                z
+                    .object({
+                    mode: z.literal("checkout-branch"),
+                    branch: z.string().min(1).describe("Existing branch to check out."),
+                })
+                    .describe("Check out an existing branch."),
+                z
+                    .object({
+                    mode: z.literal("checkout-pr"),
+                    prNumber: z.number().int().positive().describe("Pull request number."),
+                })
+                    .describe("Check out a GitHub pull request."),
+            ])
+                .describe("What the worktree should contain."),
         },
         outputSchema: {
             branchName: z.string(),
             worktreePath: z.string(),
         },
-    }, async ({ cwd, branchName, baseBranch, refName, action, githubPrNumber }) => {
-        if (!branchName && !refName && githubPrNumber === undefined) {
-            throw new Error("create_worktree requires branchName, refName, or githubPrNumber");
-        }
+    }, async ({ cwd, target }) => {
         const repoRoot = resolveScopedCwd(cwd, { required: true });
+        const mcpInput = mcpCreateWorktreeInput(repoRoot, target, options.paseoHome);
         const createdWorktree = await createMcpWorktree({
-            input: {
-                cwd: repoRoot,
-                worktreeSlug: branchName,
-                refName,
-                action,
-                githubPrNumber,
-                runSetup: false,
-                paseoHome: options.paseoHome,
-            },
+            input: mcpInput.input,
             createPaseoWorktree: options.createPaseoWorktree,
-            resolveDefaultBranch: baseBranch ? async () => baseBranch : undefined,
-            workspaceGitService: options.workspaceGitService,
-            logger: options.logger,
+            resolveDefaultBranch: mcpInput.resolveDefaultBranch,
         });
         const { worktree } = createdWorktree;
         return {
@@ -1359,9 +1395,15 @@ export async function createAgentMcpServer(options) {
         if (!options.archiveWorkspaceRecord) {
             throw new Error("Workspace registry archiver is required to archive worktrees");
         }
-        if (!options.emitWorkspaceUpdatesForCwds) {
+        if (!options.emitWorkspaceUpdatesForWorkspaceIds) {
             throw new Error("Workspace update emitter is required to archive worktrees");
         }
+        if (!options.markWorkspaceArchiving) {
+            throw new Error("Workspace archiving marker is required to archive worktrees");
+        }
+        if (!options.clearWorkspaceArchiving) {
+            throw new Error("Workspace archiving clearer is required to archive worktrees");
+        }
         if (!options.emitSessionMessage) {
             throw new Error("Session message emitter is required to archive worktrees");
         }
@@ -1375,7 +1417,9 @@ export async function createAgentMcpServer(options) {
             agentStorage,
             archiveWorkspaceRecord: options.archiveWorkspaceRecord,
             emit: options.emitSessionMessage,
-            emitWorkspaceUpdatesForCwds: options.emitWorkspaceUpdatesForCwds,
+            emitWorkspaceUpdatesForWorkspaceIds: options.emitWorkspaceUpdatesForWorkspaceIds,
+            markWorkspaceArchiving: options.markWorkspaceArchiving,
+            clearWorkspaceArchiving: options.clearWorkspaceArchiving,
             isPathWithinRoot: isSameOrDescendantPath,
             killTerminalsUnderPath: (rootPath) => killTerminalsUnderPath({
                 terminalManager: terminalManager ?? null,
@@ -1418,17 +1462,17 @@ export async function createAgentMcpServer(options) {
         });
         const timeline = agentManager.getTimeline(agentId);
         const snapshot = agentManager.getAgent(agentId);
-        const activitiesToCurate = limit ? timeline.slice(-limit) : timeline;
-        const curatedContent = curateAgentActivity(activitiesToCurate);
-        const totalCount = timeline.length;
-        const shownCount = activitiesToCurate.length;
-        let countHeader;
-        if (limit && shownCount < totalCount) {
-            countHeader = `Showing ${shownCount} of ${totalCount} ${totalCount === 1 ? "activity" : "activities"} (limited to ${limit})`;
-        }
-        else {
-            countHeader = `Showing all ${totalCount} ${totalCount === 1 ? "activity" : "activities"}`;
-        }
+        const selection = selectItemsByProjectedLimit({
+            items: timeline,
+            direction: "tail",
+            limit: limit ?? 0,
+        });
+        const curatedContent = curateAgentActivity(selection.items);
+        const { totalProjected, shownProjected } = selection;
+        const noun = totalProjected === 1 ? "activity" : "activities";
+        const countHeader = limit && shownProjected < totalProjected
+            ? `Showing ${shownProjected} of ${totalProjected} ${noun} (limited to ${limit})`
+            : `Showing all ${totalProjected} ${noun}`;
         const contentWithCount = `${countHeader}\n\n${curatedContent}`;
         return {
             content: [],
@@ -1503,35 +1547,39 @@ export async function createAgentMcpServer(options) {
     });
     return server;
 }
+function mcpCreateWorktreeInput(repoRoot, target, paseoHome) {
+    const base = { cwd: repoRoot, runSetup: false, paseoHome };
+    switch (target.mode) {
+        case "branch-off":
+            return {
+                input: {
+                    ...base,
+                    worktreeSlug: target.newBranch,
+                    action: "branch-off",
+                    ...(target.base ? { refName: target.base } : {}),
+                },
+            };
+        case "checkout-branch":
+            return {
+                input: { ...base, action: "checkout", refName: target.branch },
+            };
+        case "checkout-pr":
+            return {
+                input: { ...base, action: "checkout", githubPrNumber: target.prNumber },
+            };
+    }
+}
 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,
+            ...(options.resolveDefaultBranch
+                ? { resolveDefaultBranch: options.resolveDefaultBranch }
+                : {}),
+            ...(options.setupContinuation ? { setupContinuation: options.setupContinuation } : {}),
         });
-        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) {