perchai-cli 2.4.28 → 2.4.29

package/README.md

@@ -19,6 +19,7 @@ Run `perch`, then use these commands inside the terminal chat:
 
 - `/help` — show commands.
 - `/status` — show cwd, auth, mode, persona, permission, and thread.
+- `/usage` — show tokens and estimated cost for this session.
 - `/cwd [dir]` — show or change the working directory.
 - `/permission [default|auto_review|take_the_wheel|plan]` — show or change permission mode.
 - `/permissions [default|auto_review|take_the_wheel|plan]` — alias for `/permission`.

package/dist/perch.mjs

@@ -75918,6 +75918,7 @@ function isTurnAbortedError(error) {
 var TURN_STOPPED_BY_USER_MESSAGE;
 var init_turnAbort = __esm({
   "features/perchTerminal/runtime/turnAbort.ts"() {
+    "use strict";
     TURN_STOPPED_BY_USER_MESSAGE = "Turn stopped by user.";
   }
 });
@@ -86691,6 +86692,7 @@ function truncateHistoryLine(value, max2) {
 }
 var init_operatorTruth = __esm({
   "features/perchTerminal/runtime/operatorTruth.ts"() {
+    "use strict";
   }
 });
 
@@ -221593,13 +221595,282 @@ var init_runFlockTurn = __esm({
   }
 });
 
+// features/perchTerminal/runtime/usage/usageCommand.ts
+function parseUsageCommand(raw) {
+  const trimmed = raw.trim();
+  if (!/^\/usage(?:\s|$)/i.test(trimmed)) return null;
+  const task = trimmed.slice("/usage".length).trim();
+  return task ? { kind: "usage", task } : { kind: "usage" };
+}
+var init_usageCommand = __esm({
+  "features/perchTerminal/runtime/usage/usageCommand.ts"() {
+    "use strict";
+  }
+});
+
+// lib/perch-ai/access.ts
+function hasPrivilegedPerchAiRole(memberships) {
+  return memberships.some(
+    (membership) => membership.status === "active" && (membership.role === "admin" || membership.role === "internal")
+  );
+}
+function canShowPerchDevTools(membershipRole) {
+  if (!membershipRole) return false;
+  return hasPrivilegedPerchAiRole([
+    {
+      role: membershipRole,
+      status: "active"
+    }
+  ]);
+}
+var init_access = __esm({
+  "lib/perch-ai/access.ts"() {
+  }
+});
+
+// features/perchTerminal/runtime/usage/usageSummary.ts
+function collectUsageRunIds(input) {
+  const runIds = /* @__PURE__ */ new Set();
+  for (const runId of input.usageRunIds ?? []) {
+    const cleaned = runId.trim();
+    if (cleaned) runIds.add(cleaned);
+  }
+  for (const message of input.recentMessages ?? []) {
+    if (message.kind !== "text" || message.role !== "assistant") continue;
+    const stateRunId = message.operatorState?.runId?.trim();
+    if (stateRunId) runIds.add(stateRunId);
+    for (const event of message.operatorState?.events ?? []) {
+      if (event.type === "turn_started" && event.runId.trim()) runIds.add(event.runId.trim());
+    }
+    for (const event of message.transcriptEvents ?? []) {
+      if (event.type === "turn_started" && event.runId.trim()) runIds.add(event.runId.trim());
+    }
+  }
+  return Array.from(runIds).slice(-250);
+}
+function summarizeInferenceUsageRows(rows, options = {}) {
+  const promptTokens = sumRows(rows, "prompt_tokens");
+  const completionTokens = sumRows(rows, "completion_tokens");
+  const cachedTokens = sumRows(rows, "cached_tokens");
+  const totalTokens = sumRows(rows, "total_tokens");
+  const estimatedCostUsd = rows.reduce((sum, row) => sum + readNumber(row.estimated_cost_usd), 0);
+  const created = rows.map((row) => row.created_at).filter((value) => typeof value === "string" && value.length > 0).sort();
+  const summary = {
+    ok: true,
+    calls: rows.length,
+    promptTokens,
+    completionTokens,
+    cachedTokens,
+    totalTokens,
+    estimatedCostUsd,
+    runCount: new Set(options.runIds?.length ? options.runIds : rows.map((row) => row.run_id).filter(Boolean)).size,
+    since: created[0] ?? null,
+    through: created[created.length - 1] ?? null,
+    showModelDetails: Boolean(options.showModelDetails)
+  };
+  if (summary.showModelDetails) {
+    summary.modelBreakdown = buildModelBreakdown(rows);
+  }
+  return summary;
+}
+function formatUsageSummaryText(summary) {
+  const lines = [
+    "Usage this session",
+    `- Calls: ${formatInteger(summary.calls)}`,
+    `- Tokens: ${formatInteger(summary.totalTokens)} total (${formatInteger(summary.promptTokens)} input \xB7 ${formatInteger(summary.completionTokens)} output${summary.cachedTokens ? ` \xB7 ${formatInteger(summary.cachedTokens)} cached` : ""})`,
+    `- Estimated cost: ${formatUsd(summary.estimatedCostUsd)}`
+  ];
+  if (summary.calls === 0) {
+    lines.push("- Nothing has been recorded for this session yet.");
+  }
+  if (summary.showModelDetails && summary.modelBreakdown?.length) {
+    lines.push("", "Internal detail:");
+    for (const row of summary.modelBreakdown.slice(0, 8)) {
+      lines.push(
+        `- ${row.label}: ${formatInteger(row.totalTokens)} tokens \xB7 ${formatUsd(row.estimatedCostUsd)} \xB7 ${formatInteger(row.calls)} calls`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function buildModelBreakdown(rows) {
+  const byModel = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const label = [row.model_option_id, row.provider, row.model].filter((value) => typeof value === "string" && value.trim()).join(" \xB7 ") || "unknown model";
+    const current = byModel.get(label) ?? {
+      label,
+      calls: 0,
+      promptTokens: 0,
+      completionTokens: 0,
+      cachedTokens: 0,
+      totalTokens: 0,
+      estimatedCostUsd: 0
+    };
+    current.calls += 1;
+    current.promptTokens += readNumber(row.prompt_tokens);
+    current.completionTokens += readNumber(row.completion_tokens);
+    current.cachedTokens += readNumber(row.cached_tokens);
+    current.totalTokens += readNumber(row.total_tokens);
+    current.estimatedCostUsd += readNumber(row.estimated_cost_usd);
+    byModel.set(label, current);
+  }
+  return Array.from(byModel.values()).sort((a, b2) => b2.estimatedCostUsd - a.estimatedCostUsd);
+}
+function sumRows(rows, key) {
+  return rows.reduce((sum, row) => sum + readNumber(row[key]), 0);
+}
+function readNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+function formatInteger(value) {
+  return Math.max(0, Math.round(value)).toLocaleString("en-US");
+}
+function formatUsd(value) {
+  if (!Number.isFinite(value) || value <= 0) return "$0.00";
+  return value < 0.01 ? `$${value.toFixed(4)}` : `$${value.toFixed(2)}`;
+}
+var init_usageSummary = __esm({
+  "features/perchTerminal/runtime/usage/usageSummary.ts"() {
+    "use strict";
+  }
+});
+
+// features/perchTerminal/runtime/usage/runUsageTurn.ts
+async function runUsageTurn(input, deps) {
+  const startedAt = Date.now();
+  const runId = input.clientRunId ?? `usage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const now14 = () => (/* @__PURE__ */ new Date()).toISOString();
+  const events = [];
+  const emit = (event) => {
+    events.push(event);
+    deps.onEvent?.(event);
+  };
+  emit({ type: "turn_started", runId, ts: now14(), isSystemNotification: false });
+  let userMessageId = null;
+  if (input.workspaceId && input.skipUserMessagePersistence !== true) {
+    userMessageId = await deps.persistUserMessage({
+      workspaceId: input.workspaceId,
+      threadId: input.threadId,
+      role: "user",
+      mode: input.chatMode,
+      content: input.trimmedInput
+    });
+    if (userMessageId) {
+      emit({ type: "user_message_persisted", messageId: userMessageId, ts: now14() });
+    }
+  }
+  const runIds = collectUsageRunIds({
+    usageRunIds: input.usageRunIds,
+    recentMessages: input.recentMessages
+  });
+  const showModelDetails = canShowPerchDevTools(input.sessionContext.membershipRole);
+  const summary = await resolveUsageSummary(input, runIds, showModelDetails);
+  const assistantText = formatUsageSummaryText(summary);
+  let assistantMessageId = null;
+  if (input.workspaceId) {
+    assistantMessageId = await deps.persistAssistantMessage({
+      workspaceId: input.workspaceId,
+      threadId: input.threadId,
+      role: "assistant",
+      mode: input.chatMode,
+      content: assistantText,
+      contentJson: {
+        slashCommand: "usage",
+        turnSummary: assistantText,
+        usageSummary: summary,
+        transcriptEvents: events
+      }
+    });
+  }
+  emit({
+    type: "assistant_response",
+    text: assistantText,
+    messageId: assistantMessageId ?? runId,
+    ts: now14()
+  });
+  const durationMs = Date.now() - startedAt;
+  emit({ type: "turn_completed", runId, durationMs, status: "completed", ts: now14() });
+  return {
+    status: "completed",
+    assistantText,
+    messageId: assistantMessageId ?? runId,
+    runId,
+    durationMs
+  };
+}
+async function resolveUsageSummary(input, runIds, showModelDetails) {
+  if (runIds.length === 0) {
+    return summarizeInferenceUsageRows([], { showModelDetails, runIds });
+  }
+  if (input.supabase && input.userId && input.workspaceId) {
+    const rows = await fetchUsageRows(input.supabase, {
+      userId: input.userId,
+      workspaceId: input.workspaceId,
+      runIds
+    });
+    return summarizeInferenceUsageRows(rows, { showModelDetails, runIds });
+  }
+  const viaServer = await fetchUsageSummaryFromServer(input, runIds);
+  if (viaServer) return viaServer;
+  return summarizeInferenceUsageRows([], { showModelDetails, runIds });
+}
+async function fetchUsageRows(supabase, input) {
+  const { data, error } = await supabase.from("perch_ai_inference_usage").select("*").eq("user_id", input.userId).eq("workspace_id", input.workspaceId).in("run_id", input.runIds).order("created_at", { ascending: true }).limit(1e3);
+  if (error) throw error;
+  return data ?? [];
+}
+async function fetchUsageSummaryFromServer(input, runIds) {
+  const appUrl = input.cliServerAppUrl?.trim();
+  const token = input.cliServerAccessToken?.trim();
+  if (!appUrl || !token || typeof fetch !== "function") return null;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5e3);
+  try {
+    const response = await fetch(`${appUrl.replace(/\/+$/, "")}/api/perch-terminal/usage`, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`
+      },
+      body: JSON.stringify({ runIds }),
+      signal: controller.signal
+    });
+    if (!response.ok) return null;
+    const payload = await response.json();
+    return payload.ok ? payload.summary : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+var init_runUsageTurn = __esm({
+  "features/perchTerminal/runtime/usage/runUsageTurn.ts"() {
+    "use strict";
+    init_access();
+    init_usageSummary();
+  }
+});
+
 // features/perchTerminal/runtime/commands/sharedSlashCommands.ts
 function parseSharedSlashCommand(raw) {
-  return parseFlockCommand(raw);
+  return parseUsageCommand(raw) ?? parseFlockCommand(raw);
+}
+function sharedSlashCommandRunsAsTurn(command) {
+  if (!command) return false;
+  if (command.kind === "usage") return true;
+  return Boolean(command.task);
 }
 function resolveTurnRunnerForPrompt(raw) {
   const parsed = parseSharedSlashCommand(raw);
   if (!parsed) return null;
+  if (parsed.kind === "usage") return runUsageTurn;
   return runFlockTurn;
 }
 var init_sharedSlashCommands = __esm({
@@ -221607,6 +221878,8 @@ var init_sharedSlashCommands = __esm({
     "use strict";
     init_flockCommand();
     init_runFlockTurn();
+    init_usageCommand();
+    init_runUsageTurn();
   }
 });
 
@@ -230206,6 +230479,7 @@ function buildCliTurnInput(input, resolved) {
     userId,
     selectedSourceId: input.selectedSourceId ?? null,
     recentMessages: input.recentMessages ?? [],
+    usageRunIds: input.usageRunIds ?? [],
     sessionContext: emptyPerchTerminalSessionContext({
       userId,
       workspaceId
@@ -285705,7 +285979,7 @@ async function runReadlineInteractivePerchCli(writer, deps, options) {
       if (!prompt) continue;
       if (prompt === "/exit" || prompt === "exit" || prompt === "quit") break;
       const sharedCommand = parseSharedSlashCommand(prompt);
-      const runsAsSharedTurn = Boolean(sharedCommand?.task);
+      const runsAsSharedTurn = sharedSlashCommandRunsAsTurn(sharedCommand);
       if (prompt.startsWith("/") && !runsAsSharedTurn) {
         try {
           const commandResult = await runInteractiveSlashCommand({
@@ -285743,6 +286017,7 @@ async function runReadlineInteractivePerchCli(writer, deps, options) {
         permissionMode: state.permissionMode,
         threadId: state.threadId,
         recentMessages: state.recentMessages,
+        usageRunIds: state.usageRunIds,
         userId: hostedContext.userId,
         workspaceId: hostedContext.workspaceId,
         permanentMemories: hostedContext.permanentMemories,
@@ -285761,6 +286036,7 @@ async function runReadlineInteractivePerchCli(writer, deps, options) {
         appendRecentMessage(state.recentMessages, "assistant", result2.assistantText.trim());
       }
       trimRecentMessages(state.recentMessages);
+      recordCliUsageRunId(state, result2.runId);
       state.contextSnapshot = result2.contextSnapshot ?? state.contextSnapshot;
       const admitted = await admitCliLearningMemory(connection, {
         prompt,
@@ -285899,7 +286175,7 @@ async function runInkInteractivePerchCli(writer, deps, options) {
             return;
           }
           const sharedTurnCommand = parseSharedSlashCommand(prompt);
-          if (prompt.startsWith("/") && !sharedTurnCommand?.task) {
+          if (prompt.startsWith("/") && !sharedSlashCommandRunsAsTurn(sharedTurnCommand)) {
             const commandWriter = {
               stdout: (text) => {
                 const clean = text.trim();
@@ -285973,6 +286249,7 @@ async function runInkInteractivePerchCli(writer, deps, options) {
               permissionMode: state.permissionMode,
               threadId: state.threadId,
               recentMessages: state.recentMessages,
+              usageRunIds: state.usageRunIds,
               userId: hostedContext.userId,
               workspaceId: hostedContext.workspaceId,
               permanentMemories: hostedContext.permanentMemories,
@@ -286349,6 +286626,7 @@ async function runInkInteractivePerchCli(writer, deps, options) {
             appendRecentMessage(state.recentMessages, "user", prompt);
             if (assistantText) appendRecentMessage(state.recentMessages, "assistant", assistantText);
             trimRecentMessages(state.recentMessages);
+            recordCliUsageRunId(state, result2.runId);
             state.contextSnapshot = result2.contextSnapshot ?? state.contextSnapshot;
             const admitted = await admitCliLearningMemory(connection, {
               prompt,
@@ -286740,6 +287018,7 @@ async function runInteractiveSlashCommand(input) {
       }
       input.state.threadId = parsed.value === "new" ? `cli-${Date.now()}` : parsed.value;
       input.state.recentMessages = [];
+      input.state.usageRunIds = [];
       input.state.contextSnapshot = null;
       input.state.persistedThreadUpdatedAt = null;
       await hydrateInteractiveCliState(input.state);
@@ -286747,6 +287026,7 @@ async function runInteractiveSlashCommand(input) {
       return "continue";
     case "clear":
       input.state.recentMessages = [];
+      input.state.usageRunIds = [];
       input.state.contextSnapshot = null;
       input.state.persistedThreadUpdatedAt = null;
       clearThreadSession(input.state.threadId);
@@ -286997,6 +287277,7 @@ function createInteractiveCliState(options) {
     cliLocalTools: options.cliLocalTools ?? true,
     appUrl: resolveCliAppUrl(options.appUrl ?? null, null),
     recentMessages: [],
+    usageRunIds: [],
     contextSnapshot: null,
     persistedThreadUpdatedAt: null
   };
@@ -287013,6 +287294,7 @@ async function syncInteractiveCliThreadScope(state, connection, options = {}) {
   if (!options.force && state.threadScopeKey === nextScopeKey) return;
   state.threadScopeKey = nextScopeKey;
   state.recentMessages = [];
+  state.usageRunIds = [];
   state.contextSnapshot = null;
   state.persistedThreadUpdatedAt = null;
   clearThreadSession(state.threadId);
@@ -287751,6 +288033,11 @@ function trimRecentMessages(messages) {
     messages.splice(0, messages.length - 30);
   }
 }
+function recordCliUsageRunId(state, runId) {
+  const cleaned = runId?.trim();
+  if (!cleaned) return;
+  state.usageRunIds = [.../* @__PURE__ */ new Set([...state.usageRunIds, cleaned])].slice(-250);
+}
 function createCliRunId() {
   return `cli-turn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -288092,6 +288379,7 @@ Commands:
   /help                         Show this list.
   /status                       Show cwd, auth, mode, persona, permission, and thread.
   /skills [name]                 List Perch core skills, or show one skill body.
+  /usage                        Show tokens and estimated cost for this session.
   /cwd [dir]                    Show or change the working directory.
   /permission [mode]            Show or set default, auto_review, take_the_wheel, or plan.
   /permissions [mode]           Alias for /permission.
@@ -288151,6 +288439,7 @@ Commands:
     ];
     PERCH_SPLASH_COMMANDS = [
       ["/status", "show auth, route, tools, and thread"],
+      ["/usage", "show session tokens and estimated cost"],
       ["/skills", "show reusable operator skills"],
       ["/persona", "swap saffron or quill"],
       ["/permission", "change autonomy for the next turns"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perchai-cli",
-  "version": "2.4.28",
+  "version": "2.4.29",
   "description": "Perch AI command-line interface",
   "bin": {
     "perch": "bin/perch"