@ycodium-ai/agent-grok 0.2.2678 → 0.2.2694

package/README.md

@@ -47,6 +47,17 @@ Facts:
   exist (the card's `extraEnv` `$absentPath` entry), unless the instance sets
   `GROK_AUTH_PATH` itself. The login file in the account directory is left untouched.
   Settings also gives a new instance that sets these variables its own account directory.
+- Usage (ADR-0034), per instance, read only when the user asks:
+  - Quota: `ExecutorInstance.usage.readQuota` reads the weekly credit window from
+    `cli-chat-proxy.grok.com/v1/billing?format=credits` with the x.ai token in the instance's
+    account directory (only entries whose issuer starts with `https://auth.x.ai::`), through
+    `host.fetch`. An instance that sets `GROK_MODELS_BASE_URL` reports `customEndpoint` without
+    reading credentials; a signed-out instance with only `XAI_API_KEY` reports `unsupportedLogin`
+    (xAI's balance API needs a separate management key). Credentials are never refreshed or written.
+  - Tokens: no `readTokenUsage`. The turn's usage comes from the `session/prompt` reply's
+    `_meta.usage` and is booked on `turn.completed.payload.tokenUsage` (the host writes
+    `turn.usage`). The reply arrives a few milliseconds after `prompt_complete`, so
+    `turn.completed` waits up to 300 ms for it and carries no usage when it never comes.
 
 Develop with `vp run --filter @ycodium-ai/agent-grok typecheck`, `build`, and `test`.
 

package/dist/index.js

@@ -156,7 +156,7 @@ var GROK_CARD = {
 // src/grokInstance.ts
 import * as NodeCrypto2 from "node:crypto";
 import * as NodeOS2 from "node:os";
-import * as NodePath2 from "node:path";
+import * as NodePath4 from "node:path";
 import { mergeLaunchEnv } from "@ycodium-ai/plugin-api/executor";
 import { nodeStreamsFromHandle as nodeStreamsFromHandle2 } from "@ycodium-ai/plugin-api/process-stdin";
 
@@ -1429,14 +1429,14 @@ function codePointLength(str) {
   const units = str.length;
   if (!highSurrogate.test(str))
     return units;
-  let count = units;
+  let count2 = units;
   for (let i = 0; i < units - 1; i++) {
     if ((str.charCodeAt(i) & 64512) === 55296 && (str.charCodeAt(i + 1) & 64512) === 56320) {
-      count--;
+      count2--;
       i++;
     }
   }
-  return count;
+  return count2;
 }
 function getLengthableOrigin(input2) {
   if (Array.isArray(input2))
@@ -5791,8 +5791,8 @@ function az_default() {
 }
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/locales/be.js
-function getBelarusianPlural(count, one, few, many) {
-  const absCount = Math.abs(count);
+function getBelarusianPlural(count2, one, few, many) {
+  const absCount = Math.abs(count2);
   const lastDigit = absCount % 10;
   const lastTwoDigits = absCount % 100;
   if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
@@ -8439,8 +8439,8 @@ function hu_default() {
 }
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/locales/hy.js
-function getArmenianPlural(count, one, many) {
-  return Math.abs(count) === 1 ? one : many;
+function getArmenianPlural(count2, one, many) {
+  return Math.abs(count2) === 1 ? one : many;
 }
 function withDefiniteArticle(word) {
   if (!word)
@@ -9524,8 +9524,8 @@ function ko_default() {
 }
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/locales/lt.js
-var capitalizeFirstCharacter = (text2) => {
-  return text2.charAt(0).toUpperCase() + text2.slice(1);
+var capitalizeFirstCharacter = (text3) => {
+  return text3.charAt(0).toUpperCase() + text3.slice(1);
 };
 function getUnitTypeFromNumber(number4) {
   const abs = Math.abs(number4);
@@ -11178,8 +11178,8 @@ function ro_default() {
 }
 
 // ../../node_modules/.pnpm/zod@4.6.5/node_modules/zod/v4/locales/ru.js
-function getRussianPlural(count, one, few, many) {
-  const absCount = Math.abs(count);
+function getRussianPlural(count2, one, few, many) {
+  const absCount = Math.abs(count2);
   const lastDigit = absCount % 10;
   const lastTwoDigits = absCount % 100;
   if (lastTwoDigits >= 11 && lastTwoDigits <= 19) {
@@ -22120,9 +22120,9 @@ var Connection = class {
       return;
     }
     const responseBatch = isResponseBatch(batch);
-    const responseCount = responseBatch ? 0 : batch.reduce((count, message) => count + (isNotificationMessage(message) ? 0 : 1), 0);
+    const responseCount = responseBatch ? 0 : batch.reduce((count2, message) => count2 + (isNotificationMessage(message) ? 0 : 1), 0);
     let remaining = responseCount;
-    let remainingNotifications = batch.reduce((count, message) => count + (isNotificationMessage(message) ? 1 : 0), 0);
+    let remainingNotifications = batch.reduce((count2, message) => count2 + (isNotificationMessage(message) ? 1 : 0), 0);
     let responseSent = false;
     const responses = [];
     const sendResponsesIfReady = async () => {
@@ -23934,8 +23934,8 @@ function createAcpConnection(options) {
     }
     await dispatchMessage(value);
   };
-  const pullEnqueued = async (count) => {
-    for (let i = 0; i < count; i += 1) {
+  const pullEnqueued = async (count2) => {
+    for (let i = 0; i < count2; i += 1) {
       const { value, done } = await incoming.read();
       if (done || value === void 0) {
         return;
@@ -24937,6 +24937,13 @@ function parseSessionModeState(sessionResponse) {
     availableModes
   };
 }
+function acpCommandsToSlashCommands(commands) {
+  return commands.map((command) => ({
+    name: command.name,
+    ...command.description === void 0 ? {} : { description: command.description },
+    ...command.inputHint === void 0 ? {} : { input: { hint: command.inputHint } }
+  }));
+}
 function parseAvailableCommandsUpdate(params) {
   const update = params.update;
   if (update["sessionUpdate"] !== "available_commands_update") {
@@ -25036,11 +25043,11 @@ function extractToolCallCommand(rawInput, title) {
 }
 var TOOL_CALL_CONTENT_MAX_CHARS = 8e3;
 var TOOL_CALL_CONTENT_TRUNCATION_MARKER = "[Earlier output truncated]\n\n";
-function boundToolCallOutputText(text2) {
-  if (text2.length <= TOOL_CALL_CONTENT_MAX_CHARS) {
-    return text2;
+function boundToolCallOutputText(text3) {
+  if (text3.length <= TOOL_CALL_CONTENT_MAX_CHARS) {
+    return text3;
   }
-  const tail = text2.slice(text2.length - TOOL_CALL_CONTENT_MAX_CHARS);
+  const tail = text3.slice(text3.length - TOOL_CALL_CONTENT_MAX_CHARS);
   return `${TOOL_CALL_CONTENT_TRUNCATION_MARKER}${tail}`;
 }
 var RAW_OUTPUT_TEXT_FIELDS = ["content", "stdout", "stderr", "output"];
@@ -25072,9 +25079,9 @@ function extractTextContentFromToolCallContent(content) {
   const typed = content;
   const chunks = [];
   for (const entry of typed) {
-    const text2 = toolCallContentText(entry)?.trim();
-    if (text2) {
-      chunks.push(text2);
+    const text3 = toolCallContentText(entry)?.trim();
+    if (text3) {
+      chunks.push(text3);
     }
   }
   if (chunks.length === 0) {
@@ -25325,11 +25332,11 @@ function parseSessionUpdateEvent(params) {
       const contentType = content?.["type"];
       const streamKind = kind === "agent_thought_chunk" ? "reasoning_text" : "assistant_text";
       if (contentType === "text") {
-        const text2 = typeof content?.["text"] === "string" ? content["text"] : "";
-        if (text2.length > 0) {
+        const text3 = typeof content?.["text"] === "string" ? content["text"] : "";
+        if (text3.length > 0) {
           events.push({
             _tag: "ContentDelta",
-            text: text2,
+            text: text3,
             streamKind,
             rawPayload: params
           });
@@ -25362,9 +25369,9 @@ function parseSessionUpdateEvent(params) {
     case "compaction_summary_chunk": {
       const compactionId = readAcpText(upd, "compactionId");
       const content = isRecord5(upd["content"]) ? upd["content"] : void 0;
-      const text2 = content?.["type"] === "text" ? content["text"] : void 0;
-      if (compactionId === void 0 || typeof text2 !== "string" || text2.length === 0) break;
-      events.push({ _tag: "CompactionSummaryChunk", compactionId, text: text2 });
+      const text3 = content?.["type"] === "text" ? content["text"] : void 0;
+      if (compactionId === void 0 || typeof text3 !== "string" || text3.length === 0) break;
+      events.push({ _tag: "CompactionSummaryChunk", compactionId, text: text3 });
       break;
     }
     default:
@@ -25388,24 +25395,7 @@ function filterMcpServersByAgentCapabilities(mcpServers, agentCapabilities) {
   });
 }
 
-// ../../packages/ycodium-acp-executor/src/vendor-hooks.ts
-var defaultVendorHooks = {
-  completedStopReason: (response) => response.stopReason
-};
-
-// ../../packages/ycodium-acp-executor/src/executor.ts
-var DEFAULT_CANCEL_GRACE_MS = 5e3;
-var userInputAnswerOptionId = (question, answers) => {
-  const answer = answers[question.id];
-  const selected = typeof answer === "string" ? answer : Array.isArray(answer) && answer.length === 1 && typeof answer[0] === "string" ? answer[0] : void 0;
-  return selected !== void 0 && question.options.some((option) => option.id === selected) ? selected : void 0;
-};
-function defaultNowIso() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function defaultRandomId() {
-  return NodeCrypto.randomUUID();
-}
+// ../../packages/ycodium-acp-executor/src/model-selection.ts
 function normalizeModelId(value) {
   return value?.trim() || void 0;
 }
@@ -25424,6 +25414,25 @@ function modelSelectionStateFromSetup(setup) {
     advertisedModelValues: strategy === "config-option" ? modelConfigOption === void 0 ? [] : collectSessionConfigOptionValues(modelConfigOption) : collectSessionModelIds(sessionModels)
   };
 }
+
+// ../../packages/ycodium-acp-executor/src/vendor-hooks.ts
+var defaultVendorHooks = {
+  completedStopReason: (response) => response.stopReason
+};
+
+// ../../packages/ycodium-acp-executor/src/executor.ts
+var DEFAULT_CANCEL_GRACE_MS = 5e3;
+var userInputAnswerOptionId = (question, answers) => {
+  const answer = answers[question.id];
+  const selected = typeof answer === "string" ? answer : Array.isArray(answer) && answer.length === 1 && typeof answer[0] === "string" ? answer[0] : void 0;
+  return selected !== void 0 && question.options.some((option) => option.id === selected) ? selected : void 0;
+};
+function defaultNowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function defaultRandomId() {
+  return NodeCrypto.randomUUID();
+}
 function createAcpExecutor(options) {
   const hooks = { ...defaultVendorHooks, ...options.hooks };
   const cancelGraceMs = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS;
@@ -25633,6 +25642,7 @@ function createAcpExecutor(options) {
     const commands = parseAvailableCommandsUpdate(params);
     if (commands !== void 0) {
       availableCommands = commands;
+      options.onAvailableCommands?.(commands);
     }
     if (sessionLoadInFlight) {
       droppedReplayUpdates += parsed.events.filter((event) => event._tag !== "ModeChanged").length;
@@ -26748,13 +26758,13 @@ function parseCliVersion(output2) {
 }
 async function collectCappedText(stream, maxBytes) {
   const decoder = new TextDecoder();
-  let text2 = "";
+  let text3 = "";
   let total = 0;
   for await (const chunk of stream) {
     total += chunk.byteLength;
-    if (total <= maxBytes) text2 += decoder.decode(chunk, { stream: true });
+    if (total <= maxBytes) text3 += decoder.decode(chunk, { stream: true });
   }
-  return { text: text2 + decoder.decode(), overflowed: total > maxBytes };
+  return { text: text3 + decoder.decode(), overflowed: total > maxBytes };
 }
 async function collectProbeProcess(child, input2) {
   try {
@@ -26975,6 +26985,233 @@ var readGrokAccount = (homePath) => {
   };
 };
 
+// src/grokQuota.ts
+import * as NodeFS2 from "node:fs";
+import * as NodePath2 from "node:path";
+import {
+  parseRetryAfterMs
+} from "@ycodium-ai/plugin-api/usage";
+var GROK_USAGE_URL = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+var GROK_ISSUER_PREFIX = "https://auth.x.ai::";
+var AUTH_FILE_NAME2 = "auth.json";
+var QUOTA_TIMEOUT_MS = 1e4;
+var asObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+var asString3 = (value) => typeof value === "string" && value.length > 0 ? value : null;
+var asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+var parseJson = (raw) => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+var extractGrokToken = (auth) => {
+  const record3 = asObject(auth);
+  if (record3 === null) return null;
+  for (const [key, value] of Object.entries(record3)) {
+    if (!key.startsWith(GROK_ISSUER_PREFIX)) continue;
+    const nestedKey = asString3(asObject(value)?.["key"]);
+    if (nestedKey !== null) return nestedKey;
+  }
+  return null;
+};
+var clampPercent = (value) => Math.min(100, Math.max(0, value));
+var grokQuotaWindows = (body) => {
+  const config2 = asObject(asObject(body)?.["config"]);
+  const productUsage = config2?.["productUsage"];
+  const fromProduct = Array.isArray(productUsage) ? asNumber(
+    productUsage.map(asObject).find((row) => row !== null && asString3(row["product"]) === "GrokBuild")?.["usagePercent"]
+  ) : null;
+  const usedPercent = asNumber(config2?.["creditUsagePercent"]) ?? fromProduct;
+  return usedPercent === null ? [] : [
+    {
+      id: "weekly",
+      label: { key: "usage.window.weekly" },
+      usedPercent: clampPercent(usedPercent),
+      resetsAt: asString3(asObject(config2?.["currentPeriod"])?.["end"]) ?? asString3(config2?.["billingPeriodEnd"])
+    }
+  ];
+};
+var createGrokUsage = (input2) => {
+  const now = input2.now ?? Date.now;
+  const authPath = NodePath2.join(input2.homePath, AUTH_FILE_NAME2);
+  const readQuota = async (request) => {
+    const baseUrlKey = GROK_CARD.modelConnectivity.baseUrlEnvKey;
+    if (baseUrlKey !== void 0 && (input2.environment[baseUrlKey]?.trim() ?? "") !== "") {
+      return { status: "unavailable", reason: "customEndpoint" };
+    }
+    let token = null;
+    try {
+      token = extractGrokToken(parseJson(NodeFS2.readFileSync(authPath, "utf8")));
+    } catch {
+      token = null;
+    }
+    if (token === null) {
+      const apiKey = input2.environment["XAI_API_KEY"]?.trim() ?? "";
+      return {
+        status: "unavailable",
+        reason: apiKey.length > 0 ? "unsupportedLogin" : "missingCredentials"
+      };
+    }
+    let response;
+    try {
+      response = await input2.fetch(GROK_USAGE_URL, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/json",
+          "X-XAI-Token-Auth": "xai-grok-cli"
+        },
+        signal: AbortSignal.any([
+          ...request.signal === void 0 ? [] : [request.signal],
+          AbortSignal.timeout(QUOTA_TIMEOUT_MS)
+        ])
+      });
+    } catch {
+      return { status: "unavailable", reason: "unreachable" };
+    }
+    if (response.status === 401 || response.status === 403) {
+      return { status: "unavailable", reason: "authRejected" };
+    }
+    if (response.status === 429) {
+      const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"), now());
+      return {
+        status: "unavailable",
+        reason: "rateLimited",
+        ...retryAfterMs === null ? {} : { retryAfterMs }
+      };
+    }
+    if (!response.ok) return { status: "unavailable", reason: "unreachable" };
+    let body;
+    try {
+      body = parseJson(await response.text());
+    } catch {
+      return { status: "unavailable", reason: "unreachable" };
+    }
+    if (asObject(body) === null) return { status: "unavailable", reason: "unreachable" };
+    return {
+      status: "available",
+      windows: grokQuotaWindows(body),
+      balances: [],
+      accountKey: authPath
+    };
+  };
+  return { readQuota };
+};
+
+// src/grokTurnUsage.ts
+var USAGE_GRACE_MS = 300;
+var isRecord8 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var count = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+var text = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+var readModelTotals = (entry) => {
+  if (!isRecord8(entry)) return void 0;
+  const input2 = count(entry["inputTokens"]);
+  const cachedInputTokens = count(entry["cachedReadTokens"]);
+  const cacheCreationTokens = count(entry["cacheCreationTokens"]);
+  const outputTokens = count(entry["outputTokens"]);
+  return {
+    uncachedInputTokens: Math.max(0, input2 - cachedInputTokens - cacheCreationTokens),
+    cachedInputTokens,
+    cacheCreationTokens,
+    outputTokens,
+    reasoningTokens: Math.min(count(entry["reasoningTokens"]), outputTokens)
+  };
+};
+var sumOf = (totals) => totals.uncachedInputTokens + totals.cachedInputTokens + totals.cacheCreationTokens + totals.outputTokens;
+var grokTurnUsageReport = (promptResponse) => {
+  const meta3 = isRecord8(promptResponse) ? promptResponse["_meta"] : void 0;
+  const usage = isRecord8(meta3) ? meta3["usage"] : void 0;
+  if (!isRecord8(meta3) || !isRecord8(usage)) return void 0;
+  const perModel = /* @__PURE__ */ new Map();
+  const modelUsage = usage["modelUsage"];
+  if (isRecord8(modelUsage)) {
+    for (const [model, entry] of Object.entries(modelUsage)) {
+      const totals = readModelTotals(entry);
+      if (totals !== void 0 && model.trim().length > 0) perModel.set(model.trim(), totals);
+    }
+  }
+  if (perModel.size === 0) {
+    const fallbackModel = text(meta3["modelId"]);
+    const totals = readModelTotals(usage);
+    if (fallbackModel === void 0 || totals === void 0) return void 0;
+    perModel.set(fallbackModel, totals);
+  }
+  let dominant;
+  const sum = {
+    uncachedInputTokens: 0,
+    cachedInputTokens: 0,
+    cacheCreationTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0
+  };
+  for (const [model, totals] of perModel) {
+    sum.uncachedInputTokens += totals.uncachedInputTokens;
+    sum.cachedInputTokens += totals.cachedInputTokens;
+    sum.cacheCreationTokens += totals.cacheCreationTokens;
+    sum.outputTokens += totals.outputTokens;
+    sum.reasoningTokens += totals.reasoningTokens;
+    const size = sumOf(totals);
+    if (dominant === void 0 || size > dominant.size) dominant = { model, size };
+  }
+  if (dominant === void 0 || sumOf(sum) === 0) return void 0;
+  const sessionId = text(meta3["sessionId"]);
+  return {
+    provider: "grok",
+    model: dominant.model,
+    totals: sum,
+    ...sessionId === void 0 ? {} : { sessionId }
+  };
+};
+var createGrokTurnUsageCollector = (base) => {
+  const pastKeys = [];
+  let promptKey;
+  let report;
+  let seen = false;
+  let wake;
+  const mark = () => {
+    seen = true;
+    wake?.();
+  };
+  const observe = (response) => {
+    const key = base.responseKey?.(response);
+    if (key !== void 0 && key !== promptKey && pastKeys.includes(key)) return;
+    report = grokTurnUsageReport(response) ?? report;
+    mark();
+  };
+  const settlement = {
+    ...base,
+    requestFields: (key) => {
+      if (promptKey !== void 0) pastKeys.push(promptKey);
+      if (pastKeys.length > 16) pastKeys.shift();
+      promptKey = key;
+      report = void 0;
+      seen = false;
+      return base.requestFields(key);
+    },
+    responseKey: (response) => {
+      observe(response);
+      return base.responseKey?.(response);
+    }
+  };
+  const attach = async (event) => {
+    if (event.type !== "turn.completed" || !isRecord8(event.payload)) return event;
+    if (event.payload["state"] === "completed" && !seen) {
+      await new Promise((resolve2) => {
+        const timer = setTimeout(resolve2, USAGE_GRACE_MS);
+        wake = () => {
+          clearTimeout(timer);
+          resolve2();
+        };
+      });
+      wake = void 0;
+    }
+    const taken = report;
+    report = void 0;
+    return taken === void 0 ? event : { ...event, payload: { ...event.payload, tokenUsage: taken } };
+  };
+  return { settlement, attach };
+};
+
 // src/grokPlanGate.ts
 var XAI_EXIT_PLAN_MODE_METHODS = [
   "_x.ai/exit_plan_mode",
@@ -26983,16 +27220,16 @@ var XAI_EXIT_PLAN_MODE_METHODS = [
 var GROK_PLAN_APPROVE_OPTION_ID = "approved";
 var GROK_PLAN_ABANDON_OPTION_ID = "abandoned";
 var GROK_EMPTY_PLAN_TEXT = "The agent exited plan mode without writing a plan.";
-var isRecord8 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord9 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var trimmed = (value) => {
   if (typeof value !== "string") return void 0;
-  const text2 = value.trim();
-  return text2.length > 0 ? text2 : void 0;
+  const text3 = value.trim();
+  return text3.length > 0 ? text3 : void 0;
 };
 function parseXAiExitPlanModeParams(params) {
-  const candidates = [params, ...isRecord8(params) ? [params["params"]] : []];
+  const candidates = [params, ...isRecord9(params) ? [params["params"]] : []];
   for (const candidate of candidates) {
-    if (!isRecord8(candidate)) continue;
+    if (!isRecord9(candidate)) continue;
     const toolCallId = trimmed(candidate["toolCallId"]);
     if (toolCallId === void 0) continue;
     return { toolCallId, planContent: trimmed(candidate["planContent"]) };
@@ -27033,18 +27270,18 @@ function makeXAiExitPlanModeResponse(params, resolution) {
   if (resolution.kind === "cancelled") return abandoned();
   const answer = resolution.answers[params.toolCallId];
   const selected = typeof answer === "string" ? answer : Array.isArray(answer) && answer.length === 1 && typeof answer[0] === "string" ? answer[0] : void 0;
-  const text2 = trimmed(selected);
-  if (text2 === void 0) return abandoned();
-  if (text2 === GROK_PLAN_APPROVE_OPTION_ID) return { outcome: "approved" };
-  if (text2 === GROK_PLAN_ABANDON_OPTION_ID) return abandoned();
-  return { outcome: "request_changes", feedback: text2 };
+  const text3 = trimmed(selected);
+  if (text3 === void 0) return abandoned();
+  if (text3 === GROK_PLAN_APPROVE_OPTION_ID) return { outcome: "approved" };
+  if (text3 === GROK_PLAN_ABANDON_OPTION_ID) return abandoned();
+  return { outcome: "request_changes", feedback: text3 };
 }
 
 // src/grokBackgroundTasks.ts
 var record2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
-var text = (value) => typeof value === "string" ? value.trim() || void 0 : void 0;
+var text2 = (value) => typeof value === "string" ? value.trim() || void 0 : void 0;
 var lifecycle = (status, exitCode) => {
-  switch (text(status)?.toLowerCase()) {
+  switch (text2(status)?.toLowerCase()) {
     case "pending":
     case "running":
       return "running";
@@ -27098,19 +27335,19 @@ function buildGrokBackgroundTaskEvents(input2) {
     });
   };
   if (output2["type"] === "Monitor" && toolCallStatus === "completed") {
-    const id = text(output2["taskId"]);
+    const id = text2(output2["taskId"]);
     if (id) {
-      start(id, "monitor", text(record2(input2.rawInput)["description"]) ?? "Monitor", toolCallId);
+      start(id, "monitor", text2(record2(input2.rawInput)["description"]) ?? "Monitor", toolCallId);
     }
   } else if (output2["type"] === "BackgroundTaskStarted") {
-    const id = text(output2["task_id"]) ?? text(output2["taskId"]);
-    const command = text(output2["command"]);
+    const id = text2(output2["task_id"]) ?? text2(output2["taskId"]);
+    const command = text2(output2["command"]);
     if (id && command) start(id, "shell", command.split("\n")[0].slice(0, 200), toolCallId);
   } else if (output2["type"] === "TaskOutput" || output2["type"] === "KillTask") {
     const results = record2(output2["MultiResult"])["results"];
     for (const value of Array.isArray(results) ? results : [output2["Result"]]) {
       const result = record2(value);
-      const id = text(result["task_id"]);
+      const id = text2(result["task_id"]);
       if (!id) continue;
       if (output2["type"] === "KillTask") {
         const task2 = tasks.get(id);
@@ -27119,11 +27356,11 @@ function buildGrokBackgroundTaskEvents(input2) {
         }
         continue;
       }
-      const command = text(result["command"]);
+      const command = text2(result["command"]);
       const status = lifecycle(result["status"], result["exit_code"]);
       if (!command || !status || command.startsWith("[subagent:")) continue;
       const task = start(id, /^\[monitor[:\]]/.test(command) ? "monitor" : "shell", command);
-      const summary = text(result["output"])?.split("\n").find((line) => line.trim())?.trim();
+      const summary = text2(result["output"])?.split("\n").find((line) => line.trim())?.trim();
       if (status === "running") {
         events.push({
           type: "task.progress",
@@ -27140,11 +27377,11 @@ function buildGrokBackgroundTaskEvents(input2) {
 
 // src/grokSupport.ts
 import { modelSelectionStringOption } from "@ycodium-ai/plugin-api/executor";
-var isRecord9 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord10 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var trimmed2 = (value) => {
   if (typeof value !== "string") return void 0;
-  const text2 = value.trim();
-  return text2.length > 0 ? text2 : void 0;
+  const text3 = value.trim();
+  return text3.length > 0 ? text3 : void 0;
 };
 function grokReasoningEffortArgs(effort) {
   const value = effort?.trim();
@@ -27255,28 +27492,28 @@ function grokRuntimeModeCaveat(nativeModeId) {
 }
 var GROK_REASONING_OPTION_ID = "reasoningEffort";
 function resolveGrokAuthMethodId(initializeResult) {
-  const authMethods = isRecord9(initializeResult) ? initializeResult["authMethods"] : void 0;
+  const authMethods = isRecord10(initializeResult) ? initializeResult["authMethods"] : void 0;
   if (!Array.isArray(authMethods)) return void 0;
   for (const method of authMethods) {
-    if (isRecord9(method) && method["id"] === "cached_token") return "cached_token";
+    if (isRecord10(method) && method["id"] === "cached_token") return "cached_token";
   }
   return void 0;
 }
 var positive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.trunc(value) : void 0;
 function grokPromptUsage(promptResponse) {
-  if (!isRecord9(promptResponse)) return void 0;
+  if (!isRecord10(promptResponse)) return void 0;
   const meta3 = promptResponse["_meta"];
-  if (!isRecord9(meta3)) return void 0;
+  if (!isRecord10(meta3)) return void 0;
   const usedTokens = positive(meta3["totalTokens"]);
   if (usedTokens === void 0) return void 0;
   return { usedTokens, modelId: trimmed2(meta3["modelId"]) };
 }
 function grokModelState(initializeResult) {
-  if (!isRecord9(initializeResult)) return void 0;
+  if (!isRecord10(initializeResult)) return void 0;
   const meta3 = initializeResult["_meta"];
-  if (!isRecord9(meta3)) return void 0;
+  if (!isRecord10(meta3)) return void 0;
   const modelState = meta3["modelState"];
-  if (!isRecord9(modelState)) return void 0;
+  if (!isRecord10(modelState)) return void 0;
   const availableModels = modelState["availableModels"];
   if (!Array.isArray(availableModels)) return void 0;
   return { currentModelId: trimmed2(modelState["currentModelId"]), availableModels };
@@ -27286,11 +27523,11 @@ function grokAdvertisedModels(initializeResult) {
   if (state === void 0) return [];
   const models = [];
   for (const entry of state.availableModels) {
-    if (!isRecord9(entry)) continue;
+    if (!isRecord10(entry)) continue;
     const modelId = trimmed2(entry["modelId"]);
     if (modelId === void 0) continue;
     const modelMeta = entry["_meta"];
-    const contextWindow = isRecord9(modelMeta) ? positive(modelMeta["totalContextTokens"]) : void 0;
+    const contextWindow = isRecord10(modelMeta) ? positive(modelMeta["totalContextTokens"]) : void 0;
     models.push({
       modelId,
       name: trimmed2(entry["name"]),
@@ -27305,7 +27542,7 @@ var XAI_ASK_USER_QUESTION_METHODS = [
   "x.ai/ask_user_question"
 ];
 var readOption = (value) => {
-  if (!isRecord9(value)) return void 0;
+  if (!isRecord10(value)) return void 0;
   const label = typeof value["label"] === "string" ? value["label"] : void 0;
   if (label === void 0) return void 0;
   return {
@@ -27316,7 +27553,7 @@ var readOption = (value) => {
   };
 };
 var readQuestion = (value) => {
-  if (!isRecord9(value)) return void 0;
+  if (!isRecord10(value)) return void 0;
   const question = typeof value["question"] === "string" ? value["question"] : void 0;
   if (question === void 0) return void 0;
   const optionsRaw = value["options"];
@@ -27332,9 +27569,9 @@ var readQuestion = (value) => {
   };
 };
 function parseXAiAskUserQuestionParams(params) {
-  const candidates = [params, ...isRecord9(params) ? [params["params"]] : []];
+  const candidates = [params, ...isRecord10(params) ? [params["params"]] : []];
   for (const candidate of candidates) {
-    if (!isRecord9(candidate)) continue;
+    if (!isRecord10(candidate)) continue;
     const questionsRaw = candidate["questions"];
     if (!Array.isArray(questionsRaw)) continue;
     const questions = questionsRaw.flatMap((entry) => {
@@ -27360,12 +27597,12 @@ function extractXAiAskUserQuestions(params) {
 var answerValues = (answer) => {
   if (Array.isArray(answer)) {
     return answer.flatMap((entry) => {
-      const text3 = trimmed2(entry);
-      return text3 === void 0 ? [] : [text3];
+      const text4 = trimmed2(entry);
+      return text4 === void 0 ? [] : [text4];
     });
   }
-  const text2 = trimmed2(answer);
-  return text2 === void 0 ? [] : [text2];
+  const text3 = trimmed2(answer);
+  return text3 === void 0 ? [] : [text3];
 };
 function makeXAiAskUserQuestionResponse(params, answers) {
   const normalized = params.questions.flatMap((question) => {
@@ -27409,21 +27646,21 @@ var XAI_PROMPT_COMPLETE_METHOD = "_x.ai/session/prompt_complete";
 var GROK_RATE_LIMIT_MESSAGE = "Grok usage limit reached or rate limited. Try again later.";
 var grokAgentResultMessage = (value) => {
   if (typeof value === "string") return trimmed2(value);
-  return isRecord9(value) ? trimmed2(value["message"]) : void 0;
+  return isRecord10(value) ? trimmed2(value["message"]) : void 0;
 };
 var grokPromptSettlement = {
   // 关联 id 双写 promptId 与 requestId（宿主 XAiAcpExtension 同款）：
   // agent 认回哪个键是它的事，两个都给才不猜版本。
   requestFields: (promptKey) => ({ _meta: { promptId: promptKey, requestId: promptKey } }),
   responseKey: (response) => {
-    if (!isRecord9(response)) return void 0;
+    if (!isRecord10(response)) return void 0;
     const meta3 = response["_meta"];
-    if (!isRecord9(meta3)) return void 0;
+    if (!isRecord10(meta3)) return void 0;
     return trimmed2(meta3["promptId"]) ?? trimmed2(meta3["requestId"]);
   },
   fromNotification: (method, params) => {
     if (method !== XAI_PROMPT_COMPLETE_METHOD) return void 0;
-    if (!isRecord9(params)) return void 0;
+    if (!isRecord10(params)) return void 0;
     const sessionId = params["sessionId"];
     if (typeof sessionId !== "string") return void 0;
     const stopReason = trimmed2(params["stopReason"]);
@@ -27441,10 +27678,11 @@ var grokPromptSettlement = {
 
 // src/grokSkills.ts
 import * as NodeOS from "node:os";
+import * as NodePath3 from "node:path";
 var INSPECT_TIMEOUT_MS = 15e3;
 var MAX_INSPECT_OUTPUT_BYTES = 4 * 1024 * 1024;
 var GROK_INSPECT_ARGS = ["inspect", "--json"];
-var isRecord10 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isRecord11 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var trimmedString = (value) => typeof value === "string" ? value.trim() : "";
 function parseGrokInspectSkills(stdout) {
   let parsed;
@@ -27453,13 +27691,13 @@ function parseGrokInspectSkills(stdout) {
   } catch {
     return [];
   }
-  const entries = isRecord10(parsed) ? parsed["skills"] : void 0;
+  const entries = isRecord11(parsed) ? parsed["skills"] : void 0;
   if (!Array.isArray(entries)) return [];
   const byName = /* @__PURE__ */ new Map();
   for (const entry of entries) {
-    if (!isRecord10(entry)) continue;
+    if (!isRecord11(entry)) continue;
     const name = trimmedString(entry["name"]);
-    const source = isRecord10(entry["source"]) ? entry["source"] : void 0;
+    const source = isRecord11(entry["source"]) ? entry["source"] : void 0;
     const path = trimmedString(source?.["path"]);
     if (name.length === 0 || path.length === 0) continue;
     const scope = trimmedString(source?.["type"]);
@@ -27474,27 +27712,51 @@ function parseGrokInspectSkills(stdout) {
   }
   return [...byName.values()].toSorted((left, right) => left.name.localeCompare(right.name));
 }
+var runGrokInspect = async (input2) => {
+  const { recipe, host, env, cwd } = input2;
+  const handle = await host.process.spawn({
+    program: recipe.binaryPath,
+    args: GROK_INSPECT_ARGS,
+    cwd,
+    owner: { bindingId: host.bindingId },
+    ...Object.keys(env).length > 0 ? { env } : {}
+  });
+  const run = await collectProbeProcess(handle, {
+    timeoutMs: INSPECT_TIMEOUT_MS,
+    maxOutputBytes: MAX_INSPECT_OUTPUT_BYTES,
+    what: "grok inspect"
+  });
+  if (run.exitCode !== 0 || run.stdout === void 0) {
+    throw new Error(`grok inspect exited with ${String(run.exitCode)}`);
+  }
+  const parsed = JSON.parse(run.stdout);
+  if (!isRecord11(parsed) || !Array.isArray(parsed["skills"])) {
+    throw new Error("grok inspect output has no skills list");
+  }
+  return parseGrokInspectSkills(run.stdout);
+};
 async function probeGrokSkills(input2) {
-  const { recipe, host, env } = input2;
   try {
-    const handle = await host.process.spawn({
-      program: recipe.binaryPath,
-      args: GROK_INSPECT_ARGS,
-      cwd: NodeOS.homedir(),
-      owner: { bindingId: host.bindingId },
-      ...Object.keys(env).length > 0 ? { env } : {}
-    });
-    const run = await collectProbeProcess(handle, {
-      timeoutMs: INSPECT_TIMEOUT_MS,
-      maxOutputBytes: MAX_INSPECT_OUTPUT_BYTES,
-      what: "grok inspect"
-    });
-    if (run.exitCode !== 0 || run.stdout === void 0) return [];
-    return parseGrokInspectSkills(run.stdout);
+    return await runGrokInspect({ ...input2, cwd: NodeOS.homedir() });
   } catch {
     return [];
   }
 }
+async function inspectGrokWorkspace(input2) {
+  const skills = await runGrokInspect(input2);
+  const watched = /* @__PURE__ */ new Set([
+    // 项目技能目录的位置没有实测，这两处只是触发重查的提示，不影响答案本身。
+    NodePath3.join(input2.cwd, ".grok", "skills"),
+    NodePath3.join(input2.cwd, ".agents", "skills")
+  ]);
+  for (const skill of skills) {
+    watched.add(skill.path);
+    const skillDirectory = NodePath3.dirname(skill.path);
+    watched.add(skillDirectory);
+    watched.add(NodePath3.dirname(skillDirectory));
+  }
+  return { skills, watchPaths: [...watched] };
+}
 
 // src/probeModels.ts
 import {
@@ -27603,14 +27865,14 @@ var hasDeviceCode = (output2) => deviceCodeUrl(output2) !== void 0 && deviceCode
 function expandHomePath(value) {
   if (value === "~") return NodeOS2.homedir();
   if (value.startsWith("~/") || value.startsWith("~\\")) {
-    return NodePath2.join(NodeOS2.homedir(), value.slice(2));
+    return NodePath4.join(NodeOS2.homedir(), value.slice(2));
   }
   return value;
 }
 function resolveGrokHomePath(value) {
   const trimmed3 = value.trim();
-  if (trimmed3.length === 0) return NodePath2.join(NodeOS2.homedir(), ".grok");
-  return NodePath2.resolve(expandHomePath(trimmed3));
+  if (trimmed3.length === 0) return NodePath4.join(NodeOS2.homedir(), ".grok");
+  return NodePath4.resolve(expandHomePath(trimmed3));
 }
 function probeGrokAccount(accountPath) {
   const resolved = resolveGrokHomePath(accountPath);
@@ -27629,12 +27891,12 @@ function grokContinuationKey(recipe) {
 function resolveAccountHomePath(recipe, configuredHome) {
   const fromEnvironment = recipe.environment["GROK_HOME"]?.trim();
   if (fromEnvironment !== void 0 && fromEnvironment.length > 0) {
-    return NodePath2.resolve(expandHomePath(fromEnvironment));
+    return NodePath4.resolve(expandHomePath(fromEnvironment));
   }
   return resolveGrokHomePath(configuredHome);
 }
 function absentPath() {
-  return NodePath2.join(
+  return NodePath4.join(
     NodeOS2.tmpdir(),
     `ycodium-grok-no-auth-${NodeCrypto2.randomUUID()}`,
     "auth.json"
@@ -27758,6 +28020,23 @@ var createGrokInstance = (config2, host) => {
   };
   const instance = {
     probe,
+    // 项目里的技能：探测在 home 下跑 inspect 只看得到整机的；这里在项目目录里再跑一次。
+    workspaceInventory: ({ cwd }) => {
+      if (recipe.binaryPath.length === 0) {
+        return Promise.reject(new Error("Grok program path is not configured"));
+      }
+      const configuredHome = recipe.homePath;
+      return inspectGrokWorkspace({
+        recipe,
+        host,
+        cwd,
+        env: buildSpawnEnv(
+          recipe,
+          resolveGrokHomePath(configuredHome),
+          configuredHome.trim().length > 0
+        )
+      });
+    },
     // 有意不处理 input.readOnlyDirectories：grok 的 read_file 在每一档都不弹审批、
     // 绝对路径读到哪儿都一样（实测表见 grokSupport.ts），附件目录无需放行。
     startSession: async (input2, signal) => {
@@ -27801,6 +28080,7 @@ var createGrokInstance = (config2, host) => {
       const requestedModelId = modelIdFromSelection(input2.modelSelection);
       let initializeResult;
       const backgroundTasks = /* @__PURE__ */ new Map();
+      const turnUsage = createGrokTurnUsageCollector(grokPromptSettlement);
       const executor = createAcpExecutor({
         readable,
         writable,
@@ -27811,11 +28091,16 @@ var createGrokInstance = (config2, host) => {
         providerInstanceId: host.instanceId,
         clientInfo: GROK_CLIENT_INFO,
         log: host.log,
+        // agent 自己宣告的斜杠命令按会话报给宿主，输入区的 / 菜单才有它们。
+        onAvailableCommands: (commands) => host.reportSessionInventory?.({
+          threadId: input2.threadId,
+          slashCommands: acpCommandsToSlashCommands(commands)
+        }),
         // 等 `initialize` 回来再挑认证方式：能不能用 `cached_token`，只有 agent
         // 播报的 `authMethods` 说了算（见 resolveGrokAuthMethodId）。
         authMethodId: resolveGrokAuthMethodId,
         hooks: {
-          promptSettlement: grokPromptSettlement,
+          promptSettlement: turnUsage.settlement,
           onToolCallUpdated: (update) => buildGrokBackgroundTaskEvents({
             tasks: backgroundTasks,
             toolCallId: update.toolCallId,
@@ -27867,7 +28152,7 @@ var createGrokInstance = (config2, host) => {
       });
       const forwarding = (async () => {
         for await (const event of executor.events) {
-          events.push(event);
+          events.push(await turnUsage.attach(event));
         }
       })();
       try {
@@ -28014,6 +28299,12 @@ var createGrokInstance = (config2, host) => {
       return { threadId, turns: booked.turns };
     },
     events,
+    // 额度读实例自己的账号目录与连接（与它的 CLI 同源）；token 走编排账本，见 grokTurnUsage.ts。
+    usage: createGrokUsage({
+      homePath: resolveAccountHomePath(recipe, recipe.homePath),
+      environment: recipe.environment,
+      fetch: host.fetch
+    }),
     continuationKey: grokContinuationKey(recipe),
     dispose: async () => {
       if (disposed) return;
@@ -28054,9 +28345,9 @@ var createGrokInstance = (config2, host) => {
         const stdoutText = (async () => {
           const decoder = new TextDecoder();
           for await (const chunk of handle.stdout) {
-            const text2 = decoder.decode(chunk, { stream: true });
-            collected.push(text2);
-            host.log.info("sign-in output", { text: text2 });
+            const text3 = decoder.decode(chunk, { stream: true });
+            collected.push(text3);
+            host.log.info("sign-in output", { text: text3 });
             if (onCodeFound !== void 0 && hasDeviceCode(collected.join(""))) {
               onCodeFound();
               onCodeFound = void 0;

package/locales/en.json

@@ -10,5 +10,10 @@
       "description": "Sessions and the `grok login` credentials live here, so providers sharing this directory can pick up each other's threads and providers with different directories cannot. Leave empty to use the CLI's default (~/.grok).",
       "placeholder": "e.g. ~/.grok-work"
     }
+  },
+  "usage": {
+    "window": {
+      "weekly": "Weekly"
+    }
   }
 }

package/locales/zh-CN.json

@@ -10,5 +10,10 @@
       "description": "会话和 `grok login` 的凭据都保存在这里，因此共用同一目录的 provider 可以接手彼此的会话，目录不同的则不能。留空则使用该命令行工具的默认目录（~/.grok）。",
       "placeholder": "例如 ~/.grok-work"
     }
+  },
+  "usage": {
+    "window": {
+      "weekly": "每周"
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ycodium-ai/agent-grok",
-  "version": "0.2.2678",
+  "version": "0.2.2694",
   "description": "Grok executor: grok CLI over Agent Client Protocol stdio.",
   "keywords": [
     "ycodium",
@@ -21,9 +21,9 @@
     "@types/node": "24.12.4",
     "esbuild": "0.28.1",
     "vite-plus": "0.2.2",
-    "ycodium-acp-executor": "0.2.2678",
+    "ycodium-acp-executor": "0.2.2694",
     "ycodium-executor-testing": "0.0.0",
-    "@ycodium-ai/plugin-api": "0.2.2678"
+    "@ycodium-ai/plugin-api": "0.2.2694"
   },
   "ycodium": {
     "plugin": "./dist/index.js",