feat(plugins): New workspace items set the branch and workspace metadata

addNewWorkspaceItem mounts a plugin field on the New workspace screen, and
useNewWorkspace() exposes host, project, isolation, base ref, branch and
metadata with commands that follow the composer item rules: they act on the
screen's state when they run, resolve once applied, reject while the screen
is locked, and take JSON payloads. Host and project are read-only because a
command that switched them would unmount the item that called it.

The screen's pickable state (base selection, manual isolation, branch,
metadata) moves into one plain store so pickers and plugin commands write to
the same place; the screen reports derived facts to it on each render. The
branch is sent as source.branchName only for a branch-off worktree, and
metadata on workspace.create.

Items render through ComposerControl with a new "field" surface (badge on
desktop, full-width field when compact). Combobox ships here: Paseo owns the
loading and error states, keeps previous results, and drops superseded
searches.

packages/plugin/src/boundaries.test.ts

@@ -250,6 +250,51 @@ describe("plugin composer SDK boundary", () => {
   });
 });
 
+describe("plugin New workspace SDK boundary", () => {
+  it("lets a New workspace item read the setup and change it through typed commands and a Combobox", () => {
+    expect(
+      typeErrors(`
+      import { useNewWorkspace, type PluginClientContext } from "@getpaseo/plugin/client";
+      import { Combobox } from "@getpaseo/plugin/client/ui";
+      interface Issue { id: string; label: string; branch: string }
+      function Item() {
+        const newWorkspace = useNewWorkspace();
+        const isolation: "local" | "worktree" = newWorkspace.isolation;
+        const branch: string | null = newWorkspace.branch;
+        const project: string | undefined = newWorkspace.project?.name;
+        const host: string = newWorkspace.host.label;
+        const base = newWorkspace.baseRef;
+        if (base?.type === "branch") { const name: string = base.name; }
+        // @ts-expect-error project is read-only
+        newWorkspace.project = null;
+        // @ts-expect-error host is read-only
+        newWorkspace.setHost("other");
+        // @ts-expect-error metadata reads are not writable
+        newWorkspace.metadata.key = "x";
+        newWorkspace.setIsolation("worktree").then(() => newWorkspace.setBaseRef({ type: "branch", name: "main" }));
+        newWorkspace.setBranch(null);
+        newWorkspace.setMetadata({ issue: "1", stale: null });
+        // @ts-expect-error commands take JSON values
+        newWorkspace.setMetadata({ fn: () => {} });
+        return (
+          <Combobox<Issue>
+            title="Issue"
+            icon="CircleDot"
+            value={{ id: "1", label: "One" }}
+            search={async ({ query }: { query: string }) => [{ id: query, label: query, branch: "b" }]}
+            onSelect={({ item }) => newWorkspace.setBranch(item.branch)}
+          />
+        );
+      }
+      export default function contribute(client: PluginClientContext) {
+        client.addNewWorkspaceItem({ id: "item", Component: Item });
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});
+
 describe("plugin agent tools SDK boundary", () => {
   it("lets a session hook attach typed tools without exposing their transport", () => {
     expect(

packages/plugin/src/client/contracts.ts

@@ -5,6 +5,7 @@ import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-type
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
 import type { PluginFile } from "./file.js";
 import type { PluginComposerItemContribution } from "./composer.js";
+import type { PluginNewWorkspaceItemContribution } from "./new-workspace.js";
 import type {
   PluginRpcContract,
   PluginSubscribeOptions,
@@ -202,6 +203,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
   ): PluginButtonRegistration<PluginText>;
   addAttachmentSource(contribution: PluginAttachmentSourceContribution<PluginText>): PluginCleanup;
   addComposerItem(contribution: PluginComposerItemContribution): PluginCleanup;
+  addNewWorkspaceItem(contribution: PluginNewWorkspaceItemContribution): PluginCleanup;
   addTheme(contribution: PluginThemeContribution<PluginText>): PluginCleanup;
   addFilePanel(contribution: PluginFilePanelContribution<PluginText>): PluginCleanup;
   addTimelineTransformer<ItemType extends AgentTimelineItem["type"]>(

packages/plugin/src/client/host.ts

@@ -2,6 +2,7 @@ import type { PluginText } from "../text.js";
 import { PluginAttachmentSearchPayloadSchema } from "../attachments.js";
 export { PluginClientStateProvider, type PluginClientStateSource } from "./client-state.js";
 export { PluginComposerProvider } from "./composer.js";
+export { PluginNewWorkspaceProvider } from "./new-workspace.js";
 export {
   usePluginRuntimeContextBridge,
   type PluginRuntimeContextBridge,

packages/plugin/src/client/index.ts

@@ -78,6 +78,12 @@ export type {
   PluginComposerItemContribution,
   PluginComposerItemProps,
 } from "./composer.js";
+export { useNewWorkspace } from "./new-workspace.js";
+export type {
+  PluginNewWorkspace,
+  PluginNewWorkspaceItemContribution,
+  PluginNewWorkspaceItemProps,
+} from "./new-workspace.js";
 export { useRpc, useSubscription, type PluginSubscriptionState } from "./rpc-context.js";
 export type {
   PluginSubscribeOptions,

packages/plugin/src/client/new-workspace.tsx

@@ -0,0 +1,65 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginHostProps } from "./contracts.js";
+
+/**
+ * The New workspace setup the item sits in. `host` and `project` are the user's choices and are
+ * read-only. The commands change what the created workspace is built from, under the same rules as
+ * the screen's own pickers.
+ */
+export interface PluginNewWorkspace {
+  readonly host: { readonly id: string; readonly label: string };
+  readonly project: { readonly id: string; readonly name: string } | null;
+  /** What the screen will create. A project that cannot make worktrees reads `"local"`. */
+  readonly isolation: "local" | "worktree";
+  /** What a new worktree starts from; `null` until the project's default is known. */
+  readonly baseRef:
+    | { readonly type: "branch"; readonly name: string }
+    | { readonly type: "change-request"; readonly number: number }
+    | null;
+  /**
+   * The name of the branch a new worktree is created on; `null` lets Paseo pick one. It is kept
+   * while isolation is local or the base is a change request, and applies only to a worktree
+   * created from a branch.
+   */
+  readonly branch: string | null;
+  /** The workspace's metadata, not the first agent's. */
+  readonly metadata: Readonly<Record<string, JsonValue>>;
+  /** Rejects `"worktree"` for a project that cannot make worktrees. */
+  setIsolation(isolation: "local" | "worktree"): Promise<void>;
+  /** Starts the workspace from a branch. Rejects while no project is chosen. */
+  setBaseRef(ref: { type: "branch"; name: string }): Promise<void>;
+  setBranch(name: string | null): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. Rejects on a host without metadata support. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+export interface PluginNewWorkspaceItemProps extends PluginHostProps {}
+
+export interface PluginNewWorkspaceItemContribution {
+  id: string;
+  Component: ComponentType<PluginNewWorkspaceItemProps>;
+}
+
+const PluginNewWorkspaceContext = createContext<PluginNewWorkspace | null>(null);
+
+export function PluginNewWorkspaceProvider({
+  newWorkspace,
+  children,
+}: {
+  newWorkspace: PluginNewWorkspace;
+  children: ReactNode;
+}) {
+  return (
+    <PluginNewWorkspaceContext.Provider value={newWorkspace}>
+      {children}
+    </PluginNewWorkspaceContext.Provider>
+  );
+}
+
+/** The New workspace setup this item sits in. Call it from a component registered with `addNewWorkspaceItem`. */
+export function useNewWorkspace(): PluginNewWorkspace {
+  const newWorkspace = useContext(PluginNewWorkspaceContext);
+  if (!newWorkspace) throw new Error("useNewWorkspace must run inside a New workspace item");
+  return newWorkspace;
+}

packages/plugin/src/client/ui.ts

@@ -210,10 +210,35 @@ export interface ActionPressEvent {}
 export interface ActionProps extends ComposerControlProps {
   onPress(event: ActionPressEvent): void | Promise<void>;
 }
+/** One result of a `Combobox` search. Extra fields ride along to `onSelect`. */
+export interface ComboboxItem {
+  id: string;
+  label: string;
+  description?: string;
+}
+export interface ComboboxSearchEvent {
+  /** Empty when the list opens. */
+  query: string;
+}
+export interface ComboboxProps<
+  Item extends ComboboxItem = ComboboxItem,
+> extends ComposerControlProps {
+  /** What the control shows. It need not be among the search results. */
+  value: ComboboxItem | null;
+  /**
+   * Called when the list opens and again, debounced, as the user types. Paseo shows the loading
+   * and error states, keeps the previous results while a search runs, and ignores a search that a
+   * newer one replaced.
+   */
+  search(event: ComboboxSearchEvent): Promise<readonly Item[]>;
+  onSelect(event: { item: Item }): void | Promise<void>;
+}
 /**
- * Composer controls. Render them from a composer item's `Component`. Paseo draws them inline when
- * the composer has room and as rows in its overflow sheet when it does not.
+ * Paseo's controls. Render them from a composer item's or a New workspace item's `Component`.
+ * Paseo draws them where the item sits: inline when the composer has room and as rows in its
+ * overflow sheet when it does not, and as a field in the New workspace setup.
  */
 export declare const Toggle: ComponentType<ToggleProps>;
 export declare function Select<Value extends string>(props: SelectProps<Value>): ReactNode;
 export declare const Action: ComponentType<ActionProps>;
+export declare function Combobox<Item extends ComboboxItem>(props: ComboboxProps<Item>): ReactNode;