@getpaseo/cli 0.2.0-beta.2 → 0.2.0-beta.3

package/dist/commands/agent/index.js

@@ -14,6 +14,7 @@ import { addReloadOptions, runReloadCommand } from "./reload.js";
 import { addImportOptions, runImportCommand } from "./import.js";
 import { runUpdateCommand } from "./update.js";
 import { runDetachCommand } from "./detach.js";
+import { addOpenOptions, runOpenCommand } from "./open.js";
 import { withOutput } from "../../output/index.js";
 import { addDaemonHostOption, addJsonAndDaemonHostOptions, collectMultiple, } from "../../utils/command-options.js";
 export function createAgentCommand() {
@@ -24,6 +25,7 @@ export function createAgentCommand() {
     addJsonAndDaemonHostOptions(addImportOptions(agent.command("import"))).action(withOutput(runImportCommand));
     addDaemonHostOption(addAttachOptions(agent.command("attach"))).action(runAttachCommand);
     addDaemonHostOption(addLogsOptions(agent.command("logs"))).action(runLogsCommand);
+    addJsonAndDaemonHostOptions(addOpenOptions(agent.command("open"))).action(withOutput(runOpenCommand));
     addJsonAndDaemonHostOptions(addStopOptions(agent.command("stop"))).action(withOutput(runStopCommand));
     addJsonAndDaemonHostOptions(addDeleteOptions(agent.command("delete"))).action(withOutput(runDeleteCommand));
     addJsonAndDaemonHostOptions(addSendOptions(agent.command("send"))).action(withOutput(runSendCommand));

package/dist/commands/agent/open.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+import type { CommandOptions, SingleResult } from "../../output/index.js";
+interface OpenAgentResult {
+    agentId: string;
+    serverId: string;
+    status: "opened";
+}
+export declare function addOpenOptions(command: Command): Command;
+export declare function runOpenCommand(agentIdArg: string, options: CommandOptions, _command: Command): Promise<SingleResult<OpenAgentResult>>;
+export {};
+//# sourceMappingURL=open.d.ts.map

package/dist/commands/agent/open.js

@@ -0,0 +1,61 @@
+import { buildDaemonConnectionCommandError, connectToDaemon } from "../../utils/client.js";
+import { openDesktopWithAgent } from "../open.js";
+const openAgentSchema = {
+    idField: "agentId",
+    columns: [
+        { header: "AGENT ID", field: "agentId" },
+        { header: "SERVER ID", field: "serverId" },
+        { header: "STATUS", field: "status" },
+    ],
+};
+export function addOpenOptions(command) {
+    return command
+        .description("Open an existing agent in Paseo Desktop")
+        .argument("<agent-id>", "Existing agent ID")
+        .option("--server <server-id>", "Server ID (defaults to the local daemon)");
+}
+async function resolveServerId(options) {
+    const explicitServerId = typeof options.server === "string" ? options.server.trim() : "";
+    if (explicitServerId) {
+        return explicitServerId;
+    }
+    let client;
+    try {
+        client = await connectToDaemon({ host: options.host });
+    }
+    catch (error) {
+        throw buildDaemonConnectionCommandError({ host: options.host, error });
+    }
+    try {
+        const serverId = client.getLastServerInfoMessage()?.serverId.trim();
+        if (!serverId) {
+            const error = {
+                code: "SERVER_ID_UNAVAILABLE",
+                message: "The daemon did not report a server ID.",
+            };
+            throw error;
+        }
+        return serverId;
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+export async function runOpenCommand(agentIdArg, options, _command) {
+    const agentId = agentIdArg.trim();
+    if (!agentId) {
+        const error = {
+            code: "MISSING_AGENT_ID",
+            message: "Agent ID is required.",
+        };
+        throw error;
+    }
+    const serverId = await resolveServerId(options);
+    await openDesktopWithAgent({ serverId, agentId });
+    return {
+        type: "single",
+        data: { agentId, serverId, status: "opened" },
+        schema: openAgentSchema,
+    };
+}
+//# sourceMappingURL=open.js.map

package/dist/commands/agent/run.d.ts

@@ -22,9 +22,15 @@ export interface AgentRunOptions extends CommandOptions {
     model?: string;
     thinking?: string;
     mode?: string;
-    isolation?: string;
+    newWorkspace?: string;
     worktree?: string;
+    worktreeMode?: string;
+    worktreeSlug?: string;
+    newBranch?: string;
     base?: string;
+    branch?: string;
+    prNumber?: string;
+    forge?: string;
     workspace?: string;
     image?: string[];
     cwd?: string;

package/dist/commands/agent/run.js

@@ -7,6 +7,7 @@ import { lookup } from "mime-types";
 import { parseDuration } from "../../utils/duration.js";
 import { collectMultiple } from "../../utils/command-options.js";
 import { resolveProviderAndModel } from "../../utils/provider-model.js";
+import { buildWorkspaceSource } from "../workspace/create.js";
 export { resolveProviderAndModel } from "../../utils/provider-model.js";
 export function addRunOptions(cmd) {
     return (cmd
@@ -22,10 +23,16 @@ export function addRunOptions(cmd) {
         .option("--model <model>", "Model to use (e.g., claude-sonnet-4-20250514, claude-3-5-haiku-20241022)")
         .option("--thinking <id>", "Thinking option ID to use for this run")
         .option("--mode <mode>", "Provider-specific mode (e.g., plan, default, bypass)")
-        .option("--isolation <local|worktree>", "Create a new workspace with this isolation")
+        .option("--new-workspace <local|worktree>", "Create a separate local or worktree workspace")
         .addOption(new Option("--worktree <name>", "Legacy workspace isolation alias").hideHelp())
-        .option("--base <branch>", "Base branch for an isolated workspace")
-        .option("--workspace <id>", "Run in an existing workspace (default: a new workspace is created per run; falls back to $PASEO_WORKSPACE_ID)")
+        .option("--worktree-mode <mode>", "Worktree mode: branch-off, checkout-branch, or checkout-pr")
+        .option("--worktree-slug <slug>", "Managed worktree path slug")
+        .option("--new-branch <name>", "New branch name for branch-off mode")
+        .option("--base <ref>", "Base ref for branch-off mode")
+        .option("--branch <name>", "Existing branch for checkout-branch mode")
+        .option("--pr-number <n>", "Pull request or change request number for checkout-pr mode")
+        .option("--forge <forge>", "Forge for checkout-pr mode")
+        .option("--workspace <id>", "Run in an existing workspace (defaults to the caller workspace when agent-scoped)")
         .option("--image <path>", "Attach image(s) to the initial prompt (can be used multiple times)", collectMultiple, [])
         .option("--cwd <path>", "Working directory (default: current)")
         .option("--env <key=value>", "Set environment variable(s) for the agent process (can be used multiple times)", collectMultiple, [])
@@ -44,6 +51,23 @@ export const agentRunSchema = {
         { header: "TITLE", field: "title", width: 20 },
     ],
 };
+function resolveNewWorkspaceKind(options) {
+    return options.newWorkspace ?? (options.worktree ? "worktree" : undefined);
+}
+function buildRunWorkspaceSource(options, cwd) {
+    const newWorkspace = resolveNewWorkspaceKind(options) ?? "local";
+    return buildWorkspaceSource({
+        isolation: newWorkspace,
+        path: cwd,
+        mode: options.worktreeMode,
+        worktreeSlug: options.worktreeSlug ?? options.worktree,
+        newBranch: options.newBranch,
+        base: options.base,
+        branch: options.branch,
+        prNumber: options.prNumber,
+        forge: options.forge,
+    });
+}
 function toRunResult(agent, statusOverride) {
     return {
         agentId: agent.id,
@@ -168,34 +192,56 @@ function structuredRunSchema(output) {
         serialize: () => output,
     };
 }
-function validateRunOptions(prompt, options, outputSchema) {
-    if (!prompt || prompt.trim().length === 0) {
+function validateRunWorkspaceOptions(options) {
+    const newWorkspace = resolveNewWorkspaceKind(options);
+    if (options.newWorkspace &&
+        options.newWorkspace !== "local" &&
+        options.newWorkspace !== "worktree") {
         throw {
-            code: "MISSING_PROMPT",
-            message: "A prompt is required",
-            details: "Usage: paseo agent run [options] <prompt>",
+            code: "INVALID_OPTIONS",
+            message: `Unsupported new workspace kind: ${options.newWorkspace}`,
+            details: "Use --new-workspace local or --new-workspace worktree",
         };
     }
-    const createsIsolatedWorkspace = options.isolation === "worktree" || Boolean(options.worktree);
-    if (options.isolation && options.isolation !== "local" && options.isolation !== "worktree") {
+    if (options.newWorkspace && options.worktree) {
         throw {
             code: "INVALID_OPTIONS",
-            message: `Unsupported workspace isolation: ${options.isolation}`,
-            details: "Use --isolation local or --isolation worktree",
+            message: "--new-workspace and --worktree cannot be combined",
+            details: "Use --new-workspace worktree and the supported worktree options",
         };
     }
-    if (options.base && !createsIsolatedWorkspace) {
+    const hasWorktreeCreationOptions = [
+        options.worktreeMode,
+        options.worktreeSlug,
+        options.newBranch,
+        options.base,
+        options.branch,
+        options.prNumber,
+        options.forge,
+    ].some((value) => value !== undefined);
+    if (hasWorktreeCreationOptions && newWorkspace !== "worktree") {
         throw {
             code: "INVALID_OPTIONS",
-            message: "--base can only be used with --isolation worktree",
-            details: "Usage: paseo agent run --isolation worktree --base <branch> <prompt>",
+            message: "Worktree options require --new-workspace worktree",
+            details: "Usage: paseo run --new-workspace worktree [worktree options] <prompt>",
         };
     }
-    if (options.isolation && options.workspace) {
+    if (newWorkspace === "worktree") {
+        try {
+            buildRunWorkspaceSource(options, options.cwd ?? process.cwd());
+        }
+        catch (error) {
+            throw {
+                code: "INVALID_OPTIONS",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    if (options.newWorkspace && options.workspace) {
         throw {
             code: "INVALID_OPTIONS",
-            message: "--isolation and --workspace cannot be combined",
-            details: "Select an existing workspace or create a new one with an isolation choice",
+            message: "--new-workspace and --workspace cannot be combined",
+            details: "Select an existing workspace or explicitly create a new one",
         };
     }
     // COMPAT(worktreeRunFlag): --worktree implies a new worktree-isolated workspace.
@@ -204,9 +250,19 @@ function validateRunOptions(prompt, options, outputSchema) {
         throw {
             code: "INVALID_OPTIONS",
             message: "--worktree and --workspace cannot be combined",
-            details: "Use --isolation worktree instead of the legacy --worktree flag",
+            details: "Use --new-workspace worktree instead of the legacy --worktree flag",
+        };
+    }
+}
+function validateRunOptions(prompt, options, outputSchema) {
+    if (!prompt || prompt.trim().length === 0) {
+        throw {
+            code: "MISSING_PROMPT",
+            message: "A prompt is required",
+            details: "Usage: paseo agent run [options] <prompt>",
         };
     }
+    validateRunWorkspaceOptions(options);
     if (outputSchema && runsInBackground(options)) {
         throw {
             code: "INVALID_OPTIONS",
@@ -324,37 +380,27 @@ export async function resolveExistingRunWorkspace(client, workspaceId) {
 //   1. --workspace <id>            -> run in that existing workspace
 //   2. $PASEO_AGENT_ID             -> daemon resolves the caller's workspace
 //   3. $PASEO_WORKSPACE_ID         -> exported by workspace terminals
-//   4. --isolation <kind>          -> mint a new workspace with explicit isolation
+//   4. --new-workspace <kind>      -> mint a new workspace explicitly
 //   5. bare run                    -> mint a new local-backed workspace for cwd
 async function resolveRunWorkspace(client, options, cwd) {
-    const requestedIsolation = options.isolation ?? (options.worktree ? "worktree" : undefined);
-    const explicit = requestedIsolation ? undefined : options.workspace?.trim();
+    const newWorkspace = resolveNewWorkspaceKind(options);
+    const explicit = newWorkspace ? undefined : options.workspace?.trim();
     if (explicit) {
         console.error(`Using workspace ${explicit}`);
         return resolveExistingRunWorkspace(client, explicit);
     }
-    if (!requestedIsolation && resolveRunCallerAgentId()) {
+    if (!newWorkspace && resolveRunCallerAgentId()) {
         return { cwd };
     }
-    const ambientWorkspaceId = requestedIsolation
-        ? undefined
-        : process.env.PASEO_WORKSPACE_ID?.trim();
+    const ambientWorkspaceId = newWorkspace ? undefined : process.env.PASEO_WORKSPACE_ID?.trim();
     if (ambientWorkspaceId) {
         console.error(`Using workspace ${ambientWorkspaceId}`);
         return resolveExistingRunWorkspace(client, ambientWorkspaceId);
     }
     // TODO: thread the run `prompt` as firstAgentContext so workspace-level
     // title/branch generation picks up the task description (U8/U6 deferred).
-    const result = requestedIsolation === "worktree"
-        ? await client.createWorkspace({
-            source: {
-                kind: "worktree",
-                cwd,
-                worktreeSlug: options.worktree,
-                baseBranch: options.base,
-            },
-        })
-        : await client.createWorkspace({ source: { kind: "directory", path: cwd } });
+    const source = buildRunWorkspaceSource(options, cwd);
+    const result = await client.createWorkspace({ source });
     if (!result.workspace) {
         throw {
             code: "WORKSPACE_CREATE_FAILED",

package/dist/commands/open.d.ts

@@ -1,2 +1,4 @@
+import { type AgentDeepLinkTarget } from "@getpaseo/protocol/agent-deep-link";
 export declare function openDesktopWithProject(projectPath: string): Promise<void>;
+export declare function openDesktopWithAgent(target: AgentDeepLinkTarget): Promise<void>;
 //# sourceMappingURL=open.d.ts.map

package/dist/commands/open.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { spawnProcess } from "@getpaseo/server";
+import { buildAgentDeepLink } from "@getpaseo/protocol/agent-deep-link";
 function findDesktopApp() {
     if (process.platform === "darwin") {
         const candidates = [
@@ -55,25 +56,26 @@ function spawnDetached(command, args) {
         env: cleanEnvForDesktopLaunch(),
     }).unref();
 }
+function launchDesktop(args) {
+    if (process.env.PASEO_DESKTOP_CLI === "1") {
+        throw new Error("Cannot open Paseo Desktop while running in desktop CLI passthrough mode.");
+    }
+    const desktopApp = findDesktopApp();
+    if (!desktopApp) {
+        throw new Error("Paseo desktop app not found. Install it from https://github.com/getpaseo/paseo/releases");
+    }
+    if (process.platform === "darwin") {
+        // -n forces a new instance even if the app is already running. The new
+        // instance relays its argv to the existing one through Electron's
+        // single-instance lock. -g keeps the terminal in the foreground.
+        spawnDetached("open", ["-n", "-g", "-a", desktopApp, "--args", ...args]);
+        return;
+    }
+    spawnDetached(desktopApp, args);
+}
 export async function openDesktopWithProject(projectPath) {
     try {
-        if (process.env.PASEO_DESKTOP_CLI === "1") {
-            throw new Error("Cannot open a desktop project while running in desktop CLI passthrough mode.");
-        }
-        const desktopApp = findDesktopApp();
-        if (!desktopApp) {
-            throw new Error("Paseo desktop app not found. Install it from https://github.com/getpaseo/paseo/releases");
-        }
-        if (process.platform === "darwin") {
-            // -n forces a new instance even if the app is already running.
-            // The new instance hits requestSingleInstanceLock(), fails, and relays
-            // the argv to the first instance via the second-instance event.
-            // -g keeps the terminal in the foreground (better CLI UX).
-            // Without -n, macOS just activates the existing window and drops --args.
-            spawnDetached("open", ["-n", "-g", "-a", desktopApp, "--args", projectPath]);
-            return;
-        }
-        spawnDetached(desktopApp, [projectPath]);
+        launchDesktop([projectPath]);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -81,4 +83,7 @@ export async function openDesktopWithProject(projectPath) {
         process.exitCode = 1;
     }
 }
+export async function openDesktopWithAgent(target) {
+    launchDesktop([buildAgentDeepLink(target)]);
+}
 //# sourceMappingURL=open.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpaseo/cli",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.3",
   "description": "Paseo CLI - control your AI coding agents from the command line",
   "bin": {
     "paseo": "bin/paseo"
@@ -27,9 +27,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.0.0",
-    "@getpaseo/client": "0.2.0-beta.2",
-    "@getpaseo/protocol": "0.2.0-beta.2",
-    "@getpaseo/server": "0.2.0-beta.2",
+    "@getpaseo/client": "0.2.0-beta.3",
+    "@getpaseo/protocol": "0.2.0-beta.3",
+    "@getpaseo/server": "0.2.0-beta.3",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "mime-types": "^2.1.35",