@protolabsai/proto 0.14.0 → 0.16.0

package/README.md

@@ -23,16 +23,16 @@ proto is a fork of [Qwen Code](https://github.com/QwenLM/qwen-code) (itself fork
 Requires Node.js 20+ and Rust toolchain (for beads_rust).
 
 ```bash
-# Clone and build
+# Install from npm (recommended)
+npm install -g @protolabsai/proto
+proto --version
+
+# Or install from source
 git clone https://github.com/protoLabsAI/protoCLI.git
 cd protoCLI
-npm install
-npm run build
-
-# Link globally
-npm link
+npm install && npm run build && npm link
 
-# Install beads_rust task manager (optional but recommended)
+# Optional: task manager for persistent task tracking
 cargo install beads_rust
 ```
 
@@ -159,6 +159,56 @@ Tools are exposed as `mcp__<server_name>__<tool_name>` and available to the agen
 
 proto auto-discovers Claude Code plugins installed at `~/.claude/plugins/`. Any plugin's `commands/` directory is automatically loaded as slash commands — no additional config needed.
 
+## Observability
+
+proto supports [Langfuse](https://langfuse.com) tracing out of the box. Set three environment variables and every session is fully traced — LLM calls (all providers), tool executions, subagent lifecycles, and turn hierarchy.
+
+### Setup
+
+Add to the `env` block in `~/.proto/settings.json`:
+
+```json
+{
+  "env": {
+    "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
+    "LANGFUSE_SECRET_KEY": "sk-lf-...",
+    "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
+  }
+}
+```
+
+`LANGFUSE_BASE_URL` is optional and defaults to `https://cloud.langfuse.com`. For a self-hosted instance, set it to your deployment URL.
+
+> **Why `settings.json` and not `.env`?** proto walks up from your CWD loading `.env` files, so a project-level `.env` with Langfuse keys would bleed into proto's tracing and mix your traces into the wrong dataset. The `env` block in `settings.json` is proto-namespaced and completely isolated from your projects.
+
+### What gets traced
+
+| Span                  | Attributes                                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `turn`                | `session.id`, `turn.id` — root span per user prompt                                                  |
+| `gen_ai chat {model}` | `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.request.model` — one per LLM call |
+| `tool/{name}`         | `tool.name`, `tool.type`, `tool.duration_ms` — one per tool execution                                |
+| `agent/{name}`        | `agent.name`, `agent.status`, `agent.duration_ms` — one per subagent                                 |
+
+All three provider backends are covered: OpenAI-compatible, Anthropic, and Gemini.
+
+### Prompt content logging
+
+Full prompt messages and response text are included in traces by default. To disable:
+
+```json
+// ~/.proto/settings.json
+{
+  "telemetry": { "logPrompts": false }
+}
+```
+
+> **Privacy note:** `logPrompts` is enabled by default. When enabled, full prompt and response content is sent to your Langfuse instance. Set to `false` if you want traces without message content.
+
+### Langfuse activates independently
+
+Langfuse tracing activates from env vars alone — it does not require `telemetry.enabled: true` in settings. The general telemetry pipeline (OTLP/GCP) and Langfuse are independent.
+
 ## Task Management
 
 proto integrates [beads_rust](https://github.com/Dicklesworthstone/beads_rust) for persistent, SQLite-backed task tracking. When `br` is on PATH, the 6 task tools (`task_create`, `task_get`, `task_list`, `task_update`, `task_stop`, `task_output`) use it as the backend. Tasks persist across sessions in `.beads/` within the project directory.
@@ -261,9 +311,41 @@ Use `/skills` to list available skills in a session.
 | `Ctrl+D`  | Exit (on empty line)     |
 | `Up/Down` | Navigate command history |
 
-## IDE Integration
+## Voice Integration
+
+proto supports push-to-talk voice input. Press the mic button in the footer or use `/voice` to toggle.
+
+### Requirements
+
+Voice capture requires a system audio backend:
+
+| OS    | Backend | Install                               |
+| ----- | ------- | ------------------------------------- |
+| macOS | sox     | `brew install sox`                    |
+| Linux | sox     | `apt install sox` / `dnf install sox` |
+| Linux | arecord | `apt install alsa-utils` (fallback)   |
+
+Verify detection: `/voice status`
+
+### STT backend
+
+Voice input transcribes audio via a Whisper-compatible `/v1/audio/transcriptions` endpoint. Self-host one (e.g. [faster-whisper-server](https://github.com/fedirz/faster-whisper-server)):
+
+```bash
+docker run --gpus all -p 8000:8000 fedirz/faster-whisper-server:latest-cuda
+```
+
+```json
+// ~/.proto/settings.json
+{
+  "voice": {
+    "enabled": true,
+    "sttEndpoint": "http://localhost:8000/v1/audio/transcriptions"
+  }
+}
+```
 
-proto works with VS Code, Zed, and JetBrains IDEs. See the upstream [Qwen Code docs](https://qwenlm.github.io/qwen-code-docs/en/users/overview) for setup instructions.
+The default endpoint is `http://localhost:8000/v1/audio/transcriptions` if none is configured.
 
 ## Architecture
 

package/{dist/bundled → bundled}/qc-helper/docs/configuration/settings.md

@@ -109,6 +109,9 @@ Settings are organized into categories. All settings should be placed within the
 | `ui.accessibility.enableLoadingPhrases` | boolean          | Enable loading phrases (disable for accessibility).                                                                                                                                                                                                                                                                                                                                                                 | `true`      |
 | `ui.accessibility.screenReader`         | boolean          | Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers.                                                                                                                                                                                                                                                                                                                     | `false`     |
 | `ui.customWittyPhrases`                 | array of strings | A list of custom phrases to display during loading states. When provided, the CLI will cycle through these phrases instead of the default ones.                                                                                                                                                                                                                                                                     | `[]`        |
+| `ui.enableFollowupSuggestions`          | boolean          | Enable [followup suggestions](../features/followup-suggestions) that predict what you want to type next after the model responds. Suggestions appear as ghost text and can be accepted with Tab, Enter, or Right Arrow.                                                                                                                                                                                             | `true`      |
+| `ui.enableCacheSharing`                 | boolean          | Use cache-aware forked queries for suggestion generation. Reduces cost on providers that support prefix caching (experimental).                                                                                                                                                                                                                                                                                     | `true`      |
+| `ui.enableSpeculation`                  | boolean          | Speculatively execute accepted suggestions before submission. Results appear instantly when you accept (experimental).                                                                                                                                                                                                                                                                                              | `false`     |
 
 #### ide
 
@@ -185,6 +188,12 @@ The `extra_body` field allows you to add custom parameters to the request body s
 - `"./custom-logs"` - Logs to `./custom-logs` relative to current directory
 - `"/tmp/openai-logs"` - Logs to absolute path `/tmp/openai-logs`
 
+#### fastModel
+
+| Setting     | Type   | Description                                                                                                                                                                                                                                           | Default |
+| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `fastModel` | string | Model for background tasks ([suggestion generation](../features/followup-suggestions), speculation). Leave empty to use the main model. A smaller/faster model (e.g., `qwen3.5-flash`) reduces latency and cost. Can also be set via `/model --fast`. | `""`    |
+
 #### context
 
 | Setting                                           | Type                       | Description                                                                                                                                                                                                                                                                                                                                                           | Default     |

package/{dist/bundled → bundled}/qc-helper/docs/extension/extension-releasing.md

@@ -1,11 +1,12 @@
 # Extension Releasing
 
-There are two primary ways of releasing extensions to users:
+There are three primary ways of releasing extensions to users:
 
 - [Git repository](#releasing-through-a-git-repository)
 - [Github Releases](#releasing-through-github-releases)
+- [npm Registry](#releasing-through-npm-registry)
 
-Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files.
+Git repository releases tend to be the simplest and most flexible approach, while GitHub releases can be more efficient on initial install as they are shipped as single archives instead of requiring a git clone which downloads each file individually. Github releases may also contain platform specific archives if you need to ship platform specific binary files. npm registry releases are ideal for teams that already use npm for package distribution, especially with private registries.
 
 ## Releasing through a git repository
 
@@ -119,3 +120,85 @@ jobs:
             release/linux.arm64.my-tool.tar.gz
             release/win32.arm64.my-tool.zip
 ```
+
+## Releasing through npm registry
+
+You can publish Qwen Code extensions as scoped npm packages (e.g. `@your-org/my-extension`). This is a good fit when:
+
+- Your team already uses npm for package distribution
+- You need private registry support with existing auth infrastructure
+- You want version resolution and access control handled by npm
+
+### Package requirements
+
+Your npm package must include a `qwen-extension.json` file at the package root. This is the same config file used by all Qwen Code extensions — the npm tarball is simply another delivery mechanism.
+
+A minimal package structure looks like:
+
+```
+my-extension/
+├── package.json
+├── qwen-extension.json
+├── QWEN.md              # optional context file
+├── commands/             # optional custom commands
+├── skills/               # optional custom skills
+└── agents/               # optional custom subagents
+```
+
+Make sure `qwen-extension.json` is included in your published package (i.e. not excluded by `.npmignore` or the `files` field in `package.json`).
+
+### Publishing
+
+Use standard npm publishing tools:
+
+```bash
+# Publish to the default registry
+npm publish
+
+# Publish to a private/custom registry
+npm publish --registry https://your-registry.com
+```
+
+### Installation
+
+Users install your extension using the scoped package name:
+
+```bash
+# Install latest version
+qwen extensions install @your-org/my-extension
+
+# Install a specific version
+qwen extensions install @your-org/my-extension@1.2.0
+
+# Install from a custom registry
+qwen extensions install @your-org/my-extension --registry https://your-registry.com
+```
+
+### Update behavior
+
+- Extensions installed without a version pin (e.g. `@scope/pkg`) track the `latest` dist-tag.
+- Extensions installed with a dist-tag (e.g. `@scope/pkg@beta`) track that specific tag.
+- Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date and will not prompt for updates.
+
+### Authentication for private registries
+
+Qwen Code reads npm auth credentials automatically:
+
+1. **`NPM_TOKEN` environment variable** — highest priority
+2. **`.npmrc` file** — supports both host-level and path-scoped `_authToken` entries (e.g. `//your-registry.com/:_authToken=TOKEN` or `//pkgs.dev.azure.com/org/_packaging/feed/npm/registry/:_authToken=TOKEN`)
+
+`.npmrc` files are read from the current directory and the user's home directory.
+
+### Managing release channels
+
+You can use npm dist-tags to manage release channels:
+
+```bash
+# Publish a beta release
+npm publish --tag beta
+
+# Users install beta channel
+qwen extensions install @your-org/my-extension@beta
+```
+
+This works similarly to git branch-based release channels but uses npm's native dist-tag mechanism.

package/{dist/bundled → bundled}/qc-helper/docs/extension/introduction.md

@@ -12,11 +12,11 @@ We offer a suite of extension management tools using both `qwen extensions` CLI
 
 You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
 
-| Command                               | Description                                                       |
-| ------------------------------------- | ----------------------------------------------------------------- |
-| `/extensions` or `/extensions manage` | Manage all installed extensions                                   |
-| `/extensions install <source>`        | Install an extension from a git URL, local path, or marketplace   |
-| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser |
+| Command                               | Description                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| `/extensions` or `/extensions manage` | Manage all installed extensions                                              |
+| `/extensions install <source>`        | Install an extension from a git URL, local path, npm package, or marketplace |
+| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser            |
 
 ### CLI Extension Management
 
@@ -89,6 +89,34 @@ Gemini extensions are automatically converted to Qwen Code format during install
 - TOML command files are automatically migrated to Markdown format
 - MCP servers, context files, and settings are preserved
 
+#### From npm Registry
+
+Qwen Code supports installing extensions from npm registries using scoped package names. This is ideal for teams with private registries that already have auth, versioning, and publishing infrastructure in place.
+
+```bash
+# Install the latest version
+qwen extensions install @scope/my-extension
+
+# Install a specific version
+qwen extensions install @scope/my-extension@1.2.0
+
+# Install from a custom registry
+qwen extensions install @scope/my-extension --registry https://your-registry.com
+```
+
+Only scoped packages (`@scope/package-name`) are supported to avoid ambiguity with the `owner/repo` GitHub shorthand format.
+
+**Registry resolution** follows this priority:
+
+1. `--registry` CLI flag (explicit override)
+2. Scoped registry from `.npmrc` (e.g. `@scope:registry=https://...`)
+3. Default registry from `.npmrc`
+4. Fallback: `https://registry.npmjs.org/`
+
+**Authentication** is handled automatically via the `NPM_TOKEN` environment variable or registry-specific `_authToken` entries in your `.npmrc` file.
+
+> **Note:** npm extensions must include a `qwen-extension.json` file at the package root, following the same format as any other Qwen Code extension. See [Extension Releasing](./extension-releasing.md#releasing-through-npm-registry) for packaging details.
+
 #### From Git Repository
 
 ```bash
@@ -127,7 +155,7 @@ This is useful if you have an extension disabled at the top-level and only enabl
 
 ### Updating an extension
 
-For extensions installed from a local path or a git repository, you can explicitly update to the latest version (as reflected in the `qwen-extension.json` `version` field) with `qwen extensions update extension-name`.
+For extensions installed from a local path, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
 
 You can update all extensions with:
 

package/{dist/bundled → bundled}/qc-helper/docs/features/_meta.ts

@@ -1,5 +1,6 @@
 export default {
   commands: 'Commands',
+  'followup-suggestions': 'Followup Suggestions',
   'sub-agents': 'SubAgents',
   arena: 'Agent Arena',
   skills: 'Skills',

package/{dist/bundled → bundled}/qc-helper/docs/features/commands.md

@@ -56,19 +56,20 @@ Commands specifically for controlling interface and output language.
 
 Commands for managing AI tools and models.
 
-| Command          | Description                                   | Usage Examples                                |
-| ---------------- | --------------------------------------------- | --------------------------------------------- |
-| `/mcp`           | List configured MCP servers and tools         | `/mcp`, `/mcp desc`                           |
-| `/tools`         | Display currently available tool list         | `/tools`, `/tools desc`                       |
-| `/skills`        | List and run available skills                 | `/skills`, `/skills <name>`                   |
-| `/approval-mode` | Change approval mode for tool usage           | `/approval-mode <mode (auto-edit)> --project` |
-| →`plan`          | Analysis only, no execution                   | Secure review                                 |
-| →`default`       | Require approval for edits                    | Daily use                                     |
-| →`auto-edit`     | Automatically approve edits                   | Trusted environment                           |
-| →`yolo`          | Automatically approve all                     | Quick prototyping                             |
-| `/model`         | Switch model used in current session          | `/model`                                      |
-| `/extensions`    | List all active extensions in current session | `/extensions`                                 |
-| `/memory`        | Manage AI's instruction context               | `/memory add Important Info`                  |
+| Command          | Description                                       | Usage Examples                                |
+| ---------------- | ------------------------------------------------- | --------------------------------------------- |
+| `/mcp`           | List configured MCP servers and tools             | `/mcp`, `/mcp desc`                           |
+| `/tools`         | Display currently available tool list             | `/tools`, `/tools desc`                       |
+| `/skills`        | List and run available skills                     | `/skills`, `/skills <name>`                   |
+| `/approval-mode` | Change approval mode for tool usage               | `/approval-mode <mode (auto-edit)> --project` |
+| →`plan`          | Analysis only, no execution                       | Secure review                                 |
+| →`default`       | Require approval for edits                        | Daily use                                     |
+| →`auto-edit`     | Automatically approve edits                       | Trusted environment                           |
+| →`yolo`          | Automatically approve all                         | Quick prototyping                             |
+| `/model`         | Switch model used in current session              | `/model`                                      |
+| `/model --fast`  | Set or select the fast model for background tasks | `/model --fast qwen3.5-flash`                 |
+| `/extensions`    | List all active extensions in current session     | `/extensions`                                 |
+| `/memory`        | Manage AI's instruction context                   | `/memory add Important Info`                  |
 
 ### 1.5 Information, Settings, and Help
 

package/bundled/qc-helper/docs/features/followup-suggestions.md

@@ -0,0 +1,109 @@
+# Followup Suggestions
+
+Qwen Code can predict what you want to type next and show it as ghost text in the input area. This feature uses an LLM call to analyze the conversation context and generate a natural next step suggestion.
+
+This feature works end-to-end in the CLI. In the WebUI, the hook and UI plumbing are available, but host applications must trigger suggestion generation and wire the followup state for suggestions to appear.
+
+## How It Works
+
+After Qwen Code finishes responding, a suggestion appears as dimmed text in the input area after a short delay (~300ms). For example, after fixing a bug, you might see:
+
+```
+> run the tests
+```
+
+The suggestion is generated by sending the conversation history to the model, which predicts what you would naturally type next.
+
+## Accepting Suggestions
+
+| Key           | Action                                           |
+| ------------- | ------------------------------------------------ |
+| `Tab`         | Accept the suggestion and fill it into the input |
+| `Enter`       | Accept the suggestion and submit it immediately  |
+| `Right Arrow` | Accept the suggestion and fill it into the input |
+| Any typing    | Dismiss the suggestion and type normally         |
+
+## When Suggestions Appear
+
+Suggestions are generated when all of the following conditions are met:
+
+- The model has completed its response (not during streaming)
+- At least 2 model turns have occurred in the conversation
+- There are no errors in the most recent response
+- No confirmation dialogs are pending (e.g., shell confirmation, permissions)
+- The approval mode is not set to `plan`
+- The feature is enabled in settings (enabled by default)
+
+Suggestions will not appear in non-interactive mode (e.g., headless/SDK mode).
+
+Suggestions are automatically dismissed when:
+
+- You start typing
+- A new model turn begins
+- The suggestion is accepted
+
+## Fast Model
+
+By default, suggestions use the same model as your main conversation. For faster and cheaper suggestions, configure a dedicated fast model:
+
+### Via command
+
+```
+/model --fast qwen3.5-flash
+```
+
+Or use `/model --fast` (without a model name) to open a selection dialog.
+
+### Via settings.json
+
+```json
+{
+  "fastModel": "qwen3.5-flash"
+}
+```
+
+The fast model is used for background tasks like suggestion generation. When not configured, the main conversation model is used as fallback.
+
+Thinking/reasoning mode is automatically disabled for all background tasks (suggestion generation and speculation), regardless of your main model's thinking configuration. This avoids wasting tokens on internal reasoning that isn't needed for these tasks.
+
+## Configuration
+
+These settings can be configured in `settings.json`:
+
+| Setting                        | Type    | Default | Description                                                        |
+| ------------------------------ | ------- | ------- | ------------------------------------------------------------------ |
+| `ui.enableFollowupSuggestions` | boolean | `true`  | Enable or disable followup suggestions                             |
+| `ui.enableCacheSharing`        | boolean | `true`  | Use cache-aware forked queries to reduce cost (experimental)       |
+| `ui.enableSpeculation`         | boolean | `false` | Speculatively execute suggestions before submission (experimental) |
+| `fastModel`                    | string  | `""`    | Model for background tasks (suggestion generation, speculation)    |
+
+### Example
+
+```json
+{
+  "fastModel": "qwen3.5-flash",
+  "ui": {
+    "enableFollowupSuggestions": true,
+    "enableCacheSharing": true
+  }
+}
+```
+
+## Monitoring
+
+Suggestion model usage appears in `/stats` output, showing tokens consumed by the fast model for suggestion generation.
+
+The fast model is also shown in `/about` output under "Fast Model".
+
+## Suggestion Quality
+
+Suggestions go through quality filters to ensure they are useful:
+
+- Must be 2-12 words (CJK: 2-30 characters), under 100 characters total
+- Cannot be evaluative ("looks good", "thanks")
+- Cannot use AI voice ("Let me...", "I'll...")
+- Cannot be multiple sentences or contain formatting (markdown, newlines)
+- Cannot be meta-commentary ("nothing to suggest", "silence")
+- Cannot be error messages or prefixed labels ("Suggestion: ...")
+- Single-word suggestions are only allowed for common commands (yes, commit, push, etc.)
+- Slash commands (e.g., `/commit`) are always allowed as single-word suggestions

package/{dist/bundled → bundled}/qc-helper/docs/features/hooks.md

@@ -4,6 +4,19 @@ Run custom scripts at key points in the proto lifecycle — before tool calls, a
 
 This page covers how to configure hooks, the available hook types and events, and the input/output contract for each event.
 
+Hooks are enabled by default. You can temporarily disable all hooks by setting `disableAllHooks` to `true` in your settings file (at the top level, alongside `hooks`):
+
+```json
+{
+  "disableAllHooks": true,
+  "hooks": {
+    "PreToolUse": [...]
+  }
+}
+```
+
+This disables all hooks without deleting their configurations.
+
 ## Configure a hook
 
 Hooks are defined in `.proto/settings.json` (project) or `~/.proto/settings.json` (global). Each hook attaches to an event name and optionally filters by a matcher pattern.

package/{dist/bundled → bundled}/qc-helper/docs/overview.md

@@ -56,6 +56,7 @@ You'll be prompted to log in on first use. That's it! [Continue with Quickstart
 - **Debug and fix issues**: Describe a bug or paste an error message. Qwen Code will analyze your codebase, identify the problem, and implement a fix.
 - **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Qwen Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](./features/mcp) can pull from external datasources like Google Drive, Figma, and Slack.
 - **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.
+- **[Followup suggestions](./features/followup-suggestions)**: Qwen Code predicts what you want to type next and shows it as ghost text. Press Tab to accept, or just keep typing to dismiss.
 
 ## Why developers love Qwen Code