@yannelli/paseo-linear-plugin 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,13 @@
+paseo-linear-plugin
+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.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

@@ -0,0 +1,33 @@
+# Linear issues
+
+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.
+
+## Connect Linear
+
+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.
+
+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.
+
+## Browse issues
+
+- 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.
+- `/linear` opens the panel. `/linear ENG-123` opens an issue.
+
+## Start an agent
+
+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
+
+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
+
+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,3 +1,208 @@
-# Temporary Holding Version
+![Linear issues in Paseo: an issue view with Start agent and Start review buttons, next to the install command](docs/images/social-preview.png)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Linear issues for Paseo
+
+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.
+
+- 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.
+- 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.
+
+![Linear screen with an issue list grouped by status on the left and issue ENG-123 open on the right](docs/images/browse.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.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.
+
+## Install
+
+```sh
+paseo plugin add npm:@yannelli/paseo-linear-plugin
+paseo plugin ls linear
+```
+
+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.
+
+## 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
+export LINEAR_API_KEY="lin_api_..."
+```
+
+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
+
+### 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 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.
+- 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 |
+| --- | --- | --- |
+| `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/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 |
+| `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.
+
+## Development
+
+Use Node.js 24.
+
+```sh
+git clone https://github.com/yannelli/paseo-linear-plugin.git
+cd paseo-linear-plugin
+npm ci
+npm run check
+paseo plugin add "$PWD"
+```
+
+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, the agent options, and the release scripts. They use a local GraphQL server and do not call Linear.
+
+## Graphics
+
+`docs/graphics/scene.html` and `scene.css` define the README images, the GitHub social preview, and the icon. Render them into `docs/images` with Playwright and Chromium:
+
+```sh
+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. 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
+
+GitHub Actions runs the checks and publishes a release on qualifying pushes to `main`. The first release is `v0.1.0`. The workflow updates `package.json` and `package-lock.json`, pushes an annotated tag, and publishes release notes. It then publishes [`@yannelli/paseo-linear-plugin`](https://www.npmjs.com/package/@yannelli/paseo-linear-plugin) to npm through trusted publishing (OIDC), with no npm token. See [npm publishing](docs/npm-publishing.md) for the first-publish steps.
+
+Use Conventional Commits in commits and squash-merge titles:
+
+| Commit | Version change |
+| --- | --- |
+| `fix:`, `perf:`, `revert:` | Patch |
+| `feat:` | Minor |
+| `!` after the type or scope, or a `BREAKING CHANGE:` footer | Major, including before 1.0 |
+| `docs:`, `chore:`, `ci:`, and other types without a breaking marker | No release |
+
+The highest change since the last release sets the next version. For example, `fix: trim identifier queries` changes `0.1.0` to `0.1.1`, and `feat: filter by project` changes it to `0.2.0`.
+
+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 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);
+}