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.

plugin-examples/new-workspace-issues/README.md

@@ -0,0 +1,17 @@
+# New workspace issues
+
+Install this directory as a plugin and open New workspace. An **Issue** field appears beside the
+project, host, and branch pickers: a field on a phone, a badge on desktop.
+
+Choosing an issue:
+
+- Calls `newWorkspace.setBranch(issue.branch)`, so a worktree is created on that branch name.
+- Calls `newWorkspace.setMetadata({ "new-workspace-issues.issue": issue.id })`, so the created
+  workspace carries the issue id.
+
+`Combobox` runs `search` when the list opens and again as the user types. Paseo shows the loading
+and error states and drops results that a newer search replaced. The server handler in
+[server/issues.ts](server/issues.ts) filters a fixed list; a real plugin would call its tracker.
+
+[client/issue-field.tsx](client/issue-field.tsx) is the field; [index.client.tsx](index.client.tsx)
+registers it with `addNewWorkspaceItem`.

plugin-examples/new-workspace-issues/client/issue-field.tsx

@@ -0,0 +1,31 @@
+import { useCallback, useMemo } from "react";
+import { useNewWorkspace, useRpc } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc, type Issue } from "../shared/issues";
+
+const ISSUE_KEY = "new-workspace-issues.issue";
+
+/** Starts the workspace on the issue's branch and records which issue it is for. */
+export function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata[ISSUE_KEY];
+  const value = useMemo(
+    () => (typeof issueId === "string" ? { id: issueId, label: issueId } : null),
+    [issueId],
+  );
+  const search = useCallback(
+    async ({ query }: { query: string }) => (await searchIssues({ query })).issues,
+    [searchIssues],
+  );
+  const select = useCallback(
+    async ({ item }: { item: Issue }) => {
+      await newWorkspace.setBranch(item.branch);
+      await newWorkspace.setMetadata({ [ISSUE_KEY]: item.id });
+    },
+    [newWorkspace],
+  );
+  return (
+    <Combobox title="Issue" icon="CircleDot" value={value} search={search} onSelect={select} />
+  );
+}

plugin-examples/new-workspace-issues/index.client.tsx

@@ -0,0 +1,7 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { IssueField } from "./client/issue-field";
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}

plugin-examples/new-workspace-issues/index.server.ts

@@ -0,0 +1,8 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { searchIssues } from "./server/issues";
+import { searchIssuesRpc } from "./shared/issues";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(searchIssuesRpc, searchIssues);
+  return () => {};
+}

plugin-examples/new-workspace-issues/paseo-plugin.json

@@ -0,0 +1,4 @@
+{
+  "id": "new-workspace-issues-example",
+  "requirements": { "paseo": ">=0.8.0" }
+}

plugin-examples/new-workspace-issues/server/issues.ts

@@ -0,0 +1,26 @@
+import type { RpcInput } from "@getpaseo/plugin";
+import { searchIssuesRpc, type Issue } from "../shared/issues";
+
+// A real plugin would ask its tracker. A fixed list keeps the example self-contained.
+const ISSUES: Issue[] = [
+  {
+    id: "PAS-101",
+    label: "PAS-101 Slow sidebar",
+    description: "Lists lag at 200 rows",
+    branch: "pas-101-slow-sidebar",
+  },
+  {
+    id: "PAS-102",
+    label: "PAS-102 Crash on resume",
+    description: "Agent resume throws",
+    branch: "pas-102-crash-on-resume",
+  },
+  { id: "PAS-103", label: "PAS-103 Dark theme contrast", branch: "pas-103-dark-theme-contrast" },
+];
+
+export async function searchIssues({ query }: RpcInput<typeof searchIssuesRpc>) {
+  const needle = query.trim().toLowerCase();
+  return {
+    issues: ISSUES.filter((issue) => issue.label.toLowerCase().includes(needle)),
+  };
+}

plugin-examples/new-workspace-issues/shared/issues.ts

@@ -0,0 +1,18 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const IssueSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  /** The branch the issue's work goes on. */
+  branch: z.string(),
+});
+
+export type Issue = z.infer<typeof IssueSchema>;
+
+export const searchIssuesRpc = defineRpc({
+  name: "issues.search",
+  input: z.object({ query: z.string() }),
+  output: z.object({ issues: z.array(IssueSchema) }),
+});