@alexlikevibe/pi-jev 0.2.0

package/README.zh-CN.md

@@ -0,0 +1,340 @@
+<div align="center">
+
+# pi-jev
+
+**由 [Jev](https://typesafe.ai) 驱动，为 [pi](https://github.com/earendil-works/pi-coding-agent) 提供选择性上下文压缩和逐轮模型路由。**
+
+[English](README.md) · **简体中文**
+
+<img src="media/banner.svg" alt="Pi 事件触发 Jev 类型化请求：保留评分决定上下文取舍，难度评分决定使用哪个模型" width="100%">
+
+[![checks](https://img.shields.io/github/actions/workflow/status/iefnaf/pi-jev/test.yml?branch=main&style=for-the-badge&label=checks)](https://github.com/iefnaf/pi-jev/actions/workflows/test.yml)
+[![pi extension](https://img.shields.io/badge/pi-extension-8b5cf6?style=for-the-badge)](https://github.com/earendil-works/pi-coding-agent)
+[![Jev](https://img.shields.io/badge/Jev-TypeSafe%20%7C%20OpenRouter-0ea5e9?style=for-the-badge)](https://typesafe.ai)
+[![license](https://img.shields.io/badge/license-MIT-f4c430?style=for-the-badge)](LICENSE)
+
+</div>
+
+pi-jev 使用 Jev 的类型化判断，识别仍有价值的工具输出，并评估用户请求的难度。压缩时保留有用的原文，而不是生成新的摘要；每轮开始前，还可以根据难度切换模型。两项功能均可选：Jev 不可用时，pi 会使用原生压缩或继续使用当前模型。
+
+| 扩展 | 功能 | Pi 接入点 |
+| --- | --- | --- |
+| **上下文压缩** | 移除过时的工具调用，缩短不再需要的结果，其余文本保留原文 | `session_before_compact` |
+| **模型路由** | 简单请求交给低成本模型，复杂请求交给能力更强的模型 | `before_agent_start` |
+| **`/jev` 设置** | 通过交互菜单配置服务提供方、压缩和路由 | `/jev` 命令 |
+
+每个扩展都可通过 `pi config` 独立启停。配置会在下次钩子触发时读取，无需重启 pi。
+
+## 快速开始
+
+需要已安装 pi，并拥有 **TypeSafe 或 OpenRouter 中任意一个** Jev 接入服务的 API Key。路由目标模型还需要在 pi 中完成配置和认证。
+
+### 1. 配置 Jev API Key
+
+在启动 pi 的终端中，选择一种方式：
+
+```sh
+# 方式 A：TypeSafe
+export TYPESAFE_API_KEY="your-typesafe-api-key"
+```
+
+```sh
+# 方式 B：OpenRouter
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+```
+
+未显式配置服务提供方时，项目会根据 API Key 自动选择。如果两个 Key 都存在，优先使用 TypeSafe；设置 `JEVC_PROVIDER=openrouter` 可显式选择 OpenRouter。
+
+### 2. 安装并启动
+
+```sh
+pi install npm:@alexlikevibe/pi-jev
+pi config   # 检查已启用的 pi-jev 扩展
+pi
+```
+
+如果在 pi 会话运行期间安装，使用 `/reload` 加载扩展。
+
+### 3. 在 pi 中配置
+
+```text
+/jev
+```
+
+进入 **Routing**，从 pi 的模型列表选择 `cheap` 和／或 `strong` 目标，还可选择思考等级。**至少设置一个目标后，模型路由才会启用。** 上下文压缩不需要配置路由目标；可以通过 `/compact` 手动触发，也会随 pi 的自动压缩运行。
+
+| 操作 | 命令或方式 |
+| --- | --- |
+| 打开设置 | `/jev` |
+| 压缩当前会话 | `/compact` |
+| 查看可用设置项 | `/jev keys` |
+| 查看路由目标 | `/jev get routing.cheap` |
+| 移除路由目标 | `/jev unset routing.strong` |
+| 暂时跳过两项功能 | `/jev set disabled true` |
+| 重新启用两项功能 | `/jev set disabled false` |
+| 写入项目配置 | 添加 `-l`，例如 `/jev set provider openrouter -l` |
+
+配置**默认写入全局文件**，`disabled` 也不例外；使用 `-l` 可限定到项目。若只想对一次 pi 进程跳过两项功能，使用 `JEVC_DISABLED=1 pi` 启动。
+
+<details>
+<summary>从 GitHub、本地源码安装，或单独加载一个扩展</summary>
+
+直接从 GitHub 安装：
+
+```sh
+pi install https://github.com/iefnaf/pi-jev
+```
+
+从本地源码安装：
+
+```sh
+git clone https://github.com/iefnaf/pi-jev.git
+cd pi-jev
+npm ci
+npm run build
+pi install /absolute/path/to/pi-jev
+```
+
+在仓库根目录进行开发时，可使用：
+
+```sh
+pi -e ./extensions/compaction.ts
+pi -e ./extensions/routing.ts
+pi -e ./extensions/jev.ts
+```
+
+每条命令显式加载一个扩展。信任此仓库后，项目的 `.pi/extensions/jev-*` 加载器也会被自动发现。
+
+</details>
+
+## 上下文压缩
+
+pi-jev 不让摘要模型改写整个对话，而是针对每个可评估的工具调用，向 Jev 提出类型化问题：是否保留调用、是否保留完整结果（`noul`），以及结果有多过时（`score`）。随后将保留内容渲染为对话记录。
+
+- **保留：** 保留用户和助手文本、受保护的近期消息，以及有用的工具调用和结果。上一轮压缩摘要原样嵌入。
+- **移除：** 过时的工具调用及其结果一起删除，记录头部会说明移除数量。
+- **缩短：** 保留工具调用，将较长的结果缩短至前 `truncateHeadChars` 个字符，并添加明确的截断标记。较短的结果可能保持不变。
+- **补救：** 如果结果的保留概率接近阈值，且过时程度判断以足够置信度表明它仍有用，则完整保留。
+- **回退：** Jev 出错、请求中止、待压缩片段为空，或估算缩减比例低于 `minReduction` 时，交给 pi 生成原生摘要。单个调用的回答缺失或格式异常时，保守地保留该调用。
+
+请求会根据上下文和请求预算分批，因此一次压缩可能发出多个 Jev 请求。近期消息保护作用于 pi 提供的待压缩片段中经过转换的消息。
+
+**“保留原文”针对保留的文本，并非原始消息的所有字段：** 转换时图片替换为 `[image]` 占位符，助手的思考块会被省略；工具输入会序列化到记录中。
+
+### 结果示例
+
+本项目记录的一次示例运行，将转换后的片段从 **32 条消息／39,379 个字符** 缩减至 **16 条消息／9,553 个字符**，耗时 **757 ms**，使用一次 Jev 请求和 652 个输出 token。这只是示例，并非延迟或压缩比例保证。
+
+成功的压缩会将审计数据写入会话的 `compaction` 条目：
+
+```json
+{
+  "engine": "jev",
+  "stats": {
+    "messagesBefore": 32,
+    "messagesAfter": 16,
+    "charsBefore": 39379,
+    "charsAfter": 9553,
+    "calls": 15,
+    "pinned": 3,
+    "callsDropped": 12,
+    "ms": 757,
+    "requests": 1,
+    "jevUsage": { "input": 9784, "output": 652 }
+  }
+}
+```
+
+以上是条目中 `details` 对象的精简示例。查看 `details.engine`、`details.stats` 和 `details.decisions` 可了解完整结果。钩子保留 `firstKeptEntryId`，供 pi 正确保留会话的剩余部分。
+
+## 模型路由
+
+每轮开始前，Jev 根据**当前用户提示**，按三个等级评估难度：
+
+| 等级 | 典型请求 |
+| --- | --- |
+| `0` — 简单 | 问候、简短问题、格式调整、机械性的单文件修改 |
+| `1` — 中等 | 日常编码任务 |
+| `2` — 复杂 | 多文件重构、隐蔽问题调试、架构决策 |
+
+使用默认阈值时：
+
+| 条件 | 动作 |
+| --- | --- |
+| 难度 ≤ `0.5`、置信度 ≥ `0.6`，且设置了 `routing.cheap` | 切换到低成本模型 |
+| 难度 ≥ `1.5`、置信度 ≥ `0.6`，且设置了 `routing.strong` | 切换到强模型 |
+| 中间难度、低置信度、回答缺失，或对应目标未设置 | 保持当前模型 |
+
+**中间难度的请求会沿用当前模型，包括上一轮路由选择的模型。** 它不会自动切回初始默认模型。路由评估使用当前提示，而非完整对话历史。
+
+模型引用格式错误、模型不存在、服务提供方未认证，或 Jev 请求失败时，保持当前模型。提示包含图片时，会跳过仅支持文本的 `cheap` 目标。目标与当前模型相同时不执行切换。成功切换和路由错误通过 pi 界面通知显示。
+
+模型引用格式为 `provider/model-id`，可附加 `:thinking` 后缀，例如 `:high` 或 `:max`。建议通过 `/jev` 选择 pi 中实际配置的模型；思考等级在发生模型切换时应用。
+
+## 配置
+
+配置按以下顺序解析，优先级从高到低：
+
+1. 环境变量
+2. 项目配置：`.pi/jev.json`
+3. 全局配置：`~/.pi/agent/jev.json`
+4. 内置默认值
+
+API Key **仅通过环境变量设置**，不会写入配置文件。钩子在每次事件中重新读取配置，改动对下一轮或下一次压缩生效。环境变量仍会覆盖通过 `/jev` 修改的文件配置。
+
+### 交互菜单与命令
+
+在交互模式的 pi 中，直接输入 `/jev` 打开设置菜单：
+
+```text
+pi-jev
+├─ Toggle scope (global ⇄ project)  切换写入范围
+├─ General        provider · model · baseUrl · disabled
+├─ Compaction     压缩阈值和 token 预算
+├─ Routing        cheap · strong → 模型 → 思考等级
+└─ Show resolved config            查看最终生效配置
+```
+
+文本命令支持动作、配置键和模型引用的补全：
+
+```text
+/jev set provider openrouter -l
+/jev get routing.cheap
+/jev unset routing.strong
+/jev keys
+/jev path -l
+```
+
+### 配置文件示例
+
+项目的 `.pi/jev.json` 可以设置接入服务和压缩策略：
+
+```json
+{
+  "provider": "openrouter",
+  "disabled": false,
+  "compaction": {
+    "keepThreshold": 0.5,
+    "preserveRecentMessages": 3,
+    "minReduction": 0.15
+  }
+}
+```
+
+通过 `/jev` → **Routing** 添加路由目标，或将 `routing.cheap`／`routing.strong` 设置为已配置的模型引用。设置任意一个目标即可独立启用路由。
+
+### 终端 CLI
+
+从已构建的本地仓库中，CLI 可管理同一组配置文件：
+
+```sh
+node bin/pi-jev.js config
+node bin/pi-jev.js config set provider openrouter -l
+node bin/pi-jev.js config get routing.cheap
+node bin/pi-jev.js config unset routing.strong
+node bin/pi-jev.js config keys
+node bin/pi-jev.js config path -l
+```
+
+如果包的可执行文件已加入 `PATH`，可改用 `pi-jev config …`。`get` 读取最终生效值；`set`、`unset` 和 `path` 默认使用全局范围，添加 `-l`／`--project` 则使用项目范围。
+
+### Jev 接入服务
+
+以下是本项目代码中的默认值：
+
+| 设置 | TypeSafe | OpenRouter |
+| --- | --- | --- |
+| 服务提供方 | `typesafe` | `openrouter` |
+| 接口地址 | `https://api.typesafe.ai/v1/systemone` | `https://openrouter.ai/api/alpha/decisions`（alpha） |
+| API Key | `TYPESAFE_API_KEY` | `OPENROUTER_API_KEY` |
+| Jev 模型 | `jev-latest` | `typesafe/jev-1.13` |
+
+两者使用相同的 `{ model, state, questions }` → `{ answers }` 协议。Jev 判断模型与作为路由目标的 pi 模型是分别配置的。
+
+`JEVC_API_KEY` 会覆盖所选服务的专用 Key，但本身不会选择服务提供方；使用 OpenRouter Key 时，应同时设置 `JEVC_PROVIDER=openrouter`。
+
+### 环境变量
+
+通用设置：
+
+| 变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | 未设置 | TypeSafe 认证 |
+| `OPENROUTER_API_KEY` | 未设置 | OpenRouter 认证 |
+| `JEVC_API_KEY` | 未设置 | 覆盖所选服务的 API Key |
+| `JEVC_PROVIDER` | 自动检测 | `typesafe` 或 `openrouter` |
+| `JEVC_MODEL` | 随接入服务选择 | Jev 模型标识 |
+| `JEVC_BASE_URL` | 随接入服务选择 | Jev 接口地址 |
+| `JEVC_DISABLED` | `false` | `1`、`true` 或 `yes` 跳过两项功能的钩子 |
+
+上下文压缩：
+
+| 变量 | 配置键 | 默认值 |
+| --- | --- | --- |
+| `JEVC_KEEP_THRESHOLD` | `compaction.keepThreshold` | `0.5` |
+| `JEVC_BORDERLINE` | `compaction.borderline` | `0.1` |
+| `JEVC_PRESERVE_RECENT` | `compaction.preserveRecentMessages` | `3` |
+| `JEVC_TRUNCATE_HEAD` | `compaction.truncateHeadChars` | `300` |
+| `JEVC_MIN_REDUCTION` | `compaction.minReduction` | `0.15` |
+| `JEVC_MAX_STATE_TOKENS` | `compaction.maxStateTokens` | `25000` |
+| `JEVC_MAX_REQUEST_TOKENS` | `compaction.maxRequestTokens` | `30000` |
+
+`keepThreshold` 控制原文保留阈值，`borderline` 定义阈值下方可由过时程度判断补救的区间。`preserveRecentMessages` 保护近期转换后的消息；`truncateHeadChars` 限制截断结果保留的头部字符数。`minReduction` 是替代 pi 原生摘要所需的最低估算缩减比例。两个 token 上限分别约束 Jev 上下文，以及上下文加问题的单次请求。
+
+模型路由：
+
+| 变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `JEVC_ROUTE_CHEAP` | 未设置 | 简单请求的目标模型引用 |
+| `JEVC_ROUTE_STRONG` | 未设置 | 复杂请求的目标模型引用 |
+| `JEVC_ROUTE_EASY_MAX` | `0.5` | 使用低成本模型的最高难度 |
+| `JEVC_ROUTE_HARD_MIN` | `1.5` | 使用强模型的最低难度 |
+| `JEVC_ROUTE_MIN_CONFIDENCE` | `0.6` | 切换模型所需的最低置信度 |
+
+路由阈值属于配置加载器支持的高级覆盖项，不在设置菜单或 CLI 配置键列表中展示。
+
+## 常见问题
+
+| 现象 | 检查方式 |
+| --- | --- |
+| `/jev` 不可用 | 通过 `pi config` 启用 `extensions/jev.ts`，必要时执行 `/reload` |
+| 压缩仍使用 pi 原生摘要 | 检查所选服务的 API Key、`disabled`、Jev 错误和 `minReduction` |
+| 路由始终不切换模型 | 至少设置一个目标，确认 pi 模型已认证，并检查难度与置信度条件 |
+| 修改配置后没有生效 | 检查环境变量和项目配置，它们的优先级高于全局配置 |
+| 本地 CLI 找不到 `dist/cli/main.js` | 执行 `npm run build` |
+
+## 开发
+
+CI 使用 Node.js 22。在仓库根目录运行：
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+```
+
+测试使用固定样例和模拟的 `JevAsker`，不会调用 Jev API。覆盖压缩决策和消息转换、路由、配置优先级、CLI、参数补全、模型选择及菜单界面。
+
+| 路径 | 职责 |
+| --- | --- |
+| [src/compaction](src/compaction) | 消息转换、Jev 请求分批、保留规则、记录渲染和压缩钩子 |
+| [src/routing](src/routing) | 难度决策与模型切换 |
+| [src/commands](src/commands) | `/jev`、设置菜单、参数补全和模型选择 |
+| [src/cli](src/cli) | 共用配置命令引擎 |
+| [src/shared/config.ts](src/shared/config.ts) | 配置分层、默认值和配置键元数据 |
+| [extensions](extensions) | 扩展入口 |
+| [src/vendor/fast-jev-compaction](src/vendor/fast-jev-compaction) | 内置的第三方 Jev 客户端和压缩基础模块 |
+| [test](test) | 离线测试套件 |
+
+新增功能时，在 `src/<feature>/` 创建默认导出的扩展工厂及纯函数辅助模块，在 `extensions/` 添加薄入口，在 `src/shared/config.ts` 定义配置，并在 `test/` 覆盖行为。Jev 请求失败时必须允许 pi 继续运行。
+
+## 致谢
+
+- [tamaratran/fast-jev-compaction](https://github.com/tamaratran/fast-jev-compaction)：以 MIT 许可内置的 Jev 客户端和压缩基础模块，许可证随源码保留。
+- [@narumitw/pi-tui-kit](https://www.npmjs.com/package/@narumitw/pi-tui-kit)：提供 `/jev` 交互设置菜单。
+- [TypeSafe](https://typesafe.ai)：提供 Jev System One；OpenRouter 提供另一种 Decisions API 接入方式。
+
+## 许可证
+
+[MIT](LICENSE)。

package/bin/pi-jev.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from '../dist/cli/main.js';
+
+const code = runCli(process.argv.slice(2), {
+  env: process.env,
+  globalPath: join(homedir(), '.pi', 'agent', 'jev.json'),
+  projectPath: join(process.cwd(), '.pi', 'jev.json'),
+  out: (text) => process.stdout.write(text + '\n'),
+  err: (text) => process.stderr.write(text + '\n'),
+});
+process.exit(code);

package/dist/cli/main.js

@@ -0,0 +1,223 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CONFIG_KEYS, configFromEnv, loadConfig, mergeConfigFiles, readConfigFile, } from '../shared/config.js';
+const USAGE = `pi-jev — configuration CLI for the pi-jev extension suite
+
+Usage:
+  pi-jev config                          Show resolved config and each value's source
+  pi-jev config set <key> <value>        Write a key (global by default)
+  pi-jev config get <key>                Print the resolved value of a key
+  pi-jev config unset <key>              Remove a key
+  pi-jev config path                     Print the config file path
+  pi-jev config keys                     List all keys with types and env overrides
+
+Options:
+  -l, --project    Target the project file (.pi/jev.json) instead of the global one
+
+Sources resolve highest-first: environment variables > project file > global file > defaults.
+API keys are environment-only and never stored in files.
+Changes take effect after pi restarts or /reload.`;
+export function keyMeta(path) {
+    return CONFIG_KEYS.find((key) => key.path === path);
+}
+export function getPath(file, path) {
+    const [section, key] = path.split('.');
+    if (!key)
+        return file[section];
+    return file[section]?.[key];
+}
+export function setPath(file, path, value) {
+    const [section, key] = path.split('.');
+    if (!key) {
+        file[section] = value;
+        return;
+    }
+    const holder = (file[section] ??= {});
+    holder[key] = value;
+}
+function deletePath(file, path) {
+    const [section, key] = path.split('.');
+    if (!key)
+        return delete file[section];
+    const holder = file[section];
+    if (!holder || !(key in holder))
+        return false;
+    delete holder[key];
+    if (Object.keys(holder).length === 0)
+        delete file[section];
+    return true;
+}
+export function coerce(meta, raw) {
+    if (meta.type === 'number') {
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new Error(`${meta.path}: expected a number, got "${raw}"`);
+        return value;
+    }
+    if (meta.type === 'boolean') {
+        if (/^(1|true|yes)$/i.test(raw))
+            return true;
+        if (/^(0|false|no)$/i.test(raw))
+            return false;
+        throw new Error(`${meta.path}: expected a boolean, got "${raw}"`);
+    }
+    const value = raw.trim();
+    if (!value)
+        throw new Error(`${meta.path}: expected a non-empty value`);
+    if (meta.path === 'provider' && value !== 'typesafe' && value !== 'openrouter') {
+        throw new Error(`provider: expected "typesafe" or "openrouter", got "${value}"`);
+    }
+    return value;
+}
+export function readOrInit(path) {
+    try {
+        return readConfigFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw new Error(`cannot read ${path}: ${error.message}`);
+    }
+}
+export function saveFile(path, file) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(file, null, 2) + '\n');
+}
+function takeProjectFlag(rest) {
+    const positional = rest.filter((arg) => arg !== '-l' && arg !== '--project');
+    return { project: positional.length !== rest.length, positional };
+}
+function tryReadFile(path, io) {
+    try {
+        return readConfigFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        io.err(`pi-jev: ignoring config at ${path} (${error.message})`);
+        return undefined;
+    }
+}
+export function valueAt(config, path) {
+    const record = config;
+    // `compaction.*` keys are flat fields on JevConfig; `routing.*` is nested.
+    if (path.startsWith('compaction.'))
+        return record[path.slice('compaction.'.length)];
+    const [section, key] = path.split('.');
+    if (!key)
+        return record[section];
+    return record[section]?.[key];
+}
+export function formatValue(value) {
+    if (value === undefined)
+        return 'unset';
+    return String(value);
+}
+function show(io) {
+    const global = tryReadFile(io.globalPath, io);
+    const project = tryReadFile(io.projectPath, io);
+    const config = configFromEnv(io.env, mergeConfigFiles(global, project));
+    const width = Math.max(...CONFIG_KEYS.map((key) => key.path.length));
+    for (const meta of CONFIG_KEYS) {
+        const source = io.env[meta.env ?? '']?.trim()
+            ? 'env'
+            : getPath(project ?? {}, meta.path) !== undefined
+                ? 'project'
+                : getPath(global ?? {}, meta.path) !== undefined
+                    ? 'global'
+                    : 'default';
+        io.out(`${meta.path.padEnd(width)} = ${formatValue(valueAt(config, meta.path)).padEnd(28)} # ${source}`);
+    }
+    io.out(`${'apiKey'.padEnd(width)} = ${config.apiKey ? 'set' : 'unset'}${''.padEnd(23)} # env only`);
+    if (!config.routing.cheap && !config.routing.strong) {
+        io.err('# routing is disabled: set routing.cheap (or routing.strong) to enable it');
+    }
+    return 0;
+}
+/** Runs the CLI against injectable IO. Returns the process exit code. */
+export function runCli(argv, io) {
+    const [cmd, sub, ...rest] = argv;
+    if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        io.out(USAGE);
+        return 0;
+    }
+    if (cmd !== 'config') {
+        io.err(`unknown command "${cmd}"`);
+        io.err(USAGE);
+        return 1;
+    }
+    try {
+        if (sub === undefined)
+            return show(io);
+        // Actions: `pi-jev config set|get|unset <key> [value] [-l]`
+        if (sub === 'set') {
+            const { project, positional } = takeProjectFlag(rest);
+            const [keyPath, ...valueParts] = positional;
+            const meta = keyMeta(keyPath ?? '');
+            if (!meta) {
+                io.err(`unknown key "${keyPath}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+                return 1;
+            }
+            const raw = valueParts.join(' ');
+            if (!raw.trim()) {
+                io.err(`usage: pi-jev config set ${meta.path} <value>`);
+                return 1;
+            }
+            const value = coerce(meta, raw);
+            const targetPath = project ? io.projectPath : io.globalPath;
+            const file = readOrInit(targetPath);
+            setPath(file, meta.path, value);
+            saveFile(targetPath, file);
+            io.out(`set ${meta.path} = ${String(value)} (${project ? 'project' : 'global'}: ${targetPath})`);
+            return 0;
+        }
+        if (sub === 'get' || sub === 'unset') {
+            const { project, positional } = takeProjectFlag(rest);
+            const meta = keyMeta(positional[0] ?? '');
+            if (!meta) {
+                io.err(`unknown key "${positional[0]}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+                return 1;
+            }
+            const targetPath = project ? io.projectPath : io.globalPath;
+            if (sub === 'get') {
+                const config = loadConfig({ env: io.env, globalPath: io.globalPath, projectPath: io.projectPath, warn: io.err });
+                io.out(formatValue(valueAt(config, meta.path)));
+                return 0;
+            }
+            const file = readOrInit(targetPath);
+            if (deletePath(file, meta.path)) {
+                saveFile(targetPath, file);
+                io.out(`unset ${meta.path} (${project ? 'project' : 'global'}: ${targetPath})`);
+            }
+            else {
+                io.out(`${meta.path} is not set (${project ? 'project' : 'global'})`);
+            }
+            return 0;
+        }
+        if (sub === 'path') {
+            const { project } = takeProjectFlag(rest);
+            io.out(project ? io.projectPath : io.globalPath);
+            return 0;
+        }
+        if (sub === 'keys') {
+            const width = Math.max(...CONFIG_KEYS.map((key) => key.path.length));
+            for (const meta of CONFIG_KEYS) {
+                io.out(`${meta.path.padEnd(width)}  ${meta.type.padEnd(7)} ${meta.env ? `env: ${meta.env.padEnd(26)} ` : ''}${meta.description}`);
+            }
+            return 0;
+        }
+        // Shorthand: `pi-jev config <key>` = get
+        const meta = keyMeta(sub);
+        if (!meta) {
+            io.err(`unknown key "${sub}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+            return 1;
+        }
+        const config = loadConfig({ env: io.env, globalPath: io.globalPath, projectPath: io.projectPath, warn: io.err });
+        io.out(formatValue(valueAt(config, meta.path)));
+        return 0;
+    }
+    catch (error) {
+        io.err(`pi-jev: ${error.message}`);
+        return 1;
+    }
+}

package/dist/commands/completions.js

@@ -0,0 +1,87 @@
+import { CONFIG_KEYS } from '../shared/config.js';
+const ACTIONS = [
+    { value: 'set', label: 'set', description: 'write a key (add -l for the project file)' },
+    { value: 'get', label: 'get', description: 'print the resolved value of a key' },
+    { value: 'unset', label: 'unset', description: 'remove a key' },
+    { value: 'keys', label: 'keys', description: 'list all keys with types and env overrides' },
+    { value: 'path', label: 'path', description: 'print the config file path' },
+];
+const FLAG_RE = /^(-l|--project)$/;
+function filterItems(items, prefix) {
+    const normalized = prefix.trim().toLowerCase();
+    const matches = items.filter((item) => item.value.toLowerCase().startsWith(normalized));
+    return matches.length > 0 ? matches : null;
+}
+function keyItems(action) {
+    return CONFIG_KEYS.map((meta) => ({
+        value: `${action} ${meta.path}`,
+        label: meta.path,
+        description: meta.description,
+    }));
+}
+/** Enum-valued keys offer their options; free-form keys get no value completion. */
+export const VALUE_OPTIONS = {
+    provider: [
+        { label: 'openrouter', description: 'OpenRouter Decisions API' },
+        { label: 'typesafe', description: 'TypeSafe System One' },
+    ],
+    disabled: [
+        { label: 'true', description: 'bypass all pi-jev hooks' },
+        { label: 'false', description: 'enable pi-jev hooks' },
+    ],
+};
+/**
+ * Completes the argument text after `/jev `. Flags are position-neutral; the
+ * last non-flag token in progress decides what is offered.
+ */
+/** Model refs for cheap/strong value completion; empty when no snapshot is available. */
+const modelOptions = [];
+/** Refreshes the model snapshot (called on session_start). */
+export function setModelOptions(options) {
+    modelOptions.length = 0;
+    modelOptions.push(...options);
+}
+export function completeJevArguments(argText) {
+    const endsWithSpace = /\s$/.test(argText);
+    const tokens = argText.trim().split(/\s+/).filter(Boolean);
+    const prior = (endsWithSpace ? tokens : tokens.slice(0, -1)).filter((token) => !FLAG_RE.test(token));
+    const partial = endsWithSpace || tokens.length === 0 ? '' : tokens[tokens.length - 1];
+    // Completing the action itself.
+    if (prior.length === 0 && !endsWithSpace) {
+        return filterItems(ACTIONS, partial);
+    }
+    if (prior.length === 0)
+        return ACTIONS; // space typed, nothing yet: offer the menu
+    const action = prior[0];
+    const flags = argText.trim().split(/\s+/).some((token) => FLAG_RE.test(token));
+    const suffix = flags ? ' -l' : '';
+    if (action === 'set' || action === 'get' || action === 'unset') {
+        if (prior.length === 1) {
+            const items = keyItems(action + suffix);
+            return filterItems(items, `${action}${suffix} ${partial}`.trim());
+        }
+        if (action === 'set' && prior.length === 2) {
+            const key = prior[1];
+            if (key === 'routing.cheap' || key === 'routing.strong') {
+                if (modelOptions.length === 0)
+                    return null;
+                const items = modelOptions.map((model) => ({
+                    value: `set ${key} ${model.ref}${suffix}`,
+                    label: model.name,
+                    description: `${model.provider}${model.image ? ' · images' : ''}${model.reasoning ? ' · thinking' : ''}`,
+                }));
+                return filterItems(items, `set ${key}${suffix} ${partial}`.trim());
+            }
+            const options = VALUE_OPTIONS[key] ?? [];
+            if (options.length === 0)
+                return null;
+            const items = options.map((option) => ({
+                value: `set ${key} ${option.label}${suffix}`,
+                label: option.label,
+                description: option.description,
+            }));
+            return filterItems(items, `set ${key}${suffix} ${partial}`.trim());
+        }
+    }
+    return null;
+}