praxis-agent 0.16.0 → 0.17.0

package/dist/cli.js

@@ -7,15 +7,17 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { randomUUID } from 'node:crypto';
 import { ClaudeSessionService, } from './application/session-service.js';
+import { ClaudeCostStateStore } from './persistence/claude-cost-state-store.js';
 import { agentColorMessage, parseAgentColorInput, } from './compatibility/claude/agent-color.js';
 import { ClaudeConditionalRuleResolver, ClaudeContextAssembler, } from './compatibility/claude/context.js';
 import { loadClaudeDynamicContext } from './compatibility/claude/dynamic-context.js';
 import { createClaudePrSessionFilter, filterClaudePrLinkedSessions, } from './compatibility/claude/pr-links.js';
 import { isClaudeSessionId, resolveClaudePaths, } from './compatibility/claude/paths.js';
-import { loadClaudeContextResources, loadClaudeSettings, loadClaudeSharedResources, resolveClaudeProjectMemoryDirectory, } from './compatibility/claude/shared-resources.js';
+import { loadClaudeContextResources, loadClaudeSettings, loadClaudeSharedResources, resolveClaudeProjectIdentity, resolveClaudeProjectMemoryDirectory, } from './compatibility/claude/shared-resources.js';
 import { AgentRunCancelledError, } from './core/runtime.js';
 import { persistTuiPermissionUpdates } from './cli/tui/permission-settings.js';
 import { loadClaudeReleaseNotes } from './cli/tui/release-notes.js';
+import { canonicalClaudeCostModelName, formatCostSummary, } from './cli/tui/cost-summary.js';
 import { projectTuiHooks, } from './cli/tui/hook-settings.js';
 import { DEFAULT_CLI_CONTROLS, resolveCliControls } from './cli/controls.js';
 import { applyRuntimeSettingDefaults, loadRuntimeSettings, runtimeSettingsSystemPrompt, } from './cli/tui/runtime-settings.js';
@@ -47,7 +49,7 @@ import { WorkspaceContext } from './application/session-worktree.js';
 import { launchTmuxWorktree } from './platform/tmux-worktree.js';
 import { claudeSandboxRuntime } from './sandbox/claude-sandbox-runtime.js';
 import { claudeSandboxTempDirectory, loadClaudeSandboxSettings, } from './sandbox/claude-sandbox-settings.js';
-import { createErrorResult, createSuccessResult, matchHeadlessColorCommand, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
+import { createErrorResult, createSuccessResult, isHeadlessCostCommand, matchHeadlessColorCommand, parseCliInvocation, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
 import { describeClaudePlugin, initClaudePlugin, installClaudePlugin, loadClaudePlugins, readPluginRegistry, setClaudePluginEnabled, uninstallClaudePlugin, updateClaudePlugin, validateClaudePlugin, } from './plugins/claude-plugin-runtime.js';
 import { addClaudeMarketplace, disableAllNativePlugins, installClaudeMarketplacePlugin, listClaudeMarketplaceAvailablePlugins, listNativePluginRecords, readClaudeKnownMarketplaces, removeClaudeMarketplace, setNativePluginEnabled, saveClaudePluginConfig, uninstallNativePlugin, updateClaudeMarketplace, updateNativePlugin, validateClaudeMarketplace, } from './plugins/claude-plugin-marketplace.js';
 import { executeClaudePluginEvalCommand, PLUGIN_EVAL_HELP, } from './plugins/claude-plugin-eval.js';
@@ -770,12 +772,17 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
         };
         provider = providerForMainModel(model);
     }
+    const costStateStore = new ClaudeCostStateStore({
+        statePath: claudeStatePath,
+        projectIdentity: await resolveClaudeProjectIdentity({ cwd }),
+    });
     const options = {
         configRoot,
         cwd,
         claudeVersion,
         eventSink: runtimeEventSink,
         sessionPersistence: cli.sessionPersistence,
+        costStateStore,
         explicitModel: interactiveModel !== undefined || controls.model !== undefined,
         explicitSystemPrompt: cli.systemPrompt !== undefined,
         agentInitialPromptHandledExternally: interactive,
@@ -1293,6 +1300,9 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
             ...(provider?.capabilities.contextWindowTokens === undefined
                 ? {}
                 : { contextWindowTokens: provider.capabilities.contextWindowTokens }),
+            ...(provider?.capabilities.maxOutputTokens === undefined
+                ? {}
+                : { maxOutputTokens: provider.capabilities.maxOutputTokens }),
             tools: toolNames,
             mcpServers: mcpTools.serverStatuses(),
             permissionMode: cli.dangerouslySkipPermissions
@@ -1382,6 +1392,7 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                 }
             },
             sessions: () => service.sessions(),
+            costSnapshot: (sessionId) => service.costSnapshot(sessionId),
             slashCommands: () => extensions.slashCommandDefinitions().map((definition) => ({
                 name: definition.name,
                 description: definition.description,
@@ -1433,14 +1444,32 @@ const createDefaultService = async ({ eventSink, requireProvider, hooksOnly = fa
                 if (failure !== undefined)
                     throw failure;
             },
-            runtimeInfo: () => ({
-                ...runtimeInfo,
-                cwd: workspace.cwd(),
-                model: service.model() ??
-                    provider?.model ??
-                    runtimeEnvironment.PRAXIS_MODEL ??
-                    'unknown',
-            }),
+            runtimeInfo: () => {
+                // Drop the static capability snapshot so a fallback-routed provider
+                // never reports stale context/output limits, then re-derive them from
+                // the currently active provider.
+                const staticInfo = {
+                    ...runtimeInfo,
+                    cwd: workspace.cwd(),
+                    model: service.model() ??
+                        provider?.model ??
+                        runtimeEnvironment.PRAXIS_MODEL ??
+                        'unknown',
+                };
+                delete staticInfo.contextWindowTokens;
+                delete staticInfo.maxOutputTokens;
+                return {
+                    ...staticInfo,
+                    ...(provider?.capabilities.contextWindowTokens === undefined
+                        ? {}
+                        : {
+                            contextWindowTokens: provider.capabilities.contextWindowTokens,
+                        }),
+                    ...(provider?.capabilities.maxOutputTokens === undefined
+                        ? {}
+                        : { maxOutputTokens: provider.capabilities.maxOutputTokens }),
+                };
+            },
             promptSuggestion: (sessionId, suggestionSignal) => service.promptSuggestion(sessionId, suggestionSignal),
         };
     }
@@ -3266,6 +3295,104 @@ function isCancellation(error, signal) {
         signal?.aborted === true ||
         (error instanceof DOMException && error.name === 'AbortError'));
 }
+function emptyCostSnapshot(sessionId) {
+    return {
+        sessionId,
+        totalCostUsd: 0,
+        apiDurationMs: 0,
+        apiDurationWithoutRetriesMs: 0,
+        toolDurationMs: 0,
+        wallDurationMs: 0,
+        linesAdded: 0,
+        linesRemoved: 0,
+        modelUsage: {},
+        hasUnknownModelCost: false,
+    };
+}
+/**
+ * Computes the validated nonnegative delta between a current cost snapshot and
+ * a process-local baseline. The baseline represents restored historic state or
+ * the empty state before this process touched the session, so the delta shows
+ * only same-process accumulation. Counter regression and incompatible model
+ * state are rejected explicitly rather than clamped.
+ */
+function costSummaryDelta(current, baseline) {
+    const base = baseline ?? emptyCostSnapshot(current.sessionId);
+    const assertAtLeast = (label, value, floor) => {
+        if (value < floor) {
+            throw new Error(`Cost state regression: ${label} fell below the process baseline`);
+        }
+        return value - floor;
+    };
+    const totalCostUsd = assertAtLeast('total cost', current.totalCostUsd, base.totalCostUsd);
+    const apiDurationMs = assertAtLeast('API duration', current.apiDurationMs, base.apiDurationMs);
+    const wallDurationMs = assertAtLeast('wall duration', current.wallDurationMs, base.wallDurationMs);
+    const linesAdded = assertAtLeast('lines added', current.linesAdded, base.linesAdded);
+    const linesRemoved = assertAtLeast('lines removed', current.linesRemoved, base.linesRemoved);
+    const modelUsage = [];
+    for (const [model, usage] of Object.entries(current.modelUsage)) {
+        const baseUsage = base.modelUsage[model];
+        if (baseUsage === undefined) {
+            modelUsage.push({
+                model,
+                canonicalName: canonicalClaudeCostModelName(model),
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                cacheReadInputTokens: usage.cacheReadInputTokens,
+                cacheCreationInputTokens: usage.cacheCreationInputTokens,
+                webSearchRequests: usage.webSearchRequests,
+                costUsd: usage.costUsd,
+            });
+            continue;
+        }
+        const inputTokens = usage.inputTokens - baseUsage.inputTokens;
+        const outputTokens = usage.outputTokens - baseUsage.outputTokens;
+        const cacheReadInputTokens = usage.cacheReadInputTokens - baseUsage.cacheReadInputTokens;
+        const cacheCreationInputTokens = usage.cacheCreationInputTokens - baseUsage.cacheCreationInputTokens;
+        const webSearchRequests = usage.webSearchRequests - baseUsage.webSearchRequests;
+        const costUsd = usage.costUsd - baseUsage.costUsd;
+        if (inputTokens < 0 ||
+            outputTokens < 0 ||
+            cacheReadInputTokens < 0 ||
+            cacheCreationInputTokens < 0 ||
+            webSearchRequests < 0 ||
+            costUsd < 0) {
+            throw new Error(`Cost state regression for model ${model}: counters fell below the process baseline`);
+        }
+        if (inputTokens === 0 &&
+            outputTokens === 0 &&
+            cacheReadInputTokens === 0 &&
+            cacheCreationInputTokens === 0 &&
+            webSearchRequests === 0 &&
+            costUsd === 0) {
+            continue;
+        }
+        modelUsage.push({
+            model,
+            canonicalName: canonicalClaudeCostModelName(model),
+            inputTokens,
+            outputTokens,
+            cacheReadInputTokens,
+            cacheCreationInputTokens,
+            webSearchRequests,
+            costUsd,
+        });
+    }
+    for (const model of Object.keys(base.modelUsage)) {
+        if (current.modelUsage[model] === undefined) {
+            throw new Error(`Cost state regression for model ${model}: model disappeared from the session tracker`);
+        }
+    }
+    return {
+        totalCostUsd,
+        apiDurationMs,
+        wallDurationMs,
+        linesAdded,
+        linesRemoved,
+        hasUnknownModelCost: current.hasUnknownModelCost && !base.hasUnknownModelCost,
+        modelUsage,
+    };
+}
 function helpActionAt(argv, commandIndex, actions) {
     for (let index = commandIndex + 1; index < argv.length; index += 1) {
         const value = argv[index];
@@ -3951,6 +4078,9 @@ async function execute(argv, io, dependencies, signal) {
     const firstTurnIsLocalColor = !invocation.disableSlashCommands &&
         firstHeadlessPrompt !== undefined &&
         matchHeadlessColorCommand(firstHeadlessPrompt) !== undefined;
+    const firstTurnIsLocalCost = !invocation.disableSlashCommands &&
+        firstHeadlessPrompt !== undefined &&
+        isHeadlessCostCommand(firstHeadlessPrompt);
     const service = await dependencies.createService({
         eventSink: outputFormat === 'stream-json' && !invocation.legacyJson
             ? (event) => {
@@ -3975,7 +4105,10 @@ async function execute(argv, io, dependencies, signal) {
                     }
                 }
                 : eventSink(io, outputFormat, invocation.legacyJson),
-        requireProvider: !streamInputExhausted && !firstTurnIsLocalColor && headlessTurnReached,
+        requireProvider: !streamInputExhausted &&
+            !firstTurnIsLocalColor &&
+            !firstTurnIsLocalCost &&
+            headlessTurnReached,
         ...(retryInterruptedTools ? { approveRecovery: () => true } : {}),
         ...(streamIterator ? { approveTool: approveStreamTool } : {}),
         ...(streamIterator ? { onElicitation: respondStreamElicitation } : {}),
@@ -3984,6 +4117,12 @@ async function execute(argv, io, dependencies, signal) {
         ...(agent ? { agent } : {}),
         controls: invocation,
     });
+    const costBaselines = new Map();
+    const ensureCostBaseline = async (sessionId) => {
+        if (!service.costSnapshot || costBaselines.has(sessionId))
+            return;
+        costBaselines.set(sessionId, await service.costSnapshot(sessionId));
+    };
     try {
         const lifecycleTrigger = invocation.init
             ? 'init'
@@ -4101,6 +4240,7 @@ async function execute(argv, io, dependencies, signal) {
             signal?.addEventListener('abort', forwardAbort, { once: true });
             currentTurnAbort = streamIterator ? turnAbort : undefined;
             const runSignal = streamIterator ? turnAbort.signal : signal;
+            await ensureCostBaseline(activeSessionId);
             if (streamOutput) {
                 streamOutput.init();
                 if (isFirstTurn) {
@@ -4112,11 +4252,46 @@ async function execute(argv, io, dependencies, signal) {
             }
             let result;
             let colorArgs;
+            let costTurn = false;
             try {
+                costTurn =
+                    !invocation.disableSlashCommands && isHeadlessCostCommand(prompt);
                 colorArgs = invocation.disableSlashCommands
                     ? undefined
                     : matchHeadlessColorCommand(prompt);
-                if (colorArgs !== undefined) {
+                if (costTurn) {
+                    if (!service.costSnapshot) {
+                        throw new Error('Session cost is unavailable.');
+                    }
+                    const current = await service.costSnapshot(activeSessionId);
+                    const delta = costSummaryDelta(current, costBaselines.get(activeSessionId));
+                    const modelUsageEntries = delta.modelUsage.map((entry) => [
+                        entry.model,
+                        {
+                            inputTokens: entry.inputTokens,
+                            outputTokens: entry.outputTokens,
+                            ...(entry.cacheReadInputTokens === undefined
+                                ? {}
+                                : { cacheReadInputTokens: entry.cacheReadInputTokens }),
+                            ...(entry.cacheCreationInputTokens === undefined
+                                ? {}
+                                : { cacheCreationInputTokens: entry.cacheCreationInputTokens }),
+                            ...(entry.webSearchRequests === undefined
+                                ? {}
+                                : { webSearchRequests: entry.webSearchRequests }),
+                        },
+                    ]);
+                    result = {
+                        sessionId: activeSessionId,
+                        text: formatCostSummary(delta),
+                        usage: { inputTokens: 0, outputTokens: 0 },
+                        durationApiMs: 0,
+                        costUsd: delta.totalCostUsd,
+                        modelUsage: Object.fromEntries(modelUsageEntries),
+                        modelCostUsd: Object.fromEntries(delta.modelUsage.map((entry) => [entry.model, entry.costUsd])),
+                    };
+                }
+                else if (colorArgs !== undefined) {
                     if (!service.recordColorUsage) {
                         throw new Error('Session color is unavailable.');
                     }
@@ -4169,20 +4344,22 @@ async function execute(argv, io, dependencies, signal) {
                 return false;
             }
             activeSessionId = result.sessionId;
+            await ensureCostBaseline(activeSessionId);
+            const localCommand = colorArgs !== undefined || costTurn;
             if (streamOutput) {
-                if (colorArgs !== undefined) {
+                if (localCommand) {
                     streamOutput.syntheticAssistant(result.text);
                 }
                 streamOutput.result(result, startedAt);
             }
             else if (outputFormat === 'json') {
                 const resultRuntimeInfo = service.runtimeInfo?.() ?? runtimeInfo;
-                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, colorArgs !== undefined ? 0 : Math.max(1, jsonModelTurns)));
+                writeJson(io, createSuccessResult(result, resultRuntimeInfo, startedAt, localCommand ? 0 : Math.max(1, jsonModelTurns)));
             }
             else if (outputFormat !== 'text')
                 writeJson(io, { type: 'result', ...result });
             else
-                io.stdout(colorArgs !== undefined ? `${result.text}\n` : '\n');
+                io.stdout(localCommand ? `${result.text}\n` : '\n');
             if (streamOutput && invocation.promptSuggestions) {
                 try {
                     const suggestion = await service.promptSuggestion?.(activeSessionId, runSignal);

package/dist/core/compaction.d.ts

@@ -9,6 +9,8 @@ export interface CompactionResult {
     summary: string;
     usage: ModelUsage;
     durationMs: number;
+    durationWithoutRetriesMs?: number;
+    model?: string;
 }
 export interface Compactor {
     compact(request: CompactionRequest): Promise<CompactionResult>;

package/dist/core/runtime.d.ts

@@ -66,7 +66,13 @@ export interface ModelUsage {
     outputTokens: number;
     cacheReadInputTokens?: number;
     cacheCreationInputTokens?: number;
+    webSearchRequests?: number;
+    /** Positive safe integer when the completing model's context window is known. */
+    contextWindow?: number;
+    /** Positive safe integer when the completing model's max output tokens are known. */
+    maxOutputTokens?: number;
 }
+export type ModelUsageByModel = Readonly<Record<string, ModelUsage>>;
 export interface ModelWebSearch {
     allowedDomains?: readonly string[];
     blockedDomains?: readonly string[];
@@ -103,6 +109,9 @@ export type ModelStreamEvent = {
     retryDelayMs: number;
     errorStatus: number | null;
     error: ProviderErrorKind;
+} | {
+    type: 'api-attempt-duration';
+    durationMs: number;
 };
 export interface ModelRequest {
     messages: readonly ModelMessage[];
@@ -125,6 +134,7 @@ export interface ModelProviderCapabilities {
         maxTokens: boolean;
     };
     contextWindowTokens?: number;
+    maxOutputTokens?: number;
 }
 export interface ModelProvider {
     readonly capabilities: ModelProviderCapabilities;
@@ -276,12 +286,17 @@ export interface ToolExecutionResult {
     images?: readonly ModelImage[];
     documents?: readonly ModelDocument[];
     isError: boolean;
+    linesAdded?: number;
+    linesRemoved?: number;
     usage?: ModelUsage;
+    modelUsage?: ModelUsageByModel;
     accessedPaths?: readonly string[];
     followUpUserMessages?: readonly string[];
     nativeToolUseResult?: Record<string, unknown>;
     nativeMcpMeta?: Record<string, unknown>;
     durationApiMs?: number;
+    durationApiWithoutRetriesMs?: number;
+    durationToolMs?: number;
     processOutput?: {
         stdout: string;
         stderr: string;
@@ -389,6 +404,14 @@ export interface AgentRunObserver {
     toolCompleted(call: ModelToolCall, result: ToolExecutionResult): Promise<void>;
     followUpUserMessagesCompleted?(messages: readonly string[]): Promise<void>;
 }
+export interface ToolUseSummaryOutcome {
+    summary: string | null;
+    usage: ModelUsage;
+    modelUsage?: ModelUsageByModel;
+    durationApiMs: number;
+    durationApiWithoutRetriesMs: number;
+    meteredExternally: boolean;
+}
 export interface AgentRuntimeOptions {
     tools?: ToolRegistry;
     permissions?: PermissionResolver;
@@ -407,7 +430,7 @@ export interface AgentRuntimeOptions {
         }[];
         lastAssistantText?: string;
         signal: AbortSignal;
-    }) => Promise<string | null>;
+    }) => Promise<ToolUseSummaryOutcome | null>;
 }
 export interface AgentRunRequest {
     messages: readonly ModelMessage[];
@@ -421,6 +444,9 @@ export interface AgentRunRequest {
     onStop?: (text: string) => Promise<readonly string[] | {
         messages: readonly string[];
         usage?: ModelUsage;
+        modelUsage?: ModelUsageByModel;
+        durationApiMs?: number;
+        durationApiWithoutRetriesMs?: number;
     }>;
     signal?: AbortSignal;
     effort?: string;
@@ -436,7 +462,18 @@ export interface AgentToolRecoveryRequest extends Pick<AgentRunRequest, 'approve
 export interface AgentRunResult {
     text: string;
     usage: ModelUsage;
+    modelUsage?: ModelUsageByModel;
     durationApiMs?: number;
+    durationApiWithoutRetriesMs?: number;
+    durationToolMs?: number;
+    linesAdded?: number;
+    linesRemoved?: number;
+    /** Model rows the session tracker still must record after at least one
+     *  externally metered summary outcome; undefined when every summary outcome
+     *  is still unrecorded (so inclusive fields stay authoritative). */
+    unrecordedModelUsage?: ModelUsageByModel;
+    unrecordedDurationApiMs?: number;
+    unrecordedDurationApiWithoutRetriesMs?: number;
 }
 export declare class ModelProviderError extends Error {
     readonly name = "ModelProviderError";