@kairyou/agent-tools 0.19.0 → 0.21.0

package/README.md

@@ -116,8 +116,9 @@ compatibility and configuration.
 ### Provider usage
 
 Shows API relay / gateway balance and quota inside the agent. Supports Sub2API,
-One API (including OneHub and DoneHub), New API, Claude Code Hub, and OpenRouter;
-compatibility depends on the gateway version and enabled usage endpoints.
+One API (including OneHub and DoneHub), New API, Claude Code Hub, OpenRouter, and
+Command Code; compatibility depends on the gateway version and enabled usage
+endpoints.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
@@ -139,8 +140,8 @@ configuration; official (non-relay) endpoints are skipped. If it reports
 {
   "providerUsage": {
     // auto | sub2api | openai-compatible | one-api | one-hub |
-    // done-hub | new-api | claude-code-hub | openrouter | <custom-route-id>
-    "preset": "auto",
+    // done-hub | new-api | claude-code-hub | openrouter | commandcode | <custom-route-id>
+    "preset": "auto", // auto-detect, or select one protocol listed above
     "days": 30,       // how many recent days of spend to count
     "debug": false    // true: log probes to ~/.agent-tools/logs/usage-debug.log
   }
@@ -149,7 +150,8 @@ configuration; official (non-relay) endpoints are skipped. If it reports
 
 Keep `preset` set to `auto` for automatic detection. Select a specific protocol
 only when you know which usage endpoint the gateway exposes; a configured custom
-route id is also accepted.
+route id is also accepted. Command Code usage relies on a version-sensitive
+endpoint that is not part of its documented Provider API.
 
 Output examples:
 

package/README.zh-CN.md

@@ -114,8 +114,8 @@ npx -y @kairyou/agent-tools@latest statusline -a claude
 ### Provider usage
 
 在 agent 内查看 API 中转网关的余额和额度. 支持 Sub2API, One API (包括 OneHub
-与 DoneHub), New API, Claude Code Hub 和 OpenRouter. 具体兼容性取决于网关版本
-及其是否开放相应接口.
+与 DoneHub), New API, Claude Code Hub, OpenRouter 和 Command Code. 具体兼容性
+取决于网关版本及其是否开放相应接口.
 
 ```bash
 npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
@@ -136,8 +136,8 @@ npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
 {
   "providerUsage": {
     // auto | sub2api | openai-compatible | one-api | one-hub |
-    // done-hub | new-api | claude-code-hub | openrouter | <自定义 route id>
-    "preset": "auto",
+    // done-hub | new-api | claude-code-hub | openrouter | commandcode | <自定义 route id>
+    "preset": "auto", // 自动探测, 也可指定上面列出的协议
     "days": 30,       // 统计最近多少天的消耗
     "debug": false    // true: 探测过程写入 ~/.agent-tools/logs/usage-debug.log
   }
@@ -145,7 +145,8 @@ npx -y @kairyou/agent-tools@latest usage -a claude codex opencode
 ```
 
 保持 `preset: "auto"` 即可自动探测. 只有明确知道网关开放的是哪种用量协议时,
-才指定相应的内置 preset 或已配置的自定义 route id.
+才指定相应的内置 preset 或已配置的自定义 route id. Command Code 用量查询依赖
+未包含在公开 Provider API 中的接口, 可能随版本变化.
 
 显示效果示例:
 

package/capabilities/usage/lib/format.mjs

@@ -226,6 +226,31 @@ export function formatOpenRouterLine(data) {
   return parts.join(" | ");
 }
 
+function formatCredits(value) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value.toLocaleString("en-US", { maximumFractionDigits: 1 })
+    : "";
+}
+
+function formatCommandCodeWindow(label, window) {
+  if (!window || !Number.isFinite(window.used) || !Number.isFinite(window.cap)) return "";
+  const reset = window.resetAt ? compactDurationUntil(window.resetAt) : "";
+  return `${label} ${formatCredits(window.used)}/${formatCredits(window.cap)}${reset ? ` ⟳${reset}` : ""}`;
+}
+
+export function formatCommandCodeLine(data) {
+  const credits = data?.credits || {};
+  const limits = data?.windowLimits || {};
+  const parts = [];
+  if (Number.isFinite(credits.monthlyCredits)) parts.push(`credits ${formatCredits(credits.monthlyCredits)}`);
+  const fiveHour = formatCommandCodeWindow("5h", limits.fiveHour);
+  const weekly = formatCommandCodeWindow("W", limits.weekly);
+  if (fiveHour) parts.push(fiveHour);
+  if (weekly) parts.push(weekly);
+  if (parts.length === 0) throw new Error("Command Code billing payload has no usage fields");
+  return parts.join(" | ");
+}
+
 export function formatOneApiBillingLine(limit, used) {
   if (!hasSpendableOneApiLimit(limit)) return `used ${formatMoney(used)}`;
   return `balance ${formatMoney(Math.max(0, limit - used))} | used ${formatMoney(used)}/${formatMoney(limit)}`;

package/capabilities/usage/lib/routes.mjs

@@ -30,6 +30,7 @@ import {
   hasSpendableOneApiLimit,
   formatOpenRouterLine,
   formatClaudeCodeHubLine,
+  formatCommandCodeLine,
 } from "./format.mjs";
 import { readRouteCache } from "./cache.mjs";
 
@@ -170,6 +171,22 @@ async function fetchOpenRouterUsage(context) {
   throw lastError || new Error("OpenRouter usage unavailable");
 }
 
+// Command Code exposes subscription credits and rolling windows through the
+// same internal endpoint used by its `/usage` overlay. This route is opt-in
+// via the commandcode preset or the official host and is intentionally kept
+// out of generic probing because the endpoint is not a documented Provider API.
+async function fetchCommandCodeUsage(context) {
+  const base = cleanBaseUrl(context.baseUrl)
+    .replace(/\/provider\/v1$/i, "")
+    .replace(/\/provider$/i, "")
+    .replace(/\/v1$/i, "");
+  const json = await requestJson(joinUrl(base, "/alpha/billing/credits"), {
+    key: context.key,
+    name: "Command Code billing credits",
+  });
+  return usageResult(context, "commandcode-billing", formatCommandCodeLine(json), json);
+}
+
 const USAGE_ROUTES = {
   "v1-usage": {
     id: "v1-usage",
@@ -196,6 +213,11 @@ const USAGE_ROUTES = {
     path: "/api/v1/me/quota",
     run: fetchClaudeCodeHubUsage,
   },
+  "commandcode": {
+    id: "commandcode",
+    path: "/alpha/billing/credits",
+    run: fetchCommandCodeUsage,
+  },
 };
 
 // User-authored gateway routes, declared in config.jsonc:
@@ -292,6 +314,7 @@ async function usageRouteIds(context) {
     "done-hub": ["oneapi-billing"],
     "openrouter": ["openrouter"],
     "claude-code-hub": ["claude-code-hub"],
+    "commandcode": ["commandcode"],
   };
   if (routes[preset]) return routes[preset];
 
@@ -302,6 +325,8 @@ async function usageRouteIds(context) {
   const customIds = (await customRoutes()).map((route) => route.id);
   const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai")
     ? ["openrouter"]
+    : hostIncludes(context.baseUrl, "commandcode.ai")
+      ? ["commandcode"]
     : ["v1-usage", "newapi-token", "oneapi-billing", "claude-code-hub"];
   return [...new Set([...customIds, ...builtinIds])];
 }

package/dist/usage/core.mjs

@@ -1490,6 +1490,26 @@ function formatOpenRouterLine(data) {
   if (parts.length === 0) throw new Error("OpenRouter payload has no usage fields");
   return parts.join(" | ");
 }
+function formatCredits(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value.toLocaleString("en-US", { maximumFractionDigits: 1 }) : "";
+}
+function formatCommandCodeWindow(label, window) {
+  if (!window || !Number.isFinite(window.used) || !Number.isFinite(window.cap)) return "";
+  const reset = window.resetAt ? compactDurationUntil(window.resetAt) : "";
+  return `${label} ${formatCredits(window.used)}/${formatCredits(window.cap)}${reset ? ` \u27F3${reset}` : ""}`;
+}
+function formatCommandCodeLine(data) {
+  const credits = data?.credits || {};
+  const limits = data?.windowLimits || {};
+  const parts = [];
+  if (Number.isFinite(credits.monthlyCredits)) parts.push(`credits ${formatCredits(credits.monthlyCredits)}`);
+  const fiveHour = formatCommandCodeWindow("5h", limits.fiveHour);
+  const weekly = formatCommandCodeWindow("W", limits.weekly);
+  if (fiveHour) parts.push(fiveHour);
+  if (weekly) parts.push(weekly);
+  if (parts.length === 0) throw new Error("Command Code billing payload has no usage fields");
+  return parts.join(" | ");
+}
 function formatOneApiBillingLine(limit, used) {
   if (!hasSpendableOneApiLimit(limit)) return `used ${formatMoney(used)}`;
   return `balance ${formatMoney(Math.max(0, limit - used))} | used ${formatMoney(used)}/${formatMoney(limit)}`;
@@ -1706,6 +1726,14 @@ async function fetchOpenRouterUsage(context) {
   }
   throw lastError || new Error("OpenRouter usage unavailable");
 }
+async function fetchCommandCodeUsage(context) {
+  const base = cleanBaseUrl(context.baseUrl).replace(/\/provider\/v1$/i, "").replace(/\/provider$/i, "").replace(/\/v1$/i, "");
+  const json = await requestJson(joinUrl(base, "/alpha/billing/credits"), {
+    key: context.key,
+    name: "Command Code billing credits"
+  });
+  return usageResult(context, "commandcode-billing", formatCommandCodeLine(json), json);
+}
 var USAGE_ROUTES = {
   "v1-usage": {
     id: "v1-usage",
@@ -1731,6 +1759,11 @@ var USAGE_ROUTES = {
     id: "claude-code-hub",
     path: "/api/v1/me/quota",
     run: fetchClaudeCodeHubUsage
+  },
+  "commandcode": {
+    id: "commandcode",
+    path: "/alpha/billing/credits",
+    run: fetchCommandCodeUsage
   }
 };
 var CUSTOM_ROUTE_HELPERS = { requestJson, agentConfig };
@@ -1806,12 +1839,13 @@ async function usageRouteIds(context) {
     "one-hub": ["oneapi-billing"],
     "done-hub": ["oneapi-billing"],
     "openrouter": ["openrouter"],
-    "claude-code-hub": ["claude-code-hub"]
+    "claude-code-hub": ["claude-code-hub"],
+    "commandcode": ["commandcode"]
   };
   if (routes[preset]) return routes[preset];
   if (preset !== "auto") return (await routeRegistry())[preset] ? [preset] : [];
   const customIds = (await customRoutes()).map((route) => route.id);
-  const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai") ? ["openrouter"] : ["v1-usage", "newapi-token", "oneapi-billing", "claude-code-hub"];
+  const builtinIds = hostIncludes(context.baseUrl, "openrouter.ai") ? ["openrouter"] : hostIncludes(context.baseUrl, "commandcode.ai") ? ["commandcode"] : ["v1-usage", "newapi-token", "oneapi-billing", "claude-code-hub"];
   return [.../* @__PURE__ */ new Set([...customIds, ...builtinIds])];
 }
 async function cachedUsageRoute(context, registry) {

package/docs/en/custom-gateway-routes.md

@@ -4,6 +4,9 @@ Advanced guide for [provider usage](../../README.md#provider-usage): write your
 usage probe for relays the built-in presets cannot reach (e.g. cookie-authenticated
 gateways) without modifying package code.
 
+Built-in presets, including `commandcode`, are documented in the main
+[provider usage](../../README.md#provider-usage) section.
+
 ## Declare a route
 
 Write a route module and list it in `providerUsage.routes` (paths resolve against

package/docs/zh-CN/custom-gateway-routes.md

@@ -6,6 +6,8 @@
 
 编写路由模块, 并在 `providerUsage.routes` 里声明(相对 `~/.agent-tools` 解析). 声明的路由优先探测; `"preset"` 填路由 id 可直接选中.
 
+包括 `commandcode` 在内的内置 preset 见主文档的[Provider usage](../../README.zh-CN.md#provider-usage)章节.
+
 ```jsonc
 {
   "providerUsage": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Reusable Agent Skills, plus runtime capabilities (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

package/skills/systems/at-zentao/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: at-zentao
-description: "Work ZenTao bugs/tasks end to end, manage task lifecycle and hours, or read a linked story as development context: fetch details, handle the user's request, verify changes, and ask before committing or writing back to ZenTao. Supports single items and sequential batches. Use when the user references ZenTao (禅道) bugs, tasks, stories, requirements, task status, or task hours."
+description: "Handle ZenTao (禅道) Bugs and Tasks end to end, including updating or writing back an item after code changes, managing Task status and hours, and reading linked Stories. Use for referenced ZenTao items, requirements, status changes, time entries, or post-implementation synchronization."
 argument-hint: "bug <id> [request] | task <id> [request] | story <id> | bugs | tasks | export bug|task <id>"
 ---
 
@@ -72,6 +72,7 @@ node <skill-root>/scripts/zentao-cli.mjs get bug <id>
 node <skill-root>/scripts/zentao-cli.mjs get task <id>
 node <skill-root>/scripts/zentao-cli.mjs get story <id>
 node <skill-root>/scripts/zentao-cli.mjs get bug <id> --download-dir <path>
+node <skill-root>/scripts/zentao-cli.mjs hours task <id>
 ```
 
 `get` downloads token-gated inline images and attachments into a temporary
@@ -89,6 +90,7 @@ node <skill-root>/scripts/zentao-cli.mjs start task <id>
 node <skill-root>/scripts/zentao-cli.mjs pause task <id>
 node <skill-root>/scripts/zentao-cli.mjs resume task <id>
 node <skill-root>/scripts/zentao-cli.mjs log-hours task <id>
+node <skill-root>/scripts/zentao-cli.mjs edit-hours task <id> <effort-id>
 node <skill-root>/scripts/zentao-cli.mjs finish task <id>
 ```
 
@@ -99,6 +101,7 @@ Input shapes:
 {"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
 {"realStarted":"2026-08-11 09:00:00","comment":"Started implementation."}
 {"date":"2026-08-11","consumed":2,"left":14,"work":"Implemented the first part of the task."}
+{"work":"Corrected work description, commit abc1234."}
 {"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00"}
 ```
 
@@ -109,7 +112,9 @@ computes a task's total consumed hours from its current ZenTao value.
 accepts `realStarted` and otherwise uses the current time. The CLI preserves
 the task's current hours when starting or resuming it.
 `log-hours` defaults `date` to today, requires positive remaining hours,
-and keeps the task open. Use `finish` when the task is complete.
+and keeps the task open. `hours` is read-only. `edit-hours` preserves omitted
+fields from the existing record and updates it through ZenTao's native effort
+workflow. Use `finish` when the task is complete.
 
 ## Usage
 
@@ -128,6 +133,9 @@ lifecycle requests such as `开始`, `暂停`, `继续`, `start`, `pause`, and
 `resume`, and time-entry requests such as `填工时`, `记录工时`, `log hours`,
 and `worklog`. Users do not need to know the internal CLI commands. Reuse any
 date, hours, or work description already supplied instead of asking twice.
+Recognize corrections to an existing time entry. Run `hours`, identify the
+record from returned ids and values, and ask when more than one record could
+match; never guess or call `log-hours` again to compensate for a mistake.
 
 If a list response includes pager data showing more items than returned, tell
 the user the shown and total counts. Do not silently imply the list is complete.
@@ -180,6 +188,11 @@ Bug resolutions are `fixed`, `notrepro`, `duplicate`, `bydesign`, `external`,
 write-back comment is one sentence containing root cause, change summary, and
 the commit hash when committed.
 
+Immediately before confirming any ZenTao write that cites the latest commit,
+run `git rev-parse HEAD` and `git log -1 --format=%h`. Do not reuse a hash from
+earlier conversation. If HEAD is not the item-specific commit, identify the
+relevant commit and tell the user instead of blindly citing HEAD.
+
 For tasks, ask whether to record the current work after the verified result.
 For an incomplete task, collect the actual `consumed` hours and work date. When
 the task has a numeric current `left`, suggest the new `left` by subtracting the
@@ -191,6 +204,15 @@ collect `currentConsumed` and draft a `finish` write. Never infer consumed
 hours. Show all submitted values and require the same explicit ZenTao
 confirmation before either write.
 
+To correct an existing time entry, use `hours` to select its effort id. Show
+the current and proposed `date`, `consumed`, `left`, and `work`, then obtain
+explicit confirmation and call `edit-hours` once. Preserve every field the
+user did not change. Stop when ownership cannot be verified or the edit route
+is unsupported. If the proposed `left` is zero, explicitly warn that ZenTao
+may change the task status as part of its native recalculation. Never edit an
+action comment as a substitute for correcting the underlying work-hour record,
+and never delete a record.
+
 When the user wants to record hours and pause, show both exact writes in one
 confirmation, then run `log-hours` before `pause`. Stop if the hour write fails.
 Do not add lifecycle support for `activate`, `cancel`, or `close`.

package/skills/systems/at-zentao/scripts/zentao-cli.mjs

@@ -459,10 +459,13 @@ async function readInput() {
   return value;
 }
 
-function formBody(fields) {
+function formBody(fields, includeEmpty = []) {
   const body = new URLSearchParams();
+  const keepEmpty = new Set(includeEmpty);
   for (const [key, value] of Object.entries(fields)) {
-    if (value !== undefined && value !== null && value !== "") body.set(key, String(value));
+    if (value !== undefined && value !== null && (value !== "" || keepEmpty.has(key))) {
+      body.set(key, String(value));
+    }
   }
   return body;
 }
@@ -484,8 +487,8 @@ async function workhourVariant(client, id) {
   ];
   for (const variant of variants) {
     try {
-      decodeLegacy(await client.json(variant.route));
-      return variant;
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, form };
     } catch (error) {
       const unavailable = error instanceof CliError && (
         (error.code === "http_error" && error.status === 404) ||
@@ -500,6 +503,88 @@ async function workhourVariant(client, id) {
   );
 }
 
+function effortRecords(form) {
+  const candidates = [
+    form?.efforts,
+    form?.estimates,
+    form?.workhours,
+    form?.taskEfforts,
+    form?.task?.efforts,
+    form?.task?.estimates,
+  ];
+  const collection = candidates.find((value) => value && typeof value === "object");
+  if (!collection) return [];
+  const entries = Array.isArray(collection)
+    ? collection.map((value) => [null, value])
+    : Object.entries(collection);
+  const records = entries
+    .filter(([, value]) => value && typeof value === "object")
+    .map(([key, value]) => ({
+      ...(value.id === undefined && /^\d+$/.test(key || "") ? { id: Number(key) } : {}),
+      ...pick(value, ["id", "date", "consumed", "left", "work"]),
+    }));
+  return records;
+}
+
+function effortFromEditForm(form) {
+  const effort = form?.effort || form?.estimate || form?.workhour ||
+    (form?.id !== undefined ? form : null);
+  if (!effort || typeof effort !== "object") {
+    throw new CliError("response_error", "ZenTao returned no editable work-hour record");
+  }
+  return effort;
+}
+
+function verifyEffortTask(effort, taskId) {
+  if (effort.objectType !== undefined && effort.objectType !== "task") {
+    throw new CliError("ownership_error", "The work-hour record does not belong to a task");
+  }
+  const owner = effort.objectID ?? effort.task ?? effort.taskID;
+  if (owner === undefined || String(owner) !== String(taskId)) {
+    throw new CliError("ownership_error", "The work-hour record does not belong to the requested task");
+  }
+}
+
+async function editableEffortVariant(client, effortId) {
+  const variants = [
+    { route: `task-editeffort-${effortId}.json`, legacy: false },
+    { route: `task-editestimate-${effortId}.json`, legacy: true },
+  ];
+  for (const variant of variants) {
+    try {
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, effort: effortFromEditForm(form) };
+    } catch (error) {
+      const unavailable = error instanceof CliError && (
+        (error.code === "http_error" && error.status === 404) ||
+        error.code === "response_error"
+      );
+      if (!unavailable) throw error;
+    }
+  }
+  throw new CliError(
+    "unsupported_version",
+    "ZenTao exposes neither editEffort nor editEstimate for this work-hour record"
+  );
+}
+
+function effortFields(effort, input) {
+  const date = effortDate(input.date ?? effort.date);
+  const consumed = Number(input.consumed ?? effort.consumed);
+  const left = Number(input.left ?? effort.left);
+  const work = input.work ?? effort.work ?? "";
+  if (!Number.isFinite(consumed) || consumed <= 0) {
+    throw new CliError("usage_error", "consumed must be positive");
+  }
+  if (!Number.isFinite(left) || left < 0) {
+    throw new CliError("usage_error", "left must be zero or positive");
+  }
+  if (typeof work !== "string") {
+    throw new CliError("usage_error", "work must be a string");
+  }
+  return { date, consumed, left, work: work.trim() };
+}
+
 function localDateTime(date = new Date()) {
   const part = (value) => String(value).padStart(2, "0");
   return `${date.getFullYear()}-${part(date.getMonth() + 1)}-${part(date.getDate())} ${part(date.getHours())}:${part(date.getMinutes())}:${part(date.getSeconds())}`;
@@ -537,7 +622,9 @@ function help() {
   zentao-cli.mjs start task <id>           # JSON on stdin
   zentao-cli.mjs pause task <id>           # JSON on stdin
   zentao-cli.mjs resume task <id>          # JSON on stdin
+  zentao-cli.mjs hours task <id>
   zentao-cli.mjs log-hours task <id>       # JSON on stdin
+  zentao-cli.mjs edit-hours task <id> <effort-id> # JSON on stdin
   zentao-cli.mjs finish task <id>          # JSON on stdin`;
 }
 
@@ -702,6 +789,36 @@ export async function run(argv, { env = process.env } = {}) {
     return legacyResult(response);
   }
 
+  if (command === "hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "hours supports tasks only");
+    const id = positiveId(args[1]);
+    const variant = await workhourVariant(client, id);
+    return { records: effortRecords(variant.form) };
+  }
+
+  if (command === "edit-hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "edit-hours supports tasks only");
+    const taskId = positiveId(args[1]);
+    const effortId = positiveId(args[2]);
+    const input = await readInput();
+    const allowed = ["date", "consumed", "left", "work"];
+    if (!allowed.some((field) => Object.hasOwn(input, field))) {
+      throw new CliError("usage_error", "at least one work-hour field is required");
+    }
+    if (input.work !== undefined && typeof input.work !== "string") {
+      throw new CliError("usage_error", "work must be a string when provided");
+    }
+    const variant = await editableEffortVariant(client, effortId);
+    verifyEffortTask(variant.effort, taskId);
+    const fields = effortFields(variant.effort, input);
+    const response = await client.json(variant.route, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: formBody(fields, ["work"]),
+    });
+    return legacyResult(response);
+  }
+
   if (command === "finish") {
     if (args[0] !== "task") throw new CliError("usage_error", "finish supports tasks only");
     const id = positiveId(args[1]);