Let plugins provide custom sidebar views across hosts (#8906)

* feat(plugin): expose stable sidebar entity data across hosts Collections return interned references and preserve their arrays when membership and order stay unchanged. Entity selectors share one hook with identity defaults for full snapshots and shallow defaults for selections. The app caches host projections and shares underlying store and host subscriptions. Browser render counts exercise the real session store and plugin provider without memoized rows. Terminal hooks consume the collection source port; daemon-wide terminal discovery is the separate terminal phase. * feat(plugin): let users select a sidebar view An exclusive view replaces the sidebar content while the host retains navigation, callouts, and footer. The device remembers the selection, unavailable views fall back to the default, and throwing views provide recovery. Device-scoped plugin settings persist locally with schema validation and revision conflicts. Web E2E and Android tablet QA cover selection, preserved chrome, disabled-view fallback, and error recovery. * feat(plugin): add sidebar view examples and ref actions Keep sidebar layout and gestures inside the plugin while routing entity handles to their owning hosts. Examples cover empty projects, pinned workspaces, task sections, nested agents and device-local label folders. * feat(plugin): observe terminals across connected hosts Share host-wide terminal observations across plugin surfaces and gate them on terminalCollection. Keep directory observations compatible, and carry creation time in worker v6 state so v5 terminals can drain with an unknown timestamp.
2026-11-07 17:04:42 +00:00 · 2026-11-07 18:05:31 +07:00
parent aac228e0a8
commit a449271d57
106 changed files with 4385 additions and 269 deletions
@@ -0,0 +1,34 @@
+import type { PluginAgentSnapshot } from "@getpaseo/plugin";
+import { ScrollView, View } from "react-native";
+import { useAgents, type PluginSidebarViewProps } from "@getpaseo/plugin/client";
+import { AgentRow, Heading } from "./rows";
+export function agentTask(agent: PluginAgentSnapshot) {
+  if (agent.attentionReason === "permission") return "Respond";
+  if (agent.requiresAttention || agent.status === "error") return "Review";
+  if (agent.status === "running" || agent.status === "initializing") return "Wait";
+  return "Start";
+}
+function Task({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => agentTask(item) === title,
+    orderBy: ["lastActivityAt", "desc"],
+  });
+  return (
+    <View>
+      <Heading title={title} view={view} />
+      {agents.map((reference) => (
+        <AgentRow key={reference.key} reference={reference} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Agents(view: PluginSidebarViewProps) {
+  return (
+    <ScrollView>
+      <Task title="Respond" view={view} />
+      <Task title="Review" view={view} />
+      <Task title="Wait" view={view} />
+      <Task title="Start" view={view} />
+    </ScrollView>
+  );
+}
@@ -0,0 +1,191 @@
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import {
+  usePaseo,
+  useSettings,
+  useWorkspaces,
+  type WorkspaceRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { folders } from "../shared/preferences";
+import { Heading, WorkspaceRow } from "./rows";
+interface Move {
+  reference: WorkspaceRef;
+  from: string | null;
+}
+function folderLabel(key: string): string | null {
+  return key === "unlabelled" ? null : key.slice("label:".length);
+}
+function Movable({
+  reference,
+  folder,
+  view,
+  select,
+}: {
+  reference: WorkspaceRef;
+  folder: string | null;
+  view: PluginSidebarViewProps;
+  select: (move: Move) => void;
+}) {
+  const pick = useCallback(() => select({ reference, from: folder }), [select, reference, folder]);
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} onLongPress={pick} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Move workspace ${reference.id}`}
+        onPress={pick}
+      >
+        <Heading title="Move…" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+export function Labels(view: PluginSidebarViewProps) {
+  const paseo = usePaseo();
+  const settings = useSettings(folders);
+  const [selected, select] = useState<Move | null>(null);
+  const groups = useWorkspaces({
+    orderBy: "name",
+    groupBy: (item) =>
+      item.labels.length ? item.labels.map((label) => `label:${label}`) : ["unlabelled"],
+  });
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, paddingHorizontal: 12 }),
+    [view.theme],
+  );
+  const move = useMutation({
+    mutationFn: async (destination: string | null) => {
+      if (!selected) return;
+      const workspace = paseo.workspaces.ref(selected.reference);
+      // Add first: if adding fails the workspace keeps its original folder.
+      if (destination && destination !== selected.from)
+        await workspace.setLabel(destination, { assigned: true });
+      if (selected.from && selected.from !== destination)
+        await workspace.setLabel(selected.from, { assigned: false });
+      select(null);
+    },
+  });
+  const toggle = useCallback(
+    (folder: string) => {
+      if (settings.status !== "ready") return;
+      void settings.save(
+        {
+          collapsed: settings.values.collapsed.includes(folder)
+            ? settings.values.collapsed.filter((item) => item !== folder)
+            : [...settings.values.collapsed, folder],
+        },
+        settings.revision,
+      );
+    },
+    [settings],
+  );
+  const cancel = useCallback(() => select(null), []);
+  if (settings.status === "loading") return <Text style={style}>Loading folders…</Text>;
+  if (settings.status !== "ready")
+    return (
+      <View>
+        <Text style={style}>{settings.error}</Text>
+        <Pressable accessibilityRole="button" onPress={settings.reload}>
+          <Heading title="Reload folders" view={view} />
+        </Pressable>
+        {settings.status === "invalid" ? (
+          <Pressable accessibilityRole="button" onPress={settings.reset}>
+            <Heading title="Reset folders" view={view} />
+          </Pressable>
+        ) : null}
+      </View>
+    );
+  return (
+    <ScrollView>
+      {selected ? (
+        <View>
+          <Text style={style}>Choose a destination folder</Text>
+          <Pressable accessibilityRole="button" onPress={cancel}>
+            <Heading title="Cancel move" view={view} />
+          </Pressable>
+        </View>
+      ) : (
+        <Text style={style}>Long press a workspace or choose Move…</Text>
+      )}
+      {move.error ? <Text style={style}>{move.error.message}</Text> : null}
+      {Array.from(
+        new Set(["label:Inbox", "label:Later", "unlabelled", ...groups.map((group) => group.key)]),
+      ).map((folder) => (
+        <Folder
+          key={folder}
+          folder={folder}
+          view={view}
+          selected={!!selected}
+          pending={move.isPending}
+          move={move.mutate}
+          collapsed={settings.values.collapsed.includes(folder)}
+          toggle={toggle}
+        >
+          {groups
+            .find((group) => group.key === folder)
+            ?.items.map((reference) => (
+              <Movable
+                key={reference.key}
+                reference={reference}
+                folder={folderLabel(folder)}
+                view={view}
+                select={select}
+              />
+            ))}
+        </Folder>
+      ))}
+      {settings.saveError ? <Text style={style}>{settings.saveError}</Text> : null}
+    </ScrollView>
+  );
+}
+function Folder({
+  folder,
+  view,
+  selected,
+  pending,
+  move,
+  collapsed,
+  toggle,
+  children,
+}: {
+  folder: string;
+  view: PluginSidebarViewProps;
+  selected: boolean;
+  pending: boolean;
+  move: (folder: string | null) => void;
+  collapsed: boolean;
+  toggle: (folder: string) => void;
+  children: import("react").ReactNode;
+}) {
+  const toggleFolder = useCallback(() => toggle(folder), [toggle, folder]);
+  const label = folderLabel(folder);
+  const title = label ?? "Unlabelled";
+  const destination = useCallback(() => move(label), [move, label]);
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Toggle ${title}`}
+        onPress={toggleFolder}
+      >
+        <Heading title={`${collapsed ? "▸" : "▾"} ${title}`} view={view} />
+      </Pressable>
+      {selected ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={label === null ? "Remove current label" : `Move to ${title}`}
+          disabled={pending}
+          onPress={destination}
+        >
+          <Heading
+            title={label === null ? "Remove current label" : `Move to ${title}`}
+            view={view}
+          />
+        </Pressable>
+      ) : null}
+      {collapsed ? null : children}
+    </View>
+  );
+}
@@ -0,0 +1,109 @@
+import { ScrollView, View } from "react-native";
+import {
+  useProjects,
+  useWorkspaces,
+  useAgents,
+  useAgent,
+  type AgentRef,
+  type WorkspaceRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { AgentRow, ProjectHeading, WorkspaceRow } from "./rows";
+const indent = { paddingLeft: 12 };
+function AgentTree({ reference, view }: { reference: AgentRef; view: PluginSidebarViewProps }) {
+  const agent = useAgent(reference);
+  const children = useAgents({
+    where: (item) =>
+      item.parentAgent?.key === reference.key && item.workspace.key === agent?.workspace.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <AgentRow reference={reference} view={view} />
+      <View style={indent}>
+        {children.map((child) => (
+          <AgentTree key={child.key} reference={child} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function RootWithParent({
+  reference,
+  parent,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  parent: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const parents = useAgents({
+    where: (item) => item.ref.key === parent.key && item.workspace.key === workspace.key,
+  });
+  return parents.length > 0 ? null : <AgentTree reference={reference} view={view} />;
+}
+function Root({
+  reference,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  if (!agent) return null;
+  return agent.parentAgent ? (
+    <RootWithParent
+      reference={reference}
+      parent={agent.parentAgent}
+      workspace={workspace}
+      view={view}
+    />
+  ) : (
+    <AgentTree reference={reference} view={view} />
+  );
+}
+function Workspace({ reference, view }: { reference: WorkspaceRef; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => item.workspace.key === reference.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} />
+      <View style={indent}>
+        {agents.map((agent) => (
+          <Root key={agent.key} reference={agent} workspace={reference} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key,
+    orderBy: "name",
+  });
+  return (
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <Workspace key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Nested(view: PluginSidebarViewProps) {
+  const projects = useProjects({ orderBy: "displayName" });
+  return (
+    <ScrollView>
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
+    </ScrollView>
+  );
+}
@@ -0,0 +1,139 @@
+import { useCallback, useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+import {
+  useWorkspace,
+  useAgent,
+  useProject,
+  type WorkspaceRef,
+  type AgentRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+
+export function Heading({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const style = useMemo(
+    () => ({
+      color: view.theme.colors.foregroundMuted,
+      fontSize: 11,
+      paddingHorizontal: 12,
+      paddingTop: 12,
+      paddingBottom: 4,
+    }),
+    [view.theme],
+  );
+  return (
+    <Text accessibilityRole="header" style={style}>
+      {title}
+    </Text>
+  );
+}
+export function WorkspaceRow({
+  reference,
+  view,
+  onLongPress,
+}: {
+  reference: WorkspaceRef;
+  view: PluginSidebarViewProps;
+  onLongPress?: () => void;
+}) {
+  const workspace = useWorkspace(reference);
+  const open = useCallback(
+    () => view.navigation.openWorkspace(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12, lineHeight: 16 }),
+    [view.theme],
+  );
+  const detail = useMemo(
+    () => ({ color: view.theme.colors.foregroundMuted, fontSize: 11 }),
+    [view.theme],
+  );
+  const background = useMemo(
+    () => ({
+      ...rowStyle,
+      backgroundColor:
+        view.active.workspace?.key === reference.key ? view.theme.colors.surface2 : undefined,
+    }),
+    [view.active.workspace, view.theme, reference],
+  );
+  if (!workspace) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open ${workspace.title ?? workspace.name}`}
+      onPress={open}
+      onLongPress={onLongPress}
+      style={background}
+    >
+      <Text numberOfLines={1} style={style}>
+        {workspace.title ?? workspace.name}
+      </Text>
+      <Text numberOfLines={1} style={detail}>
+        {workspace.indicatorLabel}
+      </Text>
+    </Pressable>
+  );
+}
+export function AgentRow({
+  reference,
+  view,
+}: {
+  reference: AgentRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  const open = useCallback(
+    () => view.navigation.openAgent(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12 }),
+    [view.theme],
+  );
+  if (!agent) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open agent ${agent.title ?? agent.provider}`}
+      onPress={open}
+      style={rowStyle}
+    >
+      <Text numberOfLines={1} style={style}>
+        {agent.title ?? agent.provider}
+      </Text>
+    </Pressable>
+  );
+}
+export function ProjectHeading({
+  reference,
+  view,
+}: {
+  reference: ProjectRef;
+  view: PluginSidebarViewProps;
+}) {
+  const project = useProject(reference);
+  const open = useCallback(
+    () => view.navigation.openProject(reference),
+    [view.navigation, reference],
+  );
+  if (!project) return null;
+  return (
+    <View>
+      <Heading title={project.displayName} view={view} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`New workspace in ${project.displayName}`}
+        onPress={open}
+      >
+        <Heading title="+ New workspace" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+const rowStyle = {
+  minHeight: 28,
+  paddingHorizontal: 12,
+  paddingVertical: 4,
+  justifyContent: "center",
+} as const;
@@ -0,0 +1,131 @@
+import { Component, useCallback, useMemo, useState, type ReactNode } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import { useMutation } from "@tanstack/react-query";
+import {
+  useHosts,
+  useTerminals,
+  useTerminal,
+  usePaseo,
+  type TerminalRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { Heading } from "./rows";
+
+class TerminalError extends Component<{ children: ReactNode }, { error: Error | null }> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  render() {
+    return this.state.error ? <Text>{this.state.error.message}</Text> : this.props.children;
+  }
+}
+function TerminalRow({
+  reference,
+  view,
+}: {
+  reference: TerminalRef;
+  view: PluginSidebarViewProps;
+}) {
+  const terminal = useTerminal(reference);
+  const paseo = usePaseo();
+  const focus = useCallback(() => paseo.terminals.ref(reference).focus(), [paseo, reference]);
+  const close = useMutation({ mutationFn: () => paseo.terminals.ref(reference).kill() });
+  const kill = useCallback(() => close.mutate(), [close]);
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12, padding: 12 }),
+    [view.theme],
+  );
+  if (!terminal) return null;
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Focus terminal ${terminal.title}`}
+        testID={`sidebar-terminal-open-${reference.id}`}
+        onPress={focus}
+      >
+        <Text style={style}>
+          {terminal.title}
+          {terminal.isScript ? " (script)" : ""}
+        </Text>
+      </Pressable>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Kill terminal ${terminal.title}`}
+        testID={`sidebar-terminal-kill-${reference.id}`}
+        disabled={close.isPending}
+        onPress={kill}
+      >
+        <Text style={style}>Close terminal</Text>
+      </Pressable>
+      {close.error ? <Text style={style}>{close.error.message}</Text> : null}
+    </View>
+  );
+}
+function HostTerminals({ hostId, view }: { hostId: string; view: PluginSidebarViewProps }) {
+  const terminals = useTerminals({ hosts: [hostId], orderBy: "createdAt" });
+  return (
+    <View>
+      {terminals.length ? (
+        terminals.map((reference) => (
+          <TerminalRow key={reference.key} reference={reference} view={view} />
+        ))
+      ) : (
+        <Heading title="No terminals" view={view} />
+      )}
+    </View>
+  );
+}
+function HostButton({
+  hostId,
+  label,
+  select,
+  view,
+}: {
+  hostId: string;
+  label: string;
+  select: (id: string) => void;
+  view: PluginSidebarViewProps;
+}) {
+  const choose = useCallback(() => select(hostId), [select, hostId]);
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Terminals on ${hostId}`}
+      onPress={choose}
+    >
+      <Heading title={label} view={view} />
+    </Pressable>
+  );
+}
+export function Terminals(view: PluginSidebarViewProps) {
+  const hosts = useHosts();
+  const [chosen, select] = useState<string | null>(null);
+  const selected = chosen;
+  return (
+    <ScrollView>
+      {hosts.map((host) => (
+        <HostButton
+          key={host.serverId}
+          hostId={host.serverId}
+          label={host.label}
+          select={select}
+          view={view}
+        />
+      ))}
+      {selected ? (
+        <TerminalError key={selected}>
+          <HostTerminals hostId={selected} view={view} />
+        </TerminalError>
+      ) : (
+        <Heading
+          title={
+            hosts.length ? "Choose a host to list terminals" : "Connect a host to list terminals"
+          }
+          view={view}
+        />
+      )}
+    </ScrollView>
+  );
+}
@@ -0,0 +1,37 @@
+import { ScrollView, View } from "react-native";
+import {
+  useProjects,
+  useWorkspaces,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { Heading, ProjectHeading, WorkspaceRow } from "./rows";
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key && !item.pinnedAt,
+    orderBy: "name",
+  });
+  return (
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <WorkspaceRow key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Workspaces(view: PluginSidebarViewProps) {
+  const projects = useProjects({ orderBy: "displayName" });
+  const pinned = useWorkspaces({ where: (item) => !!item.pinnedAt, orderBy: "name" });
+  return (
+    <ScrollView>
+      {pinned.length ? <Heading title="Pinned" view={view} /> : null}
+      {pinned.map((reference) => (
+        <WorkspaceRow key={reference.key} reference={reference} view={view} />
+      ))}
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
+    </ScrollView>
+  );
+}
@@ -0,0 +1,18 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { Workspaces } from "./client/workspaces";
+import { Agents } from "./client/agents";
+import { Nested } from "./client/nested";
+import { Terminals } from "./client/terminals";
+import { Labels } from "./client/labels";
+export default function contribute(client: PluginClientContext) {
+  const cleanups = [
+    client.addSidebarView({ id: "terminals", title: "Example terminals", Component: Terminals }),
+    client.addSidebarView({ id: "workspaces", title: "Example workspaces", Component: Workspaces }),
+    client.addSidebarView({ id: "agents", title: "Example agents", Component: Agents }),
+    client.addSidebarView({ id: "nested", title: "Example nested agents", Component: Nested }),
+    client.addSidebarView({ id: "labels", title: "Example label folders", Component: Labels }),
+  ];
+  return () => {
+    for (const cleanup of cleanups) void cleanup();
+  };
+}
@@ -0,0 +1,4 @@
+{
+  "id": "sidebar-views",
+  "requirements": { "paseo": ">=0.16.0" }
+}
@@ -0,0 +1,8 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+export const folders = defineSettings({
+  id: "folders",
+  scope: "device",
+  version: 1,
+  schema: z.object({ collapsed: z.array(z.string()).default([]) }),
+});