feat(plugins): let a plugin put the cursor in any agent's composer

A pill could insert text but left the cursor elsewhere, so the user had
to click the composer before typing. Plugins can address any agent's
composer, and an author cannot know where the user is, so focus() owns
revealing the agent as well as focusing it.

A running agent's composer holds one pending request and navigates to
the agent, completing when an input that can take the keyboard attaches.
Drafts and the New workspace composer have nothing to navigate to and
must not pull the user back, so they reject when off screen.

packages/plugin/src/boundaries.test.ts

@@ -230,6 +230,7 @@ describe("plugin composer SDK boundary", () => {
         composer.setOptions({ effort: null });
         composer.setMetadata({ flag: true, stale: null });
         composer.insertText("text");
+        composer.focus({ selection: { start: 0, end: composer.prompt.length } }).then(() => composer.focus());
         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: () => {} });

packages/plugin/src/client/composer.tsx

@@ -16,6 +16,12 @@ export interface PluginComposerAttachment {
   readonly item: PluginAttachmentItem;
 }
 
+/** Where the cursor goes when a composer takes focus. */
+export interface PluginComposerFocusOptions {
+  /** Offsets into `prompt`, clamped to its length. Equal offsets place the cursor. Omit to keep the cursor where it is. */
+  selection?: { start: number; end: number };
+}
+
 /**
  * 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
@@ -39,6 +45,11 @@ export interface PluginComposer {
   setPrompt(text: string): void;
   /** Inserts at the cursor, replacing the selection. */
   insertText(text: string): void;
+  /**
+   * Puts the cursor in this composer, ready to type. Paseo opens the agent's tab or workspace when
+   * it is not on screen. Resolves once the input has focus; rejects when it could not get there.
+   */
+  focus(options?: PluginComposerFocusOptions): Promise<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. */

packages/plugin/src/client/index.ts

@@ -86,6 +86,7 @@ export { useComposer, useComposers } from "./composer.js";
 export type {
   PluginComposer,
   PluginComposerAttachment,
+  PluginComposerFocusOptions,
   PluginComposerItemContribution,
   PluginComposerItemProps,
   PluginComposerSelector,