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

package/dist/commands/hub/connect.d.ts

@@ -7,6 +7,8 @@ interface HubConnectOptions {
     apiKey?: string;
     host?: string;
     json?: boolean;
+    permission?: readonly string[];
+    permissions?: readonly string[];
 }
 interface HubConnectDependencies {
     env: Readonly<Record<string, string | undefined>>;

package/dist/commands/hub/connect.js

@@ -15,8 +15,14 @@ export async function runHubConnect(originInput, options, dependencies) {
     reportHubProgress(dependencies.reporter, options, `Connecting this daemon to ${origin}`);
     const credential = resolveHubCredential({ ...resolution, origin });
     const token = await dependencies.hub.issueEnrollmentToken(origin, credential);
+    const permissions = options.permissions ?? options.permission ?? [];
     return withHubDaemon(dependencies.daemon, options.host, async (daemon) => {
-        const response = await daemon.connectHub(origin, token);
+        const response = await daemon.connectHub(origin, token, permissions);
+        if (response.status.hubOrigin !== null &&
+            !samePermissions(response.status.permissions, permissions)) {
+            await daemon.disconnectHub(false).catch(() => undefined);
+            throw new Error("The daemon did not honor the requested Hub access. Update Paseo before connecting it.");
+        }
         return hubStatusResult(response.status);
     });
 }
@@ -25,10 +31,14 @@ export function addHubConnectCommand(parent, dependencies) {
         .command("connect")
         .description("Enroll this daemon with a Paseo Hub")
         .argument("[origin]", "Paseo Hub origin")
-        .option("--api-key <secret>", "Organization API key"))).action(withOutput(async (...args) => {
+        .option("--api-key <secret>", "Organization API key")
+        .option("--permission <permission...>", "Grant daemon permission during connection"))).action(withOutput(async (...args) => {
         const origin = args[0];
         const options = args.at(-2);
         return runHubConnect(origin, options, dependencies);
     }));
 }
+function samePermissions(actual, expected) {
+    return actual.length === expected.length && expected.every((scope) => actual.includes(scope));
+}
 //# sourceMappingURL=connect.js.map

package/dist/commands/hub/daemon-client.d.ts

@@ -3,7 +3,7 @@ export interface HubStatus {
     state: string;
     daemonId: string | null;
     hubOrigin: string | null;
-    scopes: string[];
+    permissions: string[];
     connectedAt: string | null;
     lastError: string | null;
 }
@@ -11,7 +11,13 @@ export interface HubProvidersSnapshotOptions {
     cwd?: string;
 }
 export interface HubDaemonClient {
-    connectHub(url: string, token: string): Promise<{
+    connectHub(url: string, token: string, permissions?: readonly string[]): Promise<{
+        status: HubStatus;
+    }>;
+    updateHubPermissions(input: {
+        grant?: readonly string[];
+        revoke?: readonly string[];
+    }): Promise<{
         status: HubStatus;
     }>;
     getHubStatus(): Promise<{

package/dist/commands/hub/export.d.ts

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import { type SingleResult } from "../../output/index.js";
+import type { HubCredentialStore } from "./credentials.js";
+import type { HubHttpClient } from "./hub-client/index.js";
+import { type HubReporter } from "./reporter.js";
+interface HubExportResult {
+    origin: string;
+    directory: string;
+    exported: number;
+    unchanged: number;
+}
+export interface HubExportOptions {
+    hub?: string;
+    apiKey?: string;
+    force?: boolean;
+    json?: boolean;
+}
+interface HubExportDependencies {
+    env: Readonly<Record<string, string | undefined>>;
+    credentials: HubCredentialStore;
+    hub: Pick<HubHttpClient, "listTriggers">;
+    reporter: HubReporter;
+    cwd(): string;
+}
+export declare function runHubExport(directoryInput: string | undefined, options: HubExportOptions, dependencies: HubExportDependencies): Promise<SingleResult<HubExportResult>>;
+export declare function addHubExportCommand(parent: Command, dependencies: HubExportDependencies): void;
+export {};
+//# sourceMappingURL=export.d.ts.map

package/dist/commands/hub/export.js

@@ -0,0 +1,80 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { withOutput } from "../../output/index.js";
+import { addJsonOption } from "../../utils/command-options.js";
+import { resolveHubCredential, resolveHubOrigin } from "./authority.js";
+import { HubCommandError } from "./error.js";
+import { addHubResolutionHelp } from "./help.js";
+import { reportHubProgress } from "./reporter.js";
+const schema = {
+    idField: "directory",
+    columns: [
+        { header: "DIRECTORY", field: "directory" },
+        { header: "EXPORTED", field: "exported" },
+        { header: "UNCHANGED", field: "unchanged" },
+        { header: "HUB", field: "origin" },
+    ],
+};
+export async function runHubExport(directoryInput, options, dependencies) {
+    const resolution = {
+        options: { origin: options.hub, apiKey: options.apiKey },
+        env: dependencies.env,
+        credentials: dependencies.credentials,
+    };
+    const origin = resolveHubOrigin(resolution);
+    const credential = resolveHubCredential({ ...resolution, origin });
+    const directory = path.resolve(dependencies.cwd(), directoryInput ?? ".paseo/triggers");
+    reportHubProgress(dependencies.reporter, options, `Exporting triggers from ${origin}`);
+    const triggers = await dependencies.hub.listTriggers(origin, credential);
+    await mkdir(directory, { recursive: true });
+    const files = await Promise.all(triggers.map(async (trigger) => {
+        const destination = path.join(directory, `${trigger.name}.yml`);
+        return { destination, trigger, existing: await readOptionalFile(destination) };
+    }));
+    const conflict = files.find(({ existing, trigger }) => existing !== undefined && existing !== trigger.yaml && options.force !== true);
+    if (conflict !== undefined) {
+        throw new HubCommandError("HUB_EXPORT_CONFLICT", `${conflict.destination} already exists with different contents. Pass --force to replace it.`);
+    }
+    for (const file of files) {
+        if (file.existing === file.trigger.yaml)
+            continue;
+        await writeFile(file.destination, file.trigger.yaml, file.existing === undefined ? { flag: "wx" } : undefined);
+    }
+    return {
+        type: "single",
+        data: {
+            origin,
+            directory,
+            exported: files.filter(({ existing, trigger }) => existing !== trigger.yaml).length,
+            unchanged: files.filter(({ existing, trigger }) => existing === trigger.yaml).length,
+        },
+        schema,
+    };
+}
+export function addHubExportCommand(parent, dependencies) {
+    addJsonOption(addHubResolutionHelp(parent
+        .command("export")
+        .description("Export active Hub triggers as one YAML file per trigger")
+        .argument("[directory]", "Destination directory", ".paseo/triggers")
+        .option("--hub <origin>", "Paseo Hub origin")
+        .option("--api-key <secret>", "Organization API key")
+        .option("--force", "Replace trigger files with different contents"))).action(withOutput(async (...args) => {
+        const directory = args[0];
+        const options = args.at(-2);
+        return runHubExport(directory, options, dependencies);
+    }));
+}
+async function readOptionalFile(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/hub/hub-client/index.d.ts

@@ -1,6 +1,6 @@
 import type { HubBundleFile } from "../deploy-bundle.js";
-import { type CliAuthorization, type CliAuthorizationPoll, type HubInstallResult, type HubConfigurationResources, type HubSetupResources, type HubProject, type HubValidationResult } from "./internal/contracts.js";
-export type { CliAuthorization, CliAuthorizationPoll, HubInstallResult, HubConfigurationResources, HubSetupResources, HubProject, HubValidationResult, } from "./internal/contracts.js";
+import { type CliAuthorization, type CliAuthorizationPoll, type HubInstallResult, type HubConfigurationResources, type HubSetupResources, type HubProject, type HubTrigger, type HubValidationResult } from "./internal/contracts.js";
+export type { CliAuthorization, CliAuthorizationPoll, HubInstallResult, HubConfigurationResources, HubSetupResources, HubProject, HubTrigger, HubValidationResult, } from "./internal/contracts.js";
 interface HubConfigurationInput {
     origin: string;
     apiKey: string;
@@ -11,6 +11,7 @@ export declare class HubHttpClient {
     startCliAuthorization(origin: string): Promise<CliAuthorization>;
     pollCliAuthorization(origin: string, deviceCode: string, timeoutMilliseconds: number): Promise<CliAuthorizationPoll>;
     listProjects(origin: string, apiKey: string): Promise<HubProject[]>;
+    listTriggers(origin: string, apiKey: string): Promise<HubTrigger[]>;
     listConfigurationResources(origin: string, apiKey: string): Promise<HubConfigurationResources>;
     listSetupResources(origin: string, apiKey: string): Promise<HubSetupResources>;
     installConfiguration(input: HubConfigurationInput): Promise<HubInstallResult>;

package/dist/commands/hub/hub-client/index.js

@@ -1,5 +1,5 @@
 import { HubCommandError } from "../error.js";
-import { authorizationPollSchema, authorizationSchema, configurationResourcesSchema, enrollmentTokenSchema, installResponseSchema, projectsResponseSchema, validationResponseSchema, setupResourcesSchema, } from "./internal/contracts.js";
+import { authorizationPollSchema, authorizationSchema, configurationResourcesSchema, enrollmentTokenSchema, installResponseSchema, projectsResponseSchema, triggersResponseSchema, validationResponseSchema, setupResourcesSchema, } from "./internal/contracts.js";
 import { requestHub } from "./internal/transport.js";
 export class HubHttpClient {
     startCliAuthorization(origin) {
@@ -45,6 +45,18 @@ export class HubHttpClient {
         });
         return response.projects;
     }
+    async listTriggers(origin, apiKey) {
+        const response = await requestHub({
+            origin,
+            path: "/api/v1/triggers",
+            method: "GET",
+            apiKey,
+            successStatus: 200,
+            schema: triggersResponseSchema,
+            failureMessage: "Hub trigger export failed",
+        });
+        return response.triggers;
+    }
     listConfigurationResources(origin, apiKey) {
         return requestHub({
             origin,

package/dist/commands/hub/hub-client/internal/contracts.d.ts

@@ -42,6 +42,28 @@ export declare const projectsResponseSchema: z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+declare const triggerSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    enabled: z.ZodBoolean;
+    format: z.ZodEnum<{
+        single_run: "single_run";
+        legacy_multistep: "legacy_multistep";
+    }>;
+    yaml: z.ZodString;
+}, z.core.$strict>;
+export declare const triggersResponseSchema: z.ZodObject<{
+    triggers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        enabled: z.ZodBoolean;
+        format: z.ZodEnum<{
+            single_run: "single_run";
+            legacy_multistep: "legacy_multistep";
+        }>;
+        yaml: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const configurationResourcesSchema: z.ZodObject<{
     daemons: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -95,6 +117,7 @@ export declare const enrollmentTokenSchema: z.ZodObject<{
 export type CliAuthorization = z.infer<typeof authorizationSchema>;
 export type CliAuthorizationPoll = z.infer<typeof authorizationPollSchema>;
 export type HubProject = z.infer<typeof projectSchema>;
+export type HubTrigger = z.infer<typeof triggerSchema>;
 export type HubConfigurationResources = z.infer<typeof configurationResourcesSchema>;
 export type HubSetupResources = z.infer<typeof setupResourcesSchema>;
 export type HubInstallResult = z.infer<typeof installResponseSchema>;

package/dist/commands/hub/hub-client/internal/contracts.js

@@ -30,6 +30,16 @@ const projectSchema = z
     .object({ id: z.string().uuid(), slug: z.string().min(1), name: z.string().min(1) })
     .strict();
 export const projectsResponseSchema = z.object({ projects: z.array(projectSchema) }).strict();
+const triggerSchema = z
+    .object({
+    id: z.string().uuid(),
+    name: z.string().regex(/^[a-z][a-z0-9_-]*$/u),
+    enabled: z.boolean(),
+    format: z.enum(["single_run", "legacy_multistep"]),
+    yaml: z.string(),
+})
+    .strict();
+export const triggersResponseSchema = z.object({ triggers: z.array(triggerSchema) }).strict();
 export const configurationResourcesSchema = z
     .object({
     daemons: z.array(z.object({ id: z.string().uuid(), slug: z.string().min(1) }).strict()),

package/dist/commands/hub/index.js

@@ -11,10 +11,12 @@ import { createCliLoginFlow } from "./login-flow.js";
 import { addHubLoginCommand } from "./login.js";
 import { addHubLogoutCommand, productionLogoutPrompt } from "./logout.js";
 import { addHubProjectsCommand } from "./projects.js";
+import { addHubExportCommand } from "./export.js";
 import { processHubReporter } from "./reporter.js";
 import { hubStatusResult } from "./status-output.js";
 import { addHubResolutionHelp } from "./help.js";
 import { addHubInitCommand, continueHubGuidedSetup } from "./init.js";
+import { addHubPermissionsCommand } from "./permissions.js";
 function productionEnvironment() {
     const env = process.env;
     const hub = new HubHttpClient();
@@ -56,12 +58,23 @@ export function createHubCommand(overrides = {}) {
         daemon: environment.daemon,
         reporter: environment.reporter,
     });
+    addHubPermissionsCommand(hub, {
+        daemon: environment.daemon,
+        reporter: environment.reporter,
+    });
     addHubProjectsCommand(hub, {
         env: environment.env,
         credentials: environment.credentials,
         hub: environment.hub,
         reporter: environment.reporter,
     });
+    addHubExportCommand(hub, {
+        env: environment.env,
+        credentials: environment.credentials,
+        hub: environment.hub,
+        reporter: environment.reporter,
+        cwd: environment.cwd,
+    });
     addHubDeployCommand(hub, {
         env: environment.env,
         credentials: environment.credentials,

package/dist/commands/hub/init.js

@@ -112,31 +112,28 @@ export async function runHubGuidedSetup(environment, state = {}) {
     outro(deploy ? "Hub is ready" : "Hub bundle is ready");
 }
 export async function continueHubGuidedSetup(origin, environment) {
-    if (!(await requiredConfirm(environment, "Connect this daemon to this Hub?", true))) {
-        reportMessage(environment, `Skipped daemon connection. Run: ${hubLoginResumeCommand("connect", origin)}; then paseo hub init`);
-        return;
-    }
-    const daemonId = await ensureDaemonConnection(origin, environment, true);
-    if (!(await requiredConfirm(environment, "Initialize and deploy a starter workflow?", true))) {
-        reportMessage(environment, `Skipped starter workflow. Run: ${hubLoginResumeCommand("init", origin)}`);
-        return;
-    }
-    try {
-        await runHubGuidedSetup(environment, { origin, daemonId, deploy: true });
-    }
-    catch (error) {
-        if (error instanceof HubInitCancelledError) {
-            if (environment.prompts === undefined) {
-                log.message(error.message);
-                outro("Connect an app to continue");
-            }
-            else {
-                environment.prompts.message(error.message);
-            }
-            return;
+    const currentStatus = await withHubDaemon(environment.daemon, undefined, async (daemon) => daemon.getHubStatus().then((response) => response.status));
+    const current = resolveHubInitConnection(currentStatus, origin);
+    if (current.kind === "connected") {
+        reportMessage(environment, `This daemon is already connected to ${origin}. Permissions: ${currentStatus.permissions.join(", ") || "None"}.`);
+    }
+    else if (current.kind === "pending") {
+        await waitForDaemonReady(origin, environment.daemon);
+    }
+    else if (current.kind === "conflict") {
+        reportMessage(environment, `This daemon is connected to ${current.origin}. Disconnect it before connecting to ${origin}.`);
+    }
+    else if (await requiredConfirm(environment, "Connect this daemon to Paseo Hub?\n\nConnecting lets Hub identify this daemon and show whether it is online.\nIt does not allow Hub to create workspaces or run agents.", true)) {
+        const grantExecution = await requiredConfirm(environment, "Allow Hub automations to run agents on this daemon?\n\nThis lets workflows triggered from GitHub, Slack, Discord, Linear, and other integrations create workspaces and run agents here.\n\nAgents can access files and run commands allowed by their workspace runtime.", false);
+        await ensureDaemonConnection(origin, environment, true, grantExecution ? ["hub.execute"] : []);
+        if (!grantExecution) {
+            reportMessage(environment, "Daemon connected with no permissions.\n\nEnable Hub automations later:\n  paseo hub permissions grant hub.execute");
         }
-        throw error;
     }
+    else {
+        reportMessage(environment, `Skipped daemon connection. Connect later with: ${hubLoginResumeCommand("connect", origin)}`);
+    }
+    reportMessage(environment, `Configure triggers in Hub: ${new URL("/triggers", origin).toString()}\nOr scaffold triggers as code: ${hubLoginResumeCommand("init", origin)}`);
 }
 async function ensureLogin(activeOrigin, environment) {
     const endpoint = await requiredSelect(environment, {
@@ -175,10 +172,13 @@ async function ensureLogin(activeOrigin, environment) {
     log.success(`Logged in to ${normalizedOrigin}`);
     return normalizedOrigin;
 }
-async function ensureDaemonConnection(origin, environment, confirmed = false) {
+async function ensureDaemonConnection(origin, environment, confirmed = false, permissions = ["hub.execute"]) {
     const status = await withHubDaemon(environment.daemon, undefined, async (daemon) => daemon.getHubStatus().then((response) => response.status));
     const connection = resolveHubInitConnection(status, origin);
     if (connection.kind === "connected") {
+        if (permissions.includes("hub.execute") && !status.permissions.includes("hub.execute")) {
+            throw new HubCommandError("HUB_DAEMON_EXECUTION_NOT_ALLOWED", "This daemon is connected to Hub but cannot run Hub automations. Run `paseo hub permissions grant hub.execute`, then run Hub init again.");
+        }
         return connection.daemonId;
     }
     if (connection.kind === "pending") {
@@ -188,13 +188,13 @@ async function ensureDaemonConnection(origin, environment, confirmed = false) {
         throw new HubCommandError("HUB_DAEMON_ALREADY_CONNECTED", `This daemon is connected to ${connection.origin}. Disconnect it before running Hub init for ${origin}.`);
     }
     if (!confirmed &&
-        !(await requiredConfirm(environment, `Connect this daemon to ${origin}?`, true))) {
+        !(await requiredConfirm(environment, `Connect this daemon to ${origin} and allow Hub workflows to create and control workspaces and agents?`, true))) {
         throw new HubInitCancelledError("A connected daemon is required to create the bundle.");
     }
-    return connectDaemon(origin, environment);
+    return connectDaemon(origin, environment, permissions);
 }
-async function connectDaemon(origin, environment) {
-    await runHubConnect(origin, {}, {
+async function connectDaemon(origin, environment, permissions = ["hub.execute"]) {
+    await runHubConnect(origin, { permissions }, {
         env: environment.env,
         credentials: environment.credentials,
         hub: environment.hub,

package/dist/commands/hub/permissions.d.ts

@@ -0,0 +1,21 @@
+import type { Command } from "commander";
+import { type ListResult } from "../../output/index.js";
+import type { HubDaemonConnection } from "./daemon-client.js";
+import { type HubReporter } from "./reporter.js";
+interface HubPermissionsOptions {
+    host?: string;
+    json?: boolean;
+}
+interface HubPermissionsDependencies {
+    daemon: HubDaemonConnection;
+    reporter: HubReporter;
+}
+interface PermissionRow {
+    permission: string;
+    description: string;
+}
+export declare function runHubPermissionsList(options: HubPermissionsOptions, dependencies: HubPermissionsDependencies): Promise<ListResult<PermissionRow>>;
+export declare function runHubPermissionChange(operation: "grant" | "revoke", permission: string, options: HubPermissionsOptions, dependencies: HubPermissionsDependencies): Promise<ListResult<import("./status-output.js").HubRow>>;
+export declare function addHubPermissionsCommand(parent: Command, dependencies: HubPermissionsDependencies): void;
+export {};
+//# sourceMappingURL=permissions.d.ts.map

package/dist/commands/hub/permissions.js

@@ -0,0 +1,61 @@
+import { withOutput } from "../../output/index.js";
+import { addJsonAndDaemonHostOptions } from "../../utils/command-options.js";
+import { withHubDaemon } from "./daemon-client.js";
+import { reportHubProgress } from "./reporter.js";
+import { hubStatusResult } from "./status-output.js";
+const schema = {
+    idField: "permission",
+    columns: [
+        { header: "PERMISSION", field: "permission" },
+        { header: "DESCRIPTION", field: "description" },
+    ],
+};
+export function runHubPermissionsList(options, dependencies) {
+    return withHubDaemon(dependencies.daemon, options.host, async (client) => {
+        const status = (await client.getHubStatus()).status;
+        requireConnectedHub(status);
+        return {
+            type: "list",
+            data: status.permissions.map((permission) => ({
+                permission,
+                description: describePermission(permission),
+            })),
+            schema,
+        };
+    });
+}
+export function runHubPermissionChange(operation, permission, options, dependencies) {
+    return withHubDaemon(dependencies.daemon, options.host, async (client) => {
+        const current = (await client.getHubStatus()).status;
+        requireConnectedHub(current);
+        const response = await client.updateHubPermissions(operation === "grant" ? { grant: [permission] } : { revoke: [permission] });
+        reportHubProgress(dependencies.reporter, options, `${operation === "grant" ? "Granted" : "Revoked"} ${permission} ${operation === "grant" ? "to" : "from"} ${response.status.hubOrigin}`);
+        return hubStatusResult(response.status);
+    });
+}
+export function addHubPermissionsCommand(parent, dependencies) {
+    const permissions = parent
+        .command("permissions")
+        .description("Manage this Hub's daemon permissions");
+    addJsonAndDaemonHostOptions(permissions.command("list")).action(withOutput(async (...args) => {
+        const options = args.at(-2);
+        return runHubPermissionsList(options, dependencies);
+    }));
+    for (const operation of ["grant", "revoke"]) {
+        addJsonAndDaemonHostOptions(permissions.command(operation).argument("<permission>", "Daemon permission")).action(withOutput(async (...args) => {
+            const permission = args[0];
+            const options = args.at(-2);
+            return runHubPermissionChange(operation, permission, options, dependencies);
+        }));
+    }
+}
+function requireConnectedHub(status) {
+    if (status.hubOrigin === null ||
+        (status.state !== "connected" && status.state !== "reconnecting")) {
+        throw new Error("This daemon is not connected to a Hub");
+    }
+}
+function describePermission(permission) {
+    return permission === "hub.execute" ? "Run agents for Hub automations" : permission;
+}
+//# sourceMappingURL=permissions.js.map

package/dist/commands/hub/status-output.d.ts

@@ -4,7 +4,7 @@ export interface HubRow {
     state: string;
     daemonId: string | null;
     hub: string | null;
-    scopes: string;
+    permissions: string;
     connectedAt: string | null;
     error: string | null;
     warning?: string;

package/dist/commands/hub/status-output.js

@@ -4,7 +4,7 @@ const schema = {
         { header: "STATE", field: "state" },
         { header: "HUB", field: "hub" },
         { header: "DAEMON", field: "daemonId" },
-        { header: "SCOPES", field: "scopes" },
+        { header: "PERMISSIONS", field: "permissions" },
         { header: "CONNECTED", field: "connectedAt" },
         { header: "ERROR", field: "error" },
         { header: "WARNING", field: "warning" },
@@ -18,7 +18,7 @@ export function hubStatusResult(status, warning, reportedHubOrigin = status.hubO
                 state: status.state,
                 daemonId: status.daemonId,
                 hub: reportedHubOrigin,
-                scopes: status.scopes.join(", "),
+                permissions: status.permissions.join(", "),
                 connectedAt: status.connectedAt,
                 error: status.lastError,
                 warning,

package/dist/commands/plugin/scaffold.js

@@ -140,7 +140,15 @@ declare module "@getpaseo/plugin" {
     layout: { compact: boolean; platform: "ios" | "android" | "web" };
   }
 
-  export interface PluginSurfaceProps extends PluginHostProps {}
+  interface PluginNavigableHostProps extends PluginHostProps {
+    /** Client-owned navigation. Undefined on older hosts; hide dependent affordances when absent. */
+    readonly navigation?: {
+      readonly openAgent: (input: { readonly agentId: string }) => void;
+      readonly openWorkspace: (input: { readonly workspaceId: string }) => void;
+    };
+  }
+
+  export interface PluginSurfaceProps extends PluginNavigableHostProps {}
 
   export interface PluginIconProps {
     name: string;
@@ -183,12 +191,12 @@ declare module "@getpaseo/plugin" {
     readonly labels: Readonly<Record<string, string>>;
   }
 
-  export interface PluginWorkspacePanelProps extends PluginHostProps {
+  export interface PluginWorkspacePanelProps extends PluginNavigableHostProps {
     context: "workspace";
     workspaceId: string;
   }
 
-  export interface PluginAgentPanelProps extends PluginHostProps {
+  export interface PluginAgentPanelProps extends PluginNavigableHostProps {
     context: "agent";
     workspaceId: string;
     agentId: string;

package/package.json

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