@inf-monkeys-tech/monkeys-cli 0.10.0

package/README.md

@@ -0,0 +1,292 @@
+# Monkeys CLI
+
+`monkeys` 是面向 AI Agent、自动化脚本、CI 和人工终端的 Monkeys 命令行客户端。CLI 是唯一执行层；随包分发的官方中文 `monkeys` Skill 负责指导 Agent 选择命令、上下文与安全恢复策略。
+
+CLI 不内置模型、自然语言解释器、规划器或 Agent Runtime，也不依赖 Monkeys MCP Server。
+
+## 能力
+
+- 多 Deployment、Tenant、Team 与 Profile 快速切换，支持云端和私有化部署
+- API Key 与账户 Session 认证，支持环境变量、stdin、系统 Keyring、受保护的 POSIX Session 文件、私有 CA 和代理
+- OpenAPI 动态发现、缓存、精确 Operation 描述与原始 API 调用
+- Workflow 完整 CRUD、严格单包导入与运行、Execution 查询/等待/状态流、文件流式上传下载
+- Kernel Agent Work 查询、创建、编辑、分配、对话、Spec 审批、运行控制、验收与状态观察
+- Data 的 Ontology、View、Asset、媒体、Field、Feature Value、Tag/Tag Group 查询与受控写入
+- Kernel Bucket 初步治理，以及 Container Move/Copy/Remove/Trash Restore 可恢复生命周期
+- Kernel System Config 总览、Key 发现/读取、当前配置校验、审计历史、脱敏导出与受控窄更新
+- JSON/NDJSON 稳定输出、固定退出码、Secret 脱敏和语义到 API 的受控降级
+
+## 安装
+
+### npm
+
+要求 Node.js 22 或 24：
+
+```bash
+npx @inf-monkeys-tech/monkeys-cli@latest install
+monkeys version check --output json
+```
+
+安装向导会先全局安装 CLI，再通过 `skills` CLI 把 npm 制品内同版本的官方 `monkeys` Skill 安装到本机 Agent。若只需要 CLI，使用
+`npm install --global @inf-monkeys-tech/monkeys-cli`。
+
+### 独立包
+
+Windows、Linux 和 macOS 独立包内置 Node.js，不要求系统预装 Node.js。下载与系统匹配的制品，核对 `SHA256SUMS`，解压后运行：
+
+```bash
+monkeys version check --output json
+```
+
+独立包采用 oclif 官方 tarball 机制构建。发布构建固定携带 Node.js 24.18.0 LTS；npm 包同时在 Node.js 22/24 验证。
+
+## 快速开始
+
+先查看真实参数，不要凭记忆构造命令：
+
+```bash
+monkeys auth login --help
+```
+
+典型流程：
+
+```bash
+# 浏览器登录：URL 决定订阅 Endpoint，成功后自动用租户 tenantId 命名 Profile
+monkeys auth login --url https://customer.example.com --output json
+
+# API Key 登录：Key 只从 stdin 或指定环境变量读取
+monkeys auth login --url https://customer.example.com --api-key-stdin --output json
+
+# 明确 Profile 和 Team，获得稳定的 Execution ID
+monkeys workflow run workflow-id \
+  --profile customer-a \
+  --team team-id \
+  --input-json '{"prompt":"hello"}' \
+  --output json
+
+monkeys execution wait execution-id \
+  --profile customer-a \
+  --team team-id \
+  --timeout-seconds 600 \
+  --output json
+```
+
+Agent 应使用[官方 monkeys Skill](skills/monkeys/SKILL.md)。参数真相始终来自 `monkeys <命令> --help`。
+
+### Workflow CRUD
+
+Workflow 写命令只使用当前部署发布且新鲜的 OpenAPI 语义合同，不会降级到 Raw API。真实写入必须显式 `--yes`，建议先以同一输入运行 `--dry-run`：
+
+```bash
+monkeys workflow create --file workflow.json --profile customer-a --team team-id --dry-run --output json
+monkeys workflow import --file package.json --mode create --profile customer-a --team team-id --dry-run --output json
+monkeys workflow update workflow-id --file workflow.json --profile customer-a --team team-id --dry-run --output json
+monkeys workflow delete workflow-id --profile customer-a --team team-id --dry-run --output json
+```
+
+`workflow import` 只接受严格的 `{ "workflows": [<单个定义>], "pages": [] }`。Update 是完整定义的直接修改，不使用 ETag 或额外并发版本头；真实 Update/Delete 会先保存本地快照，并在服务端写入后回读验证。Delete 只支持一个精确 ID，不提供批量入口。
+
+### Agent Work
+
+Agent Work 对应 Kernel Agent Console。它只接受声明 Kernel Surface 的 Profile，固定为 Kernel 全局视角，不接受也不继承 Team。
+
+```bash
+monkeys agent work list --profile customer-kernel --limit 20 --output json
+monkeys agent work get issue-id --profile customer-kernel --output json
+monkeys agent work wait issue-id --profile customer-kernel --until review --output json
+```
+
+创建、更新、分配、对话、Spec 审批、运行控制、验收和删除均有独立原子命令。分配、retry、Spec/Review approve 需要明确 `--yes`，删除属于 destructive 操作。引用图片只由 CLI 上传给 Server，CLI 不生成对象存储签名；任何写操作返回 `MUTATION_OUTCOME_UNKNOWN` 时禁止自动重试，先用 `agent work list/get` 核查。
+
+### System Config
+
+System Config 命令只接受声明 Kernel Surface 的 Profile。配置作用域是当前 Deployment/Tenant/Environment；`--team` 仅用于身份上下文，不表示 Team 级配置。
+
+```bash
+monkeys config overview --profile customer-kernel --output json
+monkeys config list --profile customer-kernel --prefix server.workflow --output json
+monkeys config get server.workflowPostReview.enabled --profile customer-kernel --output json
+
+# 写入前先预检；获得当前精确操作授权后再使用 --yes
+monkeys config set server.workflowPostReview.enabled=true \
+  --profile customer-kernel \
+  --dry-run \
+  --output json
+
+monkeys config set server.workflowPostReview.enabled=true \
+  --profile customer-kernel \
+  --yes \
+  --output json
+```
+
+敏感 Key 只能通过 `config set <Key> --value-stdin` 写入，不得放入参数、JSON 或文件。`config patch` 支持 1–50 个精确非敏感 Key 的原子窄更新；`config export` 会依据 Schema 脱敏敏感 Key，且默认不覆盖本地已有文件。写入结果未知时禁止重试，使用 `config get` 与 `config history` 核查。
+
+### 浏览器登录
+
+CLI 不接收账户密码。首次登录直接提供订阅 Endpoint URL，不需要预先创建 Deployment 或 Profile。浏览器模式创建短期 Device Code 并打开该 URL 对应租户的登录页；API Key 模式使用同一个 URL 和安全输入。认证成功后，CLI 从 `/api/configs` 读取已认证租户的 `tenantId`，将它作为订阅/Profile 名，并把该 Profile 设为当前订阅。
+
+人工终端直接运行：
+
+```bash
+monkeys auth login --url https://customer.example.com --output json
+monkeys auth status --profile <tenantId> --output json
+```
+
+Agent 使用分段流程，先把授权 URL 交给用户，再在用户完成浏览器登录后继续轮询：
+
+```bash
+monkeys auth login --url https://customer.example.com --no-wait --output json
+monkeys auth login --profile <上一步返回的临时Profile> --device-code <device_code> --output json
+```
+
+API Key 不允许进入命令参数或 shell history：
+
+```bash
+monkeys auth login --url https://customer.example.com --api-key-stdin --output json
+monkeys auth login --url https://customer.example.com --api-key-env MONKEYS_API_KEY --output json
+```
+
+`auth doctor` 只对当前浏览器会话 Profile 的 Session Store 做随机探针写入、读取、校验和删除，不访问业务服务。`session-file:service/account` 不是任意文件路径：CLI 把 Session 写入版本化、哈希命名的托管目录；首版仅支持 POSIX，并要求当前用户所有权、目录 `0700`、文件 `0600`，遇到符号链接、异常类型或宽松权限会拒绝运行。它依赖操作系统用户与文件权限保护，不宣称应用层加密；Windows 和桌面系统继续使用 `keyring:`。长期运行的 Agent/CI 仍应优先使用可轮换、可撤销的 API Key。
+
+## 语义优先与原始 API
+
+Agent 默认使用 `workflow`、`execution`、`agent work`、`file`、`data`、`config` 等语义命令。OpenAPI 负责提供通用原始 API 能力，不用于一次性生成全部语义命令。
+
+语义命令遇到 Binding 缺失、Binding 歧义或响应合同漂移时，错误会在允许降级的情况下返回：
+
+- `fallbackEligible: true`
+- `safeDetails.fallbackEvidence`
+- `safeDetails.semanticAttemptId`
+
+随后只能在相同 Profile/Tenant/Team/Credential Context 中，把凭据传给 `api call --fallback-evidence ...`。Evidence 使用当前 Credential 派生密钥签名，有效期为 10 分钟，禁止编辑；写操作 Evidence 只能消费一次。写请求如果已经发送或结果未知，CLI 会拒绝 Raw API 重放。认证、授权、输入和确认错误不能降级。
+
+## Data 安全边界
+
+- 新任务使用 Ontology；`--bucket` 仅用于旧部署兼容。Data 写命令要求显式 Ontology 和精确资源 ID；Public/Shared/可读不代表可写。
+- Kernel 全局读取默认不传 `--team`；只有明确筛选某 Team 时才传。Field、View、Feature Value、Advanced Asset Search 和 Asset Export 等需要下游数据资源 Team 的读取使用独立 `--resource-team`，仍保持 Kernel `teamMode=none`。CLI 不会用 Ontology owner Team 猜测资源 Team。Studio 使用明确的 Team 工作空间上下文。
+- Ontology Create/Update 只接受 Kernel Profile 和显式目标/归属 Team；资源定位 Team 与用户 Team 筛选是不同合同，不得把 `resourceLocator.teamId` 描述成 Kernel 查询作用域。
+- 服务端原生批量 JSONL 导入使用 `data asset import-jsonl --file <file> --ontology <id> --team <id> --perspective kernel --profile <profile> --yes`。命令返回持久 `logId`，后续通过 `data asset import-jsonl status <logId>` 查询进度；导入任务不可自动重放。可迁移数据包仍使用 `data asset import`，Ontology 结构迁移仍使用 `data ontology import`。
+- 外部生成清单要补充已有 Asset Feature 时使用 `data asset feature-backfill`（资产特征回填）：必须提供来源 ID 到目标 `assetId` 的映射文件，并先运行 `--dry-run`。该命令固定关闭 Asset/Tag 创建，只写指定图片列和文本列；`--priority-file` 会先通过同一映射解析最终目标 Asset，因此不同来源别名不能绕过高质量结果保护；未知优先来源、非法选中行或重复未保护目标都会在上传前失败。`--select-key/--select-value` 可做精确样本验收。`data asset enrich-jsonl` 仅作为已弃用兼容入口，JSON 结果会给出替代命令。
+- Data JSON 输出通过 `teamMode=none|filter|context` 与可选的 `effectiveTeamId` 说明 CLI 实际施加的 Team 语义；可选 `resourceLocator` 只说明后端资源分区定位，不改变 Team 模式。
+- `data container remove` 只移除 Membership 并进入 Trash，不删除 Asset。
+- View 行数据使用 `data view rows --ontology <id> --view <id>` 批量读取。结果包含有序 `columns` 与 `rows`，按 View 配置补齐 Feature Value；现有 `data asset list` 继续保持紧凑投影。
+- Ontology 全局标量 Feature 的临时结构化筛选使用 `data asset search --expression-json <JSON>` 或 `--expression-file <path>`。先通过 `data field list` 读取目标列的 `config.fieldKey` 和类型；表达式使用 `fieldKey`，不能使用展示名、Field ID 或 ES 路径。该能力是精确结构化过滤，不是语义、模糊或全文搜索。
+- 普通 Filter View 保存筛选条件；`data view convert-to-container` 会按当前筛选快照生成 Container View。转换是高风险后台任务，需精确 View ID 与显式确认。
+- Asset 媒体使用 `data asset media download <asset-id> --ontology <id> --out <path>` 下载。CLI 对公开 HTTPS 对象使用匿名安全下载；对象返回 401/403/404 时再向 Server 请求短期签名 URL。CLI 不自行签名、不输出对象 URL，也不会把 Monkeys 身份头发送给对象存储。
+- View Feature 中的 PDF/文件使用 `data asset attachment download <asset-id> --ontology <id> --view <id> --field <id-or-exact-name> --out <path>` 下载。Field Value 读取携带 View Scope，签名仍由 Server 完成。
+- V1 不提供 Bucket Delete、Container Purge、批量 Trash 或 Field Delete。
+- Feature Value 批量写最多 100 项；部分成功返回退出码 9 和逐项结果。
+
+```bash
+# 只读预检；priority.jsonl 映射到的目标 Asset 会被保护，来源别名也不能覆盖
+monkeys data asset feature-backfill \
+  --file generated.jsonl \
+  --asset-map-file asset-map.jsonl \
+  --priority-file priority.jsonl \
+  --source-id-key file_token \
+  --priority-source-id-key file_token \
+  --image-key url \
+  --text-key source_name \
+  --image-field "AI 生成线稿图" \
+  --text-field "AI 线稿标签" \
+  --ontology <ontology-id> \
+  --team <team-id> \
+  --perspective kernel \
+  --profile <kernel-profile> \
+  --dry-run \
+  --output json
+```
+
+### Ontology Feature 结构化检索
+
+先读取 Ontology 全局 Feature Column，再用稳定 `config.fieldKey` 查询：
+
+```bash
+monkeys data field list \
+  --profile <profile> \
+  --perspective kernel \
+  --ontology <ontology-id> \
+  --resource-team <data-team> \
+  --output json
+
+monkeys data asset search \
+  --profile <profile> \
+  --perspective kernel \
+  --ontology <ontology-id> \
+  --resource-team <data-team> \
+  --expression-json '{"op":"and","filters":[{"op":"feature","fieldKey":"status","cmp":"eq","value":"ready"},{"op":"feature","fieldKey":"score","cmp":"gte","value":80}]}' \
+  --limit 20 \
+  --output json
+```
+
+`string/text/select/enum` 支持 `eq/in`；数字支持 `eq/in/gt/gte/lt/lte/between`；布尔值支持 `eq`；日期时间支持 `eq/gt/gte/lt/lte/between`。最终类型和比较符匹配由服务端真实 Feature Schema 校验。HTTP 400 表示条件或 Schema 不兼容，应重新读取 Field；HTTP 503 表示 Feature 搜索依赖的 ES/索引不可用，不会降级到 PostgreSQL 扫描或 Raw API。Feature Value 写入通过异步索引生效，紧邻写入的首次空结果可能需要短暂等待后做一次有界重试。
+
+### Ontology 与数据导入导出
+
+- `data ontology export/import` 使用版本化 JSON 迁移 Ontology 结构，不包含业务 Asset；导入只支持 `create` 和非破坏性 `merge`，不支持 replace/delete。
+- Ontology 的所有权/定位 Team 使用 `--team`；View、Field、Tag 等数据资源 Team 可通过 `--resource-team` 单独指定，未传时兼容回退为 `--team`。
+- `data asset export/import` 交换业务数据。未传 `--format` 时固定使用 JSONL；CSV/XLSX 必须显式传 `--format csv|xlsx`，CLI 不根据扩展名静默切换。Ontology 全局导出默认保留完整 View Membership，并从各 View 合并可读的 Feature Value。
+- 导出默认拒绝覆盖；覆盖已有文件必须同时传 `--overwrite --yes`。导入先对不可变输入快照做全量预检；真实写入必须传 `--yes`，建议先运行 `--dry-run`。
+- 原生 CSV/XLSX 使用 `json:<JSON>` 类型化 Cell 保存字符串、数字、布尔值和复杂值，避免往返时改变类型；第三方表格通过 `--mapping-file` 显式把来源列映射到 `asset.<字段>`、`values.<Field ID>`、`sourceId`、`tagSourceIds` 或 `viewSourceIds`。
+- CSV/XLSX 首版最多 50,000 行、500 列；XLSX 输入最大 100 MiB，解压后最大 128 MiB，Shared Strings 最大 64 MiB。更大数据集使用默认 JSONL。XLSX 流式读取 `data` 工作表且拒绝公式。
+- Asset 导入首版是 append/create。来源 Asset ID 只进入映射报告，目标 ID 由 Server 生成；Field、Tag 或 View 来源引用必须通过同一 Context 的真实 Ontology 导入报告完成 `sourceId -> targetId` 映射，不能直接沿用来源 ID。映射报告最大 32 MiB。部分失败返回退出码 9，必须查看报告，禁止整文件自动重放。
+
+```powershell
+# 默认 JSONL
+monkeys data asset export --profile <profile> --perspective kernel --ontology <id> --resource-team <data-team> --out assets.jsonl --output json
+
+# 显式 XLSX
+monkeys data asset export --profile <profile> --perspective kernel --ontology <id> --resource-team <data-team> --format xlsx --out assets.xlsx --output json
+
+# 先导入结构并保存真实报告，再进行 Asset 零写入预检
+monkeys data ontology import --profile <profile> --perspective kernel --team <owner-team> --resource-team <data-team> --file ontology.json --mode create --yes --report ontology-report.json --output json
+monkeys data asset import --profile <profile> --perspective kernel --team <data-team> --ontology <id> --ontology-report ontology-report.json --file assets.jsonl --dry-run --output json
+```
+
+## 输出与退出码
+
+自动化和 Agent 使用 `--output json`；状态流使用 NDJSON。所有结果包含 Schema 版本和时间戳，远端调用附带可用的 Request ID 与 Context 摘要。
+
+| 退出码 | 含义                     |
+| -----: | ------------------------ |
+|      0 | 成功                     |
+|      1 | 输入校验失败             |
+|      2 | 配置失败                 |
+|      3 | 认证失败                 |
+|      4 | 授权失败                 |
+|      5 | 网络失败                 |
+|      6 | API 失败                 |
+|      7 | 缺少高风险确认           |
+|      8 | CLI/API/Skill 兼容性失败 |
+|      9 | 部分成功                 |
+|     10 | 内部错误                 |
+
+## 安全
+
+- CLI 不接收账户密码；账户认证只在 Deployment 的浏览器登录页完成。
+- API Key 只通过 stdin 或环境变量导入；系统 Keyring 和 Session 文件只保存 API Key 或服务端签发的 Session Token。
+- HTTPS 为默认要求；HTTP 只允许本机地址。私有 CA 用于验证客户内部 CA 签发的服务端证书，不会关闭 TLS 校验。
+- 自定义 Header 不能覆盖 Authorization、Tenant、Team、Host、Cookie 或代理认证 Header。
+- 输出统一递归脱敏；任何测试 Secret 都不应出现在 stdout、stderr、缓存或配置中。
+- 删除与治理操作要求精确目标和显式确认；`--yes` 不扩大用户授权范围。
+
+## 开发与发布验证
+
+仓库开发使用 Bun `1.3.14` 管理依赖和执行脚本；发布产物仍面向 Node.js 22/24 与 npm Registry。
+
+```bash
+bun install --frozen-lockfile
+bun run verify
+
+# 为三个桌面平台生成携带 Node.js 的独立包
+bun run pack:standalone
+bun run checksums
+```
+
+`bun run verify` 包含格式、类型、单元/合同测试、构建、版本兼容检查、npm 安装冒烟和本地性能门禁。CI 额外覆盖 Node.js 22/24、Windows/Linux/macOS 和各平台独立包安装冒烟。
+
+GitLab 对所有分支 push 运行完整验证；只有默认分支 push 会串行发布 npm `latest`。发布任务先确认当前 Commit 仍是远端默认分支 HEAD，再从 npm 已发布的最高稳定版本计算最小可用 patch 版本。首次发布使用仓库中尚未发布的稳定版本。npm 发布验证成功后，流水线使用内置 `CI_JOB_TOKEN` 创建同版本的 `vX.Y.Z` Git tag 和 GitLab Release；同一 Commit 重试时复用原版本。项目只需配置受保护、遮蔽的 `NPM_TOKEN` CI/CD 变量，且不得把 npm Token 写入仓库。
+
+性能默认门禁为 Linux/macOS 冷启动不超过 3000 ms、Windows 不超过 5000 ms、RSS 不超过 256 MiB。Windows 基线包含进程安全扫描与 oclif 命令加载成本；可通过 `MONKEYS_BENCHMARK_MAX_COLD_MS` 与 `MONKEYS_BENCHMARK_MAX_RSS_MB` 在发布环境收紧，但不能静默放宽。`version show` 使用不加载业务命令的本地快速路径。
+
+本仓库的产品定义、架构决策和执行计划由 Monkeys 上层工作区的私有文档治理；本 README 只保留使用和贡献所需内容。

package/bin/dev.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from '@oclif/core';
+
+await execute({ development: true, dir: import.meta.url });

package/bin/install-wizard.js

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function createInstallPlan({ packageName, packageRoot }) {
+  if (!packageName) throw new Error('npm 包名不能为空。');
+  if (!packageRoot) throw new Error('npm 包目录不能为空。');
+
+  return [
+    {
+      args: ['install', '--global', packageName],
+      command: 'npm',
+      label: `全局安装 ${packageName}`,
+    },
+    {
+      args: ['-y', 'skills', 'add', resolve(packageRoot, 'skills'), '-y', '-g', '--copy'],
+      command: 'npx',
+      label: '安装 Monkeys AI Skill',
+    },
+  ];
+}
+
+export function runCommand(command, args, options = {}) {
+  const windows = process.platform === 'win32';
+  const executable = windows ? (process.env.ComSpec ?? 'cmd.exe') : command;
+  const commandArgs = windows ? ['/d', '/s', '/c', command, ...args] : args;
+  const result = spawnSync(executable, commandArgs, {
+    encoding: 'utf8',
+    stdio: 'inherit',
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} 执行失败，退出码 ${result.status ?? 'unknown'}。`);
+}
+
+export async function runInstallWizard(options = {}) {
+  const packageRoot = options.packageRoot ?? resolve(import.meta.dirname, '..');
+  const packageJson = JSON.parse(await readFile(resolve(packageRoot, 'package.json'), 'utf8'));
+  const plan = createInstallPlan({ packageName: packageJson.name, packageRoot });
+  const execute = options.execute ?? runCommand;
+  const output = options.output ?? ((message) => process.stdout.write(`${message}\n`));
+
+  output('正在设置 Monkeys CLI...');
+  for (const step of plan) {
+    output(`${step.label}...`);
+    execute(step.command, step.args);
+  }
+  output('Monkeys CLI 与 AI Skill 已安装。');
+
+  return plan;
+}
+
+export async function runInstallWizardCli() {
+  try {
+    await runInstallWizard();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Monkeys CLI 安装失败：${message}\n`);
+    process.stderr.write('可分别重试：\n');
+    process.stderr.write('  npm install --global @inf-monkeys-tech/monkeys-cli\n');
+    process.stderr.write('  npx -y skills add <已安装 npm 包中的 skills 目录> -y -g --copy\n');
+    process.exitCode = 1;
+  }
+}

package/bin/run.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const install = args.length === 1 && args[0] === 'install';
+const fastVersion =
+  args[0] === 'version' &&
+  args[1] === 'show' &&
+  (args.length === 2 || (args.length === 4 && args[2] === '--output' && ['json', 'text'].includes(args[3])));
+const fastProfileList =
+  args[0] === 'profile' &&
+  args[1] === 'list' &&
+  (args.length === 2 || (args.length === 4 && args[2] === '--output' && ['json', 'text'].includes(args[3])));
+if (install) {
+  const { runInstallWizardCli } = await import('./install-wizard.js');
+  await runInstallWizardCli();
+} else if (fastVersion) {
+  const [{ readFile }, { BUNDLED_SKILL_MINIMUM_CLI_VERSION, BUNDLED_SKILL_NAME, COMMAND_SCHEMA_MAJOR }] = await Promise.all([
+    import('node:fs/promises'),
+    import('../dist/contracts/version.js'),
+  ]);
+  const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const data = {
+    cliVersion: packageJson.version,
+    commandSchemaMajor: COMMAND_SCHEMA_MAJOR,
+    nodeVersion: process.version,
+    platform: `${process.platform}-${process.arch}`,
+    skill: { minimumCliVersion: BUNDLED_SKILL_MINIMUM_CLI_VERSION, name: BUNDLED_SKILL_NAME },
+  };
+  const outputIndex = args.indexOf('--output');
+  const output = outputIndex >= 0 ? args[outputIndex + 1] : 'text';
+  if (output === 'json') {
+    process.stdout.write(
+      `${JSON.stringify({ data, meta: { command: 'version show', schemaVersion: '1', timestamp: new Date().toISOString() }, ok: true })}\n`,
+    );
+  } else {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+  }
+} else if (fastProfileList) {
+  const { renderFastProfileList } = await import('../dist/config/fast-profile-list.js');
+  const outputIndex = args.indexOf('--output');
+  const result = await renderFastProfileList(outputIndex >= 0 ? args[outputIndex + 1] : 'text');
+  process.stdout.write(`${result.text}\n`);
+  process.exitCode = result.exitCode;
+} else {
+  const { execute } = await import('@oclif/core');
+
+  await execute({ dir: import.meta.url });
+}

package/dist/agent-work/adapters.d.ts

@@ -0,0 +1,14 @@
+import { type AgentWorkDetail, type AgentWorkListResult, type AgentWorkStatus, type AgentWorkSummary } from './contracts.js';
+export declare function normalizeAgentWorkStatus(value: unknown): AgentWorkStatus;
+export declare function adaptAgentWorkSummary(value: unknown): AgentWorkSummary;
+export declare function adaptAgentWorkDetail(value: unknown): AgentWorkDetail;
+export declare function adaptAgentWorkList(value: unknown, options: {
+    attentionRequired?: boolean;
+    limit: number;
+}): AgentWorkListResult;
+export declare function adaptSafeCollection(value: unknown): {
+    items: Record<string, unknown>[];
+    returned: number;
+    serverTotal: number;
+};
+//# sourceMappingURL=adapters.d.ts.map

package/dist/agent-work/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/agent-work/adapters.ts"],"names":[],"mappings":"AACA,OAAO,EAYL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAKxB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAMxB,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAIxE;AA0CD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CA8BtE;AAqDD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA4CpE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,mBAAmB,CAc/H;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CA4B/H"}

package/dist/agent-work/adapters.js

@@ -0,0 +1,227 @@
+import { AGENT_WORK_ASSIGNMENT_MODES, AGENT_WORK_ATTENTION_STATES, AGENT_WORK_PHASES, AGENT_WORK_PRIORITIES, AGENT_WORK_STATUSES, AGENT_WORK_TYPES, rawAgentWorkListSchema, rawAgentWorkSchema, rawCollectionSchema, } from './contracts.js';
+function enumValue(values, value, fallback) {
+    return typeof value === 'string' && values.includes(value) ? value : fallback;
+}
+export function normalizeAgentWorkStatus(value) {
+    if (value === 'open')
+        return 'provisioning';
+    if (value === 'changes_requested')
+        return 'running';
+    return enumValue(AGENT_WORK_STATUSES, value, 'provisioning');
+}
+function inferPhase(status) {
+    if (status === 'awaiting_acceptance')
+        return 'verification';
+    if (status === 'accepted')
+        return 'completed';
+    if (status === 'cancelled')
+        return 'cancelled';
+    if (status === 'running' || status === 'paused' || status === 'failed')
+        return 'execution';
+    return 'analysis';
+}
+function inferAttention(status) {
+    if (status === 'running' || status === 'provisioning')
+        return 'agent_working';
+    if (status === 'failed')
+        return 'blocked';
+    return 'none';
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function optionalNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function referenceImage(value) {
+    return {
+        id: value.id,
+        ...(optionalString(value.filename) ? { filename: optionalString(value.filename) } : {}),
+        ...(optionalString(value.mimeType) ? { mimeType: optionalString(value.mimeType) } : {}),
+        ...(optionalNumber(value.size) === undefined ? {} : { size: optionalNumber(value.size) }),
+        ...(optionalNumber(value.width) === undefined ? {} : { width: optionalNumber(value.width) }),
+        ...(optionalNumber(value.height) === undefined ? {} : { height: optionalNumber(value.height) }),
+        ...(optionalNumber(value.uploadedAt) === undefined ? {} : { uploadedAt: optionalNumber(value.uploadedAt) }),
+    };
+}
+function userLabel(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    return optionalString(record.name) ?? optionalString(record.email) ?? optionalString(record.id);
+}
+export function adaptAgentWorkSummary(value) {
+    const raw = rawAgentWorkSchema.parse(value);
+    const status = normalizeAgentWorkStatus(raw.status);
+    return {
+        attentionState: enumValue(AGENT_WORK_ATTENTION_STATES, raw.attentionState, inferAttention(status)),
+        createdTimestamp: raw.createdTimestamp,
+        id: raw.id,
+        phase: enumValue(AGENT_WORK_PHASES, raw.phase, inferPhase(status)),
+        priority: enumValue(AGENT_WORK_PRIORITIES, raw.priority, 'medium'),
+        referenceImages: raw.referenceImages.map(referenceImage),
+        status,
+        title: raw.title,
+        updatedTimestamp: raw.updatedTimestamp,
+        workType: enumValue(AGENT_WORK_TYPES, raw.workType, 'adaptive'),
+        ...(optionalString(raw.description) ? { description: optionalString(raw.description) } : {}),
+        ...(optionalString(raw.repoUrl) ? { repoUrl: optionalString(raw.repoUrl) } : {}),
+        ...(optionalString(raw.repoRef) ? { repoRef: optionalString(raw.repoRef) } : {}),
+        ...(optionalString(raw.repoSubpath) ? { repoSubpath: optionalString(raw.repoSubpath) } : {}),
+        ...(optionalString(raw.baseBranch) ? { baseBranch: optionalString(raw.baseBranch) } : {}),
+        ...(optionalString(raw.assignedRuntimeId) ? { assignedRuntimeId: optionalString(raw.assignedRuntimeId) } : {}),
+        ...(optionalString(raw.currentRunId) ? { currentRunId: optionalString(raw.currentRunId) } : {}),
+        ...(optionalString(raw.currentSpecRevisionId) ? { currentSpecRevisionId: optionalString(raw.currentSpecRevisionId) } : {}),
+        ...((userLabel(raw.createdByUser) ?? optionalString(raw.createdBy))
+            ? { createdBy: userLabel(raw.createdByUser) ?? optionalString(raw.createdBy) }
+            : {}),
+        ...((userLabel(raw.acceptedByUser) ?? optionalString(raw.acceptedBy))
+            ? { acceptedBy: userLabel(raw.acceptedByUser) ?? optionalString(raw.acceptedBy) }
+            : {}),
+        ...(optionalNumber(raw.acceptedAt) === undefined ? {} : { acceptedAt: optionalNumber(raw.acceptedAt) }),
+    };
+}
+function adaptRun(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    const id = optionalString(item.id);
+    if (!id)
+        return undefined;
+    return {
+        id,
+        ...(optionalString(item.status) ? { status: optionalString(item.status) } : {}),
+        ...(optionalString(item.runtimeId) ? { runtimeId: optionalString(item.runtimeId) } : {}),
+        ...(optionalString(item.triggerType) ? { triggerType: optionalString(item.triggerType) } : {}),
+        ...(optionalString(item.resultSummary) ? { resultSummary: optionalString(item.resultSummary) } : {}),
+        ...(optionalString(item.errorMessage) ? { errorMessage: optionalString(item.errorMessage) } : {}),
+        ...(optionalNumber(item.startedAt) === undefined ? {} : { startedAt: optionalNumber(item.startedAt) }),
+        ...(optionalNumber(item.completedAt) === undefined ? {} : { completedAt: optionalNumber(item.completedAt) }),
+        ...(optionalNumber(item.lastEventAt) === undefined ? {} : { lastEventAt: optionalNumber(item.lastEventAt) }),
+    };
+}
+function adaptSpec(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    const id = optionalString(item.id);
+    if (!id)
+        return undefined;
+    return {
+        id,
+        ...(optionalString(item.title) ? { title: optionalString(item.title) } : {}),
+        ...(optionalString(item.status) ? { status: optionalString(item.status) } : {}),
+        ...(optionalString(item.contentMarkdown) ? { contentMarkdown: optionalString(item.contentMarkdown) } : {}),
+        ...(optionalNumber(item.revision) === undefined ? {} : { revision: optionalNumber(item.revision) }),
+    };
+}
+function adaptReviewPack(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    const tests = Array.isArray(item.tests)
+        ? item.tests.slice(0, 100).map((test) => {
+            const record = test && typeof test === 'object' ? test : {};
+            return {
+                ...(optionalString(record.name) ? { name: optionalString(record.name) } : {}),
+                ...(optionalString(record.status) ? { status: optionalString(record.status) } : {}),
+            };
+        })
+        : [];
+    return {
+        hasEvidence: Boolean(item.evidence || item.artifacts || item.previewUrl || item.url),
+        tests,
+        ...(optionalString(item.summary) ? { summary: optionalString(item.summary) } : {}),
+    };
+}
+export function adaptAgentWorkDetail(value) {
+    const raw = rawAgentWorkSchema.parse(value);
+    const summary = adaptAgentWorkSummary(raw);
+    const currentRun = adaptRun(raw.currentRun);
+    const currentSpec = adaptSpec(raw.currentSpec);
+    const runs = (raw.runs ?? []).map(adaptRun).filter((item) => Boolean(item));
+    const assignment = raw.assignmentPolicy;
+    const assignmentMode = assignment ? enumValue(AGENT_WORK_ASSIGNMENT_MODES, assignment.mode, 'auto') : undefined;
+    const tokenUsage = raw.tokenUsage;
+    return {
+        ...summary,
+        activities: (raw.activities ?? []).slice(0, 200).map((item) => ({
+            ...(optionalString(item.action) ? { action: optionalString(item.action) } : {}),
+            ...(optionalString(item.id) ? { id: optionalString(item.id) } : {}),
+            ...(optionalNumber(item.occurredAt) === undefined ? {} : { occurredAt: optionalNumber(item.occurredAt) }),
+        })),
+        runs,
+        ...(optionalString(raw.approvedSpecRevisionId) ? { approvedSpecRevisionId: optionalString(raw.approvedSpecRevisionId) } : {}),
+        ...(assignmentMode
+            ? {
+                assignmentPolicy: {
+                    mode: assignmentMode,
+                    ...(optionalString(assignment?.runtimeId) ? { runtimeId: optionalString(assignment?.runtimeId) } : {}),
+                    ...(optionalString(assignment?.resourceId) ? { resourceId: optionalString(assignment?.resourceId) } : {}),
+                    ...(optionalString(assignment?.runtimeName) ? { runtimeName: optionalString(assignment?.runtimeName) } : {}),
+                },
+            }
+            : {}),
+        ...(currentRun ? { currentRun } : {}),
+        ...(currentSpec ? { currentSpec } : {}),
+        ...(adaptReviewPack(raw.reviewPack) ? { reviewPack: adaptReviewPack(raw.reviewPack) } : {}),
+        ...(tokenUsage
+            ? {
+                tokenUsage: {
+                    ...(optionalNumber(tokenUsage.inputTokens) === undefined ? {} : { inputTokens: optionalNumber(tokenUsage.inputTokens) }),
+                    ...(optionalNumber(tokenUsage.outputTokens) === undefined ? {} : { outputTokens: optionalNumber(tokenUsage.outputTokens) }),
+                    ...(optionalNumber(tokenUsage.cachedInputTokens) === undefined
+                        ? {}
+                        : { cachedInputTokens: optionalNumber(tokenUsage.cachedInputTokens) }),
+                    ...(optionalNumber(tokenUsage.totalTokens) === undefined ? {} : { totalTokens: optionalNumber(tokenUsage.totalTokens) }),
+                },
+            }
+            : {}),
+    };
+}
+export function adaptAgentWorkList(value, options) {
+    const raw = rawAgentWorkListSchema.parse(value);
+    const all = raw.items.map(adaptAgentWorkSummary);
+    const filtered = options.attentionRequired
+        ? all.filter((item) => ['user_input_required', 'spec_approval_required', 'blocked'].includes(item.attentionState))
+        : all;
+    const items = filtered.slice(0, options.limit);
+    return {
+        items,
+        returned: items.length,
+        serverTotal: all.length,
+        ...(raw.summary ? { summary: raw.summary } : {}),
+        truncated: filtered.length > items.length,
+    };
+}
+export function adaptSafeCollection(value) {
+    const raw = rawCollectionSchema.parse(value);
+    const items = raw.items.map((item) => {
+        const safe = {};
+        for (const key of [
+            'id',
+            'name',
+            'status',
+            'connectionStatus',
+            'clusterAlias',
+            'namespace',
+            'image',
+            'bindingStatus',
+            'leaseMode',
+            'createdTimestamp',
+            'updatedTimestamp',
+            'resourceId',
+            'runtimeProfileId',
+        ]) {
+            if (item[key] !== undefined && item[key] !== null)
+                safe[key] = item[key];
+        }
+        if (item.issue && typeof item.issue === 'object') {
+            const issue = item.issue;
+            safe.issue = { id: issue.id, title: issue.title, status: issue.status, priority: issue.priority };
+        }
+        return safe;
+    });
+    return { items, returned: items.length, serverTotal: raw.count ?? items.length };
+}
+//# sourceMappingURL=adapters.js.map