paseo-tab-namer 0.0.0-bootstrap.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OVERVIEW.md

@@ -0,0 +1,11 @@
+# Tab Namer
+
+Tab Namer gives an existing workspace a new name based on what its Tabs are about. Open it from the ✨ button in the workspace header or from the command center. You can preview the input, choose which Tabs to use, and generate again. A generated name is applied right away. To apply a name you edited by hand, click "应用手动修改" (Apply manual edit).
+
+The settings screen holds one naming prompt, model, maximum input budget, name length, and timeout for all workspaces. You pick the provider and model from the providers already enabled on this Paseo host. The plugin has no endpoint of its own and never handles API keys.
+
+The default input budget is a conservative upper bound of 128,000 tokens (UTF-8 bytes plus a margin), usually above the real token count. When the selected text goes over budget, Tab Namer keeps the start of each Tab and its recent part, and shows that it cut the text. Tool logs, reasoning, and raw image content are never sent. The selected text goes to the provider you chose: the plugin starts a temporary session in the current workspace for the request and archives it when the reply arrives.
+
+The plugin UI and the default naming prompt are in Simplified Chinese. Edit the prompt in settings to get names in another language.
+
+Requires Paseo 0.11.2 or later. Paseo does not let plugins add items to the native workspace context menu or rename dialog, so Tab Namer uses the header button and the command center.

package/OVERVIEW.zh-CN.md

@@ -0,0 +1,9 @@
+# Tab Namer
+
+根据 Tab 内容为已有 workspace 生成新名称。通过顶部 ✨ 按钮或命令中心打开。可以预览输入、选择 Tab 范围和反复生成；生成成功后立即自动应用。手动编辑时可点击“应用手动修改”。
+
+设置页统一配置命名提示词、模型、最大输入预算、名称长度和超时。服务和模型从此主机 Paseo 已启用的服务列表中选择，不绑定特定接口，插件不接触任何密钥。
+
+默认输入预算为 128,000 的保守 token 上界（UTF-8 字节数加余量），通常高于模型实际 tokens。超限保留任务开头和近期内容，并显示截取状态。工具日志、推理和图片原始内容不进入请求。所选文字会发送到所选服务：插件在当前 workspace 临时启动一个命名会话，完成后自动归档。
+
+需要 Paseo 0.11.2 或更新版本。原生 workspace 右键菜单和重命名对话框不提供插件扩展位置。

package/README.md

@@ -1,3 +1,167 @@
-# paseo-tab-namer
+<p align="center">
+  <img src="docs/images/banner.png" alt="Tab Namer — rename Paseo workspaces from what their Tabs are actually about" width="100%" />
+</p>
 
-Placeholder. See https://github.com/stv1024/paseo-tab-namer.
+<p align="center">
+  <a href="https://github.com/stv1024/paseo-tab-namer/releases"><img alt="Version" src="https://img.shields.io/badge/version-0.1.0-20744a?style=flat-square" /></a>
+  <img alt="Paseo" src="https://img.shields.io/badge/paseo-%E2%89%A5%200.11.2-7ccba0?style=flat-square" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" />
+  <img alt="Tests" src="https://img.shields.io/badge/tests-node%3Atest-555?style=flat-square" />
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <b>English</b> · <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+---
+
+**Tab Namer** is a [Paseo](https://github.com/getpaseo/paseo) plugin that gives your workspaces names that actually mean something. It reads the conversation in a workspace's Tabs, asks a model from one of the providers you've already enabled in Paseo, and applies a short, specific name, such as `修复 OAuth 回调重定向循环` instead of `new-workspace-7`.
+
+- ✨ **One click**: a Sparkles button in every workspace header. The new name is applied as soon as it's generated.
+- 🔌 **Uses your existing providers**: Claude, Codex, OMP or any custom provider enabled in Paseo. The plugin has no endpoint, API key or extra dependency of its own.
+- 🎯 **You choose the context**: name from the most recent Tab, all Tabs, or one Tab you pick.
+- 📏 **Fits long Tabs into a budget**: a conservative input budget keeps the beginning and the most recent part of each Tab and makes no extra summarization calls.
+- 🔒 **Text only**: only user and assistant text is sent. Tool logs, reasoning and raw images stay out.
+- 🧹 **Cleans up after itself**: the helper session is archived as soon as it replies. The directory and Git branch are never touched.
+
+> [!NOTE]
+> The plugin UI and the default naming prompt are in **Simplified Chinese**. Edit the prompt in settings to generate names in another language.
+
+## Screenshots
+
+<p align="center">
+  <img src="docs/images/popover.png" alt="Tab Namer popover open from the workspace header" width="100%" />
+  <br /><sub>The header popover after a generation, with <b>More</b> expanded to show budget and usage.</sub>
+</p>
+
+<p align="center">
+  <img src="docs/images/settings.png" alt="Tab Namer settings screen" width="100%" />
+  <br /><sub>Settings apply to every workspace on the host: provider, model, thinking level, budget and prompt.</sub>
+</p>
+
+> Images are illustrative mockups built from the plugin's real UI and Paseo's dark theme. Their sources are in [`docs/media-src`](docs/media-src).
+
+## Installation
+
+Requires **Paseo 0.11.2 or newer**.
+
+```sh
+paseo plugin install git:stv1024/paseo-tab-namer
+```
+
+Pin a version with `--ref <tag-or-commit>`. Update later with `paseo plugin update tab-namer`.
+
+On first use, open **Settings → Tab Namer**, pick a **provider** and a **model**, then click **保存设置** (Save settings).
+
+## Usage
+
+1. Click the **✨ Tab Namer** button in a workspace header.
+2. Pick the scope: **最近 Tab** (most recent), **全部 Tab** (all) or **指定 Tab** (a specific Tab).
+3. Click **生成名称** (Generate). The name is applied right away. **再次生成** (Regenerate) gives you another one.
+4. To fine-tune by hand, edit the field and click **应用手动修改** (Apply manual edit).
+
+Under **更多** (More), **预览输入** (Preview input) shows exactly what will be sent and how much of the budget it uses, without calling the model.
+
+Other entry points:
+
+| Where                 | What                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| Command center        | `Tab Namer：选择 workspace 重命名` (searchable list of every workspace), `Tab Namer：重命名当前 workspace`, `Tab Namer：根据当前 Tab`, `Tab Namer 设置` |
+
+## How it works
+
+<p align="center">
+  <img src="docs/images/flow.png" alt="Read Tabs → fit the budget → ask your provider → apply and clean up" width="100%" />
+</p>
+
+Paseo exposes models to plugins only through agents. When you click Generate, the plugin starts a temporary session titled **Tab Namer** (tagged `tab-namer`) in the current workspace and sends the prompt and the selected Tab text as one message. It reads the reply and archives the session right away. Tagged sessions are never read back as Tabs. All authentication stays in Paseo's provider configuration.
+
+Generation runs as a background job that the UI polls, so you can close the popover. Each workspace runs one job at a time, with at most three jobs in parallel. Before writing, the plugin re-reads the current name and refuses to overwrite one that changed in the meantime.
+
+## Settings
+
+| Setting                   | Default                         | Notes                                                   |
+| ------------------------- | ------------------------------- | ------------------------------------------------------- |
+| Provider & model          | _not set_                       | Listed from the providers enabled on this Paseo host     |
+| Thinking level            | Model default                   | Lower is usually faster; naming is a simple task         |
+| Max input budget          | 128,000                         | Range 2,048–256,000; conservative upper bound            |
+| Default scope             | Most recent Tab                 | Or all Tabs                                              |
+| Content                   | User + assistant text           | Or user text only                                        |
+| Max name length           | 48 characters                   | 8–120                                                    |
+| Request timeout           | 180 s                           | 15–600                                                   |
+| Naming prompt             | Built-in Chinese prompt         | Shared by all workspaces; can be reset to the default    |
+
+<details>
+<summary><b>About the input budget</b></summary>
+
+Tokenizers differ between models, so the budget counts **UTF-8 bytes + 256** for the system prompt and the selected messages. This is usually well above the real token count: 128,000 typically holds a few tens of thousands of real tokens. When the provider reports usage, the UI shows the real figures. Make sure the model's context window can hold the budget you set.
+
+Short Tabs are included in full. When the total goes over budget, each Tab keeps roughly its first 25% and its most recent 75%, and the budget is split fairly across Tabs (short Tabs give back what they don't use). Very long Tabs are read page by page, with a page limit. Up to 100 Tabs per run. The preview always says whether anything was cut.
+
+Providers such as Claude Code and Codex add their own system prompt and tool definitions, so billed input tokens are higher than the naming content itself. The prompt tells the model not to use tools. If it asks for tool permission anyway, the job stops with an error.
+
+</details>
+
+## Privacy
+
+- The text of the selected Tabs is sent to the provider **you** picked, and nowhere else.
+- Preview never calls a model and never renames anything.
+- The plugin stores no credentials. Settings live in Paseo host settings.
+- Finished job results are kept in memory for about ten minutes, then dropped.
+
+## Limitations
+
+- Paseo doesn't let plugins add items to the native workspace context menu or rename dialog, so Tab Namer adds a header button and command-center entries instead. It does not use the sidebar, so it takes no space in the mobile workspace list.
+- Names can only be based on history Paseo still has. Anything the host already discarded can't be recovered.
+- Paseo has no atomic compare-and-set for names, so a change made in the instant between the check and the write can still be overwritten.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test                      # node:test suite under server/
+
+# Name the workspace for the current directory against your local Paseo,
+# without renaming it
+npm run test:smoke -- <provider>/<model>
+
+paseo plugin install .        # install from a local checkout
+paseo plugin reload tab-namer # after changes
+```
+
+When Paseo installs a plugin from Git, it bundles the source with esbuild and **does not run `npm install`**. Runtime code may only import what Paseo provides: `@getpaseo/plugin`, `react`, `react-native`, `zod` and Node built-ins. Everything in `devDependencies` is for type-checking, tests and scripts only.
+
+```
+index.client.tsx   UI entry: header button, screens, command center
+index.server.ts    RPC handlers and background jobs
+client/            rename popover/screen, settings screen, shared UI
+server/            Tab reading, budgeting, model session, naming logic (+ tests)
+shared/            RPC contracts and settings schema
+docs/media-src/    HTML sources for README images (node docs/media-src/render.mjs)
+```
+
+### Release
+
+Releases go to npm as `paseo-tab-namer` through
+[`.github/workflows/release.yml`](.github/workflows/release.yml), with npm Trusted
+Publishing (no npm token). Bump `version` in `package.json`, add a `CHANGELOG.md`
+section, then commit, tag and push:
+
+```sh
+npm run typecheck && npm test && npm run pack:npm   # check the packed file list
+git push origin main
+git tag -a v0.1.0 -m "Tab Namer 0.1.0" && git push origin v0.1.0
+```
+
+The tag push publishes the tarball. Then create the GitHub release from the tag.
+The official registry opens a bump PR for each new npm version.
+
+## Contributing
+
+Issues and pull requests are welcome. Before opening a PR, run `npm run typecheck` and `npm test`. For changes that affect naming quality, include before/after examples from `npm run test:smoke`.
+
+## License
+
+[MIT](LICENSE) © Stephen Zhou

package/README.zh-CN.md

@@ -0,0 +1,147 @@
+<p align="center">
+  <img src="docs/images/banner.png" alt="Tab Namer：根据 Tab 内容为 Paseo workspace 起名" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/stv1024/paseo-tab-namer/releases"><img alt="Version" src="https://img.shields.io/badge/version-0.1.0-20744a?style=flat-square" /></a>
+  <img alt="Paseo" src="https://img.shields.io/badge/paseo-%E2%89%A5%200.11.2-7ccba0?style=flat-square" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white" />
+  <img alt="Tests" src="https://img.shields.io/badge/tests-node%3Atest-555?style=flat-square" />
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> · <b>简体中文</b>
+</p>
+
+---
+
+**Tab Namer** 是一个 [Paseo](https://github.com/getpaseo/paseo) 插件，根据 workspace 中 Tab 的对话内容，用你在 Paseo 中已启用的模型服务生成一个简短、具体的名称并直接应用，比如把 `new-workspace-7` 改成 `修复 OAuth 回调重定向循环`。
+
+- ✨ **一键生成**：每个 workspace 顶部都有 ✨ 按钮，生成成功后立即自动应用。
+- 🔌 **复用已有服务**：Claude、Codex、OMP 或任何自定义服务均可。插件本身不需要地址、密钥或额外依赖。
+- 🎯 **自选上下文**：可依据最近 Tab、全部 Tab 或指定 Tab 命名。
+- 📏 **长 Tab 也能装下**：按保守预算截取，保留每个 Tab 的开头和近期内容，不额外调用模型做摘要。
+- 🔒 **只发文字**：仅发送用户与助手的文字消息，工具日志、推理过程和图片原始内容不进入请求。
+- 🧹 **用完即清**：临时命名会话回复后立即归档；不修改目录或 Git 分支。
+
+## 截图
+
+<p align="center">
+  <img src="docs/images/popover.png" alt="从 workspace 顶部打开的 Tab Namer 弹窗" width="100%" />
+  <br /><sub>生成完成后的顶部弹窗，展开“更多”可查看预算与用量。</sub>
+</p>
+
+<p align="center">
+  <img src="docs/images/settings.png" alt="Tab Namer 设置页" width="100%" />
+  <br /><sub>设置对本机所有 workspace 生效：服务、模型、思考强度、预算与提示词。</sub>
+</p>
+
+> 图片为根据插件真实界面和 Paseo 深色主题制作的示意图，源文件见 [`docs/media-src`](docs/media-src)。
+
+## 安装
+
+需要 **Paseo 0.11.2 或更新版本**。
+
+```sh
+paseo plugin install git:stv1024/paseo-tab-namer
+```
+
+可用 `--ref <tag 或 commit>` 固定版本；之后用 `paseo plugin update tab-namer` 更新。
+
+首次使用请打开 **设置 → Tab Namer**，选择 **服务** 和 **模型**，再点 **保存设置**。
+
+## 使用
+
+1. 点击 workspace 顶部的 **✨ Tab Namer** 按钮。
+2. 选择范围：**最近 Tab**、**全部 Tab** 或 **指定 Tab**。
+3. 点击 **生成名称**，名称会立即应用；点 **再次生成** 可换一个。
+4. 如需手动微调，修改输入框后点击 **应用手动修改**。
+
+展开 **更多** 后点 **预览输入**，可查看将要发送的内容和预算占用，不调用模型。
+
+其他入口：
+
+| 位置       | 内容                                                                         |
+| ---------- | ---------------------------------------------------------------------------- |
+| 命令中心   | `Tab Namer：选择 workspace 重命名`（可搜索全部 workspace）、`Tab Namer：重命名当前 workspace`、`Tab Namer：根据当前 Tab`、`Tab Namer 设置` |
+
+## 工作原理
+
+<p align="center">
+  <img src="docs/images/flow.png" alt="读取 Tab → 适配预算 → 调用服务 → 应用并清理" width="100%" />
+</p>
+
+Paseo 目前只通过 agent 向插件提供模型能力。点击生成时，插件在当前 workspace 临时启动一个标题为 **Tab Namer**、带 `tab-namer` 标签的会话，把提示词和所选 Tab 文字作为一条消息发送，读取回复后立即归档。带该标签的会话不会被当作 Tab 读取。认证完全由 Paseo 的服务配置负责。
+
+生成以后台任务运行，界面轮询状态，关闭弹窗也会完成。每个 workspace 同时只运行一项任务，全局最多并发三项。写入前会重读当前名称，若已被修改则拒绝覆盖。
+
+## 设置
+
+| 设置         | 默认值             | 说明                                   |
+| ------------ | ------------------ | -------------------------------------- |
+| 服务与模型   | 未选择             | 列表来自本机 Paseo 已启用的服务        |
+| 思考强度     | 模型默认           | 命名任务简单，较低强度通常更快         |
+| 最大输入预算 | 128,000            | 可设 2,048–256,000，保守上界           |
+| 默认范围     | 最近 Tab           | 或全部 Tab                             |
+| 内容         | 用户与助手文字     | 或仅用户文字                           |
+| 名称长度     | 最多 48 个字符     | 8–120                                  |
+| 请求超时     | 180 秒             | 15–600                                 |
+| 命名提示词   | 内置中文提示词     | 所有 workspace 共用，可恢复默认        |
+
+<details>
+<summary><b>关于输入预算</b></summary>
+
+不同模型的 tokenizer 不同，因此预算按 **UTF-8 字节数加 256** 计算，包含系统提示词和选取的消息。这个数通常显著高于实际 tokens：128,000 的预算通常容纳几万个实际 tokens。服务返回用量时界面会显示实际数值；请确保所选模型的上下文窗口足够容纳该预算。
+
+短 Tab 的文字完整纳入。超限时每个 Tab 保留开头约 25% 和近期约 75%；多个 Tab 公平分配预算，短 Tab 退还未用空间。很长的 Tab 分页读取，有读取页数上限。一次最多处理 100 个 Tab。预览会明确显示是否截取。
+
+Claude Code、Codex 等服务会附带自身的系统提示词与工具定义，因此实际计费的输入 tokens 会高于命名内容本身。提示词要求模型不调用工具；若模型仍请求工具权限，任务会停止并报错。
+
+</details>
+
+## 隐私
+
+- 所选 Tab 的文字只发送到 **你** 选择的服务。
+- 预览输入不会调用模型，也不会修改名称。
+- 插件不保存任何凭据；设置保存在 Paseo 的 host settings 中。
+- 完成任务的临时结果约十分钟后从内存移除。
+
+## 限制
+
+- Paseo 不支持把插件按钮放入原生 workspace 右键菜单或重命名对话框，因此改为提供顶部按钮和命令中心条目。插件不使用侧栏，不占用手机端 workspace 列表的空间。
+- 只能依据 Paseo 当前可读取的记录命名，无法恢复宿主已丢弃的历史。
+- 宿主没有原子 compare-and-set 接口，无法防止“检查后、写入前”这一瞬间的并发修改。
+
+## 开发
+
+```sh
+npm ci
+npm run typecheck
+npm test                      # server/ 下的 node:test 测试
+
+# 连接本机 Paseo，对当前目录对应的 workspace 跑一次真实命名，不修改名称
+npm run test:smoke -- <provider>/<model>
+
+paseo plugin install .        # 从本地目录安装
+paseo plugin reload tab-namer # 修改后重新加载
+```
+
+Paseo 从 Git 安装插件时直接用 esbuild 打包源码，**不执行 `npm install`**。运行时代码只能导入 Paseo 自带的 `@getpaseo/plugin`、`react`、`react-native`、`zod` 和 Node 内置模块；`devDependencies` 只用于类型检查、测试和脚本。
+
+```
+index.client.tsx   界面入口：顶部按钮、页面、命令中心
+index.server.ts    RPC 处理与后台任务
+client/            重命名弹窗/页面、设置页、通用组件
+server/            Tab 读取、预算、模型会话、命名逻辑（含测试）
+shared/            RPC 契约与设置 schema
+docs/media-src/    README 插图的 HTML 源（node docs/media-src/render.mjs）
+```
+
+## 参与贡献
+
+欢迎提交 Issue 和 Pull Request。提交 PR 前请运行 `npm run typecheck` 和 `npm test`；涉及命名质量的改动，请附上 `npm run test:smoke` 的前后对比。
+
+## 许可证
+
+[MIT](LICENSE) © Stephen Zhou