codeep 2.16.0 → 2.18.0

package/dist/renderer/commands.js

@@ -166,6 +166,26 @@ export async function handleCommand(command, args, ctx) {
                     });
                     break;
                 }
+                if (providerId === 'modelscope') {
+                    ctx.app.notify('Fetching ModelScope catalog…');
+                    const { fetchOpenAiCompatibleModels, getApiKey: _getKey } = await import('../config/index.js');
+                    const base = 'https://api-inference.modelscope.cn/v1';
+                    const models = await fetchOpenAiCompatibleModels(base, _getKey('modelscope') || undefined);
+                    const fallback = getModelsForCurrentProvider();
+                    const available = models && models.length > 0
+                        ? models
+                        : Object.keys(fallback).map(id => ({ id, name: id, description: 'Built-in fallback' }));
+                    if (!models || models.length === 0) {
+                        ctx.app.notify('Could not fetch the ModelScope catalog. Using the built-in fallback model.');
+                    }
+                    const modelItems = available.map(m => ({ key: m.id, label: m.name, description: m.description }));
+                    const currentModel = config.get('model');
+                    ctx.app.showSelect(`Select ModelScope Model (${available.length})`, modelItems, currentModel, (item) => {
+                        config.set('model', item.key);
+                        ctx.app.notify(`Model: ${item.key}`);
+                    });
+                    break;
+                }
                 if (providerId === 'custom') {
                     const base = config.get('customBaseUrl') || 'http://localhost:8000/v1';
                     ctx.app.notify(`Fetching models from ${base}…`);
@@ -304,7 +324,7 @@ export async function handleCommand(command, args, ctx) {
             const providerId = config.get('provider');
             const model = config.get('model');
             const supported = modelSupportsReasoningEffort(providerId, model);
-            // Tiers THIS model actually distinguishes (e.g. GLM-5.2 → auto/high/max).
+            // Tiers THIS model actually distinguishes (e.g. Kimi K3 → auto/low/high/max).
             const available = availableReasoningTiers(providerId, model);
             const sub = args[0]?.toLowerCase();
             if (sub && REASONING_TIERS.includes(sub)) {
@@ -313,11 +333,11 @@ export async function handleCommand(command, args, ctx) {
                     ctx.app.notify('Thinking effort: auto — each model uses its own default.');
                 }
                 else if (!supported) {
-                    ctx.app.notify(`Thinking effort set to "${sub}", but ${model} has no graded thinking control — it will be ignored until you switch to a model that does (e.g. Opus 5, GPT-5.x, Gemini 3, DeepSeek V4, GLM-5.2).`);
+                    ctx.app.notify(`Thinking effort set to "${sub}", but ${model} has no graded thinking control — it will be ignored until you switch to a model that does (e.g. Opus 5, GPT-5.x, Gemini 3, DeepSeek V4, Kimi K3).`);
                 }
                 else {
                     // Tell the user what THIS model will actually run (the tier may
-                    // collapse onto a level the model distinguishes, e.g. low→high on GLM).
+                    // collapse onto a level the model distinguishes, e.g. medium→high on Kimi K3).
                     const resolved = resolveReasoningTier(providerId, model, sub);
                     const note = resolved === sub ? '' : ` (${model} runs this as "${resolved}")`;
                     ctx.app.notify(`Thinking effort: ${sub}${note} — sending ${JSON.stringify(reasoningParamsFor(providerId, model, sub))}.`);
@@ -346,7 +366,7 @@ export async function handleCommand(command, args, ctx) {
             if (supported)
                 tLines.push(`**Available**  ${available.join(' · ')}`);
             tLines.push('');
-            tLines.push('Sets how hard the model reasons. Each model offers only the levels it distinguishes (GLM-5.2 / DeepSeek → high · max; Gemini → low · high; Opus/Sonnet & GPT-5.x → the full set). The setting is global and clamps to the active model, so it never sends a value the API rejects. `/effort` is an alias.');
+            tLines.push('Sets how hard the model reasons. Each model offers only the levels it distinguishes (DeepSeek → high · max; Kimi K3 → low · high · max; Gemini → low · high; Opus/Sonnet & GPT-5.x → the full set). The setting is global and clamps to the active model, so it never sends a value the API rejects. `/effort` is an alias.');
             ctx.app.addMessage({ role: 'system', content: tLines.join('\n') });
             break;
         }
@@ -2261,6 +2281,7 @@ Describe what this skill does. The agent reads this body verbatim when it invoke
         // case no longer also claims 'cost' (which always hit the handler above).
         case 'stats': {
             const { getCostBreakdown, getSessionStats, formatTokenCount, getPricingTable, getCacheStats } = await import('../utils/tokenTracker.js');
+            const { formatResourceImpactReport } = await import('../utils/resourceImpact.js');
             const stats = getSessionStats();
             const content = formatStatsReport({
                 totals: stats,
@@ -2269,6 +2290,7 @@ Describe what this skill does. The agent reads this body verbatim when it invoke
                 pricing: getPricingTable(),
                 currentProvider: config.get('provider'),
                 fmt: formatTokenCount,
+                impactLines: formatResourceImpactReport(stats.totalTokens),
             });
             ctx.app.addMessage({ role: 'system', content });
             break;

package/dist/renderer/components/AgentTimeline.d.ts

@@ -0,0 +1,44 @@
+export type TimelineStageId = 'PLAN' | 'READ' | 'EDIT' | 'VERIFY' | 'SUMMARY';
+export type TimelineStageStatus = 'done' | 'active' | 'pending';
+export interface TimelineAction {
+    type: string;
+    target: string;
+    result: string;
+}
+export interface TimelineStage {
+    id: TimelineStageId;
+    status: TimelineStageStatus;
+    summary: string;
+    detail: string;
+}
+export interface TimelineFile {
+    type: 'write' | 'edit' | 'delete' | 'mkdir';
+    target: string;
+    result: string;
+}
+export interface TimelineCheck {
+    target: string;
+    result: string;
+}
+export interface AgentTimelineModel {
+    currentStage: TimelineStageId;
+    currentTarget: string;
+    stages: TimelineStage[];
+    files: TimelineFile[];
+    checks: TimelineCheck[];
+    progress: number;
+}
+export declare function buildAgentTimelineModel(args: {
+    actions: TimelineAction[];
+    thinking: string;
+    waitingForAI: boolean;
+    iteration: number;
+    maxIterations: number;
+}): AgentTimelineModel;
+export declare function formatElapsed(milliseconds: number): string;
+/**
+ * Truncate to a column budget, not a code-unit budget: Screen.write advances
+ * by charWidth, so a CJK/emoji prompt measured with String.length would draw
+ * up to twice as wide as the pane it was sized for.
+ */
+export declare function truncateMiddle(value: string, maxLength: number): string;

package/dist/renderer/components/AgentTimeline.js

@@ -0,0 +1,157 @@
+import { charWidth, stringWidth } from '../ansi.js';
+const READ_TYPES = new Set(['read', 'search', 'list', 'fetch']);
+const EDIT_TYPES = new Set(['write', 'edit', 'delete', 'mkdir']);
+function stageForAction(type) {
+    if (READ_TYPES.has(type))
+        return 'READ';
+    if (EDIT_TYPES.has(type))
+        return 'EDIT';
+    if (type === 'command')
+        return 'VERIFY';
+    return null;
+}
+function parseThinking(thinking) {
+    const separator = thinking.indexOf(':');
+    if (separator < 0)
+        return { type: '', target: '' };
+    const type = thinking.slice(0, separator).trim().toLowerCase();
+    const knownType = READ_TYPES.has(type) || EDIT_TYPES.has(type) || type === 'command';
+    if (!knownType)
+        return { type: '', target: '' };
+    return {
+        type,
+        target: thinking.slice(separator + 1).trim(),
+    };
+}
+function uniqueByTarget(items) {
+    const seen = new Set();
+    const result = [];
+    for (let index = items.length - 1; index >= 0; index--) {
+        const item = items[index];
+        if (!item.target || seen.has(item.target))
+            continue;
+        seen.add(item.target);
+        result.unshift(item);
+    }
+    return result;
+}
+export function buildAgentTimelineModel(args) {
+    const thinking = parseThinking(args.thinking);
+    const lastAction = args.actions[args.actions.length - 1];
+    const explicitStage = !args.waitingForAI ? stageForAction(thinking.type) : null;
+    const lastStage = lastAction ? stageForAction(lastAction.type) : null;
+    const currentStage = explicitStage
+        ?? lastStage
+        ?? 'PLAN';
+    const currentTarget = explicitStage
+        ? thinking.target
+        : (lastAction?.target || thinking.target);
+    const readActions = args.actions.filter(action => READ_TYPES.has(action.type));
+    const fileActions = args.actions.filter((action) => EDIT_TYPES.has(action.type));
+    const commandActions = args.actions.filter(action => action.type === 'command');
+    const stageStatus = (id, hasCompletedAction) => {
+        if (id === currentStage)
+            return 'active';
+        if (id === 'PLAN' && (args.iteration > 0 || args.actions.length > 0))
+            return 'done';
+        if (hasCompletedAction)
+            return 'done';
+        return 'pending';
+    };
+    const stages = [
+        {
+            id: 'PLAN',
+            status: stageStatus('PLAN', args.iteration > 0),
+            summary: 'Understand the request and choose the next safe step',
+            detail: args.iteration > 0 ? `${args.iteration} model step${args.iteration === 1 ? '' : 's'}` : 'Building execution plan',
+        },
+        {
+            id: 'READ',
+            status: stageStatus('READ', readActions.length > 0),
+            summary: 'Inspect project context and relevant files',
+            detail: readActions.length > 0
+                ? `${readActions.length} read/search action${readActions.length === 1 ? '' : 's'}`
+                : 'Waiting for project inspection',
+        },
+        {
+            id: 'EDIT',
+            status: stageStatus('EDIT', fileActions.some(action => action.result === 'success')),
+            summary: 'Apply focused changes to the workspace',
+            detail: fileActions.length > 0
+                ? `${uniqueByTarget(fileActions).length} file${uniqueByTarget(fileActions).length === 1 ? '' : 's'} touched`
+                : 'No file changes yet',
+        },
+        {
+            id: 'VERIFY',
+            status: stageStatus('VERIFY', commandActions.some(action => action.result === 'success')),
+            summary: 'Run commands and confirm the result',
+            detail: commandActions.length > 0
+                ? `${commandActions.length} command${commandActions.length === 1 ? '' : 's'} run`
+                : 'Checks pending',
+        },
+        {
+            id: 'SUMMARY',
+            status: 'pending',
+            summary: 'Summarize changes and next steps',
+            detail: 'Appears when the run completes',
+        },
+    ];
+    return {
+        currentStage,
+        currentTarget,
+        stages,
+        files: uniqueByTarget(fileActions),
+        checks: commandActions.slice(-4).map(action => ({
+            target: action.target,
+            result: action.result,
+        })),
+        progress: args.maxIterations > 0
+            ? Math.min(Math.max(args.iteration / args.maxIterations, 0), 1)
+            : 0,
+    };
+}
+export function formatElapsed(milliseconds) {
+    const totalSeconds = Math.max(0, Math.floor(milliseconds / 1000));
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0) {
+        return `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+    }
+    return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+}
+/**
+ * Truncate to a column budget, not a code-unit budget: Screen.write advances
+ * by charWidth, so a CJK/emoji prompt measured with String.length would draw
+ * up to twice as wide as the pane it was sized for.
+ */
+export function truncateMiddle(value, maxLength) {
+    if (maxLength <= 0)
+        return '';
+    if (stringWidth(value) <= maxLength)
+        return value;
+    if (maxLength <= 3)
+        return '.'.repeat(maxLength);
+    const chars = [...value];
+    const leftBudget = Math.ceil((maxLength - 1) / 2);
+    const rightBudget = Math.floor((maxLength - 1) / 2);
+    let head = '';
+    let headWidth = 0;
+    for (const char of chars) {
+        const w = charWidth(char);
+        if (headWidth + w > leftBudget)
+            break;
+        head += char;
+        headWidth += w;
+    }
+    let tail = '';
+    let tailWidth = 0;
+    for (let index = chars.length - 1; index >= 0; index--) {
+        const w = charWidth(chars[index]);
+        if (tailWidth + w > rightBudget)
+            break;
+        tail = chars[index] + tail;
+        tailWidth += w;
+    }
+    return `${head}…${tail}`;
+}

package/dist/renderer/components/Status.d.ts

@@ -11,6 +11,7 @@ export interface StatusInfo {
      *  when non-auto AND the active model supports a graded knob; undefined hides it. */
     reasoningEffort?: string;
     projectPath: string;
+    branch?: string;
     hasWriteAccess: boolean;
     sessionId: string;
     messageCount: number;
@@ -19,6 +20,13 @@ export interface StatusInfo {
         promptTokens: number;
         completionTokens: number;
         requestCount: number;
+        estimatedCost?: number;
+        /** `estimatedCost` minus flat-fee entries — the only spend we may show in
+         *  dollars (see providers.flatFee). */
+        billableCost?: number;
+        /** At least one entry came from a flat-fee provider, so the footer says
+         *  "in plan" instead of pricing those tokens. */
+        hasFlatFeeUsage?: boolean;
     };
 }
 /**

package/dist/renderer/main.js

@@ -16,8 +16,8 @@ import { config, loadApiKey, loadAllApiKeys, getCurrentProvider, autoSaveSession
 import { isProjectDirectory, getProjectContext, } from '../utils/project.js';
 import { getCurrentVersion, checkForUpdates, getUpdateInstructions } from '../utils/update.js';
 import { getProviderList, isNoApiKeyProvider, resolveReasoningTier } from '../config/providers.js';
-import { getSessionStats, getCostBreakdown } from '../utils/tokenTracker.js';
-import { isGitRepository } from '../utils/git.js';
+import { getSessionStats, getCostBreakdown, getRecordCount } from '../utils/tokenTracker.js';
+import { getGitStatus, isGitRepository } from '../utils/git.js';
 import { reportStats, syncSession, generateProjectId } from '../utils/codeepCloud.js';
 import { checkApiRateLimit } from '../utils/ratelimit.js';
 import { expandFileAndFolderMentions, expandGitMentions } from '../utils/mentions.js';
@@ -27,6 +27,9 @@ import { logAppError } from '../utils/logger.js';
 import { executeAgentTask, runAgentTask, } from './agentExecution.js';
 // ─── Global state ─────────────────────────────────────────────────────────────
 let projectPath = process.cwd();
+/** Cached header branch. Resolved on first use so `--version`/`--help` never
+ *  shell out to git, and cached because getStatus runs on every render frame. */
+let gitBranchCache = null;
 let projectContext = null;
 let hasWriteAccess = false;
 let sessionId = getCurrentSessionId();
@@ -34,6 +37,14 @@ let app;
 /** Human-readable session name derived from the first user message */
 let sessionDisplayName = null;
 const addedFiles = new Map();
+/** Branch shown in the persistent header, re-read whenever the project moved
+ *  or an agent run finished (an agent can check out a different branch). */
+function getHeaderBranch() {
+    if (!gitBranchCache || gitBranchCache.path !== projectPath) {
+        gitBranchCache = { path: projectPath, branch: getGitStatus(projectPath).branch };
+    }
+    return gitBranchCache.branch;
+}
 /** Derive a short display name from a user message (first ~5 words, max 48 chars). */
 export function deriveSessionName(message) {
     const clean = message.replace(/\s+/g, ' ').trim();
@@ -55,7 +66,10 @@ function makeCtx() {
         sessionDisplayName: sessionDisplayName ?? undefined,
         abortController: agentAbortController,
         isAgentRunning: () => isAgentRunningFlag,
-        setAgentRunning: (v) => { isAgentRunningFlag = v; },
+        // A finished run may have switched branches — drop the cache so the next
+        // header render re-reads it.
+        setAgentRunning: (v) => { isAgentRunningFlag = v; if (!v)
+            gitBranchCache = null; },
         setAbortController: (ctrl) => { agentAbortController = ctrl; },
         formatAddedFilesContext,
         handleCommand: (cmd, args) => dispatchCommand(cmd, args, makeCtx()),
@@ -77,7 +91,7 @@ function getStatus() {
     const stats = getSessionStats();
     // Show the thinking-effort tier beside the model. Resolve the (global) tier
     // to what THIS model actually runs — e.g. a global 'low' shows as 'high' on
-    // GLM-5.2, which only grades high|max. 'auto'/unsupported → hidden.
+    // Kimi K3, where the global medium tier resolves to high. 'auto'/unsupported → hidden.
     const resolved = resolveReasoningTier(provider.id, config.get('model'), config.get('reasoningEffort'));
     const reasoningEffort = resolved !== 'auto' ? resolved : undefined;
     return {
@@ -87,6 +101,7 @@ function getStatus() {
         agentMode: config.get('agentMode') || 'off',
         reasoningEffort,
         projectPath,
+        branch: getHeaderBranch(),
         hasWriteAccess,
         sessionId,
         messageCount: app ? app.getMessages().length : 0,
@@ -95,6 +110,9 @@ function getStatus() {
             promptTokens: stats.totalPromptTokens,
             completionTokens: stats.totalCompletionTokens,
             requestCount: stats.requestCount,
+            estimatedCost: stats.estimatedCost,
+            billableCost: stats.billableCost,
+            hasFlatFeeUsage: stats.hasFlatFeeUsage,
         },
     };
 }
@@ -162,6 +180,47 @@ async function handleSubmit(message) {
         runAgentTask(message, false, ctx, () => pendingInteractiveContext, (v) => { pendingInteractiveContext = v; });
         return;
     }
+    // Captured before the turn starts so the delta can be reported from both the
+    // success path and the catch. An aborted or failed turn has still burned
+    // tokens, and gracefulShutdown no longer sends a cumulative catch-all that
+    // would have swept them up later.
+    const tokenReportStart = getRecordCount();
+    // Cloud stats are append-only events, so report only this prompt's delta.
+    // Sending the full session accumulator after every prompt makes totals grow
+    // 1× + 2× + 3× and is the source of the inflated dashboard token count.
+    // pingWhenEmpty sends a bare session event when nothing was spent — wanted on
+    // the success path, not when the turn failed before reaching the model.
+    const reportTurnStats = (pingWhenEmpty) => {
+        const sharedFields = {
+            sessionId,
+            sessionName: sessionDisplayName || sessionId,
+            messageCount: app.getMessages().length,
+            cliVersion: getCurrentVersion(),
+            projectName: projectContext?.name,
+            projectId: projectPath ? generateProjectId(projectPath) : undefined,
+            language: projectContext?.type,
+            isGit: isGitRepository(process.cwd()),
+        };
+        const costBreakdown = getCostBreakdown(tokenReportStart);
+        if (costBreakdown.length === 0) {
+            if (pingWhenEmpty) {
+                reportStats({ ...sharedFields, model: config.get('model'), provider: config.get('provider') });
+            }
+            return;
+        }
+        for (const entry of costBreakdown) {
+            reportStats({
+                ...sharedFields,
+                model: entry.model,
+                provider: entry.provider,
+                inputTokens: entry.promptTokens || undefined,
+                outputTokens: entry.completionTokens || undefined,
+                cacheCreationTokens: entry.cacheCreationTokens || undefined,
+                cacheReadTokens: entry.cacheReadTokens || undefined,
+                estimatedCost: entry.estimatedCost || undefined,
+            });
+        }
+    };
     try {
         app.startStreaming();
         const history = app.getChatHistory();
@@ -226,7 +285,10 @@ async function handleSubmit(message) {
             language: projectContext?.type,
             isGit: isGitRepository(process.cwd()),
         };
-        const costBreakdown = getCostBreakdown();
+        // Cloud stats are append-only events, so report only this prompt's delta.
+        // Sending the full session accumulator after every prompt makes totals grow
+        // 1× + 2× + 3× and is the source of the inflated dashboard token count.
+        const costBreakdown = getCostBreakdown(tokenReportStart);
         if (costBreakdown.length > 0) {
             for (const entry of costBreakdown) {
                 reportStats({
@@ -938,31 +1000,18 @@ async function gracefulShutdown() {
         return;
     const messages = app.getMessages();
     autoSaveSession(messages, projectPath);
-    const { syncSessionAsync, reportStatsAsync, generateProjectId } = require('../utils/codeepCloud.js');
-    const tokenStats = getSessionStats();
+    const { syncSessionAsync, generateProjectId } = require('../utils/codeepCloud.js');
     const projectId = projectPath ? generateProjectId(projectPath) : undefined;
-    await Promise.all([
-        syncSessionAsync({
-            sessionId,
-            sessionName: sessionId,
-            projectName: projectContext?.name,
-            messages,
-        }),
-        reportStatsAsync({
-            model: config.get('model'),
-            provider: config.get('provider'),
-            sessionId,
-            sessionName: sessionId,
-            messageCount: messages.length,
-            projectName: projectContext?.name,
-            projectId,
-            inputTokens: tokenStats.totalPromptTokens || undefined,
-            outputTokens: tokenStats.totalCompletionTokens || undefined,
-            cacheCreationTokens: tokenStats.totalCacheCreationTokens || undefined,
-            cacheReadTokens: tokenStats.totalCacheReadTokens || undefined,
-            estimatedCost: tokenStats.estimatedCost || undefined,
-        }),
-    ]);
+    // Successful manual and agent turns report their token deltas immediately.
+    // Re-sending the cumulative session total here would count every token a
+    // second time when the append-only dashboard endpoint stores this event.
+    await syncSessionAsync({
+        sessionId,
+        sessionName: sessionDisplayName || sessionId,
+        projectName: projectContext?.name,
+        projectId,
+        messages,
+    });
 }
 // ─── Last-resort crash handlers ───────────────────────────────────────────────
 // Without these, a stray throw or rejected promise (deep in the agent loop or a

package/dist/utils/agent.js

@@ -163,7 +163,7 @@ export function buildPausedResult(kind, ctx) {
     };
 }
 const DEFAULT_OPTIONS = {
-    // Modern models (GLM-5.1, Claude 4.5, GPT-4.1) complete typical coding tasks in
+    // Modern models (GLM-5.2, Claude 5, GPT-5.x) complete typical coding tasks in
     // 3–8 iterations. The old cap of 100 mostly let broken loops wander for minutes
     // before giving up. 25 is still generous — covers multi-file refactors — without
     // turning small fixes into marathons. Users can still raise this via /settings.

package/dist/utils/agents.d.ts

@@ -18,7 +18,7 @@
  *   name: reviewer
  *   description: Reviews a diff for correctness & security
  *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
- *   model: glm-5.1            # optional provider/model or model override
+ *   model: glm-5.2            # optional provider/model or model override
  *   personality: security     # optional — reuse a personality preset
  *   maxIterations: 15         # optional budget
  *   ---

package/dist/utils/agents.js

@@ -18,7 +18,7 @@
  *   name: reviewer
  *   description: Reviews a diff for correctness & security
  *   tools: [read_file, search_code, execute_command]   # allowlist; omit = all
- *   model: glm-5.1            # optional provider/model or model override
+ *   model: glm-5.2            # optional provider/model or model override
  *   personality: security     # optional — reuse a personality preset
  *   maxIterations: 15         # optional budget
  *   ---

package/dist/utils/checkpoints.d.ts

@@ -27,7 +27,7 @@
  *   "createdAt": "...",
  *   "sessionId": "session-2026-05-18-...",
  *   "provider": "z.ai",
- *   "model": "glm-5.1",
+ *   "model": "glm-5.2",
  *   "messages": [ ... ],
  *   "filesTouched": ["src/a.ts", "src/b.ts"],
  *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo

package/dist/utils/checkpoints.js

@@ -27,7 +27,7 @@
  *   "createdAt": "...",
  *   "sessionId": "session-2026-05-18-...",
  *   "provider": "z.ai",
- *   "model": "glm-5.1",
+ *   "model": "glm-5.2",
  *   "messages": [ ... ],
  *   "filesTouched": ["src/a.ts", "src/b.ts"],
  *   "gitHead": "abcdef0"        // optional, recorded only if cwd is a git repo

package/dist/utils/resourceImpact.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Broad operational-impact estimate for hosted LLM inference.
+ *
+ * This is deliberately a range, not a meter reading:
+ * - 0.3–1.5 J/token covers published H100 inference benchmarks.
+ * - 0.27–1.08 L/kWh spans efficient direct cooling and a full-stack
+ *   production estimate that also captures associated infrastructure.
+ *
+ * Model size, batching, context length, hardware, data-centre location and
+ * provider efficiency can move the real result outside this band. Local
+ * models are included because their token usage still consumes electricity,
+ * but Codeep cannot measure the device directly.
+ */
+export interface ResourceImpactEstimate {
+    energyWhLow: number;
+    energyWhHigh: number;
+    waterMlLow: number;
+    waterMlHigh: number;
+}
+export declare function estimateResourceImpact(totalTokens: number): ResourceImpactEstimate;
+export declare function formatResourceImpact(estimate: ResourceImpactEstimate): {
+    energy: string;
+    water: string;
+};
+export declare function formatResourceImpactReport(totalTokens: number): string[];

package/dist/utils/resourceImpact.js

@@ -0,0 +1,54 @@
+/**
+ * Broad operational-impact estimate for hosted LLM inference.
+ *
+ * This is deliberately a range, not a meter reading:
+ * - 0.3–1.5 J/token covers published H100 inference benchmarks.
+ * - 0.27–1.08 L/kWh spans efficient direct cooling and a full-stack
+ *   production estimate that also captures associated infrastructure.
+ *
+ * Model size, batching, context length, hardware, data-centre location and
+ * provider efficiency can move the real result outside this band. Local
+ * models are included because their token usage still consumes electricity,
+ * but Codeep cannot measure the device directly.
+ */
+const ENERGY_JOULES_PER_TOKEN = { low: 0.3, high: 1.5 };
+const WATER_LITRES_PER_KWH = { low: 0.27, high: 1.08 };
+export function estimateResourceImpact(totalTokens) {
+    const tokens = Number.isFinite(totalTokens) ? Math.max(0, totalTokens) : 0;
+    const energyWhLow = (tokens * ENERGY_JOULES_PER_TOKEN.low) / 3600;
+    const energyWhHigh = (tokens * ENERGY_JOULES_PER_TOKEN.high) / 3600;
+    return {
+        energyWhLow,
+        energyWhHigh,
+        waterMlLow: (energyWhLow / 1000) * WATER_LITRES_PER_KWH.low * 1000,
+        waterMlHigh: (energyWhHigh / 1000) * WATER_LITRES_PER_KWH.high * 1000,
+    };
+}
+function compact(value) {
+    if (value === 0)
+        return '0';
+    if (value < 0.01)
+        return value.toFixed(3);
+    if (value < 1)
+        return value.toFixed(2);
+    if (value < 10)
+        return value.toFixed(1);
+    return Math.round(value).toLocaleString('en-US');
+}
+export function formatResourceImpact(estimate) {
+    const energy = estimate.energyWhHigh >= 1000
+        ? `${compact(estimate.energyWhLow / 1000)}–${compact(estimate.energyWhHigh / 1000)} kWh`
+        : `${compact(estimate.energyWhLow)}–${compact(estimate.energyWhHigh)} Wh`;
+    const water = estimate.waterMlHigh >= 1000
+        ? `${compact(estimate.waterMlLow / 1000)}–${compact(estimate.waterMlHigh / 1000)} L`
+        : `${compact(estimate.waterMlLow)}–${compact(estimate.waterMlHigh)} mL`;
+    return { energy, water };
+}
+export function formatResourceImpactReport(totalTokens) {
+    const formatted = formatResourceImpact(estimateResourceImpact(totalTokens));
+    return [
+        '### Estimated compute impact',
+        `**Electricity:** ${formatted.energy}  ·  **Cooling water:** ${formatted.water}`,
+        '_Research-based range, not a provider measurement. Actual usage varies widely by model, hardware, batching, context length, data-centre location, and cooling system._',
+    ];
+}

package/dist/utils/tokenTracker.d.ts

@@ -19,6 +19,12 @@ export interface SessionTokenStats {
     totalTokens: number;
     requestCount: number;
     estimatedCost: number;
+    /** `estimatedCost` minus every flat-fee entry — the only figure we may show
+     *  as a dollar total, since flat-fee tokens carry no per-token charge. */
+    billableCost: number;
+    /** True when at least one entry came from a flat-fee provider, so callers can
+     *  say "included in plan" instead of silently dropping that usage. */
+    hasFlatFeeUsage: boolean;
     /** Anthropic prompt caching: total tokens written to cache this session. */
     totalCacheCreationTokens: number;
     /** Anthropic prompt caching: total tokens read from cache this session. */