@yannelli/paseo-linear-plugin 0.1.0 → 0.4.0

package/NOTICE

@@ -3,7 +3,11 @@ Copyright 2026 Ryan Yannelli
 
 This product includes software from Paseo (https://github.com/getpaseo/paseo),
 Copyright (c) 2025-present Mohamed Boudra, licensed under the Apache License,
-Version 2.0. The plugin source in index.client.ts, index.server.ts, server/,
-shared/, and test/linear.test.ts comes from plugin-examples/linear at commit
-8f1091da6. Changes: package metadata, manifest description, Paseo >=0.9.0
-requirement, and the test file location.
+Version 2.0. The plugin source in index.client.tsx, index.server.ts, client/,
+server/, shared/, and test/linear.test.ts started as the Linear example plugin
+(plugin-examples/linear) in the Paseo repository. This repository adds Linear keys per Paseo project, a
+response cache, list sorting, sub-issue nesting and breadcrumbs, Markdown
+rendering, and the agent setup page. It also changes the package metadata.
+
+client/provider-icon.tsx contains the provider icons from the Paseo app
+(packages/app/src/components/icons). Each icon is a mark of its owner.

package/OVERVIEW.md

@@ -1,24 +1,34 @@
 # Linear issues
 
-Adds **Attach Linear issue** to the message composer. Search your Linear issues, select one, and the agent receives the issue text with your prompt.
+Browse and edit Linear issues in Paseo, and start agents from them. Open **Linear** from the sidebar, or open the Linear panel in a workspace. Requires Paseo 0.10.0 or newer.
 
-## Setup
+## Connect Linear
 
-Set `LINEAR_API_KEY` to a Linear personal API key in the environment that starts the Paseo daemon, then restart the daemon. Create the key in Linear under Settings → Security & access → Personal API keys. The plugin only reads issues, so read permission is enough. Requires Paseo 0.9.0 or newer.
+Paste a Linear personal API key in **Settings → Plugins → Linear → Account**. Create the key in Linear under Settings → Security & access → Personal API keys. To change issues, the key must have write access. The daemon saves the key on its host with owner-only permissions. If no key is saved, the plugin uses `LINEAR_API_KEY` from the daemon environment.
 
-## Search
+To use a different Linear key for one Paseo project, add it under **Project keys**. Workspace panels in that project use its key. The Linear screen shows a key button to switch keys.
 
-- An identifier such as `ENG-123` returns that issue only. Case does not matter.
-- Other text matches issue titles, without case sensitivity. Descriptions and comments are not searched.
-- An empty search lists the 20 most recently updated issues. Title searches also return up to 20 issues.
-- Each result shows its status and assignee.
+## Browse issues
 
-## What the agent receives
+- Search titles and descriptions, or type an identifier such as `ENG-123`.
+- Filter by assignee and status. Pick a team to see only its issues.
+- Sort by Last updated, Newest, Priority, Due date, or Title.
+- Select **Sub-issues** to nest sub-issues under their parent. The breadcrumbs above an issue show its team and parent chain.
+- Change the status, priority, and assignee. Add comments, or create an issue.
+- Descriptions and comments show as Markdown.
+- Edit the description in place. It saves to Linear about one second after you stop typing, and the line under the editor confirms each save. Select a task list checkbox to check or uncheck it without opening the editor.
+- `/linear` opens the panel. `/linear ENG-123` opens an issue.
 
-The attachment text contains the identifier, title, URL, status, priority, assignee, project, labels, and description. The plugin takes this snapshot when you select the issue. Later changes in Linear do not update it.
+## Start an agent
 
-## Data and permissions
+Select **Start agent** or **Start review** on an issue. The setup page shows the prompt and the composer controls for the prompt template, model, thinking level, and mode. The model picker lists providers first, and its search covers all models. Choose the project and where the agent runs: a new worktree, a pull request checkout, the issue branch, an existing agent workspace, or the current workspace or project folder. You can include comments in the prompt. For Implement, you can also move the issue to In Progress and assign it to you.
+
+The prompt follows the template until you edit it. **Reset prompt** restores it. Edit the templates in **Prompts**, and add project instructions in **Projects**.
+
+## Attach an issue
 
-The daemon subprocess sends GraphQL queries to `https://api.linear.app/graphql` with your key. The app never receives the key. Results include any issue the key can read. Paseo sends the selected snapshot to the agent provider with the message.
+Choose **Attach Linear issue** in the composer attachment menu. The agent gets the issue text with your message. This uses the default key.
+
+## Data and permissions
 
-A rejected key, a rate limit, or a GraphQL error appears as the picker's result text. A new key takes effect only after a daemon restart.
+Only the daemon sends requests to `https://api.linear.app/graphql`. The daemon never sends a key back to the app. Paseo sends the prompt, with the issue snapshot, to the agent provider. The daemon keeps recent Linear responses in memory for up to 24 hours, and the list shows them with **Showing saved results. Updating…** while it gets new data.

package/README.md

@@ -1,59 +1,164 @@
-![Linear issues for Paseo: hand your agent the whole issue.](docs/images/social-preview.png)
+![Linear issues in Paseo: an issue view with Start agent and Start review buttons, next to the install command](docs/images/social-preview.png)
 
 # Linear issues for Paseo
 
-A Paseo plugin that adds **Attach Linear issue** to the message composer. Search by issue identifier or title, then send a snapshot of the issue to the agent with your prompt. The snapshot holds the title, URL, status, priority, assignee, project, labels, and description.
+A Paseo plugin for Linear. It adds a Linear screen and a workspace panel where you browse and edit Linear issues. From an issue, you can start an agent that implements it or reviews the work. Your Linear API key stays on the daemon host.
 
-![Attach Linear issue picker with four search results for "plugin"](docs/images/search.png)
+- Browse issues in a list next to the issue view. Search and filter the list, and change its sort order.
+- Nest sub-issues under their parent. Breadcrumbs show the parent chain of an issue.
+- Read descriptions and comments as Markdown.
+- Edit the description in place. It saves as you type. Check off task list items without opening the editor.
+- Change the status, priority, and assignee. Add comments and create issues.
+- Start an agent or a review from an issue. Choose the prompt, agent, model, effort, project, and where the agent runs.
+- Use a different Linear key for a Paseo project.
+- See saved results at once while the plugin gets new data from Linear.
+- Attach a Linear issue to a message in the composer.
 
-![Composer with an attached ENG-123 pill and the issue text sent to the agent](docs/images/attach.png)
+![Linear screen with an issue list grouped by status on the left and issue ENG-123 open on the right](docs/images/browse.png)
 
-![Terminal that sets LINEAR_API_KEY and installs the plugin, with the app, daemon, and Linear API in sequence](docs/images/setup.png)
+![Agent setup page for ENG-123 with the prompt, the prompt, model, thinking, and mode controls, the Project and Run in fields, and three options](docs/images/launch.png)
+
+![Linear account settings with the default key status, the default key form, and a project key for Acme Mobile](docs/images/keys.png)
 
 The images are illustrations with sample data. They come from `docs/graphics`; see [Graphics](#graphics).
 
 ## What you need
 
-- Paseo 0.9.0 or newer, with **Enable plugins** turned on in **Settings → Plugins**.
-- A Linear personal API key in the daemon environment. Create one in Linear under **Settings → Security & access → Personal API keys**. The plugin only reads issues, so a key with read permission is enough.
-
-## Setup
+- Paseo 0.10.0 or newer, with **Enable plugins** turned on in **Settings → Plugins**.
+- A Linear personal API key. Create one in Linear under **Settings → Security & access → Personal API keys**. To change issues, add comments, or create issues, the key must have write access.
 
-Set the key in the environment that starts the Paseo daemon:
+## Install
 
 ```sh
-export LINEAR_API_KEY="lin_api_..."
+paseo plugin add npm:@yannelli/paseo-linear-plugin
+paseo plugin ls linear
 ```
 
-Start or restart the daemon from that environment. The key stays on the daemon host. The app calls the plugin over RPC, and only the daemon subprocess sends requests to `api.linear.app`. To change the key, restart the daemon with the new value. Installing or reloading the plugin does not read a new environment.
+To pin a version, add it to the source, for example `npm:@yannelli/paseo-linear-plugin@0.1.0`. To install a Git tag instead, run `paseo plugin add github:yannelli/paseo-linear-plugin --ref v0.1.0`. Plugins run trusted code with the daemon user's access.
 
-## Install
+## Connect Linear
+
+### Default key
+
+Open **Settings → Plugins → Linear → Account**, paste your key, and select **Connect Linear**. The Linear screen shows the same form until a key is set. The plugin checks the key with Linear before it saves it.
+
+The daemon saves the key in `$PASEO_HOME/plugin-data/linear/credentials.json`, which is `~/.paseo/plugin-data/linear/credentials.json` by default. The file has mode `0600` and its folder has mode `0700`. A saved key takes effect at once. **Disconnect** deletes the saved key.
+
+### Key from the environment
+
+If no key is saved, the plugin uses `LINEAR_API_KEY` from the environment that starts the daemon:
 
 ```sh
-paseo plugin add npm:@yannelli/paseo-linear-plugin
-paseo plugin ls linear
+export LINEAR_API_KEY="lin_api_..."
 ```
 
-To pin a version, add it to the source, for example `npm:@yannelli/paseo-linear-plugin@0.1.0`. To install a Git tag instead, run `paseo plugin add github:yannelli/paseo-linear-plugin --ref v0.1.0`. Plugins run trusted code with the daemon user's access.
+A saved key takes precedence over the environment. To change the environment key, restart the daemon with the new value.
+
+### Project keys
+
+A Paseo project can use a different Linear key, for example for a different Linear workspace. In the **Project keys** section of the Account settings, choose the project, paste the key, and select **Save project key**.
+
+- The Linear panel in a workspace of that project uses the project key.
+- When project keys exist, the Linear screen shows a key button in the filter row. Use it to switch between **Default key** and the project keys.
+- The plugin looks for a key in this order: the project key, the saved default key, then `LINEAR_API_KEY`.
+- The composer attachment always uses the default key.
 
 ## Use
 
-1. Open the attachment menu in the composer and choose **Attach Linear issue**.
-2. Type an identifier, such as `ENG-123`, for an exact match. Type other text to search issue titles. An empty search lists the 20 most recently updated issues.
-3. Select an issue. A pill with the issue title appears in the composer.
-4. Send the message. The agent receives the issue text with your prompt.
+### Browse issues
+
+Open **Linear** from the sidebar, or run **Linear: Open issues** in the command center. In a workspace, run **Linear: Show issues in this workspace**, or type `/linear` in the composer. `/linear ENG-123` opens that issue, and `/linear <text>` searches.
 
-The snapshot is taken when you select the issue. Later changes in Linear do not update an attached pill.
+- The search box matches issue titles and descriptions. An identifier such as `ENG-123` shows that issue only.
+- Filter by assignee (**Mine**, **Everyone**, **Unassigned**), by status (**Active**, **Backlog**, **Done**, **All**), and by team.
+- The list groups issues by status and loads more as you scroll.
+- If you map Linear teams to a project in **Settings → Plugins → Linear → Projects**, the panel starts with the first mapped team.
+
+### Sort
+
+Select the sort button in the filter row. The options are **Last updated**, **Newest**, **Priority**, **Due date**, and **Title**.
+
+### Sub-issues
+
+Select **Sub-issues** in the filter row to nest sub-issues under their parent. A sub-issue shows under its parent when the parent is in the list, even if their statuses differ. Select the chevron to collapse or expand a parent. A collapsed parent shows how many sub-issues it hides.
+
+The issue header shows breadcrumbs: the team, the parent chain, then the issue, for example **Engineering › ENG-120 › ENG-123**. Select a parent to open it. A long chain folds its middle into **…**; select it to show all parents.
+
+### Read and edit an issue
+
+- Select the status, priority, or assignee chip to change it.
+- Descriptions and comments show as Markdown: headings, lists, task lists, code, quotes, tables, and links.
+- Select the pencil next to **Description** to edit it as Markdown. The plugin saves about one second after you stop typing, and when you leave the box. The line under the box shows **Saving…**, then **Saved to Linear**. If a save fails, it shows **Could not save** and a **Retry** button. **Done** (or Escape) closes the editor only after Linear accepts the text.
+- Select a task list checkbox in the description to check or uncheck it. The plugin changes only that box in the Markdown and saves it to Linear. If the save fails, the issue reloads from Linear.
+- Add a comment in the **Activity** section.
+- The header buttons refresh the issue, copy its branch name, and open it in Linear.
+- Select **New issue**, or run **Linear: Create issue**, to create an issue. Set the team, status, priority, assignee, title, and a Markdown description.
+
+### Start an agent
+
+Select **Start agent** or **Start review** in the issue view. The agent setup page opens in the panel or the screen. It works with or without a current workspace.
+
+1. Edit the prompt in the prompt box if you want. The prompt follows the template and options until you edit it. Select **Reset prompt** to go back to the template.
+2. Use the controls under the prompt box, as in the Paseo composer. They set the prompt template (Implement or Review), the model, the thinking level, and the mode. The thinking level shows when the model has levels, and the mode shows when the agent has modes.
+   - The model picker lists the providers first. Select a provider to see its models, or search to find models from all providers.
+   - Choosing a model from another provider also changes the agent, and resets the thinking level and mode to that agent's defaults.
+3. Choose the **Project**. The default is the project of the current workspace. Without a workspace, it is the last project you used for the team, then a project mapped to the team.
+4. Choose where the agent runs in **Run in**:
+   - **New worktree** on the issue branch.
+   - **Check out PR #N** for a review, when the issue links a GitHub pull request.
+   - **Check out issue branch** for a review.
+   - **Existing agent workspace** or **Implementation workspace**, when an agent already works on the issue.
+   - **This workspace**, or **Project folder** when you are not in a workspace of that project.
+
+   The worktree and checkout options show only for a Git project.
+5. Set the options: **Include comments in the prompt**, **Move the issue to In Progress**, and **Assign the issue to me**. The last two show only for Implement, and only when they would change the issue.
+6. Select **Start agent** or **Start review**.
+
+The plugin starts the agent and then updates Linear. If the Linear update fails, the agent keeps running and a message shows the error. The agent's timeline gets a card that links to the issue. The issue view lists the agents started from it under **Agents on this issue**.
+
+Set the default model, where agents run, the default options, and the Implement and Review templates in **Settings → Plugins → Linear → Prompts**. In **Projects**, add instructions and steps for a project, or append to or replace a template for that project.
+
+### Attach an issue to a message
+
+In the composer, open the attachment menu and choose **Attach Linear issue**. Type an identifier such as `ENG-123`, or words from a title. An empty search lists the 20 most recently updated issues. The agent gets the issue text with your message. The plugin takes this snapshot when you select the issue.
+
+## Data and permissions
+
+- **Your key stays on the daemon host.** When you save a key, the app sends it to the daemon once. The daemon never sends a key back to the app. The app gets only the last four characters, to show which key is in use. Only the daemon sends requests to `https://api.linear.app/graphql`.
+- **Data sent to Linear:** queries for issues, teams, users, and comments, and the changes you make. When you start an agent with the options on, the plugin moves the issue to In Progress and assigns it to you.
+- **Data sent to the agent provider:** the prompt. It holds the template text and an issue snapshot: identifier, title, URL, team, status, priority, assignee, project, labels, parent, description, sub-issues, and links. It holds comments only when **Include comments in the prompt** is on. It also holds the project instructions and steps from the Projects settings. An attached issue sends the identifier, title, URL, status, priority, assignee, project, labels, and description.
+- **Cached results:** the daemon keeps up to 300 recent Linear responses in memory for up to 24 hours. It groups them by a hash of the key, so two keys never share results. The app shows saved results at once with **Showing saved results. Updating…** while it gets new data. An edit clears the cached lists and issues for that key. Saving or removing a key clears the whole cache. The cache is not written to disk, and a daemon restart clears it.
+
+Linear errors, such as a rejected key or a rate limit, show in the panel or as a message.
 
 ## How it works
 
 | File | Runtime | Role |
 | --- | --- | --- |
-| `shared/issues.ts` | Both | The `issues.search` RPC contract and the attachment source definition |
-| `server/linear.ts` | Daemon | Linear GraphQL client, response validation, and snapshot text |
-| `server/issues.ts` | Daemon | RPC handler that reads `LINEAR_API_KEY` |
-| `index.server.ts` | Daemon | Registers the RPC handler |
-| `index.client.ts` | App | Registers the attachment source |
+| `index.client.tsx` | App | Registers the Linear screen, the workspace panel, the Account, Prompts, and Projects settings, the command center items, the `/linear` command, the timeline card, and the composer attachment |
+| `index.server.ts` | Daemon | Registers the settings and the RPC handlers |
+| `client/browser.tsx` | App | Screen and panel: picks the key, then shows the list, the issue, or the agent setup page |
+| `client/issue-list.tsx`, `client/issue-row.tsx`, `client/issue-tree.ts` | App | Search, filters, sort, rows, status groups, and sub-issue nesting |
+| `client/issue-detail.tsx`, `client/issue-sections.tsx`, `client/breadcrumbs.tsx` | App | Issue view: properties, breadcrumbs, sub-issues, links, agents, and comments |
+| `client/issue-description.tsx`, `client/autosave.ts` | App | Description editor, task list checkboxes, and debounced saves |
+| `client/markdown.tsx` | App | Renders Markdown |
+| `client/launch.tsx`, `client/launch-fields.tsx`, `client/launch-choices.ts`, `client/launch-plan.ts`, `client/agent-options.ts` | App | Agent setup page, Run in options, and agent start |
+| `client/model-browser.tsx`, `client/provider-icon.tsx` | App | Model picker and provider icons |
+| `client/create-issue.tsx`, `client/pickers.tsx` | App | New issue form and option pickers |
+| `client/connect.tsx`, `client/settings-*.tsx` | App | Key form and settings screens |
+| `client/queries.ts`, `client/store.ts`, `client/key-scope.tsx` | App | Data hooks with saved results, browser state, and the key in use |
+| `client/compat.ts` | App | Registers the screen on Paseo 0.10 and on later releases |
+| `client/timeline-card.tsx`, `client/ui.tsx`, `client/glyphs.tsx` | App | Timeline card, shared controls, and icons |
+| `shared/linear.ts` | Both | RPC contracts and issue schemas |
+| `shared/issues.ts` | Both | The `issues.search` RPC and the composer attachment source |
+| `shared/settings.ts` | Both | Settings schema: templates, agent defaults, and project settings |
+| `shared/prompts.ts` | Both | Default templates and the issue snapshot |
+| `shared/markdown.ts` | Both | Markdown parser and task list toggle |
+| `server/handlers.ts` | Daemon | RPC handlers, key lookup, and cache use |
+| `server/credentials.ts` | Daemon | Key file and key order |
+| `server/cache.ts` | Daemon | Response cache in memory |
+| `server/graphql.ts`, `server/queries.ts` | Daemon | Linear GraphQL client, queries, and changes |
+| `server/linear.ts` | Daemon | Search and snapshot text for the composer attachment |
 
 The client bundle holds no credentials and makes no calls to Linear.
 
@@ -69,7 +174,7 @@ npm run check
 paseo plugin add "$PWD"
 ```
 
-After you edit the source, run `paseo plugin reload linear`. `npm run check` runs the typecheck, the Linear client tests against a local GraphQL server, and the release script tests.
+After you edit the source, run `paseo plugin reload linear`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, and the release scripts. They use a local GraphQL server and do not call Linear.
 
 ## Graphics
 
@@ -79,7 +184,7 @@ After you edit the source, run `paseo plugin reload linear`. `npm run check` run
 node docs/graphics/render.mjs
 ```
 
-The script finds Playwright locally or in the global npm root. Set `PLAYWRIGHT_MODULE` to its entry file to choose another copy. The fonts are Instrument Sans and JetBrains Mono under the [SIL Open Font License](docs/graphics/fonts/OFL.txt). The mark is original and is not the Linear logo.
+The script finds Playwright locally or in the global npm root. Set `PLAYWRIGHT_MODULE` to its entry file to choose another copy. It stops if the fonts do not load, if content leaves the frame or is cut off, or if an image is 900 KB or larger. The fonts are Instrument Sans and JetBrains Mono under the [SIL Open Font License](docs/graphics/fonts/OFL.txt). The line icons follow [Lucide](https://lucide.dev), which uses the ISC License. The mark is original and is not the Linear logo.
 
 ## Releases
 
@@ -98,6 +203,10 @@ The highest change since the last release sets the next version. For example, `f
 
 Run `npm run release:dry-run` from a clean `main` checkout with all tags fetched to preview the next release. To complete a GitHub or npm publication that stopped after its tag was pushed, run the **Release** workflow again.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks, commit message rules, and how releases work.
+
 ## License
 
-Apache License 2.0. The plugin source comes from the Linear example in [getpaseo/paseo](https://github.com/getpaseo/paseo/tree/main/plugin-examples/linear). See [NOTICE](NOTICE).
+Apache License 2.0. The plugin started as the Linear example plugin (`plugin-examples/linear`) in [getpaseo/paseo](https://github.com/getpaseo/paseo). See [NOTICE](NOTICE).

package/client/agent-options.ts

@@ -0,0 +1,200 @@
+// Turns the daemon's provider snapshot into Agent, Model, Effort, and Mode choices.
+
+export interface Choice {
+  id: string;
+  label: string;
+}
+
+export interface ModelChoice extends Choice {
+  description: string | null;
+  isDefault: boolean;
+  efforts: Choice[];
+  defaultEffortId: string | null;
+}
+
+export interface ModeChoice extends Choice {
+  icon: string | null;
+  colorTier: string | null;
+}
+
+export interface AgentChoice extends Choice {
+  /** SVG markup for custom providers. Built-in providers have none. */
+  iconSvg: string | null;
+  models: ModelChoice[];
+  modes: ModeChoice[];
+  defaultModeId: string | null;
+}
+
+interface ThinkingOption {
+  id: string;
+  label: string;
+  isDefault?: boolean;
+}
+
+interface SnapshotModel {
+  id: string;
+  label: string;
+  description?: string;
+  isDefault?: boolean;
+  isSelectable?: boolean;
+  thinkingOptions?: readonly ThinkingOption[];
+  defaultThinkingOptionId?: string;
+  thinkingSet?: number;
+}
+
+interface SnapshotEntry {
+  provider: string;
+  label?: string;
+  iconSvg?: string;
+  status: string;
+  enabled?: boolean;
+  models?: readonly SnapshotModel[];
+  modes?: readonly (Choice & { icon?: string; colorTier?: string })[];
+  defaultModeId?: string | null;
+}
+
+export interface ProviderSnapshot {
+  entries: readonly SnapshotEntry[];
+  compactSnapshot?: {
+    entries: readonly SnapshotEntry[];
+    thinkingSets: readonly { options: readonly ThinkingOption[]; defaultOptionId?: string }[];
+  } | null;
+}
+
+// App connections get the compact catalog, where a model points into a shared list of efforts.
+export function agentChoices(snapshot: ProviderSnapshot): AgentChoice[] {
+  const compact = snapshot.entries.length === 0 ? snapshot.compactSnapshot : null;
+  const entries = compact ? compact.entries : snapshot.entries;
+  return entries
+    .filter((entry) => entry.status === "ready" && entry.enabled !== false)
+    .map((entry) => ({
+      id: entry.provider,
+      label: entry.label ?? entry.provider,
+      iconSvg: entry.iconSvg ?? null,
+      models: (entry.models ?? [])
+        .filter((model) => model.isSelectable !== false)
+        .map((model) => {
+          const set =
+            model.thinkingSet === undefined ? null : compact?.thinkingSets[model.thinkingSet];
+          const options = set?.options ?? model.thinkingOptions ?? [];
+          const fallback = options.find((option) => option.isDefault)?.id ?? null;
+          return {
+            id: model.id,
+            label: model.label,
+            description: model.description ?? null,
+            isDefault: model.isDefault === true,
+            efforts: options.map(({ id, label }) => ({ id, label })),
+            defaultEffortId: model.defaultThinkingOptionId ?? set?.defaultOptionId ?? fallback,
+          };
+        }),
+      modes: (entry.modes ?? []).map(({ id, label, icon, colorTier }) => ({
+        id,
+        label,
+        icon: icon ?? null,
+        colorTier: colorTier ?? null,
+      })),
+      defaultModeId: entry.defaultModeId ?? null,
+    }))
+    .filter((entry) => entry.models.length > 0);
+}
+
+export interface AgentSelection {
+  agent: AgentChoice;
+  model: ModelChoice;
+  effort: Choice | null;
+  mode: ModeChoice | null;
+}
+
+export interface AgentPicks {
+  agent: string | null;
+  model: string | null;
+  effort: string | null;
+  mode: string | null;
+}
+
+/** `configured` is the settings default in `provider/model` form. Empty uses the first agent. */
+export function resolveAgent(
+  agents: readonly AgentChoice[],
+  picks: AgentPicks,
+  configured: string,
+): AgentSelection | null {
+  const [configuredAgent, ...rest] = configured.split("/");
+  const configuredModel = rest.join("/");
+  const agent =
+    agents.find((entry) => entry.id === picks.agent) ??
+    agents.find((entry) => entry.id === configuredAgent) ??
+    agents[0];
+  if (!agent) return null;
+  const preferredModel = agent.id === configuredAgent ? configuredModel : null;
+  const model =
+    agent.models.find((entry) => entry.id === picks.model) ??
+    agent.models.find((entry) => entry.id === preferredModel) ??
+    agent.models.find((entry) => entry.isDefault) ??
+    agent.models[0];
+  if (!model) return null;
+  const effort =
+    model.efforts.find((entry) => entry.id === picks.effort) ??
+    model.efforts.find((entry) => entry.id === model.defaultEffortId) ??
+    null;
+  const mode =
+    agent.modes.find((entry) => entry.id === picks.mode) ??
+    agent.modes.find((entry) => entry.id === agent.defaultModeId) ??
+    null;
+  return { agent, model, effort, mode };
+}
+
+/** Config for `agents.create`. Ids come from the selection, so they always fit the model. */
+export function agentConfig(selection: AgentSelection) {
+  return {
+    provider: `${selection.agent.id}/${selection.model.id}`,
+    ...(selection.effort ? { thinkingOptionId: selection.effort.id } : {}),
+    ...(selection.mode ? { modeId: selection.mode.id } : {}),
+  };
+}
+
+export interface ModelMatch {
+  agent: AgentChoice;
+  model: ModelChoice;
+}
+
+/** Models whose name, id, description, or agent name contain every word of the query. */
+export function searchModels(agents: readonly AgentChoice[], query: string): ModelMatch[] {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [];
+  return agents.flatMap((agent) =>
+    agent.models
+      .filter((model) => {
+        const text = [model.label, model.id, model.description ?? "", agent.label]
+          .join(" ")
+          .toLowerCase();
+        return words.every((word) => text.includes(word));
+      })
+      .map((model) => ({ agent, model })),
+  );
+}
+
+const MODE_ICONS = new Set([
+  "Bot",
+  "Shield",
+  "ShieldAlert",
+  "ShieldCheck",
+  "ShieldEllipsis",
+  "ShieldOff",
+  "ShieldPlus",
+  "ShieldQuestionMark",
+]);
+
+/** The Lucide icon Paseo shows for a mode. */
+export function modeIcon(mode: ModeChoice): string {
+  const icon = mode.icon ?? "ShieldCheck";
+  return MODE_ICONS.has(icon) ? icon : "Bot";
+}
+
+function sentenceCase(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1).toLowerCase();
+}
+
+/** Effort and mode names as Paseo writes them, for example "Extra high". */
+export function optionLabel(option: Choice): string {
+  return option.id === "xhigh" ? "Extra high" : sentenceCase(option.label);
+}

package/client/autosave.ts

@@ -0,0 +1,77 @@
+// Debounced, single-flight saving for one text value. Pure so the tests can drive it
+// with fake timers. Only the latest value is kept, and one save runs at a time, so
+// saves always reach the server in edit order.
+
+export type SaveStatus = "idle" | "pending" | "saving" | "saved" | "error";
+
+export interface AutosaveOptions {
+  delayMs: number;
+  save(value: string): Promise<void>;
+  onStatus(status: SaveStatus, error?: unknown): void;
+}
+
+export interface Autosave {
+  /** Queues `value` and saves it after `delayMs` (or the given delay) without changes. */
+  schedule(value: string, delayMs?: number): void;
+  /** Saves the queued value now. Resolves when nothing is left to save. */
+  flush(): Promise<void>;
+  /** Drops the queued value. A save in flight still finishes. */
+  cancel(): void;
+  /** True while a value is queued or saving. */
+  busy(): boolean;
+}
+
+export function createAutosave(options: AutosaveOptions): Autosave {
+  let queued: string | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<void> | null = null;
+
+  function clearTimer() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  // Starts the next save unless one is running. Rejects with the save error.
+  function run(): Promise<void> {
+    clearTimer();
+    if (inFlight) return inFlight.then(() => (queued === null ? undefined : run()));
+    if (queued === null) return Promise.resolve();
+    const value = queued;
+    queued = null;
+    options.onStatus("saving");
+    inFlight = options.save(value).then(
+      () => {
+        inFlight = null;
+        if (queued === null) options.onStatus(timer === null ? "saved" : "pending");
+        else if (timer === null) return run();
+      },
+      (error: unknown) => {
+        inFlight = null;
+        // Keep the failed value for a retry unless a newer edit replaced it.
+        if (queued === null) queued = value;
+        if (timer === null) options.onStatus("error", error);
+        throw error;
+      },
+    );
+    return inFlight;
+  }
+
+  function background() {
+    run().catch(() => undefined);
+  }
+
+  return {
+    schedule(value, delayMs = options.delayMs) {
+      queued = value;
+      clearTimer();
+      options.onStatus("pending");
+      timer = setTimeout(background, delayMs);
+    },
+    flush: run,
+    cancel() {
+      clearTimer();
+      queued = null;
+    },
+    busy: () => queued !== null || inFlight !== null,
+  };
+}