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

package/dist/cli.js

@@ -9,6 +9,9 @@ import { createScheduleCommand } from "./commands/schedule/index.js";
 import { createSpeechCommand } from "./commands/speech/index.js";
 import { createTerminalCommand } from "./commands/terminal/index.js";
 import { createWorktreeCommand } from "./commands/worktree/index.js";
+import { createWorkspaceCommand } from "./commands/workspace/index.js";
+import { createHeartbeatCommand } from "./commands/heartbeat/index.js";
+import { createHubCommand } from "./commands/hub/index.js";
 import { createHooksCommand } from "./commands/hooks.js";
 import { startCommand as daemonStartCommand } from "./commands/daemon/start.js";
 import { runStatusCommand as runDaemonStatusCommand } from "./commands/daemon/status.js";
@@ -100,6 +103,7 @@ export function createCli() {
     program.addCommand(createAgentCommand());
     // Daemon commands
     program.addCommand(createDaemonCommand());
+    program.addCommand(createHubCommand());
     // Chat commands
     program.addCommand(createChatCommand());
     // Terminal commands
@@ -108,14 +112,18 @@ export function createCli() {
     program.addCommand(createLoopCommand());
     // Schedule commands
     program.addCommand(createScheduleCommand());
+    program.addCommand(createHeartbeatCommand());
     // Permission commands
     program.addCommand(createPermitCommand());
     // Provider commands
     program.addCommand(createProviderCommand());
     // Speech model commands
     program.addCommand(createSpeechCommand());
-    // Worktree commands
-    program.addCommand(createWorktreeCommand());
+    // Workspace commands
+    program.addCommand(createWorkspaceCommand());
+    // COMPAT(worktreeCli): legacy command alias added before workspace was the product unit.
+    // Added in v0.2.0; remove after 2027-01-17.
+    program.addCommand(createWorktreeCommand(), { hidden: true });
     return program;
 }
 //# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import type { CommandOptions, SingleResult } from "../../output/index.js";
+interface AgentDetachResult {
+    agentId: string;
+    status: "detached";
+}
+export declare function runDetachCommand(agentIdArg: string, options: CommandOptions, _command: Command): Promise<SingleResult<AgentDetachResult>>;
+export {};
+//# sourceMappingURL=detach.d.ts.map

package/dist/commands/agent/detach.js

@@ -0,0 +1,38 @@
+import { connectToDaemon, getDaemonHost, resolveAgentId } from "../../utils/client.js";
+const detachSchema = {
+    idField: "agentId",
+    columns: [
+        { header: "AGENT ID", field: "agentId" },
+        { header: "STATUS", field: "status" },
+    ],
+};
+export async function runDetachCommand(agentIdArg, options, _command) {
+    const host = getDaemonHost({ host: options.host });
+    let client;
+    try {
+        client = await connectToDaemon({ host: options.host });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw {
+            code: "DAEMON_NOT_RUNNING",
+            message: `Cannot connect to daemon at ${host}: ${message}`,
+        };
+    }
+    try {
+        const payload = await client.fetchAgents({ filter: { includeArchived: true } });
+        const agentId = resolveAgentId(agentIdArg, payload.entries.map((entry) => entry.agent));
+        if (!agentId) {
+            throw {
+                code: "AGENT_NOT_FOUND",
+                message: `Agent not found: ${agentIdArg}`,
+            };
+        }
+        await client.detachAgent(agentId);
+        return { type: "single", data: { agentId, status: "detached" }, schema: detachSchema };
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=detach.js.map

package/dist/commands/agent/index.js

@@ -13,6 +13,8 @@ import { addAttachOptions, runAttachCommand } from "./attach.js";
 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() {
@@ -23,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));
@@ -37,6 +40,10 @@ export function createAgentCommand() {
         .option("--list", "List available modes for this agent")).action(withOutput(runModeCommand));
     addJsonAndDaemonHostOptions(addArchiveOptions(agent.command("archive"))).action(withOutput(runArchiveCommand));
     addJsonAndDaemonHostOptions(addReloadOptions(agent.command("reload"))).action(withOutput(runReloadCommand));
+    addJsonAndDaemonHostOptions(agent
+        .command("detach")
+        .description("Make a subagent independent without stopping or moving it")
+        .argument("<id>", "Agent ID, prefix, or name")).action(withOutput(runDetachCommand));
     addJsonAndDaemonHostOptions(agent
         .command("update")
         .description("Update an agent's metadata")

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

@@ -14,6 +14,7 @@ export interface AgentRunResult {
 /** Schema for agent run output */
 export declare const agentRunSchema: OutputSchema<AgentRunResult>;
 export interface AgentRunOptions extends CommandOptions {
+    background?: boolean;
     detach?: boolean;
     title?: string;
     name?: string;
@@ -21,8 +22,15 @@ export interface AgentRunOptions extends CommandOptions {
     model?: string;
     thinking?: string;
     mode?: 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;
@@ -40,5 +48,31 @@ export declare function resolveStructuredResponseMessage(options: {
     agentId: string;
     lastMessage: string | null;
 }): Promise<string | null>;
+interface RunWorkspace {
+    id?: string;
+    cwd: string;
+}
+export interface RunWorkspaceLookupClient {
+    fetchWorkspaces(options: {
+        filter: {
+            query: string;
+        };
+        page: {
+            limit: number;
+        };
+    }): Promise<{
+        entries: Array<{
+            id: string;
+            workspaceDirectory: string;
+        }>;
+        pageInfo: {
+            nextCursor: string | null;
+        };
+    }>;
+}
+export declare function resolveExistingRunWorkspace(client: RunWorkspaceLookupClient, workspaceId: string): Promise<RunWorkspace>;
 export declare function runRunCommand(prompt: string, options: AgentRunOptions, _command: Command): Promise<SingleResult<AgentRunResult>>;
+export declare function resolveRunCallerAgentId(env?: {
+    PASEO_AGENT_ID?: string;
+}): string | undefined;
 //# sourceMappingURL=run.d.ts.map

package/dist/commands/agent/run.js

@@ -7,27 +7,38 @@ 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
+    return (cmd
         .description("Create and start an agent with a task")
         .argument("<prompt>", "The task/prompt for the agent")
-        .option("-d, --detach", "Run in background (detached)")
+        .option("-d, --background", "Run in background")
+        // COMPAT(detachRunFlag): --detach used to mean background execution, not
+        // ownership transfer. Added in v0.2.0; remove after 2027-01-17.
+        .addOption(new Option("--detach", "Legacy alias for --background").hideHelp())
         .option("--title <title>", "Assign a title to the agent")
         .addOption(new Option("--name <name>", "Hidden alias for --title").hideHelp())
         .option("--provider <provider>", "Agent provider, or provider/model (e.g. codex or codex/gpt-5.4)")
         .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("--worktree <name>", "Create agent in a new git worktree")
-        .option("--base <branch>", "Base branch for worktree (default: current branch)")
-        .option("--workspace <id>", "Run in an existing workspace (default: a new workspace is created per run; falls back to $PASEO_WORKSPACE_ID)")
+        .option("--new-workspace <local|worktree>", "Create a separate local or worktree workspace")
+        .addOption(new Option("--worktree <name>", "Legacy workspace isolation alias").hideHelp())
+        .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, [])
         .option("--label <key=value>", "Add label(s) to the agent (can be used multiple times)", collectMultiple, [])
         .option("--wait-timeout <duration>", "Maximum time to wait for agent to finish (e.g., 30s, 5m, 1h). Default: no limit")
-        .option("--output-schema <schema>", "Output JSON matching the provided schema file path or inline JSON schema");
+        .option("--output-schema <schema>", "Output JSON matching the provided schema file path or inline JSON schema"));
 }
 /** Schema for agent run output */
 export const agentRunSchema = {
@@ -40,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,
@@ -164,43 +192,88 @@ 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",
         };
     }
-    if (options.base && !options.worktree) {
+    if (options.newWorkspace && options.worktree) {
+        throw {
+            code: "INVALID_OPTIONS",
+            message: "--new-workspace and --worktree cannot be combined",
+            details: "Use --new-workspace worktree and the supported worktree options",
+        };
+    }
+    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: "Worktree options require --new-workspace worktree",
+            details: "Usage: paseo run --new-workspace worktree [worktree options] <prompt>",
+        };
+    }
+    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: "--base can only be used with --worktree",
-            details: "Usage: paseo agent run --worktree <name> --base <branch> <prompt>",
+            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.
+    // Added in v0.2.0; remove after 2027-01-17.
     if (options.worktree && options.workspace) {
         throw {
             code: "INVALID_OPTIONS",
             message: "--worktree and --workspace cannot be combined",
-            details: "--workspace runs in an existing workspace; --worktree mints a new one",
+            details: "Use --new-workspace worktree instead of the legacy --worktree flag",
         };
     }
-    if (options.worktree && !options.workspace && process.env.PASEO_WORKSPACE_ID) {
+}
+function validateRunOptions(prompt, options, outputSchema) {
+    if (!prompt || prompt.trim().length === 0) {
         throw {
-            code: "INVALID_OPTIONS",
-            message: "--worktree cannot be combined with an ambient PASEO_WORKSPACE_ID",
-            details: "PASEO_WORKSPACE_ID selects an existing workspace; --worktree mints a new one. Unset PASEO_WORKSPACE_ID to use --worktree.",
+            code: "MISSING_PROMPT",
+            message: "A prompt is required",
+            details: "Usage: paseo agent run [options] <prompt>",
         };
     }
-    if (outputSchema && options.detach) {
+    validateRunWorkspaceOptions(options);
+    if (outputSchema && runsInBackground(options)) {
         throw {
             code: "INVALID_OPTIONS",
-            message: "--output-schema cannot be used with --detach",
+            message: "--output-schema cannot be used with --background",
             details: "Structured output requires waiting for the agent to finish",
         };
     }
 }
+function runsInBackground(options) {
+    return Boolean(options.background || options.detach);
+}
 function parseWaitTimeoutOption(waitTimeout) {
     if (!waitTimeout)
         return 0;
@@ -289,36 +362,45 @@ async function connectToDaemonOrThrow(hostOption, host) {
         };
     }
 }
+export async function resolveExistingRunWorkspace(client, workspaceId) {
+    const result = await client.fetchWorkspaces({
+        filter: { query: workspaceId },
+        page: { limit: 200 },
+    });
+    const workspace = result.entries.find((entry) => entry.id === workspaceId);
+    if (workspace) {
+        return { id: workspace.id, cwd: workspace.workspaceDirectory };
+    }
+    throw {
+        code: "WORKSPACE_NOT_FOUND",
+        message: `Workspace not found: ${workspaceId}`,
+    };
+}
 // Workspace policy for `paseo run`. Precedence:
 //   1. --workspace <id>            -> run in that existing workspace
-//   2. $PASEO_WORKSPACE_ID         -> exported by workspace terminals
-//   3. --worktree <name>           -> mint a new worktree-backed workspace
-//   4. bare run                    -> mint a new local-backed workspace for cwd
-// --worktree is rejected alongside both --workspace and an ambient
-// $PASEO_WORKSPACE_ID (validateRunOptions), so worktree resolution here never
-// races an existing-workspace selection.
+//   2. $PASEO_AGENT_ID             -> daemon resolves the caller's workspace
+//   3. $PASEO_WORKSPACE_ID         -> exported by workspace terminals
+//   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) {
-    // An explicit --worktree mints its own workspace; --workspace and an ambient
-    // PASEO_WORKSPACE_ID are both rejected alongside --worktree upstream.
-    const explicit = options.worktree
-        ? undefined
-        : options.workspace?.trim() || process.env.PASEO_WORKSPACE_ID?.trim();
+    const newWorkspace = resolveNewWorkspaceKind(options);
+    const explicit = newWorkspace ? undefined : options.workspace?.trim();
     if (explicit) {
         console.error(`Using workspace ${explicit}`);
-        return { id: explicit, cwd };
+        return resolveExistingRunWorkspace(client, explicit);
+    }
+    if (!newWorkspace && resolveRunCallerAgentId()) {
+        return { cwd };
+    }
+    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 = options.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",
@@ -357,6 +439,7 @@ export async function runRunCommand(prompt, options, _command) {
         const requestEnv = Object.keys(env).length > 0 ? env : undefined;
         const workspace = await resolveRunWorkspace(client, options, cwd);
         const workspaceId = workspace.id;
+        const callerAgentId = resolveRunCallerAgentId();
         const runCwd = workspace.cwd;
         if (outputSchema) {
             let structuredAgent = null;
@@ -366,6 +449,7 @@ export async function runRunCommand(prompt, options, _command) {
                         provider: resolvedProviderModel.provider,
                         cwd: runCwd,
                         workspaceId,
+                        callerAgentId,
                         title: resolvedTitle,
                         modeId: options.mode,
                         model: resolvedProviderModel.model,
@@ -420,6 +504,7 @@ export async function runRunCommand(prompt, options, _command) {
             provider: resolvedProviderModel.provider,
             cwd: runCwd,
             workspaceId,
+            callerAgentId,
             title: resolvedTitle,
             modeId: options.mode,
             model: resolvedProviderModel.model,
@@ -429,8 +514,8 @@ export async function runRunCommand(prompt, options, _command) {
             env: requestEnv,
             labels: Object.keys(labels).length > 0 ? labels : undefined,
         });
-        // Default run behavior is foreground: wait for completion unless --detach is set.
-        if (!options.detach) {
+        // Default run behavior is foreground: wait for completion unless background execution is set.
+        if (!runsInBackground(options)) {
             const state = await client.waitForFinish(agent.id, waitTimeoutMs);
             await client.close();
             const finalAgent = state.final ?? agent;
@@ -461,4 +546,7 @@ export async function runRunCommand(prompt, options, _command) {
         throw error;
     }
 }
+export function resolveRunCallerAgentId(env = process.env) {
+    return env.PASEO_AGENT_ID?.trim() || undefined;
+}
 //# sourceMappingURL=run.js.map

package/dist/commands/heartbeat/index.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createHeartbeatCommand(): Command;
+//# sourceMappingURL=index.d.ts.map