@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/agent/tools/paseo-tools.js

@@ -0,0 +1,2445 @@
+import { z } from "zod";
+import { ensureValidJson } from "../../json-utils.js";
+import { AgentProfileSchema } from "@camerontaylor/paseo-protocol/messages";
+import { AgentFeatureSchema, AgentPermissionRequestPayloadSchema, AgentListItemPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, WorkspaceScriptPayloadSchema, } 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 { archiveByScope, killTerminalsForWorkspace, requireActiveWorkspaceForArchive, } from "../../workspace-archive-service.js";
+import { createAgentCommand } from "../create-agent/create.js";
+import { everyMsToFiveFieldCron } from "@camerontaylor/paseo-protocol/schedule/cadence";
+import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../../path-utils.js";
+import { ScheduleRunSchema, ScheduleSummarySchema, StoredScheduleSchema, } from "@camerontaylor/paseo-protocol/schedule/types";
+import { AgentModelSchema, AgentProviderEnum, AgentStatusEnum, ProviderModeSchema, ProviderSummarySchema, parseDurationString, resolveRequiredProviderModel, sanitizePermissionRequest, serializeSnapshotWithMetadata, toScheduleSummary, waitForAgentWithTimeout, } from "../mcp-shared.js";
+import { sendPromptToAgent, setupFinishNotification } from "../agent-prompt.js";
+import { respondToAgentPermission } from "../permission-response.js";
+import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, setAgentModeCommand, updateAgentCommand, } from "../lifecycle-command.js";
+import { resolveWorktreeSourceCwd } from "../../workspace-source.js";
+import { createPaseoWorktreeCommand, } from "../../worktree/commands.js";
+import { registerBrowserTools } from "../../browser-tools/tools.js";
+import { isPaseoToolEnabled } from "../paseo-tool-policy.js";
+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));
+}
+const WorkspaceAutomationSummarySchema = z.object({
+    workspaceId: z.string(),
+    projectId: z.string(),
+    cwd: z.string(),
+    isolation: z.enum(["local", "worktree"]),
+    kind: z.enum(["directory", "local_checkout", "worktree"]),
+    title: z.string().nullable(),
+});
+function toWorkspaceAutomationSummary(workspace) {
+    return {
+        workspaceId: workspace.workspaceId,
+        projectId: workspace.projectId,
+        cwd: workspace.cwd,
+        isolation: workspace.kind === "worktree" ? "worktree" : "local",
+        kind: workspace.kind,
+        title: workspace.title,
+    };
+}
+function assertOptionsAbsent(options, message) {
+    if (options.some(([, value]) => value !== undefined)) {
+        throw new Error(message);
+    }
+}
+function resolveWorkspaceWorktreeTarget(input) {
+    switch (input.mode ?? "branch-off") {
+        case "branch-off":
+            assertOptionsAbsent([
+                ["branch", input.branch],
+                ["prNumber", input.prNumber],
+                ["forge", input.forge],
+            ], "branch, prNumber, and forge require a checkout mode");
+            return {
+                action: "branch-off",
+                ...(input.branchName ? { branchName: input.branchName } : {}),
+                ...(input.baseBranch ? { refName: input.baseBranch } : {}),
+            };
+        case "checkout-branch":
+            if (!input.branch) {
+                throw new Error("branch is required for checkout-branch mode");
+            }
+            assertOptionsAbsent([
+                ["branchName", input.branchName],
+                ["baseBranch", input.baseBranch],
+                ["prNumber", input.prNumber],
+                ["forge", input.forge],
+            ], "branchName, baseBranch, prNumber, and forge are not valid for checkout-branch mode");
+            return { action: "checkout", refName: input.branch };
+        case "checkout-pr":
+            if (input.prNumber === undefined) {
+                throw new Error("prNumber is required for checkout-pr mode");
+            }
+            assertOptionsAbsent([
+                ["branchName", input.branchName],
+                ["baseBranch", input.baseBranch],
+                ["branch", input.branch],
+            ], "branchName, baseBranch, and branch are not valid for checkout-pr mode");
+            return {
+                action: "checkout",
+                checkoutSource: {
+                    kind: "change_request",
+                    ...(input.forge ? { forge: input.forge } : {}),
+                    number: input.prNumber,
+                },
+            };
+    }
+}
+function toProviderSummary(entry) {
+    return {
+        id: entry.provider,
+        label: entry.label ?? entry.provider,
+        description: entry.description ?? "",
+        enabled: entry.enabled,
+        ...(entry.source ? { source: entry.source } : {}),
+        ...(entry.baseProviderId ? { baseProviderId: entry.baseProviderId } : {}),
+        modes: entry.modes ?? [],
+        status: entry.status === "ready" ? "available" : entry.status,
+        ...(entry.error ? { error: entry.error } : {}),
+    };
+}
+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 resolveScheduleUpdateProviderAndModel(params) {
+    const providerInput = params.provider?.trim();
+    const modelInput = typeof params.model === "string" ? params.model.trim() : params.model;
+    if (params.model !== undefined && modelInput === "") {
+        throw new Error("model cannot be empty");
+    }
+    if (!providerInput) {
+        return params.model !== undefined ? { model: modelInput } : {};
+    }
+    const slashIndex = providerInput.indexOf("/");
+    if (slashIndex === -1) {
+        return {
+            provider: providerInput,
+            ...(params.model !== undefined ? { model: modelInput } : {}),
+        };
+    }
+    const provider = providerInput.slice(0, slashIndex).trim();
+    const modelFromProvider = providerInput.slice(slashIndex + 1).trim();
+    if (!provider || !modelFromProvider) {
+        throw new Error("provider must be <provider> or <provider>/<model>");
+    }
+    if (params.model === null) {
+        throw new Error("provider specifies a model but model is null");
+    }
+    if (typeof modelInput === "string" && modelInput !== modelFromProvider) {
+        throw new Error("Conflicting model values provided");
+    }
+    return {
+        provider,
+        model: modelInput ?? modelFromProvider,
+    };
+}
+function normalizeScheduleCadenceArg(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed;
+}
+function normalizeScheduleTimeZoneArg(value) {
+    return normalizeScheduleCadenceArg(value);
+}
+function resolveScheduleUpdateCadence(input) {
+    const every = normalizeScheduleCadenceArg(input.every);
+    const cron = normalizeScheduleCadenceArg(input.cron);
+    const timeZone = normalizeScheduleTimeZoneArg(input.timezone);
+    if (every !== undefined && cron !== undefined) {
+        throw new Error("Specify at most one of every or cron");
+    }
+    if (timeZone !== undefined && cron === undefined) {
+        throw new Error("timezone can only be used with cron");
+    }
+    if (every !== undefined) {
+        // COMPAT(scheduleEveryInput): accept the old hidden field and canonicalize it before write.
+        // Added in v0.2.0; remove after 2027-01-17.
+        const everyMs = parseDurationString(every);
+        const expression = everyMsToFiveFieldCron(everyMs);
+        if (expression) {
+            return { type: "cron", expression };
+        }
+        throw new Error(`${every} cannot be represented faithfully by five-field cron`);
+    }
+    if (cron !== undefined) {
+        return {
+            type: "cron",
+            expression: cron,
+            ...(timeZone !== undefined ? { timezone: timeZone } : {}),
+        };
+    }
+    return undefined;
+}
+function resolveScheduleUpdateExpiresAt(input) {
+    if (input.expiresIn !== undefined && input.clearExpires) {
+        throw new Error("Specify at most one of expiresIn or clearExpires");
+    }
+    if (input.expiresIn !== undefined) {
+        return new Date(Date.now() + parseDurationString(input.expiresIn)).toISOString();
+    }
+    if (input.clearExpires) {
+        return null;
+    }
+    return undefined;
+}
+function buildScheduleUpdateInput(input) {
+    const cadence = resolveScheduleUpdateCadence(input);
+    const expiresAt = resolveScheduleUpdateExpiresAt(input);
+    const providerModelPatch = resolveScheduleUpdateProviderAndModel({
+        provider: input.provider,
+        model: input.model,
+    });
+    const newAgentConfig = {
+        ...(providerModelPatch.provider !== undefined ? { provider: providerModelPatch.provider } : {}),
+        ...(providerModelPatch.model !== undefined ? { model: providerModelPatch.model } : {}),
+        ...(input.mode !== undefined ? { modeId: input.mode } : {}),
+        ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
+    };
+    return {
+        id: input.id,
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+        ...(cadence !== undefined ? { cadence } : {}),
+        ...(input.maxRuns !== undefined ? { maxRuns: input.maxRuns } : {}),
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+        ...(Object.keys(newAgentConfig).length > 0 ? { newAgentConfig } : {}),
+    };
+}
+function resolveChildAgentCwd(params) {
+    const lockedCwd = params.lockedCwd?.trim();
+    if (lockedCwd) {
+        return expandUserPath(lockedCwd);
+    }
+    const requestedCwd = params.requestedCwd?.trim();
+    if (!requestedCwd || !params.allowCustomCwd) {
+        return params.parentCwd;
+    }
+    return resolvePathFromBase(params.parentCwd, requestedCwd);
+}
+const TerminalSummarySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    cwd: z.string(),
+});
+function resolveTerminalKeyToken(key, literal) {
+    if (literal) {
+        return key;
+    }
+    switch (key) {
+        case "Enter":
+            return "\r";
+        case "Tab":
+            return "\t";
+        case "Escape":
+            return "\u001b";
+        case "Space":
+            return " ";
+        case "BSpace":
+            return "\u007f";
+        case "C-c":
+            return "\u0003";
+        case "C-d":
+            return "\u0004";
+        case "C-z":
+            return "\u001a";
+        case "C-l":
+            return "\u000c";
+        case "C-a":
+            return "\u0001";
+        case "C-e":
+            return "\u0005";
+        default:
+            return key;
+    }
+}
+export function createPaseoToolCatalog(options) {
+    const { agentManager, agentStorage, terminalManager, workspaceScripts, scheduleService, providerSnapshotManager, daemonConfigStore, callerAgentId, resolveSpeakHandler, resolveCallerContext, logger, } = options;
+    const childLogger = logger.child({ module: "agent", component: "paseo-tool-catalog" });
+    const callerContext = callerAgentId ? (resolveCallerContext?.(callerAgentId) ?? null) : null;
+    const parseToolInput = async (tool, input) => {
+        const inputSchema = tool.inputSchema;
+        if (!inputSchema) {
+            return input;
+        }
+        const schema = typeof inputSchema === "object" &&
+            inputSchema !== null &&
+            typeof inputSchema.safeParseAsync === "function"
+            ? inputSchema
+            : z.object(inputSchema).passthrough();
+        return schema.parseAsync(input);
+    };
+    const tools = new Map();
+    const registerTool = (name, config, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Tool handlers are schema-validated at registration boundaries.
+    handler) => {
+        if (!isPaseoToolEnabled(options.paseoToolPolicy, name)) {
+            return;
+        }
+        tools.set(name, {
+            name,
+            title: config.title,
+            description: config.description ?? name,
+            inputSchema: config.inputSchema,
+            outputSchema: config.outputSchema,
+            handler: handler,
+        });
+    };
+    const toCatalog = () => ({
+        tools,
+        getTool(name) {
+            return tools.get(name);
+        },
+        async executeTool(name, input, context = {}) {
+            const tool = tools.get(name);
+            if (!tool) {
+                throw new Error(`Paseo tool not found: ${name}`);
+            }
+            return tool.handler(await parseToolInput(tool, input), context);
+        },
+    });
+    const buildCronScheduleCadence = (input) => {
+        const expression = input.cron?.trim() ?? "";
+        if (!expression) {
+            throw new Error("cron is required");
+        }
+        const timezone = normalizeScheduleTimeZoneArg(input.timezone);
+        return {
+            type: "cron",
+            expression,
+            ...(timezone !== undefined ? { timezone } : {}),
+        };
+    };
+    const buildScheduleExpiry = (expiresIn) => {
+        return expiresIn === undefined
+            ? undefined
+            : new Date(Date.now() + parseDurationString(expiresIn)).toISOString();
+    };
+    const resolveCallerAgent = () => {
+        if (!callerAgentId) {
+            return null;
+        }
+        const parentAgent = agentManager.getAgent(callerAgentId);
+        if (!parentAgent) {
+            throw new Error(`Parent agent ${callerAgentId} not found`);
+        }
+        return parentAgent;
+    };
+    const resolveInheritedProviderConfig = (selectedProvider) => {
+        const callerAgent = resolveCallerAgent();
+        if (callerAgent?.provider !== selectedProvider || !callerAgent.config?.providerOptions) {
+            return undefined;
+        }
+        return { providerOptions: callerAgent.config.providerOptions };
+    };
+    const resolveScopedCwd = (requestedCwd, opts) => {
+        const callerAgent = resolveCallerAgent();
+        if (callerAgent) {
+            return resolveChildAgentCwd({
+                parentCwd: callerAgent.cwd,
+                requestedCwd,
+                lockedCwd: callerContext?.lockedCwd,
+                allowCustomCwd: callerContext?.allowCustomCwd ?? true,
+            });
+        }
+        const trimmedCwd = requestedCwd?.trim();
+        if (!trimmedCwd) {
+            if (opts?.required) {
+                throw new Error("cwd is required");
+            }
+            throw new Error("cwd is required outside an agent-scoped session");
+        }
+        return expandUserPath(trimmedCwd);
+    };
+    async function resolveTerminalWorkspaceId(resolvedCwd) {
+        // An agent-spawned terminal belongs to the caller agent's workspace. Only if
+        // the caller has no workspace do we mint one for the cwd.
+        const callerAgent = callerAgentId ? agentManager.getAgent(callerAgentId) : null;
+        if (callerAgent?.workspaceId) {
+            return callerAgent.workspaceId;
+        }
+        if (!options.ensureWorkspaceForCreate) {
+            throw new Error(callerAgentId
+                ? `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`
+                : "workspaceId is required outside an agent-scoped session");
+        }
+        return options.ensureWorkspaceForCreate(resolvedCwd);
+    }
+    function resolveWorkspaceIdForRename(requestedWorkspaceId) {
+        const explicitWorkspaceId = requestedWorkspaceId?.trim();
+        if (explicitWorkspaceId) {
+            return explicitWorkspaceId;
+        }
+        if (callerAgentId) {
+            const callerAgent = resolveCallerAgent();
+            if (!callerAgent?.workspaceId) {
+                throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+            }
+            return callerAgent.workspaceId;
+        }
+        throw new Error("workspaceId is required outside an agent-scoped session");
+    }
+    const buildCallerAgentScheduleConfigExtras = (callerAgent, resolvedProvider) => {
+        return {
+            ...(callerAgent.config.thinkingOptionId
+                ? { thinkingOptionId: callerAgent.config.thinkingOptionId }
+                : {}),
+            ...(callerAgent.provider === resolvedProvider && callerAgent.config.providerOptions
+                ? { providerOptions: callerAgent.config.providerOptions }
+                : {}),
+            ...(callerAgent.config.featureValues
+                ? { featureValues: callerAgent.config.featureValues }
+                : {}),
+            ...(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 && callerAgent.provider === resolvedProvider
+                ? {
+                    modeId: callerAgent.currentModeId,
+                }
+                : {}),
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+            ...buildCallerAgentScheduleConfigExtras(callerAgent, resolvedProvider),
+        };
+    };
+    const resolveNewAgentScheduleTarget = (params) => {
+        const callerAgent = resolveCallerAgent();
+        if (callerAgent) {
+            return {
+                type: "new-agent",
+                config: {
+                    ...buildCallerAgentScheduleConfig(callerAgent, params),
+                    ...(params?.isolation ? { isolation: params.isolation } : {}),
+                },
+            };
+        }
+        if (!params?.provider?.trim()) {
+            throw new Error("provider is required when target is new-agent");
+        }
+        const resolvedProviderModel = resolveScheduleProviderAndModel({
+            provider: params?.provider,
+            defaultProvider: params.provider,
+        });
+        return {
+            type: "new-agent",
+            config: {
+                provider: resolvedProviderModel.provider,
+                cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : process.cwd(),
+                ...(resolvedProviderModel.model ? { model: resolvedProviderModel.model } : {}),
+                ...(params?.isolation ? { isolation: params.isolation } : {}),
+            },
+        };
+    };
+    async function requireScheduleTarget(id, type) {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await scheduleService.inspect(id);
+        if (schedule.target.type !== type) {
+            throw new Error(type === "agent" ? `Heartbeat not found: ${id}` : `Schedule not found: ${id}`);
+        }
+        return schedule;
+    }
+    async function requireCallerHeartbeat(id) {
+        if (!callerAgentId) {
+            throw new Error("Heartbeat operations require an agent-scoped session");
+        }
+        const schedule = await requireScheduleTarget(id, "agent");
+        if (schedule.target.type !== "agent" || schedule.target.agentId !== callerAgentId) {
+            throw new Error(`Heartbeat ${id} does not belong to caller ${callerAgentId}`);
+        }
+        return schedule;
+    }
+    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 ProviderOrProviderModelInputSchema = AgentProviderEnum.trim()
+        .min(1, "provider is required")
+        .refine((value) => {
+        if (!value.includes("/")) {
+            return true;
+        }
+        try {
+            resolveRequiredProviderModel(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "provider must be provider or provider/model, for example codex/gpt-5.4" });
+    const CreateAgentSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Session mode to configure before the first run."),
+        thinkingOptionId: z.string().optional().describe("Thinking option ID."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Provider-specific feature values, for example { fast_mode: true } for Codex."),
+    })
+        .strict();
+    const UpdateAgentSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Session mode ID."),
+        model: z.string().nullable().optional().describe("Model ID. Pass null to clear."),
+        thinkingOptionId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Thinking option ID. Pass null to clear."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Provider-specific feature values, for example { fast_mode: true } for Codex."),
+    })
+        .strict();
+    const InspectProviderSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Draft session mode ID."),
+        model: z.string().optional().describe("Draft model ID."),
+        thinkingOptionId: z.string().optional().describe("Draft thinking option ID."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Draft provider feature values."),
+    })
+        .strict();
+    const AgentRelationshipInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({ kind: z.literal("subagent") })
+            .strict()
+            .describe("Create a child agent under this agent's subagent track."),
+        z
+            .object({ kind: z.literal("detached") })
+            .strict()
+            .describe("Create a root agent that does not appear in this agent's subagent track."),
+    ]);
+    const AgentCreateWorktreeTargetInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("branch-off"),
+            worktreeSlug: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional worktree slug/path label. Omit to let Paseo generate one."),
+            branchName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional git branch name. Defaults to the worktree slug."),
+            baseBranch: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional base branch. Defaults to the repository default branch."),
+        })
+            .strict()
+            .describe("Create a new branch in a new Paseo worktree."),
+        z
+            .object({
+            kind: z.literal("checkout-branch"),
+            branch: z.string().min(1).describe("Existing branch to check out."),
+        })
+            .strict()
+            .describe("Check out an existing branch in a new Paseo worktree."),
+        z
+            .object({
+            kind: z.literal("checkout-pr"),
+            githubPrNumber: z.number().int().positive().describe("GitHub pull request number."),
+        })
+            .strict()
+            .describe("Check out a GitHub pull request in a new Paseo worktree."),
+    ]);
+    const AgentWorkspaceInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("current"),
+            cwd: z.string().optional().describe("Optional runtime cwd. Defaults to the caller's cwd."),
+        })
+            .strict()
+            .describe("Use the caller's current workspace."),
+        z
+            .object({
+            kind: z.literal("existing"),
+            workspaceId: z.string().min(1).describe("Existing workspace id to attach the agent to."),
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional runtime cwd. Defaults to the existing workspace cwd."),
+        })
+            .strict()
+            .describe("Attach the agent to an existing workspace."),
+        z
+            .object({
+            kind: z.literal("create"),
+            source: z.discriminatedUnion("kind", [
+                z
+                    .object({
+                    kind: z.literal("directory"),
+                    path: z
+                        .string()
+                        .optional()
+                        .describe("Optional directory path. Defaults to the caller's cwd."),
+                })
+                    .strict(),
+                z
+                    .object({
+                    kind: z.literal("worktree"),
+                    cwd: z
+                        .string()
+                        .optional()
+                        .describe("Optional source repository. Defaults to the caller's cwd."),
+                    target: AgentCreateWorktreeTargetInputSchema,
+                })
+                    .strict(),
+            ]),
+        })
+            .strict()
+            .describe("Create a new workspace for the agent."),
+    ]);
+    const commonCreateAgentFields = {
+        title: z
+            .string()
+            .trim()
+            .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: ProviderModelInputSchema.describe("Required provider/model pair, for example codex/gpt-5.4."),
+        labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
+        settings: CreateAgentSettingsInputSchema.optional().describe("Initial runtime settings for the new agent."),
+        initialPrompt: z
+            .string()
+            .trim()
+            .min(1, "initialPrompt is required")
+            .describe("Required first task to run immediately after creation."),
+    };
+    const legacyCreateAgentPlacementFields = {
+        relationship: AgentRelationshipInputSchema.describe("Whether the created agent is a subagent under you or a detached root agent."),
+        workspace: AgentWorkspaceInputSchema.describe("Workspace ownership/location for the created agent."),
+    };
+    const canonicalCreateAgentFields = {
+        ...commonCreateAgentFields,
+        workspaceId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Existing workspace id. Agent-scoped calls default to the caller workspace; top-level calls create a new local workspace when omitted."),
+    };
+    const agentToAgentInputSchema = {
+        ...canonicalCreateAgentFields,
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Get notified when the created agent finishes, errors, or needs permission. Set false only for truly fire-and-forget agents."),
+    };
+    const canonicalTopLevelInputSchema = {
+        ...canonicalCreateAgentFields,
+        background: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Run agent in background. If false (default), waits for completion or permission request. If true, returns immediately."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Agent-scoped only: get notified when the created agent finishes, errors, or needs permission."),
+    };
+    const legacyAgentToAgentInputSchema = {
+        ...commonCreateAgentFields,
+        ...legacyCreateAgentPlacementFields,
+        notifyOnFinish: agentToAgentInputSchema.notifyOnFinish,
+    };
+    const legacyTopLevelCreateAgentInputSchema = {
+        ...commonCreateAgentFields,
+        relationship: legacyCreateAgentPlacementFields.relationship.optional(),
+        workspace: legacyCreateAgentPlacementFields.workspace.optional(),
+        background: canonicalTopLevelInputSchema.background,
+        notifyOnFinish: canonicalTopLevelInputSchema.notifyOnFinish,
+        cwd: z
+            .string()
+            .optional()
+            .describe("Legacy top-level working directory. Prefer workspace.source.path."),
+        mode: z.string().optional().describe("Legacy session mode ID. Prefer settings.modeId."),
+        thinking: z
+            .string()
+            .optional()
+            .describe("Legacy thinking option ID. Prefer settings.thinkingOptionId."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Legacy feature values. Prefer settings.features."),
+        worktreeName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy worktree slug. Prefer workspace.source.target.worktreeSlug."),
+        branchName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy branch name. Prefer workspace.source.target.branchName."),
+        baseBranch: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy base branch. Prefer workspace.source.target.baseBranch."),
+        refName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy branch/ref to check out. Prefer workspace.source.target.branch."),
+        githubPrNumber: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Legacy GitHub PR number. Prefer workspace.source.target.githubPrNumber."),
+    };
+    const createAgentInputSchema = z
+        .object(callerAgentId ? agentToAgentInputSchema : canonicalTopLevelInputSchema)
+        .passthrough();
+    const agentToAgentCreateAgentArgsSchema = z.object(agentToAgentInputSchema).strict();
+    const legacyAgentToAgentCreateAgentArgsSchema = z.object(legacyAgentToAgentInputSchema).strict();
+    const canonicalTopLevelCreateAgentArgsSchema = z.object(canonicalTopLevelInputSchema).strict();
+    const legacyTopLevelCreateAgentArgsSchema = z
+        .object(legacyTopLevelCreateAgentInputSchema)
+        .strict();
+    const commonSendAgentPromptInputSchema = {
+        agentId: z.string(),
+        prompt: z.string(),
+        sessionMode: z.string().optional().describe("Optional mode to set before running the prompt."),
+    };
+    const agentToAgentSendAgentPromptInputSchema = {
+        ...commonSendAgentPromptInputSchema,
+        background: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Run agent in background. Agent-scoped default is true so you can continue until the finish notification arrives. Set false only when you need a blocking response."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Get notified when the prompted agent finishes, errors, or needs permission. Set false only for truly fire-and-forget prompts."),
+    };
+    const topLevelSendAgentPromptInputSchema = {
+        ...commonSendAgentPromptInputSchema,
+        background: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Run agent in background. If false (default), waits for completion or permission request. If true, returns immediately."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Agent-scoped only: get notified when the prompted agent finishes, errors, or needs permission."),
+    };
+    const sendAgentPromptInputSchema = callerAgentId
+        ? agentToAgentSendAgentPromptInputSchema
+        : topLevelSendAgentPromptInputSchema;
+    const inspectProviderInputSchema = {
+        provider: ProviderOrProviderModelInputSchema.describe("Provider ID, optionally with a model ID (for example codex or codex/gpt-5.4)."),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory used to resolve provider feature availability."),
+        settings: InspectProviderSettingsInputSchema.optional().describe("Draft provider settings used to compute available features."),
+    };
+    if (options.voiceOnly || options.enableVoiceTools || callerContext?.enableVoiceTools) {
+        registerTool("speak", {
+            title: "Speak",
+            description: "Speak text to the user via daemon-managed voice output. Blocks until playback completes.",
+            inputSchema: {
+                text: z
+                    .string()
+                    .trim()
+                    .min(1, "text is required")
+                    .max(4000, "text must be 4000 characters or fewer"),
+            },
+            outputSchema: {
+                ok: z.boolean(),
+            },
+        }, async (args, context) => {
+            if (!callerAgentId) {
+                throw new Error("speak is only available to agent-scoped tool sessions");
+            }
+            const handler = resolveSpeakHandler?.(callerAgentId) ?? null;
+            if (!handler) {
+                throw new Error(`No speak handler registered for your session '${callerAgentId}'`);
+            }
+            await handler({
+                text: args.text,
+                callerAgentId,
+                signal: context?.signal,
+            });
+            return {
+                content: [],
+                structuredContent: ensureValidJson({ ok: true }),
+            };
+        });
+    }
+    if (options.voiceOnly) {
+        return toCatalog();
+    }
+    if (options.browserToolsEnabled && options.browserToolsBroker) {
+        registerBrowserTools({
+            registerTool,
+            broker: options.browserToolsBroker,
+            callerAgentId,
+            resolveCallerAgent,
+        });
+    }
+    registerTool("create_workspace", {
+        title: "Create workspace",
+        description: "Create a workspace using an existing local checkout or a new Paseo-managed worktree.",
+        inputSchema: {
+            isolation: z.enum(["local", "worktree"]),
+            path: z
+                .string()
+                .optional()
+                .describe("Local directory or source checkout. Defaults to your current workspace."),
+            projectId: z.string().optional().describe("Existing project id to own the workspace."),
+            title: z.string().trim().min(1).optional(),
+            mode: z
+                .enum(["branch-off", "checkout-branch", "checkout-pr"])
+                .optional()
+                .describe("Worktree creation mode. Defaults to branch-off."),
+            worktreeSlug: z.string().trim().min(1).optional(),
+            branchName: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("New branch name for branch-off mode."),
+            baseBranch: z.string().trim().min(1).optional().describe("Base ref for branch-off mode."),
+            branch: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("Existing branch for checkout-branch mode."),
+            prNumber: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Pull request or change request number for checkout-pr mode."),
+            forge: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("Forge for checkout-pr mode. Defaults to the source checkout."),
+        },
+        outputSchema: WorkspaceAutomationSummarySchema.shape,
+    }, async ({ isolation, path, projectId, title, mode, worktreeSlug, branchName, baseBranch, branch, prNumber, forge, }) => {
+        let workspace;
+        if (isolation === "local") {
+            const cwd = resolveScopedCwd(path, { required: true });
+            assertOptionsAbsent([
+                ["mode", mode],
+                ["worktreeSlug", worktreeSlug],
+                ["branchName", branchName],
+                ["baseBranch", baseBranch],
+                ["branch", branch],
+                ["prNumber", prNumber],
+                ["forge", forge],
+            ], "Worktree options require isolation worktree");
+            if (!options.createDirectoryWorkspace) {
+                throw new Error("Workspace provisioning is not configured");
+            }
+            workspace = await options.createDirectoryWorkspace(cwd, title, projectId);
+        }
+        else {
+            let cwd = path !== undefined || !projectId ? resolveScopedCwd(path, { required: true }) : null;
+            if (!cwd) {
+                if (!options.projectRegistry) {
+                    throw new Error("Project registry is not configured");
+                }
+                cwd = await resolveWorktreeSourceCwd({ projectId }, options.projectRegistry);
+            }
+            const worktreeTarget = resolveWorkspaceWorktreeTarget({
+                mode,
+                worktreeSlug,
+                branchName,
+                baseBranch,
+                branch,
+                prNumber,
+                forge,
+            });
+            const result = await createPaseoWorktreeCommand({
+                paseoHome: options.paseoHome,
+                worktreesRoot: options.worktreesRoot,
+                createPaseoWorktreeWorkflow: options.createPaseoWorktree,
+            }, {
+                cwd,
+                ...(projectId ? { projectId } : {}),
+                ...(worktreeSlug ? { worktreeSlug } : {}),
+                ...worktreeTarget,
+                ...(title ? { title } : {}),
+            });
+            if (!result.ok) {
+                throw result.cause;
+            }
+            workspace = result.createdWorktree.workspace;
+        }
+        return {
+            content: [],
+            structuredContent: ensureValidJson(toWorkspaceAutomationSummary(workspace)),
+        };
+    });
+    registerTool("list_workspaces", {
+        title: "List workspaces",
+        description: "List active workspaces.",
+        inputSchema: {},
+        outputSchema: { workspaces: z.array(WorkspaceAutomationSummarySchema) },
+    }, async () => {
+        if (!options.workspaceRegistry) {
+            throw new Error("Workspace registry is not configured");
+        }
+        const workspaces = (await options.workspaceRegistry.list())
+            .filter((workspace) => !workspace.archivedAt)
+            .map(toWorkspaceAutomationSummary);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ workspaces }),
+        };
+    });
+    registerTool("archive_workspace", {
+        title: "Archive workspace",
+        description: "Archive a workspace and everything it owns.",
+        inputSchema: { workspaceId: z.string().min(1) },
+        outputSchema: {
+            workspaceId: z.string(),
+            archivedAgentIds: z.array(z.string()),
+            removedDirectory: z.boolean(),
+        },
+    }, async ({ workspaceId }) => {
+        if (!options.listActiveWorkspaces) {
+            throw new Error("Active workspace lister is required to archive workspaces");
+        }
+        const workspace = await requireActiveWorkspaceForArchive({ listActiveWorkspaces: options.listActiveWorkspaces }, workspaceId);
+        const result = await archiveByScope(archiveWorktreeDependencies(options, {
+            agentManager,
+            agentStorage,
+            terminalManager: terminalManager ?? null,
+            logger: childLogger,
+        }), {
+            requestId: "mcp:archive_workspace",
+            scope: { kind: "workspace", workspaceId: workspace.workspaceId },
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                workspaceId,
+                archivedAgentIds: result.archivedAgentIds,
+                removedDirectory: result.removedDirectory,
+            }),
+        };
+    });
+    registerTool("create_agent", {
+        title: "Create agent",
+        description: "Create an agent. Agent-scoped creation defaults to your workspace and creates your subagent. Top-level creation without workspaceId creates a new local workspace. Requires provider/model (for example codex/gpt-5.4) and an initial prompt. Do not guess; call list_providers and list_models first if uncertain.",
+        inputSchema: createAgentInputSchema,
+        outputSchema: {
+            agentId: z.string(),
+            type: AgentProviderEnum,
+            status: AgentStatusEnum,
+            cwd: z.string(),
+            workspaceId: z.string().optional(),
+            currentModeId: z.string().nullable(),
+            availableModes: z.array(ProviderModeSchema),
+            lastMessage: z.string().nullable().optional(),
+            permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
+            guidance: z.string().optional(),
+        },
+    }, async (args) => {
+        const resolvedArgs = await resolveCreateAgentToolArgs(args);
+        const { parsedArgs, worktree } = resolvedArgs;
+        let requestedBackground;
+        let notifyOnFinish;
+        if (resolvedArgs.kind === "agent-scoped") {
+            requestedBackground = true;
+            notifyOnFinish = parsedArgs.notifyOnFinish;
+        }
+        else {
+            requestedBackground = resolvedArgs.parsedArgs.background;
+            notifyOnFinish = resolvedArgs.parsedArgs.notifyOnFinish ?? false;
+        }
+        const selectedProvider = resolveRequiredProviderModel(parsedArgs.provider).provider;
+        const inheritedConfig = resolveInheritedProviderConfig(selectedProvider);
+        const { snapshot, background: createdInBackground, initialPromptStarted, } = await createAgentCommand({
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+            paseoHome: options.paseoHome,
+            worktreesRoot: options.worktreesRoot,
+            terminalManager,
+            providerSnapshotManager,
+            createPaseoWorktree: options.createPaseoWorktree,
+            ...(options.ensureWorkspaceForCreate
+                ? { ensureWorkspaceForCreate: options.ensureWorkspaceForCreate }
+                : {}),
+        }, {
+            kind: "mcp",
+            provider: parsedArgs.provider,
+            title: parsedArgs.title,
+            initialPrompt: parsedArgs.initialPrompt,
+            config: inheritedConfig,
+            cwd: resolvedArgs.cwd,
+            workspaceId: resolvedArgs.workspaceId,
+            thinking: parsedArgs.settings?.thinkingOptionId,
+            features: parsedArgs.settings?.features,
+            labels: parsedArgs.labels,
+            mode: parsedArgs.settings?.modeId,
+            background: requestedBackground,
+            notifyOnFinish,
+            detached: resolvedArgs.detached,
+            callerAgentId,
+            callerContext,
+            worktree,
+        });
+        try {
+            if (!createdInBackground && initialPromptStarted) {
+                const result = await waitForAgentWithTimeout(agentManager, snapshot.id, {
+                    waitForActive: true,
+                });
+                const liveSnapshot = agentManager.getAgent(snapshot.id) ?? snapshot;
+                const responseData = {
+                    agentId: snapshot.id,
+                    type: snapshot.provider,
+                    status: result.status,
+                    cwd: liveSnapshot.cwd,
+                    ...(liveSnapshot.workspaceId ? { workspaceId: liveSnapshot.workspaceId } : {}),
+                    currentModeId: liveSnapshot.currentModeId,
+                    availableModes: liveSnapshot.availableModes,
+                    lastMessage: result.lastMessage,
+                    permission: sanitizePermissionRequest(result.permission),
+                };
+                const validJson = ensureValidJson(responseData);
+                const response = {
+                    content: [],
+                    structuredContent: validJson,
+                };
+                return response;
+            }
+        }
+        catch (error) {
+            childLogger.error({ err: error, agentId: snapshot.id }, "Failed to run initial prompt");
+            throw error;
+        }
+        // Return immediately for async creation.
+        const currentSnapshot = agentManager.getAgent(snapshot.id) ?? snapshot;
+        const guidance = callerAgentId && notifyOnFinish && initialPromptStarted
+            ? "You will get notified when the created agent finishes, errors, or needs permission. Do not poll for status; continue with other work until the notification arrives."
+            : undefined;
+        const response = {
+            content: [],
+            structuredContent: ensureValidJson({
+                agentId: currentSnapshot.id,
+                type: snapshot.provider,
+                status: currentSnapshot.lifecycle,
+                cwd: currentSnapshot.cwd,
+                ...(currentSnapshot.workspaceId ? { workspaceId: currentSnapshot.workspaceId } : {}),
+                currentModeId: currentSnapshot.currentModeId,
+                availableModes: currentSnapshot.availableModes,
+                lastMessage: null,
+                permission: null,
+                ...(guidance ? { guidance } : {}),
+            }),
+        };
+        return response;
+    });
+    async function resolveCreateAgentToolArgs(args) {
+        if (callerAgentId) {
+            if (hasLegacyCreateAgentPlacement(args)) {
+                // COMPAT(nestedCreateAgentPlacement): accept the old relationship/workspace shape without
+                // advertising it to models. Added in v0.2.0; remove after 2027-01-17.
+                const parsed = legacyAgentToAgentCreateAgentArgsSchema.parse(args);
+                const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsed.workspace, {
+                    prompt: parsed.initialPrompt,
+                });
+                return {
+                    kind: "agent-scoped",
+                    parsedArgs: parsed,
+                    detached: parsed.relationship.kind === "detached",
+                    cwd,
+                    workspaceId,
+                    worktree,
+                };
+            }
+            const parsed = agentToAgentCreateAgentArgsSchema.parse(args);
+            const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(parsed.workspaceId, {
+                prompt: parsed.initialPrompt,
+            });
+            return {
+                kind: "agent-scoped",
+                parsedArgs: parsed,
+                detached: false,
+                cwd,
+                workspaceId,
+                worktree: undefined,
+            };
+        }
+        if (hasLegacyCreateAgentPlacement(args)) {
+            // COMPAT(nestedCreateAgentPlacement): see the agent-scoped branch above.
+            const parsedArgs = normalizeTopLevelCreateAgentArgs(legacyTopLevelCreateAgentArgsSchema.parse(args));
+            if (parsedArgs.relationship?.kind === "subagent") {
+                throw new Error("relationship subagent requires an agent-scoped tool session");
+            }
+            if (!parsedArgs.workspace) {
+                throw new Error("Legacy create_agent placement could not be resolved");
+            }
+            const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsedArgs.workspace, { prompt: parsedArgs.initialPrompt });
+            return {
+                kind: "top-level",
+                parsedArgs,
+                detached: true,
+                cwd,
+                workspaceId,
+                worktree,
+            };
+        }
+        const parsedArgs = canonicalTopLevelCreateAgentArgsSchema.parse(args);
+        const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(parsedArgs.workspaceId, { prompt: parsedArgs.initialPrompt });
+        return {
+            kind: "top-level",
+            parsedArgs,
+            detached: false,
+            cwd,
+            workspaceId,
+            worktree: undefined,
+        };
+    }
+    function hasLegacyCreateAgentPlacement(args) {
+        if (!args || typeof args !== "object") {
+            return false;
+        }
+        const input = args;
+        return [
+            "relationship",
+            "workspace",
+            "cwd",
+            "worktreeName",
+            "branchName",
+            "baseBranch",
+            "refName",
+            "githubPrNumber",
+        ].some((key) => input[key] !== undefined);
+    }
+    async function resolveCanonicalCreateAgentWorkspace(workspaceId, firstAgentContext) {
+        if (workspaceId) {
+            const resolved = await resolveCreateAgentWorkspace({ kind: "existing", workspaceId }, undefined);
+            return { cwd: resolved.cwd, workspaceId };
+        }
+        if (!callerAgentId) {
+            if (!options.ensureWorkspaceForCreate) {
+                throw new Error("Workspace creation is not configured");
+            }
+            const cwd = process.cwd();
+            return {
+                cwd,
+                workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext),
+            };
+        }
+        const caller = resolveCallerAgent();
+        if (!caller?.workspaceId) {
+            throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+        }
+        return { cwd: undefined, workspaceId: caller.workspaceId };
+    }
+    function normalizeTopLevelCreateAgentArgs(args) {
+        const { cwd, mode, thinking, features, worktreeName, branchName, baseBranch, refName, githubPrNumber, ...canonicalCandidate } = args;
+        const settings = {
+            ...canonicalCandidate.settings,
+            ...(mode ? { modeId: mode } : {}),
+            ...(thinking ? { thinkingOptionId: thinking } : {}),
+            ...(features ? { features } : {}),
+        };
+        if (canonicalCandidate.relationship && canonicalCandidate.workspace) {
+            return legacyTopLevelCreateAgentArgsSchema.parse({
+                ...canonicalCandidate,
+                ...(Object.keys(settings).length > 0 ? { settings } : {}),
+            });
+        }
+        if (canonicalCandidate.relationship || canonicalCandidate.workspace) {
+            throw new Error("relationship and workspace must be provided together");
+        }
+        if (!cwd?.trim()) {
+            throw new Error("cwd is required for legacy top-level create_agent calls");
+        }
+        const legacyWorktreeTarget = resolveLegacyCreateAgentWorktreeTarget({
+            worktreeName,
+            branchName,
+            baseBranch,
+            refName,
+            githubPrNumber,
+        });
+        const workspace = legacyWorktreeTarget
+            ? {
+                kind: "create",
+                source: {
+                    kind: "worktree",
+                    cwd,
+                    target: legacyWorktreeTarget,
+                },
+            }
+            : {
+                kind: "create",
+                source: {
+                    kind: "directory",
+                    path: cwd,
+                },
+            };
+        return legacyTopLevelCreateAgentArgsSchema.parse({
+            ...canonicalCandidate,
+            relationship: { kind: "detached" },
+            workspace,
+            ...(Object.keys(settings).length > 0 ? { settings } : {}),
+        });
+    }
+    function resolveLegacyCreateAgentWorktreeTarget(input) {
+        if (input.githubPrNumber !== undefined) {
+            return {
+                kind: "checkout-pr",
+                githubPrNumber: input.githubPrNumber,
+            };
+        }
+        if (input.refName) {
+            return {
+                kind: "checkout-branch",
+                branch: input.refName,
+            };
+        }
+        if (input.worktreeName || input.branchName || input.baseBranch) {
+            return {
+                kind: "branch-off",
+                worktreeSlug: input.worktreeName,
+                branchName: input.branchName,
+                baseBranch: input.baseBranch,
+            };
+        }
+        return null;
+    }
+    async function resolveCreateAgentWorkspace(workspace, firstAgentContext) {
+        if (workspace.kind === "current") {
+            if (!callerAgentId) {
+                throw new Error("workspace current requires an agent-scoped tool session");
+            }
+            const callerAgent = resolveCallerAgent();
+            if (!callerAgent?.workspaceId) {
+                throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+            }
+            return {
+                cwd: workspace.cwd,
+                workspaceId: callerAgent.workspaceId,
+                worktree: undefined,
+            };
+        }
+        if (workspace.kind === "existing") {
+            if (!options.listActiveWorkspaces) {
+                throw new Error("Workspace lookup is not configured");
+            }
+            const existingWorkspace = (await options.listActiveWorkspaces()).find((candidate) => candidate.workspaceId === workspace.workspaceId);
+            if (!existingWorkspace) {
+                throw new Error(`Workspace ${workspace.workspaceId} not found`);
+            }
+            const cwd = workspace.cwd
+                ? resolveScopedCwd(workspace.cwd, { required: true })
+                : existingWorkspace.cwd;
+            const lockedCwd = callerContext?.lockedCwd?.trim();
+            if (lockedCwd && !isSameOrDescendantPath(expandUserPath(lockedCwd), cwd)) {
+                throw new Error(`Workspace ${workspace.workspaceId} is outside the allowed cwd`);
+            }
+            return {
+                cwd,
+                workspaceId: workspace.workspaceId,
+                worktree: undefined,
+            };
+        }
+        if (workspace.source.kind === "directory") {
+            const cwd = resolveScopedCwd(workspace.source.path, { required: true });
+            if (!options.ensureWorkspaceForCreate) {
+                throw new Error("Workspace creation is not configured");
+            }
+            return {
+                cwd,
+                workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext),
+                worktree: undefined,
+            };
+        }
+        const cwd = resolveScopedCwd(workspace.source.cwd, { required: true });
+        return {
+            cwd,
+            workspaceId: undefined,
+            worktree: resolveCreateAgentWorktree(workspace.source.target),
+        };
+    }
+    function resolveCreateAgentWorktree(target) {
+        switch (target.kind) {
+            case "branch-off":
+                return {
+                    action: "branch-off",
+                    worktreeName: target.worktreeSlug,
+                    branchName: target.branchName,
+                    baseBranch: target.baseBranch,
+                };
+            case "checkout-branch":
+                return {
+                    action: "checkout",
+                    refName: target.branch,
+                };
+            case "checkout-pr":
+                return {
+                    action: "checkout",
+                    githubPrNumber: target.githubPrNumber,
+                };
+            default:
+                throw new Error("unreachable");
+        }
+    }
+    registerTool("send_agent_prompt", {
+        title: "Send agent prompt",
+        description: "Send a task to a running agent. Agent-scoped callers run in background by default; top-level callers wait by default.",
+        inputSchema: sendAgentPromptInputSchema,
+        outputSchema: {
+            success: z.boolean(),
+            status: AgentStatusEnum,
+            lastMessage: z.string().nullable().optional(),
+            permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
+            guidance: z.string().optional(),
+        },
+    }, async ({ agentId, prompt, sessionMode, background = Boolean(callerAgentId), notifyOnFinish = Boolean(callerAgentId), }) => {
+        const shouldNotifyOnFinish = Boolean(callerAgentId && notifyOnFinish && background);
+        await sendPromptToAgent({
+            agentManager,
+            agentStorage,
+            agentId,
+            prompt,
+            sessionMode,
+            logger: childLogger,
+        });
+        if (shouldNotifyOnFinish && callerAgentId) {
+            setupFinishNotification({
+                agentManager,
+                agentStorage,
+                childAgentId: agentId,
+                callerAgentId,
+                logger: childLogger,
+            });
+        }
+        // If not running in background, wait for completion
+        if (!background) {
+            const result = await waitForAgentWithTimeout(agentManager, agentId, {
+                waitForActive: true,
+            });
+            const responseData = {
+                success: true,
+                status: result.status,
+                lastMessage: result.lastMessage,
+                permission: sanitizePermissionRequest(result.permission),
+            };
+            const validJson = ensureValidJson(responseData);
+            const response = {
+                content: [],
+                structuredContent: validJson,
+            };
+            return response;
+        }
+        // Return immediately if background=true
+        // Re-fetch snapshot since the state may have changed
+        const currentSnapshot = agentManager.getAgent(agentId);
+        const responseData = {
+            success: true,
+            status: currentSnapshot?.lifecycle ?? "idle",
+            lastMessage: null,
+            permission: null,
+            ...(shouldNotifyOnFinish
+                ? {
+                    guidance: "You will get notified when the prompted agent finishes, errors, or needs permission. Do not poll for status; continue with other work until the notification arrives.",
+                }
+                : {}),
+        };
+        const validJson = ensureValidJson(responseData);
+        const response = {
+            content: [],
+            structuredContent: validJson,
+        };
+        return response;
+    });
+    registerTool("get_agent_status", {
+        title: "Get agent status",
+        description: "Return the latest snapshot for an agent, including lifecycle state, capabilities, and pending permissions.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            status: AgentStatusEnum,
+            snapshot: AgentSnapshotPayloadSchema,
+        },
+    }, async ({ agentId }) => {
+        const snapshot = agentManager.getAgent(agentId);
+        if (snapshot) {
+            const structuredSnapshot = await serializeSnapshotWithMetadata(agentStorage, snapshot, childLogger);
+            return {
+                content: [],
+                structuredContent: ensureValidJson({
+                    status: snapshot.lifecycle,
+                    snapshot: structuredSnapshot,
+                }),
+            };
+        }
+        const record = await agentStorage.get(agentId);
+        if (!record || record.internal) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        const structuredSnapshot = buildStoredAgentPayload(record, new Set(providerSnapshotManager.listRegisteredProviderIds()));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                status: structuredSnapshot.status,
+                snapshot: structuredSnapshot,
+            }),
+        };
+    });
+    registerTool("list_agents", {
+        title: "List agents",
+        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(AgentListItemPayloadSchema),
+        },
+    }, 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));
+        const storedRecords = await agentStorage.list();
+        const registeredProviderIds = new Set(providerSnapshotManager.listRegisteredProviderIds());
+        const storedAgents = storedRecords
+            .filter((record) => !record.internal && !liveIds.has(record.id))
+            .filter((record) => includeArchived || !record.archivedAt)
+            .filter((record) => includeArchived || isStoredAgentProviderAvailable(record, registeredProviderIds))
+            .map((record) => buildStoredAgentPayload(record, registeredProviderIds));
+        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 }),
+        };
+    });
+    registerTool("cancel_agent", {
+        title: "Cancel agent run",
+        description: "Abort the agent's current run but keep the agent alive for future tasks.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        const { cancelled } = await cancelAgentRunCommand({ agentManager, logger: childLogger }, agentId);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: cancelled }),
+        };
+    });
+    registerTool("archive_agent", {
+        title: "Archive agent",
+        description: "Archive an agent (soft-delete). The agent is interrupted if running and removed from the active list.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        await archiveAgentCommand({
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+        }, agentId);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("kill_agent", {
+        title: "Kill agent",
+        description: "Terminate an agent session permanently.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        await closeAgentCommand({ agentManager }, agentId);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("update_agent", {
+        title: "Update agent",
+        description: "Update an agent name, labels, and/or runtime settings.",
+        inputSchema: {
+            agentId: z.string(),
+            name: z.string().optional(),
+            labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
+            settings: UpdateAgentSettingsInputSchema.optional().describe("Runtime settings to apply to the agent."),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId, name, labels, settings }) => {
+        if (settings?.modeId !== undefined) {
+            await agentManager.setAgentMode(agentId, settings.modeId);
+        }
+        if (settings?.model !== undefined) {
+            await agentManager.setAgentModel(agentId, settings.model);
+        }
+        if (settings?.thinkingOptionId !== undefined) {
+            await agentManager.setAgentThinkingOption(agentId, settings.thinkingOptionId);
+        }
+        if (settings?.features) {
+            for (const [featureId, value] of Object.entries(settings.features)) {
+                await agentManager.setAgentFeature(agentId, featureId, value);
+            }
+        }
+        await updateAgentCommand({ agentManager }, { agentId, name, labels });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("rename_workspace", {
+        title: "Rename workspace",
+        description: "Rename a workspace by setting its user-visible title. Omit workspaceId to rename your current workspace.",
+        inputSchema: {
+            workspaceId: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("Workspace id to rename. Omit to rename your current workspace."),
+            title: z
+                .string()
+                .trim()
+                .min(1, "title is required")
+                .describe("New user-visible workspace title."),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            workspaceId: z.string(),
+            title: z.string(),
+        },
+    }, async ({ workspaceId: requestedWorkspaceId, title }) => {
+        if (!options.workspaceRegistry) {
+            throw new Error("Workspace registry is required to rename workspaces");
+        }
+        if (!options.emitWorkspaceUpdatesForWorkspaceIds) {
+            throw new Error("Workspace update emitter is required to rename workspaces");
+        }
+        const workspaceId = resolveWorkspaceIdForRename(requestedWorkspaceId);
+        const existing = await options.workspaceRegistry.get(workspaceId);
+        if (!existing) {
+            throw new Error(`Workspace ${workspaceId} not found`);
+        }
+        if (existing.archivedAt) {
+            throw new Error(`Workspace ${workspaceId} is archived`);
+        }
+        await options.workspaceRegistry.upsert({
+            ...existing,
+            title,
+            updatedAt: new Date().toISOString(),
+        });
+        await options.emitWorkspaceUpdatesForWorkspaceIds([workspaceId]);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                success: true,
+                workspaceId,
+                title,
+            }),
+        };
+    });
+    registerTool("list_workspace_scripts", {
+        title: "List workspace scripts",
+        description: "List configured workspace scripts and their lifecycle, service port, proxy URL, health, and terminal ID.",
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace ID whose configured scripts to list."),
+        },
+        outputSchema: {
+            scripts: z.array(WorkspaceScriptPayloadSchema),
+        },
+    }, async ({ workspaceId }) => {
+        if (!workspaceScripts) {
+            throw new Error("Workspace script management is not configured");
+        }
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ scripts: await workspaceScripts.list(workspaceId) }),
+        };
+    });
+    registerTool("start_workspace_script", {
+        title: "Start workspace script",
+        description: "Start one configured workspace script through Paseo's managed workspace-script launcher.",
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace ID containing the configured script."),
+            scriptName: z.string().min(1).describe("Configured paseo.json script name to start."),
+        },
+        outputSchema: {
+            script: WorkspaceScriptPayloadSchema,
+        },
+    }, async ({ workspaceId, scriptName }) => {
+        if (!workspaceScripts) {
+            throw new Error("Workspace script management is not configured");
+        }
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                script: await workspaceScripts.launch({ workspaceId, scriptName }),
+            }),
+        };
+    });
+    registerTool("stop_workspace_script", {
+        title: "Stop workspace script",
+        description: "Stop a running workspace script through its supervised terminal lifecycle.",
+        inputSchema: {
+            workspaceId: z.string().describe("Workspace ID containing the running script."),
+            scriptName: z.string().min(1).describe("Configured paseo.json script name to stop."),
+        },
+        outputSchema: {
+            script: WorkspaceScriptPayloadSchema,
+        },
+    }, async ({ workspaceId, scriptName }) => {
+        if (!workspaceScripts) {
+            throw new Error("Workspace script management is not configured");
+        }
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                script: await workspaceScripts.stop({ workspaceId, scriptName }),
+            }),
+        };
+    });
+    registerTool("list_terminals", {
+        title: "List terminals",
+        description: "List terminals for a working directory or across all working directories.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional working directory. Defaults to your current working directory."),
+            all: z.boolean().optional().describe("List terminals across all working directories."),
+        },
+        outputSchema: {
+            terminals: z.array(TerminalSummarySchema),
+        },
+    }, async ({ cwd, all }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminals = all
+            ? (await Promise.all(terminalManager.listDirectories().map(async (directory) => (await terminalManager.getTerminals(directory)).map((terminal) => ({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }))))).flat()
+            : (await terminalManager.getTerminals(resolveScopedCwd(cwd, { required: true }))).map((terminal) => ({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ terminals }),
+        };
+    });
+    registerTool("create_terminal", {
+        title: "Create terminal",
+        description: "Create a terminal session for a working directory.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional working directory. Defaults to your current working directory."),
+            name: z.string().optional().describe("Optional terminal name."),
+        },
+        outputSchema: TerminalSummarySchema.shape,
+    }, async ({ cwd, name }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        const workspaceId = await resolveTerminalWorkspaceId(resolvedCwd);
+        const terminal = await terminalManager.createTerminal({
+            cwd: resolvedCwd,
+            workspaceId,
+            ...(name?.trim() ? { name: name.trim() } : {}),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }),
+        };
+    });
+    registerTool("kill_terminal", {
+        title: "Kill terminal",
+        description: "Kill an existing terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ terminalId }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminal = terminalManager.getTerminal(terminalId);
+        if (!terminal) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        terminal.kill();
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("capture_terminal", {
+        title: "Capture terminal",
+        description: "Capture plain-text terminal output lines from a terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+            start: z.number().optional(),
+            end: z.number().optional(),
+            scrollback: z.boolean().optional(),
+            stripAnsi: z.boolean().optional().default(true),
+        },
+        outputSchema: {
+            terminalId: z.string(),
+            lines: z.array(z.string()),
+            totalLines: z.number().int().nonnegative(),
+        },
+    }, async ({ terminalId, start, end, scrollback, stripAnsi = true }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        if (!terminalManager.getTerminal(terminalId)) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        const capture = await terminalManager.captureTerminal(terminalId, {
+            start: scrollback ? 0 : start,
+            end,
+            stripAnsi,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                terminalId,
+                lines: capture.lines,
+                totalLines: capture.totalLines,
+            }),
+        };
+    });
+    registerTool("send_terminal_keys", {
+        title: "Send terminal keys",
+        description: "Send literal text or special key tokens to a terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+            keys: z.string(),
+            literal: z.boolean().optional(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ terminalId, keys, literal = false }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminal = terminalManager.getTerminal(terminalId);
+        if (!terminal) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        terminal.send({
+            type: "input",
+            data: resolveTerminalKeyToken(keys, literal),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("create_schedule", {
+        title: "Create schedule",
+        description: "Create a recurring schedule that starts a new agent on a cron cadence.",
+        inputSchema: {
+            prompt: z.string().trim().min(1, "prompt is required"),
+            cron: z.string().trim().min(1, "cron is required"),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+            name: z.string().optional(),
+            provider: (callerAgentId ? AgentProviderEnum.optional() : AgentProviderEnum).describe("Provider, or provider/model (for example: codex or codex/gpt-5.4). Defaults to the caller's provider in an agent-scoped session."),
+            cwd: z.string().optional(),
+            isolation: z.enum(["local", "worktree"]).optional(),
+            maxRuns: z.number().int().positive().optional(),
+            expiresIn: z.string().optional(),
+        },
+        outputSchema: ScheduleSummarySchema.shape,
+    }, async ({ prompt, cron, timezone, name, provider, cwd, isolation, maxRuns, expiresIn }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const expiresAt = buildScheduleExpiry(expiresIn);
+        const schedule = await scheduleService.createOrReplace({
+            prompt: prompt.trim(),
+            cadence: buildCronScheduleCadence({
+                cron,
+                ...(timezone !== undefined ? { timezone } : {}),
+            }),
+            target: resolveNewAgentScheduleTarget({ provider, cwd, isolation }),
+            ...(name?.trim() ? { name: name.trim() } : {}),
+            ...(maxRuns === undefined ? {} : { maxRuns }),
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson(toScheduleSummary(schedule)),
+        };
+    });
+    registerTool("create_heartbeat", {
+        title: "Create heartbeat",
+        description: "Create a recurring heartbeat that sends you a prompt on a cron cadence.",
+        inputSchema: {
+            prompt: z.string().trim().min(1, "prompt is required"),
+            cron: z.string().trim().min(1, "cron is required"),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+            name: z.string().optional(),
+            maxRuns: z.number().int().positive().optional(),
+            expiresIn: z.string().optional(),
+        },
+        outputSchema: ScheduleSummarySchema.shape,
+    }, async ({ prompt, cron, timezone, name, maxRuns, expiresIn }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        if (!callerAgentId) {
+            throw new Error("create_heartbeat requires an agent-scoped session");
+        }
+        resolveCallerAgent();
+        const expiresAt = buildScheduleExpiry(expiresIn);
+        const schedule = await scheduleService.createOrReplace({
+            prompt: prompt.trim(),
+            cadence: buildCronScheduleCadence({
+                cron,
+                ...(timezone !== undefined ? { timezone } : {}),
+            }),
+            target: { type: "agent", agentId: callerAgentId },
+            ...(name?.trim() ? { name: name.trim() } : {}),
+            ...(maxRuns === undefined ? {} : { maxRuns }),
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson(toScheduleSummary(schedule)),
+        };
+    });
+    registerTool("delete_heartbeat", {
+        title: "Delete heartbeat",
+        description: "Delete one of your heartbeats.",
+        inputSchema: { id: z.string().min(1) },
+        outputSchema: { success: z.boolean() },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireCallerHeartbeat(id);
+        await scheduleService.delete(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("list_schedules", {
+        title: "List schedules",
+        description: "List all schedules managed by the daemon.",
+        inputSchema: {},
+        outputSchema: {
+            schedules: z.array(ScheduleSummarySchema),
+        },
+    }, async () => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedules = (await scheduleService.list())
+            .filter((schedule) => schedule.target.type === "new-agent")
+            .map((schedule) => toScheduleSummary(schedule));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ schedules }),
+        };
+    });
+    registerTool("inspect_schedule", {
+        title: "Inspect schedule",
+        description: "Inspect a schedule and its run history.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await requireScheduleTarget(id, "new-agent");
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("pause_schedule", {
+        title: "Pause schedule",
+        description: "Pause an active schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(id, "new-agent");
+        await scheduleService.pause(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("resume_schedule", {
+        title: "Resume schedule",
+        description: "Resume a paused schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(id, "new-agent");
+        await scheduleService.resume(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("delete_schedule", {
+        title: "Delete schedule",
+        description: "Delete a schedule permanently.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(id, "new-agent");
+        await scheduleService.delete(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("update_schedule", {
+        title: "Update schedule",
+        description: "Update an existing schedule. Only provided fields are changed; omitted fields remain unchanged.",
+        inputSchema: z
+            .object({
+            id: z.string(),
+            cron: z.string().optional().describe("New cron expression."),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for cron cadence; requires cron. For example: America/New_York."),
+            name: z.string().nullable().optional().describe("New name (null to clear)."),
+            prompt: z.string().trim().min(1).optional().describe("New prompt text."),
+            maxRuns: z
+                .number()
+                .int()
+                .positive()
+                .nullable()
+                .optional()
+                .describe("New max runs limit (null to clear)."),
+            provider: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("New provider for new-agent target."),
+            model: z
+                .string()
+                .trim()
+                .min(1)
+                .nullable()
+                .optional()
+                .describe("New model for new-agent target (null to clear)."),
+            mode: z
+                .string()
+                .trim()
+                .min(1)
+                .nullable()
+                .optional()
+                .describe("New mode for new-agent target (null to clear)."),
+            cwd: z.string().trim().min(1).optional().describe("New cwd for new-agent target."),
+            expiresIn: z
+                .string()
+                .optional()
+                .describe("New relative expiry duration (for example: 1h, 2d)."),
+            clearExpires: z.boolean().optional().describe("Clear any schedule expiry."),
+        })
+            .passthrough(),
+        outputSchema: StoredScheduleSchema.shape,
+    }, async (input) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(input.id, "new-agent");
+        const schedule = await scheduleService.update(buildScheduleUpdateInput(input));
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("schedule_logs", {
+        title: "Schedule logs",
+        description: "Get the run history (logs) for a schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            runs: z.array(ScheduleRunSchema),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(id, "new-agent");
+        const runs = await scheduleService.logs(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ runs }),
+        };
+    });
+    registerTool("run_schedule_once", {
+        title: "Run schedule once",
+        description: "Run a schedule immediately without changing its cron cadence.",
+        inputSchema: { id: z.string().min(1) },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await requireScheduleTarget(id, "new-agent");
+        const schedule = await scheduleService.runOnce(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("list_providers", {
+        title: "List providers",
+        description: "List configured agent providers and accounts, including availability, modes, and each account's base provider.",
+        inputSchema: {},
+        outputSchema: {
+            providers: z.array(ProviderSummarySchema),
+        },
+    }, async () => {
+        const providers = (await providerSnapshotManager.listProviders({ wait: true })).map(toProviderSummary);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ providers }),
+        };
+    });
+    registerTool("list_models", {
+        title: "List models",
+        description: "List models for an agent provider.",
+        inputSchema: {
+            provider: AgentProviderEnum,
+        },
+        outputSchema: {
+            provider: z.string(),
+            models: z.array(AgentModelSchema),
+        },
+    }, async ({ provider }) => {
+        const models = await providerSnapshotManager.listModels({
+            provider,
+            wait: true,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                provider,
+                models,
+            }),
+        };
+    });
+    registerTool("list_profiles", {
+        title: "List agent profiles",
+        description: "List agent profiles: named provider/model/mode bundles a human configured for specific " +
+            "kinds of work. Read each profile's `notes` to pick the one that fits the task you're " +
+            "delegating, then copy its `provider`, `model`, `modeId`, `thinkingOptionId`, and " +
+            "`featureValues` into create_agent (there is no `profile` parameter). Returns an empty " +
+            "list if none are configured.",
+        inputSchema: {},
+        outputSchema: {
+            profiles: z.array(AgentProfileSchema),
+        },
+    }, async () => {
+        const profiles = daemonConfigStore?.get().agentProfiles ?? [];
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ profiles }),
+        };
+    });
+    registerTool("inspect_provider", {
+        title: "Inspect provider",
+        description: "Inspect compact provider capabilities for orchestration, including modes and draft feature settings. Use list_models for the full model list.",
+        inputSchema: inspectProviderInputSchema,
+        outputSchema: {
+            provider: AgentProviderEnum,
+            label: z.string().nullable().optional(),
+            description: z.string().nullable().optional(),
+            enabled: z.boolean(),
+            source: z.enum(["builtin", "custom"]).optional(),
+            baseProviderId: z.string().optional(),
+            status: z.string(),
+            modes: z.array(ProviderModeSchema).nullish(),
+            selectedModel: z.string().nullable(),
+            features: z.array(AgentFeatureSchema),
+        },
+    }, async ({ provider, cwd, settings }) => {
+        const resolvedProviderModel = resolveScheduleProviderAndModel({
+            provider,
+            defaultProvider: provider,
+        });
+        const providerId = resolvedProviderModel.provider;
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        const entry = await providerSnapshotManager.getProvider({
+            cwd: resolvedCwd,
+            provider: providerId,
+            wait: true,
+        });
+        const summary = toProviderSummary(entry);
+        if (!entry.enabled) {
+            throw new Error(`Provider '${providerId}' is disabled`);
+        }
+        if (entry.status !== "ready") {
+            throw new Error(entry.error ?? `Provider '${providerId}' is unavailable`);
+        }
+        const selectedModel = settings?.model ?? resolvedProviderModel.model;
+        const features = await agentManager.listDraftFeatures({
+            provider: providerId,
+            cwd: resolvedCwd,
+            ...(settings?.modeId ? { modeId: settings.modeId } : {}),
+            ...(selectedModel ? { model: selectedModel } : {}),
+            ...(settings?.thinkingOptionId ? { thinkingOptionId: settings.thinkingOptionId } : {}),
+            ...(settings?.features ? { featureValues: settings.features } : {}),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                provider: providerId,
+                label: summary.label,
+                description: summary.description,
+                enabled: summary.enabled,
+                ...(summary.source ? { source: summary.source } : {}),
+                ...(summary.baseProviderId ? { baseProviderId: summary.baseProviderId } : {}),
+                status: summary.status,
+                modes: summary.modes,
+                selectedModel: selectedModel ?? null,
+                features,
+            }),
+        };
+    });
+    registerTool("get_agent_activity", {
+        title: "Get agent activity",
+        description: "Return recent agent timeline entries as a curated summary.",
+        inputSchema: {
+            agentId: z.string(),
+            limit: z
+                .number()
+                .optional()
+                .describe("Optional limit for number of activities to include (most recent first)."),
+        },
+        outputSchema: {
+            agentId: z.string(),
+            updateCount: z.number(),
+            currentModeId: z.string().nullable(),
+            content: z.string(),
+        },
+    }, async ({ agentId, limit }) => {
+        await ensureAgentLoaded(agentId, {
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+        });
+        const timeline = agentManager.getTimeline(agentId);
+        const snapshot = agentManager.getAgent(agentId);
+        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: [],
+            structuredContent: ensureValidJson({
+                agentId,
+                updateCount: timeline.length,
+                currentModeId: snapshot?.currentModeId ?? null,
+                content: contentWithCount,
+            }),
+        };
+    });
+    registerTool("set_agent_mode", {
+        title: "Set agent session mode",
+        description: "Switch the agent's session mode (plan, bypassPermissions, read-only, auto, etc.).",
+        inputSchema: {
+            agentId: z.string(),
+            modeId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            newMode: z.string(),
+        },
+    }, async ({ agentId, modeId }) => {
+        const result = await setAgentModeCommand({ agentManager }, { agentId, modeId });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true, newMode: result.modeId }),
+        };
+    });
+    registerTool("list_pending_permissions", {
+        title: "List pending permissions",
+        description: "Return all pending permission requests across all agents with the normalized payloads.",
+        inputSchema: {},
+        outputSchema: {
+            permissions: z.array(z.object({
+                agentId: z.string(),
+                status: AgentStatusEnum,
+                request: AgentPermissionRequestPayloadSchema,
+            })),
+        },
+    }, async () => {
+        const permissions = agentManager.listAgents().flatMap((agent) => {
+            const payload = toAgentPayload(agent);
+            return payload.pendingPermissions.map((request) => ({
+                agentId: agent.id,
+                status: payload.status,
+                request: sanitizePermissionRequest(request),
+            }));
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ permissions }),
+        };
+    });
+    registerTool("respond_to_permission", {
+        title: "Respond to permission",
+        description: "Approve or deny a pending permission request with an AgentManager-compatible response payload.",
+        inputSchema: {
+            agentId: z.string(),
+            requestId: z.string(),
+            response: AgentPermissionResponseSchema,
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId, requestId, response }) => {
+        await respondToAgentPermission({
+            agentManager,
+            agentId,
+            requestId,
+            response,
+            logger: childLogger,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    return toCatalog();
+}
+function archiveWorktreeDependencies(options, context) {
+    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.findWorkspaceIdForCwd) {
+        throw new Error("Workspace resolver is required to archive worktrees");
+    }
+    if (!options.listActiveWorkspaces) {
+        throw new Error("Active workspace lister is required to archive worktrees");
+    }
+    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");
+    }
+    return {
+        paseoHome: options.paseoHome,
+        paseoWorktreesBaseRoot: options.worktreesRoot,
+        github: options.github,
+        workspaceGitService: options.workspaceGitService,
+        agentManager: context.agentManager,
+        agentStorage: context.agentStorage,
+        findWorkspaceIdForCwd: options.findWorkspaceIdForCwd,
+        listActiveWorkspaces: options.listActiveWorkspaces,
+        archiveWorkspaceRecord: options.archiveWorkspaceRecord,
+        emitWorkspaceUpdatesForWorkspaceIds: options.emitWorkspaceUpdatesForWorkspaceIds,
+        markWorkspaceArchiving: options.markWorkspaceArchiving,
+        clearWorkspaceArchiving: options.clearWorkspaceArchiving,
+        killTerminalsForWorkspace: (workspaceId) => killTerminalsForWorkspace({
+            terminalManager: context.terminalManager,
+            sessionLogger: context.logger,
+        }, workspaceId),
+        sessionLogger: context.logger,
+    };
+}
+//# sourceMappingURL=paseo-tools.js.map