feat(plugins): composer items and controls in all three composers

A plugin registers a component with addComposerItem and reads and changes the
composer through useComposer(): provider, model, mode, thinking, options,
prompt, attachments and agent metadata. The agent, draft and New workspace
composers provide the same ComposerInput and ComposerAgent halves, so a
command reaches the right model without the plugin knowing which composer
it sits in.

Toggle, Select and Action are drawn by one ComposerControl renderer that
the thinking select and provider option controls now use too. Controls sit in
the toolbar when there is room and become rows in the existing overflow sheet
otherwise, so on a phone they appear in the overflow. Plugin items count in
the density presence so the composer condenses to make room. Model and mode
stay specialized but share the trigger, density and overflow.

Draft metadata is kept locally, sent at creation and reset when the prompt is
sent. PluginAgentSnapshot.metadata, deferred from the metadata phase, lands
here. The unused provider badge is removed.

vitest resolves @floating-ui/react-native to its ESM build: the CJS entry
requires the real react-native, whose Flow sources do not parse.

packages/plugin/src/boundaries.test.ts

@@ -213,6 +213,43 @@ describe("plugin panel SDK boundary", () => {
   });
 });
 
+describe("plugin composer SDK boundary", () => {
+  it("lets a composer item read and change the composer through typed commands and controls", () => {
+    expect(
+      typeErrors(`
+      import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+      import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+      function Item() {
+        const composer = useComposer();
+        const context: "agent" | "draft" | "new-workspace" = composer.context;
+        const provider: string | null = composer.agent.provider;
+        const flag: boolean = composer.agent.metadata.flag === true;
+        // @ts-expect-error reads are not writable
+        composer.agent.model = "other";
+        composer.setProvider("codex").then(() => composer.setModel("gpt"));
+        composer.setOptions({ effort: null });
+        composer.setMetadata({ flag: true, stale: null });
+        composer.insertText("text");
+        composer.addAttachment({ sourceId: "issues", item: { id: "1", identifier: "1", title: "t", url: "https://e.com", text: "t", resourceType: "issue" } });
+        // @ts-expect-error commands take JSON values
+        composer.setMetadata({ fn: () => {} });
+        return (
+          <>
+            <Toggle title="Flag" icon="Flag" value={flag} onValueChange={(next: boolean) => composer.setMetadata({ flag: next })} />
+            <Select title="Size" icon="Gauge" value="a" options={[{ value: "a", label: "A" }, { value: "b", label: "B" }]} onValueChange={(next: "a" | "b") => {}} />
+            <Action title="Insert" icon="Plus" onPress={() => composer.setPrompt("")} />
+          </>
+        );
+      }
+      export default function contribute(client: PluginClientContext) {
+        client.addComposerItem({ 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/composer.tsx

@@ -0,0 +1,78 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import type { JsonValue } from "@getpaseo/protocol/agent-types";
+import type { PluginAttachmentItem } from "../attachments.js";
+import type { PluginHostProps } from "./contracts.js";
+
+/** One item the user attached from a source this plugin registered with `addAttachmentSource`. */
+export interface PluginComposerAttachment {
+  readonly sourceId: string;
+  readonly item: PluginAttachmentItem;
+}
+
+/**
+ * The composer the item sits in: the prompt, the attachments and the agent being configured.
+ * The commands behave the same in every composer. `context` says where the composer is; it does
+ * not change what a command does, except that a running agent keeps its provider.
+ */
+export interface PluginComposer {
+  /** `"agent"`: a running agent. `"draft"`: a new agent in a workspace. `"new-workspace"`: the New workspace screen. */
+  readonly context: "agent" | "draft" | "new-workspace";
+  readonly prompt: string;
+  /** This plugin's attachments only. */
+  readonly attachments: readonly PluginComposerAttachment[];
+  readonly agent: {
+    readonly provider: string | null;
+    readonly model: string | null;
+    readonly mode: string | null;
+    readonly thinking: string | null;
+    /** The options the agent runs with, including provider defaults. */
+    readonly options: Readonly<Record<string, JsonValue>>;
+    readonly metadata: Readonly<Record<string, JsonValue>>;
+  };
+  setPrompt(text: string): void;
+  /** Inserts at the cursor, replacing the selection. */
+  insertText(text: string): void;
+  addAttachment(input: { sourceId: string; item: PluginAttachmentItem }): void;
+  removeAttachment(input: { sourceId: string; itemId: string }): void;
+  /** Resets the model like the built-in control. Rejects on a running agent, which keeps its provider. */
+  setProvider(provider: string): Promise<void>;
+  setModel(modelId: string): Promise<void>;
+  setMode(modeId: string): Promise<void>;
+  setThinking(thinkingOptionId: string): Promise<void>;
+  /** Top-level keys replace; `null` removes the agent's own value. */
+  setOptions(patch: Record<string, JsonValue>): Promise<void>;
+  /** Top-level keys replace; `null` removes the key. */
+  setMetadata(patch: Record<string, JsonValue>): Promise<void>;
+}
+
+export interface PluginComposerItemProps extends PluginHostProps {}
+
+export interface PluginComposerItemContribution {
+  id: string;
+  Component: ComponentType<PluginComposerItemProps>;
+}
+
+const PluginComposerContext = createContext<PluginComposer | null>(null);
+
+export function PluginComposerProvider({
+  composer,
+  children,
+}: {
+  composer: PluginComposer;
+  children: ReactNode;
+}) {
+  return (
+    <PluginComposerContext.Provider value={composer}>{children}</PluginComposerContext.Provider>
+  );
+}
+
+export function usePluginComposerValue(): PluginComposer | null {
+  return useContext(PluginComposerContext);
+}
+
+/** The composer this item sits in. Call it from a component registered with `addComposerItem`. */
+export function useComposer(): PluginComposer {
+  const composer = usePluginComposerValue();
+  if (!composer) throw new Error("useComposer must run inside a composer item");
+  return composer;
+}

packages/plugin/src/client/contracts.ts

@@ -4,6 +4,7 @@ import type { PaseoApi } from "@getpaseo/client";
 import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-types";
 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 { PluginRpcContract } from "../rpc.js";
 import type {
   PluginButtonRegistration,
@@ -194,6 +195,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
     contribution: PluginComposerPillContribution<PluginText>,
   ): PluginButtonRegistration<PluginText>;
   addAttachmentSource(contribution: PluginAttachmentSourceContribution<PluginText>): PluginCleanup;
+  addComposerItem(contribution: PluginComposerItemContribution): PluginCleanup;
   addTheme(contribution: PluginThemeContribution<PluginText>): PluginCleanup;
   addFilePanel(contribution: PluginFilePanelContribution<PluginText>): PluginCleanup;
   addTimelineTransformer<ItemType extends AgentTimelineItem["type"]>(

packages/plugin/src/client/host.ts

@@ -1,6 +1,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 {
   usePluginRuntimeContextBridge,
   type PluginRuntimeContextBridge,

packages/plugin/src/client/index.ts

@@ -71,6 +71,13 @@ export {
 } from "./file.js";
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";
+export { useComposer } from "./composer.js";
+export type {
+  PluginComposer,
+  PluginComposerAttachment,
+  PluginComposerItemContribution,
+  PluginComposerItemProps,
+} from "./composer.js";
 export { useRpc } from "./rpc-context.js";
 import type { SettingsDefinition } from "../settings.js";
 import type { SettingsState } from "./contracts.js";

packages/plugin/src/client/runtime-context-bridge.tsx

@@ -1,5 +1,6 @@
 import { PluginTranslationProvider, usePluginTranslationRuntime } from "./translations.js";
 import { useCallback, type ReactNode } from "react";
+import { PluginComposerProvider, usePluginComposerValue } from "./composer.js";
 import { PluginClientStateProvider, usePluginClientStateSource } from "./client-state.js";
 import { PaseoApiProvider, usePaseoContextValue } from "./paseo-context.js";
 import { PluginRpcProvider, usePluginRpcContextValue } from "./rpc-context.js";
@@ -12,6 +13,7 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
   const paseo = usePaseoContextValue();
   const rpc = usePluginRpcContextValue();
   const state = usePluginClientStateSource();
+  const composer = usePluginComposerValue();
 
   if (!paseo || !rpc) {
     throw new Error("Plugin UI must run inside a contributed plugin surface");
@@ -19,11 +21,16 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
 
   return useCallback(
     (children: ReactNode) => {
-      const content = state ? (
+      const withState = state ? (
         <PluginClientStateProvider source={state}>{children}</PluginClientStateProvider>
       ) : (
         children
       );
+      const content = composer ? (
+        <PluginComposerProvider composer={composer}>{withState}</PluginComposerProvider>
+      ) : (
+        withState
+      );
       return (
         <PaseoApiProvider paseo={paseo}>
           <PluginRpcProvider invoke={rpc.invoke}>
@@ -32,6 +39,6 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
         </PaseoApiProvider>
       );
     },
-    [paseo, rpc, state, translations],
+    [composer, paseo, rpc, state, translations],
   );
 }

packages/plugin/src/client/ui.ts

@@ -185,3 +185,30 @@ export interface MarkdownProps {
 
 /** Renders Markdown using Paseo’s theme, selection, and link behavior. */
 export declare const Markdown: ComponentType<MarkdownProps>;
+
+export interface ComposerControlProps {
+  /** The control's label and tooltip. */
+  title: string;
+  /** A Lucide icon name, inline SVG, or a component. */
+  icon: PluginIcon;
+  disabled?: boolean;
+}
+export interface ToggleProps extends ComposerControlProps {
+  value: boolean;
+  onValueChange(value: boolean): void;
+}
+export interface SelectProps<Value extends string = string> extends ComposerControlProps {
+  value: Value;
+  options: readonly { value: Value; label: string; description?: string }[];
+  onValueChange(value: Value): void;
+}
+export interface ActionProps extends ComposerControlProps {
+  onPress(): 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.
+ */
+export declare const Toggle: ComponentType<ToggleProps>;
+export declare function Select<Value extends string>(props: SelectProps<Value>): ReactNode;
+export declare const Action: ComponentType<ActionProps>;

packages/plugin/src/contracts.ts

@@ -52,6 +52,8 @@ export interface PluginAgentSnapshot {
   readonly attentionReason: "finished" | "error" | "permission" | null;
   readonly parentAgentId: string | null;
   readonly labels: Readonly<Record<string, string>>;
+  /** Structured data plugins store on the agent. */
+  readonly metadata: Readonly<Record<string, JsonValue>>;
 }
 
 export interface PluginThemeColors {