Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(telemetry): preserve usage coverage and operation outcomes (#1841)

Michael D'Angelo3a51de0d54e8
diff --git a/plugins/codex-security/mcp-app/package.json b/plugins/codex-security/mcp-app/package.json
index 7d04e810f..506838001 100644
--- a/plugins/codex-security/mcp-app/package.json
+++ b/plugins/codex-security/mcp-app/package.json
@@ -13,6 +13,7 @@
"@modelcontextprotocol/sdk": "^1.32.2",
"@openai/codex-sdk": "0.166.0",
"ajv": "8.20.0",
+ "fzstd": "0.1.1",
"smol-toml": "1.9.1",
"zod": "^4.6.7",
"yaml": "2.9.1"
diff --git a/plugins/codex-security/mcp-app/pnpm-lock.yaml b/plugins/codex-security/mcp-app/pnpm-lock.yaml
index e54d98db1..ac3d71711 100644
--- a/plugins/codex-security/mcp-app/pnpm-lock.yaml
+++ b/plugins/codex-security/mcp-app/pnpm-lock.yaml
@@ -17,6 +17,9 @@ importers:
ajv:
specifier: 8.20.0
version: 8.20.0
+ fzstd:
+ specifier: 0.1.1
+ version: 0.1.1
smol-toml:
specifier: 1.9.1
version: 1.9.1
@@ -528,6 +531,9 @@ packages:
resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+ resolution: {integrity: sha512-dkuVSOKKwh3eas5VkJy1AW1vFpet8TA/fGmVA5krThl8YcOVE/8ZIoEA1+U1vEn5ckxxhLirSdY837azmbaNHA==}
+
resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
engines: {node: '>= 0.4'}
@@ -1152,6 +1158,8 @@ snapshots:
+
dependencies:
call-bind-apply-helpers: 1.0.2
diff --git a/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs b/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
index 9bb09a1eb..6b9ace9b1 100644
--- a/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
+++ b/plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs
@@ -77,6 +77,18 @@ export async function buildMcpApp({ output, native = "universal" }) {
}
}
await writeRuntime("helpers", "helpers-main.ts");
+ await build({
+ bundle: true,
+ entryPoints: [join(root, "src/session-decompression.ts")],
+ format: "esm",
+ outfile: join(mcpDir, "session-decompression.mjs"),
+ platform: "node",
+ target: "node20",
+ });
+ await copyFile(
+ join(root, "node_modules/fzstd/LICENSE"),
+ join(mcpDir, "fzstd-LICENSE.txt"),
+ );
await build({
bundle: true,
entryPoints: [join(root, "src/deep-scan/permission-profile-preflight.ts")],
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
index 9b1e949ac..8591439c0 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/coordinator.ts
@@ -2,6 +2,10 @@
import { randomUUID } from "node:crypto";
import { promises as fs } from "node:fs";
import { basename, dirname, join, relative, sep } from "node:path";
+import {
+ writeWorkerUsageReceipt,
+ type WorkerUsageReceipt,
+} from "./usage-receipt.js";
import { mergeBatch } from "./iteration.js";
import { setTimeout as delay } from "node:timers/promises";
import {
@@ -913,16 +917,8 @@ export class DeepScanCoordinator {
this.artifacts.scanDir,
async (prompt, schema) => {
if (stop) throw stop;
- const { executor } = this.options;
- if (!executor.compareFindings)
- throw new Error("No Deep Scan finding comparison executor");
try {
- return await executor.compareFindings(
- prompt,
- this.artifacts.deepRoot,
- this.abortController.signal,
- schema,
- );
+ return await this.compareReports(prompt, schema);
} catch (error) {
// Finish checkpointing accepted workers before stopping discovery.
if (error instanceof DeepScanNonRetryableError) stop = error;
@@ -941,6 +937,77 @@ export class DeepScanCoordinator {
return { counts, stop };
}
+ private async compareReports(
+ prompt: string,
+ schema: Record<string, unknown>,
+ ): Promise<string> {
+ const { executor } = this.options;
+ if (!executor.compareFindings)
+ throw new Error("No Deep Scan finding comparison executor");
+ const { scanId, workerUsageDirectory } = this.state;
+ const signal = this.abortController.signal;
+ const startedAt = new Date(this.clock.now()).toISOString();
+ const attemptId = randomUUID();
+ const receipt: WorkerUsageReceipt = {
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId,
+ workerId: attemptId,
+ kind: "compare",
+ attemptId,
+ attempt: 1,
+ resumed: false,
+ startedAt,
+ observedAt: startedAt,
+ outcome: "running",
+ usage: null,
+ };
+ const persist = async () => {
+ if (!workerUsageDirectory) return;
+ receipt.observedAt = new Date(this.clock.now()).toISOString();
+ try {
+ await writeWorkerUsageReceipt(workerUsageDirectory, receipt);
+ } catch (error) {
+ this.log({
+ event: "worker_usage_unavailable",
+ scanId,
+ attemptId,
+ reason: errorMessage(error),
+ });
+ }
+ };
+ await persist();
+ try {
+ const report = await executor.compareFindings(
+ prompt,
+ this.artifacts.deepRoot,
+ signal,
+ schema,
+ {
+ attemptId,
+ workerUsageDirectory,
+ onThreadStarted: async (id) => {
+ receipt.threadId = id;
+ await persist();
+ },
+ onUsage: async (usage, turnId) => {
+ receipt.usage = usage;
+ receipt.turnId = turnId;
+ await persist();
+ },
+ },
+ );
+ receipt.outcome = "succeeded";
+ return report;
+ } catch (error) {
+ receipt.outcome = signal.aborted ? "canceled" : "failed";
+ throw error;
+ } finally {
+ await persist();
+ }
+ }
+
private async restoreUnion(
resultPath: string | undefined,
merged: AcceptedDiscovery[],
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/executor.ts b/plugins/codex-security/mcp-app/src/deep-scan/executor.ts
index d1d79001f..424c0fa96 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/executor.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/executor.ts
@@ -34,6 +34,7 @@ import {
} from "../../../scripts/codex_profile.mjs";
import { executablePathForSpawn } from "../executable-path.js";
import { writePrivateFile } from "./artifacts.js";
+import { workerTokenUsage } from "./usage-receipt.js";
import {
classifyCodexWorkerError,
codexWorkerTurnError,
@@ -52,6 +53,7 @@ import type {
CodexWorkerExecutor,
CodexWorkerRequest,
CodexWorkerResult,
+ WorkerTelemetryOptions,
DeepScanConfig,
} from "./types.js";
@@ -96,14 +98,16 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
// Each live coordinator keeps the executable selected for its first worker.
private codexExecutable?: Promise<BoundCodexExecutable>;
private parentCyberAccessProgram?: Promise<CyberAccessProgram | undefined>;
+ private pluginVersion?: Promise<string | undefined>;
constructor(
private readonly modelSettings: CodexSdkWorkerModelSettings = {},
) {}
async run(request: CodexWorkerRequest): Promise<CodexWorkerResult> {
- const { threadId, diagnostics } = await this.runTurn(request);
- return { threadId, ...(diagnostics && { diagnostics }) };
+ const { threadId, turnId, usage, diagnostics } =
+ await this.runTurn(request);
+ return { threadId, turnId, usage, ...(diagnostics && { diagnostics }) };
}
async compareFindings(
@@ -111,8 +115,10 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
workingDirectory: string,
signal: AbortSignal,
schema: Record<string, unknown>,
+ telemetry?: WorkerTelemetryOptions,
): Promise<string> {
const turn = await this.runTurn({
+ ...telemetry,
kind: "compare",
prompt,
workingDirectory,
@@ -125,13 +131,13 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
private async runTurn(
request:
| CodexWorkerRequest
- | {
+ | (WorkerTelemetryOptions & {
kind: "compare";
prompt: string;
workingDirectory: string;
signal: AbortSignal;
schema: Record<string, unknown>;
- },
+ }),
) {
const discovery = request.kind === "discovery" ? request : undefined;
const includePaths = this.modelSettings.artifactContext?.includePaths;
@@ -150,7 +156,17 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
"Deep Scan cannot start a read-only worker without verified parent sandbox metadata.",
);
}
- const workerProfile = workerPermissionProfile(parentSandbox);
+ const workerProfile = workerPermissionProfile(
+ request.workerUsageDirectory
+ ? {
+ ...parentSandbox,
+ literalFilesystemDenies: [
+ ...(parentSandbox.literalFilesystemDenies ?? []),
+ request.workerUsageDirectory,
+ ],
+ }
+ : parentSandbox,
+ );
const originalCwd = process.cwd();
const childEnv = await snapshotWorkerEnvironment();
// Snapshot the SDK's per-scan config once for this coordinator, including resumes.
@@ -207,18 +223,67 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
}
// Keep one native configuration for the policy check and the worker turn.
// Worker-owned tool and permission settings take precedence over inheritance.
+ const inheritedMetadata = isRecord(
+ runtimeSettings.config.responses_api_metadata,
+ )
+ ? runtimeSettings.config.responses_api_metadata
+ : {};
+ const attemptId = request.attemptId ?? randomUUID();
+ const operationId =
+ typeof inheritedMetadata.codex_security_operation_id === "string"
+ ? inheritedMetadata.codex_security_operation_id
+ : this.modelSettings.artifactContext?.scanId;
+ const parentAttemptId =
+ typeof inheritedMetadata.codex_security_attempt_id === "string"
+ ? inheritedMetadata.codex_security_attempt_id
+ : undefined;
+ const pluginRootForVersion =
+ this.modelSettings.artifactContext?.pluginRoot;
+ const pluginVersion =
+ pluginRootForVersion === undefined
+ ? undefined
+ : await (this.pluginVersion ??= fs
+ .readFile(
+ join(pluginRootForVersion, ".codex-plugin", "plugin.json"),
+ "utf8",
+ )
+ .then((text) => {
+ const manifest: unknown = JSON.parse(text);
+ return isRecord(manifest) &&
+ typeof manifest.version === "string"
+ ? manifest.version
+ : undefined;
+ })
+ .catch(() => undefined));
+ try {
+ request.onAttribution?.({ operationId, attemptId, parentAttemptId });
+ } catch {
+ // Optional observability cannot interrupt a worker.
+ }
const configOverrides = profileConfigOverrides({
...runtimeSettings.config,
responses_api_metadata: {
codex_security_surface: "plugin",
codex_security_command: "scan",
codex_security_scan_mode: "deep",
+ ...(pluginVersion === undefined
+ ? {}
+ : {
+ codex_security_plugin_version: pluginVersion,
+ }),
// Keep the host's integration/provider context as this coordinator
// launches or resumes workers with a different role.
- ...(isRecord(runtimeSettings.config.responses_api_metadata)
- ? runtimeSettings.config.responses_api_metadata
- : {}),
+ ...inheritedMetadata,
codex_security_worker_role: request.kind,
+ ...(operationId === undefined
+ ? {}
+ : { codex_security_operation_id: operationId }),
+ codex_security_attempt_id: attemptId,
+ ...(parentAttemptId === undefined
+ ? {}
+ : {
+ codex_security_parent_attempt_id: parentAttemptId,
+ }),
},
...(this.modelSettings.reasoningEffort
? { model_reasoning_effort: this.modelSettings.reasoningEffort }
@@ -355,6 +420,10 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
...codexOptions,
profileName: runtimeSettings.nativeProfile,
});
+ // The pinned SDK defaults missing cache writes to zero; native profiles
+ // preserve field presence before defaulting in our profile adapter.
+ const readUsage = (value: unknown) =>
+ workerTokenUsage(value, runtimeSettings.nativeProfile === undefined);
const threadOptions = {
...(this.modelSettings.model
? { model: this.modelSettings.model }
@@ -392,11 +461,26 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
parentProgram ?? runtimeSettings.cyberAccessProgram,
});
const diagnostics: CodexWorkerDiagnostic[] = [];
+ let turnId: string | undefined;
const turn = await readCodexSessionTurn({
thread,
events,
stopOnCompletion: true,
onEvent: async (event) => {
+ if (
+ (event.type === "turn.started" ||
+ event.type === "turn.completed") &&
+ "turn_id" in event &&
+ typeof event.turn_id === "string"
+ )
+ turnId = event.turn_id;
+ if (event.type === "turn.completed") {
+ try {
+ await request.onUsage?.(readUsage(event.usage), turnId);
+ } catch {
+ // Retaining optional usage must not change turn acceptance.
+ }
+ }
const item = event.type === "item.completed" ? event.item : event;
if (item.type === "error") {
const fallbackError = deepScanPermissionProfileFallbackError(
@@ -408,7 +492,7 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
}
}
if (event.type === "thread.started") {
- await discovery?.onThreadStarted?.(event.thread_id);
+ await request.onThreadStarted?.(event.thread_id);
} else if (event.type === "item.completed") {
appendItemDiagnostic(diagnostics, event.item);
} else if (event.type === "turn.completed") {
@@ -435,6 +519,8 @@ export class CodexSdkWorkerExecutor implements CodexWorkerExecutor {
return {
finalResponse: turn.finalResponse,
threadId: turn.threadId ?? thread.id ?? undefined,
+ ...(turnId === undefined ? {} : { turnId }),
+ usage: readUsage(turn.usage),
...(diagnostics.length > 0 ? { diagnostics } : {}),
};
} finally {
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/response.ts b/plugins/codex-security/mcp-app/src/deep-scan/response.ts
index a69b659a1..2699c2523 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/response.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/response.ts
@@ -93,6 +93,7 @@ export const runSchema = z
})
.optional(),
scanDir: requiredString,
+ workerUsageDirectory: optionalString,
dispatchedCount: nonNegativeInteger,
completionSequence: nonNegativeInteger.optional(),
noNewStreak: nonNegativeInteger,
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/types.ts b/plugins/codex-security/mcp-app/src/deep-scan/types.ts
index f1ee65361..c0a306051 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/types.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/types.ts
@@ -1,6 +1,7 @@
import type { DiscoveryBoardContext } from "../artifact-io.js";
import type { WorkbenchDeepScanStore } from "./store.js";
import type { z } from "zod";
+import type { WorkerTokenUsage } from "./usage-receipt.js";
import type {
configSchema,
dedupInputSchema,
@@ -65,7 +66,7 @@ export interface CodexWorkerArtifactContext {
}
/** Transport-neutral contract for one top-level Codex worker. */
-export interface CodexWorkerRequest {
+export interface CodexWorkerRequest extends WorkerTelemetryOptions {
kind: "discovery";
promptPath: string;
workingDirectory: string;
@@ -74,12 +75,31 @@ export interface CodexWorkerRequest {
resumeThreadId?: string;
continuationPrompt?: string;
artifactContext?: CodexWorkerArtifactContext;
- onThreadStarted?: (threadId: string) => Promise<void> | void;
onNonRetryableError?: (error: Error) => void;
}
+export interface WorkerTelemetryOptions {
+ attemptId?: string;
+ /** Host-bound receipt storage, excluded from model filesystem access. */
+ workerUsageDirectory?: string;
+ onThreadStarted?: (threadId: string) => Promise<void> | void;
+ onAttribution?: (attribution: WorkerAttribution) => void;
+ onUsage?: (
+ usage: WorkerTokenUsage | null,
+ turnId?: string,
+ ) => Promise<void> | void;
+}
+
+export interface WorkerAttribution {
+ operationId?: string;
+ attemptId: string;
+ parentAttemptId?: string;
+}
+
export interface CodexWorkerResult {
threadId?: string;
+ turnId?: string;
+ usage?: WorkerTokenUsage | null;
diagnostics?: CodexWorkerDiagnostic[];
}
@@ -100,6 +120,7 @@ export interface CodexWorkerExecutor {
workingDirectory: string,
signal: AbortSignal,
schema: Record<string, unknown>,
+ telemetry?: WorkerTelemetryOptions,
): Promise<string>;
}
@@ -122,6 +143,14 @@ export interface DeepScanLogEvent {
pass?: number;
reason?: string;
total?: number;
+ timestamp?: string;
+ durationMs?: number;
+ outcome?: "succeeded" | "failed" | "canceled";
+ retry?: boolean;
+ resumed?: boolean;
+ attemptId?: string;
+ operationId?: string;
+ parentAttemptId?: string;
}
export type DeepScanLogger = (event: DeepScanLogEvent) => void;
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/usage-receipt.ts b/plugins/codex-security/mcp-app/src/deep-scan/usage-receipt.ts
new file mode 100644
index 000000000..a55914c91
--- /dev/null
+++ b/plugins/codex-security/mcp-app/src/deep-scan/usage-receipt.ts
@@ -0,0 +1,102 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { requireArtifactRoot } from "../artifact-io.js";
+import { writeJsonAtomic } from "./artifacts.js";
+import type { DeepScanWorkerKind } from "./types.js";
+
+export interface WorkerTokenUsage {
+ input_tokens: number;
+ cached_input_tokens: number;
+ cache_write_input_tokens: number;
+ cache_write_input_tokens_reported?: false;
+ output_tokens: number;
+ reasoning_output_tokens: number;
+ total_tokens: number;
+}
+
+/** One host invocation records the SDK's cumulative thread usage. */
+export interface WorkerUsageReceipt {
+ schemaVersion: 1;
+ source: "codex_sdk";
+ usageScope: "thread_cumulative";
+ scanId: string;
+ workerId: string;
+ kind: DeepScanWorkerKind | "compare";
+ attemptId: string;
+ attempt: number;
+ resumed: boolean;
+ threadId?: string;
+ turnId?: string;
+ startedAt: string;
+ observedAt: string;
+ outcome: "running" | "succeeded" | "failed" | "canceled";
+ usage: WorkerTokenUsage | null;
+}
+
+/** Retain numeric usage only; model and diagnostic text are not receipt fields. */
+export function workerTokenUsage(
+ value: unknown,
+ cacheWritesMayBeDefaulted = false,
+): WorkerTokenUsage | null {
+ if (value === null || typeof value !== "object") return null;
+ const raw = value as Record<string, unknown>;
+ const input = raw.input_tokens;
+ const cached = raw.cached_input_tokens ?? 0;
+ const legacyCacheWrite = raw.cache_write_tokens;
+ const fields = {
+ input_tokens: input,
+ cached_input_tokens: cached,
+ cache_write_input_tokens:
+ raw.cache_write_input_tokens === 0 &&
+ typeof input === "number" &&
+ typeof cached === "number" &&
+ typeof legacyCacheWrite === "number" &&
+ Number.isSafeInteger(legacyCacheWrite) &&
+ legacyCacheWrite > 0 &&
+ cached + legacyCacheWrite <= input
+ ? legacyCacheWrite
+ : (raw.cache_write_input_tokens ?? raw.cache_write_tokens ?? 0),
+ output_tokens: raw.output_tokens,
+ reasoning_output_tokens: raw.reasoning_output_tokens ?? 0,
+ };
+ if (
+ Object.values(fields).some(
+ (count) =>
+ typeof count !== "number" || !Number.isSafeInteger(count) || count < 0,
+ )
+ )
+ return null;
+ const usage = fields as Omit<WorkerTokenUsage, "total_tokens">;
+ if (
+ usage.cached_input_tokens + usage.cache_write_input_tokens >
+ usage.input_tokens ||
+ usage.reasoning_output_tokens > usage.output_tokens
+ )
+ return null;
+ return {
+ ...usage,
+ total_tokens: usage.input_tokens + usage.output_tokens,
+ ...(raw.cache_write_input_tokens_reported === false ||
+ (cacheWritesMayBeDefaulted && usage.cache_write_input_tokens === 0) ||
+ (raw.cache_write_input_tokens == null && raw.cache_write_tokens == null)
+ ? { cache_write_input_tokens_reported: false as const }
+ : {}),
+ };
+}
+
+export async function writeWorkerUsageReceipt(
+ directory: string,
+ receipt: WorkerUsageReceipt,
+): Promise<void> {
+ const privateHome = dirname(dirname(directory));
+ await requireArtifactRoot(dirname(privateHome), "Worker usage");
+ for (const path of [privateHome, dirname(directory), directory]) {
+ await fs
+ .mkdir(path, { mode: 0o700 })
+ .catch((error: NodeJS.ErrnoException) => {
+ if (error.code !== "EEXIST") throw error;
+ });
+ await requireArtifactRoot(path, "Worker usage");
+ }
+ await writeJsonAtomic(join(directory, `${receipt.attemptId}.json`), receipt);
+}
diff --git a/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts b/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
index 927387d5f..7be8b9d01 100644
--- a/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
+++ b/plugins/codex-security/mcp-app/src/deep-scan/worker-runner.ts
@@ -1,4 +1,5 @@
import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
import type { ScanDraftInput } from "../artifact-scan-draft.js";
import { dirname, join } from "node:path";
import { validateDiscoveryArtifacts } from "./artifact-validation.js";
@@ -11,6 +12,10 @@ import {
confirmedOwnershipChange,
} from "./errors.js";
import { renderDiscoveryPrompt } from "./templates.js";
+import {
+ writeWorkerUsageReceipt,
+ type WorkerUsageReceipt,
+} from "./usage-receipt.js";
import type {
CodexWorkerExecutor,
CodexWorkerDiagnostic,
@@ -21,6 +26,7 @@ import type {
DeepScanStore,
DeepScanWorkerMutation,
PersistedDeepScanWorker,
+ WorkerAttribution,
} from "./types.js";
export interface AcceptedDiscovery {
@@ -51,8 +57,14 @@ export interface DeepScanWorkerRunnerOptions {
onNonRetryableError?: (error: Error) => void;
}
+type FinalAttemptStatus = "succeeded" | "failed" | "canceled";
type WorkerAttemptOutcome =
- | { status: "succeeded"; attempt: number; threadId?: string }
+ | {
+ status: "validated";
+ attempt: number;
+ threadId?: string;
+ finish: (status: FinalAttemptStatus) => Promise<void>;
+ }
| {
status: "failed";
error: Error;
@@ -112,7 +124,7 @@ export class DeepScanWorkerRunner {
attempt: 1,
});
let discoveryResult: ScanDraftInput | undefined;
- let outcome = await this.runWorkerWithRetries({
+ const outcome = await this.runWorkerWithRetries({
workerId,
workerLabel,
promptPath,
@@ -127,62 +139,64 @@ export class DeepScanWorkerRunner {
);
},
});
- if (outcome.status === "succeeded" && this.options.signal.aborted) {
- outcome = await this.cancelAttempt(
- {
- workerId,
- promptPath,
- artifactDir,
- },
- outcome.attempt,
- outcome.threadId,
- );
- }
if (!discoveryResult) {
await fs.rm(resultPath, { force: true });
}
if (outcome.status === "failed") {
return { ...outcome, workerId };
}
- if (outcome.status === "canceled" || this.options.signal.aborted) {
+ if (outcome.status === "canceled") {
return { status: "canceled", workerId };
}
- const acceptance = {
- id: workerId,
- scanId: run.scanId,
- kind: "discovery" as const,
- status: "succeeded" as const,
- promptPath,
- artifactDir,
- attempt: outcome.attempt,
- threadId: outcome.threadId,
- resultManifestPath: resultPath,
- };
+ let finalStatus: FinalAttemptStatus = "failed";
let persisted: PersistedDeepScanWorker;
try {
- persisted = await this.options.store.updateWorker(acceptance);
+ if (this.options.signal.aborted) {
+ finalStatus = "canceled";
+ await this.cancelAttempt(
+ { workerId, promptPath, artifactDir },
+ outcome.attempt,
+ outcome.threadId,
+ );
+ return { status: "canceled", workerId };
+ }
+ persisted = await this.options.store.updateWorker({
+ id: workerId,
+ scanId: run.scanId,
+ kind: "discovery",
+ status: "succeeded",
+ promptPath,
+ artifactDir,
+ attempt: outcome.attempt,
+ threadId: outcome.threadId,
+ resultManifestPath: resultPath,
+ });
+ if (!persisted.completionSequence) {
+ throw new Error(
+ `Discovery worker ${workerId} did not receive a completion sequence.`,
+ );
+ }
+ finalStatus = "succeeded";
} catch (error) {
if (confirmedOwnershipChange(error, run.scanId)) throw error;
if (!this.options.signal.aborted) throw error;
+ finalStatus = "canceled";
return { status: "canceled", workerId };
- }
- if (!persisted.completionSequence) {
- throw new Error(
- `Discovery worker ${workerId} did not receive a completion sequence.`,
- );
+ } finally {
+ await outcome.finish(finalStatus);
}
// A validation success can still race with cancellation or a lease change.
// Report worker success only once SQLite accepts the result.
- this.options.log({
+ this.log({
event: "worker_succeeded",
scanId: run.scanId,
workerId,
kind: "discovery",
attempt: persisted.attempt,
});
- this.options.log({
+ this.log({
event: "discovery_accepted",
scanId: run.scanId,
workerId,
@@ -231,18 +245,96 @@ export class DeepScanWorkerRunner {
threadId: resumableThreadId,
};
await this.options.store.updateWorker(baseMutation);
- this.options.log({
- event: "worker_started",
+ const started = this.options.clock.now();
+ const attemptId = randomUUID();
+ let attribution: WorkerAttribution = { attemptId };
+ let startLogged = false;
+ let finishedAt: number | undefined;
+ let outcome: "validated" | "failed" | "canceled" = "failed";
+ const receipt: WorkerUsageReceipt = {
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
scanId: run.scanId,
workerId: input.workerId,
kind: "discovery",
+ attemptId,
attempt,
- });
+ resumed: resumableThreadId !== undefined,
+ ...(resumableThreadId ? { threadId: resumableThreadId } : {}),
+ startedAt: new Date(started).toISOString(),
+ observedAt: new Date(started).toISOString(),
+ outcome: "running",
+ usage: null,
+ };
+ const logStarted = () => {
+ if (startLogged) return;
+ startLogged = true;
+ this.log({
+ event: "worker_started",
+ scanId: run.scanId,
+ workerId: input.workerId,
+ kind: "discovery",
+ attempt,
+ ...attribution,
+ timestamp: receipt.startedAt,
+ retry: attempt > 1,
+ resumed: receipt.resumed,
+ ...(resumableThreadId ? { threadId: resumableThreadId } : {}),
+ });
+ };
+ const persistUsage = async () => {
+ receipt.observedAt = new Date(this.options.clock.now()).toISOString();
+ try {
+ if (!run.workerUsageDirectory) {
+ throw new Error(
+ "The host did not provide a worker usage directory.",
+ );
+ }
+ await writeWorkerUsageReceipt(run.workerUsageDirectory, receipt);
+ } catch (error) {
+ this.log({
+ event: "worker_usage_unavailable",
+ scanId: run.scanId,
+ workerId: input.workerId,
+ kind: "discovery",
+ attempt,
+ ...attribution,
+ reason: `Could not retain worker usage: ${error instanceof Error ? error.message : String(error)}`,
+ });
+ }
+ };
+ let finishRecorded = false;
+ const finishAttempt = async (status: FinalAttemptStatus) => {
+ if (finishRecorded) return;
+ finishRecorded = true;
+ logStarted();
+ receipt.outcome = status;
+ await persistUsage();
+ const finished = finishedAt ?? this.options.clock.now();
+ this.log({
+ event: "worker_finished",
+ scanId: run.scanId,
+ workerId: input.workerId,
+ kind: "discovery",
+ attempt,
+ ...attribution,
+ ...(activeThreadId ? { threadId: activeThreadId } : {}),
+ timestamp: new Date(finished).toISOString(),
+ durationMs: finished - started,
+ outcome: status,
+ retry: attempt > 1,
+ resumed: receipt.resumed,
+ });
+ };
+ await persistUsage();
try {
const resumePrompt = resumableThreadId
? (continuationPrompt ?? transientExecutionContinuation(attempt))
: undefined;
const result = await this.options.executor.run({
+ attemptId,
+ workerUsageDirectory: run.workerUsageDirectory,
kind: "discovery",
promptPath: executionPromptPath,
workingDirectory: input.artifactDir,
@@ -276,14 +368,26 @@ export class DeepScanWorkerRunner {
author: input.workerLabel,
},
},
+ onAttribution: (value) => {
+ attribution = value;
+ logStarted();
+ },
+ onUsage: async (usage, turnId) => {
+ receipt.usage = usage;
+ receipt.turnId = turnId;
+ await persistUsage();
+ },
onThreadStarted: async (threadId) => {
+ logStarted();
activeThreadId = threadId;
lastThreadId = threadId;
+ receipt.threadId = threadId;
await this.options.store.updateWorker({
...baseMutation,
threadId,
});
- this.options.log({
+ await persistUsage();
+ this.log({
event: "worker_thread_started",
scanId: run.scanId,
workerId: input.workerId,
@@ -293,10 +397,17 @@ export class DeepScanWorkerRunner {
});
},
});
+ logStarted();
+ activeThreadId = result.threadId ?? activeThreadId;
+ receipt.threadId = activeThreadId;
+ receipt.turnId = result.turnId ?? receipt.turnId;
+ if (result.usage !== undefined) receipt.usage = result.usage;
if (terminalFailure) return terminalFailure;
if (signal.aborted) {
+ outcome = "canceled";
return await this.cancelAttempt(input, attempt, activeThreadId);
}
+ await persistUsage();
validationStarted = true;
try {
await input.validate();
@@ -305,17 +416,22 @@ export class DeepScanWorkerRunner {
}
validationCompleted = true;
if (signal.aborted) {
+ outcome = "canceled";
return await this.cancelAttempt(input, attempt, activeThreadId);
}
+ outcome = "validated";
return {
- status: "succeeded",
+ status: "validated",
+ finish: finishAttempt,
attempt,
threadId: result.threadId ?? activeThreadId,
};
} catch (error) {
+ finishedAt = this.options.clock.now();
if (confirmedOwnershipChange(error, run.scanId)) throw error;
if (terminalFailure) return terminalFailure;
if (signal.aborted) {
+ outcome = "canceled";
return await this.cancelAttempt(input, attempt, activeThreadId);
}
const normalized = asError(error);
@@ -380,11 +496,12 @@ export class DeepScanWorkerRunner {
});
}
}
+ await finishAttempt("failed");
const delayMs = Math.ceil(
this.options.retryDelaysMs[attempt - 1] *
(1 + 0.3 * this.options.random()),
);
- this.options.log({
+ this.log({
event: "worker_retry_scheduled",
scanId: run.scanId,
workerId: input.workerId,
@@ -401,10 +518,20 @@ export class DeepScanWorkerRunner {
}
throw sleepError;
}
+ } finally {
+ if (outcome !== "validated") await finishAttempt(outcome);
}
}
}
+ private log(event: Parameters<DeepScanLogger>[0]): void {
+ try {
+ this.options.log(event);
+ } catch {
+ // Optional progress logging must not stop worker execution.
+ }
+ }
+
private async archiveWorkerAttempt(artifactDir: string, attempt: number) {
await archiveDirectory(
artifactDir,
diff --git a/plugins/codex-security/mcp-app/src/session-decompression.ts b/plugins/codex-security/mcp-app/src/session-decompression.ts
new file mode 100644
index 000000000..f72726010
--- /dev/null
+++ b/plugins/codex-security/mcp-app/src/session-decompression.ts
@@ -0,0 +1,45 @@
+import { Transform, type TransformCallback } from "node:stream";
+import { Decompress } from "fzstd";
+
+/** Streaming decoder for concatenated Zstandard rollouts on supported Node versions. */
+export function createZstdDecompress(): Transform {
+ let decoder: Decompress;
+ let backpressured = false;
+ let pending: TransformCallback | undefined;
+ const stream = new Transform({
+ transform(
+ chunk: Buffer,
+ _encoding: BufferEncoding,
+ callback: TransformCallback,
+ ) {
+ try {
+ backpressured = false;
+ decoder.push(chunk);
+ // Transform's automatic backpressure stops delaying writes after end().
+ // Keep queued compressed chunks pending until the reader asks for more.
+ if (backpressured && !this.destroyed) pending = callback;
+ else callback();
+ } catch (error) {
+ callback(error as Error);
+ }
+ },
+ read(size: number) {
+ const callback = pending;
+ pending = undefined;
+ callback?.();
+ Transform.prototype._read.call(this, size);
+ },
+ flush(callback: TransformCallback) {
+ try {
+ decoder.push(new Uint8Array(), true);
+ callback();
+ } catch (error) {
+ callback(error as Error);
+ }
+ },
+ });
+ decoder = new Decompress((chunk) => {
+ if (!stream.push(chunk)) backpressured = true;
+ });
+ return stream;
+}
diff --git a/plugins/codex-security/mcp-app/src/workbench-client.ts b/plugins/codex-security/mcp-app/src/workbench-client.ts
index 0cdb49fb1..983d87f58 100644
--- a/plugins/codex-security/mcp-app/src/workbench-client.ts
+++ b/plugins/codex-security/mcp-app/src/workbench-client.ts
@@ -97,7 +97,11 @@ async function executeWorkbench(
{
cwd: PLUGIN_ROOT,
windowsHide: true,
- env: process.env,
+ env: {
+ ...process.env,
+ CODEX_MCP_NODE_PATH:
+ process.env.CODEX_MCP_NODE_PATH || process.execPath,
+ },
encoding: "utf8" as const,
maxBuffer: Infinity,
timeout,
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_context_snapshot_cases.ts b/plugins/codex-security/mcp-app/tests/deep_scan_context_snapshot_cases.ts
index 8eed702e6..b2422d4df 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_context_snapshot_cases.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_context_snapshot_cases.ts
@@ -41,7 +41,7 @@ export async function testDeepScanContextSnapshots() {
DeepScanWorkerRunner: typeof Runner;
createDeepScanArtifacts: typeof Artifacts;
};
- const fixture = await fakeCodexFixture();
+ const fixture = await fakeCodexFixture(null);
// Concurrent children record their input in their own working directories.
await writeFile(
fixture.executablePath,
@@ -162,6 +162,8 @@ export async function testDeepScanContextSnapshots() {
});
const createdAt = run.createdAt;
assert.ok(createdAt);
+ const workerUsageDirectory = run.workerUsageDirectory;
+ assert.ok(workerUsageDirectory);
assert.equal(run.config.maxTimeHours, maxTimeHours);
assert.equal(run.config.subagents, index);
const invocations: {
@@ -228,7 +230,10 @@ export async function testDeepScanContextSnapshots() {
randomUUID(),
"before-edit",
);
- assert.ok(first.status === "succeeded");
+ assert.ok(
+ first.status === "succeeded",
+ "error" in first ? String(first.error) : first.status,
+ );
const editedContext = `Updated instructions for later phases ${index}.`;
await command([
"update-scan-context",
@@ -248,6 +253,7 @@ export async function testDeepScanContextSnapshots() {
});
assert.equal(run.config.maxTimeHours, maxTimeHours);
assert.equal(run.createdAt, createdAt);
+ assert.equal(run.workerUsageDirectory, workerUsageDirectory);
sdk = new CodexSdkWorkerExecutor({
parentSandbox,
deepScanConfig: run.config,
@@ -264,6 +270,25 @@ export async function testDeepScanContextSnapshots() {
assert.equal(fresh.invocation.argv.includes("resume"), false);
assert.equal(resumed.invocation.argv.includes("resume"), true);
for (const { invocation } of [fresh, resumed]) {
+ const permissionOverride = invocation.argv.find((arg) =>
+ arg.startsWith("permissions.codex_security_deep_scan_worker="),
+ );
+ assert.ok(permissionOverride);
+ assert.deepEqual(
+ JSON.parse(
+ JSON.stringify(parseToml(permissionOverride).permissions),
+ ),
+ {
+ codex_security_deep_scan_worker: {
+ extends: ":read-only",
+ filesystem: {
+ ":root": "read",
+ [workerUsageDirectory]: { ".": "deny" },
+ },
+ network: { enabled: false },
+ },
+ },
+ );
assert.deepEqual(
{ ...(parseToml(invocation.deepConfig).deep_scan as object) },
{
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts b/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
index 96ae30824..5358f90a0 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_coordinator_fixture.ts
@@ -16,7 +16,7 @@ import { createTemporaryDirectories } from "./support/temporary-directories.ts";
import { once } from "node:events";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
-import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import path from "node:path";
import { importModule } from "./import-module.ts";
@@ -64,14 +64,23 @@ export async function fixtureRun(
const root = await temporaryDirectories.create(
"codex-security-deep-coordinator-",
);
+ const scanId = randomUUID();
+ const stateDirectory = path.join(root, "state");
+ await mkdir(stateDirectory, { mode: 0o700 });
return {
pluginRoot: path.join(root, "plugin"),
run: {
- scanId: randomUUID(),
+ scanId,
status: "running" as const,
targetPath: path.join(root, "target"),
scope: ".",
scanDir: path.join(root, "scan"),
+ workerUsageDirectory: path.join(
+ stateDirectory,
+ "codex-home",
+ "worker-usage",
+ scanId,
+ ),
config: {
workers: 1,
subagents: 0,
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_worker_telemetry_fixture.ts b/plugins/codex-security/mcp-app/tests/deep_scan_worker_telemetry_fixture.ts
index 566922db1..bf692c6a5 100644
--- a/plugins/codex-security/mcp-app/tests/deep_scan_worker_telemetry_fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_worker_telemetry_fixture.ts
@@ -26,6 +26,8 @@ export function workerTelemetryFixture(
codex_security_package_version: `0.2.${index}`,
codex_security_plugin_version: `0.1.${index}`,
codex_security_integration: "github_action",
+ codex_security_operation_id: `operation-${index}`,
+ codex_security_attempt_id: `parent-${index}`,
codex_security_provider:
index % 2 === 0 ? "openai" : "amazon-bedrock",
custom_tag: `synthetic-scan-${index}`,
@@ -71,6 +73,8 @@ export function workerTelemetryFixture(
codex_security_package_version: "0.2.0",
codex_security_plugin_version: "0.1.0",
codex_security_integration: "github_action",
+ codex_security_operation_id: "operation-0",
+ codex_security_attempt_id: "parent-0",
codex_security_provider: "openai",
custom_tag: "preflight-default",
"team.tag": "literal-key-0",
diff --git a/plugins/codex-security/mcp-app/tests/deep_scan_worker_usage_assertions.ts b/plugins/codex-security/mcp-app/tests/deep_scan_worker_usage_assertions.ts
new file mode 100644
index 000000000..bf2585683
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/deep_scan_worker_usage_assertions.ts
@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { DeepScanLogEvent } from "../src/deep-scan/types.js";
+import type { WorkerUsageReceipt } from "../src/deep-scan/usage-receipt.js";
+import { readJson } from "./support/json.ts";
+import {
+ coordinatorFixture,
+ FakeExecutor,
+ runCoordinator,
+} from "./deep_scan_coordinator_fixture.ts";
+
+export function workerUsage(completedTurns: number) {
+ return {
+ input_tokens: 10 * completedTurns,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 2 * completedTurns,
+ reasoning_output_tokens: completedTurns,
+ total_tokens: 12 * completedTurns,
+ };
+}
+
+export function withCumulativeUsage(
+ executor: FakeExecutor,
+ workerUsageDirectory: string | undefined,
+) {
+ const originalRun = executor.run.bind(executor);
+ executor.run = async (request) => {
+ assert.equal(request.workerUsageDirectory, workerUsageDirectory);
+ const completedTurns = request.resumeThreadId ? 2 : 1;
+ return {
+ ...(await originalRun(request)),
+ usage: workerUsage(completedTurns),
+ };
+ };
+}
+
+export async function testWorkerUsageWithoutHostDirectory() {
+ const { fixture, store } = await coordinatorFixture();
+ delete fixture.run.workerUsageDirectory;
+ delete store.run.workerUsageDirectory;
+ const executor = new FakeExecutor();
+ const events: DeepScanLogEvent[] = [];
+ const terminal = await runCoordinator(fixture, store, executor, {
+ log: (event) => events.push(event),
+ });
+ assert.equal(terminal?.status, "succeeded");
+ assert.ok(events.some((event) => event.event === "worker_usage_unavailable"));
+ await assertNoArtifactUsage(fixture.run.scanDir);
+}
+
+export function assertNoArtifactUsage(scanDir: string) {
+ return assert.rejects(
+ readdir(join(scanDir, "artifacts", "deep_discovery", "usage")),
+ {
+ code: "ENOENT",
+ },
+ );
+}
+
+async function workerReceipts(
+ directory: string,
+): Promise<WorkerUsageReceipt[]> {
+ return Promise.all(
+ (await readdir(directory)).map((name) => readJson(join(directory, name))),
+ );
+}
+
+function assertPairedAttempts(
+ receipts: WorkerUsageReceipt[],
+ events: DeepScanLogEvent[],
+) {
+ const starts = events.filter((event) => event.event === "worker_started");
+ const finishes = events.filter((event) => event.event === "worker_finished");
+ assert.equal(starts.length, receipts.length);
+ assert.equal(finishes.length, starts.length);
+ for (const receipt of receipts)
+ assert.equal(receipt.usageScope, "thread_cumulative");
+ for (const start of starts) {
+ const finish = finishes.find(
+ (event) => event.attemptId === start.attemptId,
+ );
+ assert.ok(finish);
+ assert.equal(finish.kind, start.kind);
+ assert.equal(finish.retry, start.retry);
+ assert.equal(finish.resumed, start.resumed);
+ assert.ok(Number.isFinite(Date.parse(start.timestamp!)));
+ assert.ok(Number.isFinite(Date.parse(finish.timestamp!)));
+ assert.ok(finish.durationMs! >= 0);
+ }
+}
+
+export async function assertWorkerRetryReceipts(
+ directory: string,
+ events: DeepScanLogEvent[],
+ kind: "discovery" | "dedup" = "discovery",
+) {
+ const receipts = await workerReceipts(directory);
+ const workers = receipts
+ .filter((receipt) => receipt.kind === kind)
+ .sort((left, right) => left.attempt - right.attempt);
+ assert.equal(workers.length, 2);
+ assert.notEqual(workers[0].attemptId, workers[1].attemptId);
+ assert.equal(workers[0].threadId, workers[1].threadId);
+ assert.deepEqual(
+ workers.map((receipt) => [
+ receipt.outcome,
+ receipt.resumed,
+ receipt.usage?.total_tokens,
+ ]),
+ [
+ ["failed", false, 12],
+ ["succeeded", true, 24],
+ ],
+ );
+ assertPairedAttempts(receipts, events);
+}
+
+export async function assertCanceledWorkerReceipts(
+ directory: string,
+ events: DeepScanLogEvent[],
+ usageReported: boolean,
+) {
+ const receipts = await workerReceipts(directory);
+ assert.equal(receipts.length, 1);
+ assert.equal(receipts[0].outcome, "canceled");
+ if (usageReported) {
+ assert.equal(receipts[0].usage?.total_tokens, 12);
+ assert.equal(receipts[0].turnId, "synthetic-turn");
+ } else assert.equal(receipts[0].usage, null);
+ assert.ok(receipts[0].threadId);
+ assert.equal(
+ events.find((event) => event.event === "worker_finished")?.outcome,
+ "canceled",
+ );
+ assertPairedAttempts(receipts, events);
+}
diff --git a/plugins/codex-security/mcp-app/tests/support/fake-codex-fixture.ts b/plugins/codex-security/mcp-app/tests/support/fake-codex-fixture.ts
index 5fde2ee74..e6ec11bc9 100644
--- a/plugins/codex-security/mcp-app/tests/support/fake-codex-fixture.ts
+++ b/plugins/codex-security/mcp-app/tests/support/fake-codex-fixture.ts
@@ -42,7 +42,9 @@ export const emptyWorkerPermissionProfile = {
export async function createFakeCodexFixture(
temporaryDirectories: ReturnType<typeof createTemporaryDirectories>,
- preflightProfile = emptyWorkerPermissionProfile,
+ // null resolves the invocation's profile; explicit values exercise mismatches.
+ preflightProfile:
+ typeof emptyWorkerPermissionProfile | null = emptyWorkerPermissionProfile,
preflightAllowed = true,
accountResult: {
account: { type: string } | null;
diff --git a/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts b/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
index 2a2559712..b6ae04195 100644
--- a/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
+++ b/plugins/codex-security/mcp-app/tests/support/fake-codex-source.ts
@@ -11,7 +11,11 @@ export function fakeCodexSource(
import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { spawnSync } from "node:child_process";
-const preflightProfile = process.env.FAKE_CODEX_PREFLIGHT_PROFILE ? JSON.parse(process.env.FAKE_CODEX_PREFLIGHT_PROFILE) : ${JSON.stringify(preflightProfile)};
+const preflightProfile = process.env.FAKE_CODEX_PREFLIGHT_PROFILE ? JSON.parse(process.env.FAKE_CODEX_PREFLIGHT_PROFILE) : ${
+ preflightProfile === null
+ ? `(await import(${JSON.stringify(import.meta.resolve("smol-toml"))})).parse(process.argv.find(arg => arg.startsWith('permissions.codex_security_deep_scan_worker=')) ?? '').permissions?.codex_security_deep_scan_worker`
+ : JSON.stringify(preflightProfile)
+ };
const preflightAllowed = ${JSON.stringify(preflightAllowed)};
const accountResult = ${JSON.stringify(accountResult)};
const preflightMarkerPath = process.env.FAKE_CODEX_PREFLIGHT_MARKER ?? ${JSON.stringify(preflightMarkerPath)};
@@ -117,7 +121,8 @@ const schemaIndex = process.argv.indexOf('--output-schema');
const schema = schemaIndex < 0 ? undefined : JSON.parse(readFileSync(process.argv[schemaIndex + 1], 'utf8'));
const text = schema?.properties?.reviews ? '{"reviews":[]}' : schema?.properties?.defects ? JSON.stringify({defects: [{operation: 'Check ownership', failure: 'foreign object', path: 'fixture.py', reports: [{id: 0, evidence: 0}]}], uncertain: []}) : 'fixture final response';
console.log(JSON.stringify({ type: 'item.completed', item: { id: 'message-1', type: 'agent_message', text } }));
-console.log(JSON.stringify({ type: 'turn.completed', usage: stdin.includes('NULL_USAGE') ? null : { input_tokens: 1, cached_input_tokens: 0, output_tokens: 1 } }));
+const completedTurns = stdin.includes('COMPLETE_THEN_HANG') && process.argv.includes('resume') ? 2 : 1;
+console.log(JSON.stringify({ type: 'turn.completed', usage: stdin.includes('NULL_USAGE') ? null : { input_tokens: completedTurns, cached_input_tokens: 0, output_tokens: completedTurns } }));
if (stdin.includes('COMPLETE_THEN_HANG')) { setInterval(() => {}, 1_000); await new Promise(() => {}); }
}
`;
diff --git a/plugins/codex-security/mcp-app/tests/test_codex_profile.ts b/plugins/codex-security/mcp-app/tests/test_codex_profile.ts
index 7c2b4091c..b7c313ad6 100644
--- a/plugins/codex-security/mcp-app/tests/test_codex_profile.ts
+++ b/plugins/codex-security/mcp-app/tests/test_codex_profile.ts
@@ -137,7 +137,7 @@ async function fixture(mode = "success") {
emit({ type: "item.completed", item: { type: "agent_message", id: "fixture-item", text: "synthetic token=fixture-secret" } });
const completion = { type: "turn.completed" };
if (process.env.PROFILE_TEST_MODE === "null_usage") completion.usage = null;
- else if (process.env.PROFILE_TEST_MODE !== "missing_usage") completion.usage = { input_tokens: 2, cached_input_tokens: 1, output_tokens: 3, reasoning_output_tokens: 0, ...(args.includes("resume") ? { cache_write_input_tokens: 9 } : {}) };
+ else if (process.env.PROFILE_TEST_MODE !== "missing_usage") completion.usage = { input_tokens: 2, cached_input_tokens: 1, output_tokens: 3, reasoning_output_tokens: 0, ...(args.includes("resume") ? { cache_write_input_tokens: 9 } : {}), ...(process.env.PROFILE_TEST_MODE === "cache_zero" ? { cache_write_input_tokens: 0 } : {}) };
emit(completion);
process.exit(0);
}
@@ -227,6 +227,7 @@ test("native profile turns preserve settings, JSON events, schema cleanup, and r
input_tokens: 2,
cached_input_tokens: 1,
cache_write_input_tokens: 0,
+ cache_write_input_tokens_reported: false,
output_tokens: 3,
reasoning_output_tokens: 0,
},
@@ -307,6 +308,22 @@ test("native profile turns preserve settings, JSON events, schema cleanup, and r
}
});
+test("native profiles distinguish explicitly reported zero cache writes", async () => {
+ const f = await fixture("cache_zero");
+ try {
+ const result = await createCodexProfileClient<ThreadEvent>(f.options)
+ .startThread()
+ .run("synthetic prompt");
+ assert.equal(result.usage?.cache_write_input_tokens, 0);
+ assert.equal(
+ Object.hasOwn(result.usage!, "cache_write_input_tokens_reported"),
+ false,
+ );
+ } finally {
+ await f.cleanup();
+ }
+});
+
test("native profile children hide Windows console windows", async () => {
const f = await fixture();
const originalSpawn = childProcess.spawn;
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
index 55c33898b..3df88cdbd 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_coordinator.ts
@@ -1,5 +1,13 @@
import { testSharedReceiptSurvivesWorkerRetry } from "./deep_scan_receipt_cases.ts";
import { readJson, writeJson } from "./support/json.ts";
+import {
+ assertNoArtifactUsage,
+ assertWorkerRetryReceipts,
+ assertCanceledWorkerReceipts,
+ testWorkerUsageWithoutHostDirectory,
+ withCumulativeUsage,
+ workerUsage,
+} from "./deep_scan_worker_usage_assertions.ts";
import type { CoordinatorOptions } from "../src/deep-scan/coordinator.js";
import type { ScanDraftInput } from "../src/artifact-scan-draft.js";
import type { JsonObject } from "../src/types.js";
@@ -807,11 +815,17 @@ async function testMissingDiscoveryResultResumesExistingThread(
}
: {}),
});
+ withCumulativeUsage(executor, fixture.run.workerUsageDirectory);
+ const events: DeepScanLogEvent[] = [];
const sleeps: number[] = [];
const terminal = await runCoordinator(fixture, store, executor, {
random: () => 0,
retryDelaysMs: [1, 3, 9],
clock: recordingClock(sleeps),
+ log: (event) => {
+ events.push(event);
+ if (withToolFailure) throw new Error("Synthetic log sink failure");
+ },
});
assert.equal(terminal?.status, "succeeded", terminal?.error);
@@ -821,6 +835,8 @@ async function testMissingDiscoveryResultResumesExistingThread(
executor.discoveryThreadIds[0],
]);
assert.equal(new Set(executor.discoveryThreadIds).size, 1);
+ await assertWorkerRetryReceipts(fixture.run.workerUsageDirectory!, events);
+ await assertNoArtifactUsage(fixture.run.scanDir);
if (withToolFailure) {
const message = executor.options.discoveryDiagnostics![0].message;
assert.ok(
@@ -1013,14 +1029,25 @@ async function testWaiterDetachAndCancellation() {
);
}
-async function testCancellationDropsUnvalidatedDiscoveryResult() {
+async function testCancellationDropsUnvalidatedDiscoveryResult(
+ usageReported = false,
+) {
const { fixture, store } = await coordinatorFixture();
const executor = new FakeExecutor({ blockDiscoveryAfterWrite: true });
+ let reportUsage: CodexWorkerRequest["onUsage"];
+ const originalRun = executor.run.bind(executor);
+ executor.run = (request) => {
+ reportUsage = request.onUsage;
+ return originalRun(request);
+ };
+ const events: DeepScanLogEvent[] = [];
const coordinator = createCoordinator(fixture, store, executor, {
threadId: "checkpoint-owner",
+ log: (event) => events.push(event),
});
coordinator.start();
await executor.discoveryArtifactsWritten.promise;
+ if (usageReported) await reportUsage?.(workerUsage(1), "synthetic-turn");
const worker = [...store.workers.values()].find(
(candidate) => candidate.kind === "discovery",
);
@@ -1033,6 +1060,11 @@ async function testCancellationDropsUnvalidatedDiscoveryResult() {
coordinator.cancel("fixture canceled before host validation");
const terminal = await coordinator.wait(undefined, 5_000);
assert.equal(terminal?.status, "canceled");
+ await assertCanceledWorkerReceipts(
+ fixture.run.workerUsageDirectory!,
+ events,
+ usageReported,
+ );
await assert.rejects(
readFile(path.join(worker!.artifactDir, "result.json")),
{
@@ -1046,6 +1078,29 @@ async function testCancellationDropsUnvalidatedDiscoveryResult() {
);
}
+async function testDiscoveryAcceptanceFailureFinishesWorkerAsFailed() {
+ const { fixture, store } = await coordinatorFixture();
+ const updateWorker = store.updateWorker.bind(store);
+ store.updateWorker = async (update) => {
+ if (update.kind === "discovery" && update.status === "succeeded") {
+ throw new Error("Synthetic acceptance write failed");
+ }
+ return updateWorker(update);
+ };
+ const events: DeepScanLogEvent[] = [];
+ const terminal = await runCoordinator(fixture, store, new FakeExecutor(), {
+ log: (event) => events.push(event),
+ });
+ assert.equal(terminal?.status, "failed");
+ const finished = events.filter((event) => event.event === "worker_finished");
+ assert.equal(finished.length, 1);
+ assert.equal(finished[0].outcome, "failed");
+ const directory = fixture.run.workerUsageDirectory!;
+ const names = await readdir(directory);
+ assert.equal(names.length, 1);
+ assert.equal((await readJson(directory, names[0])).outcome, "failed");
+}
+
async function testCancellationDuringDiscoveryAcceptanceRejectsLateSuccess() {
const { fixture, store } = await coordinatorFixture();
store.blockDiscoveryUpdate = "succeeded";
@@ -1103,6 +1158,11 @@ async function testCancellationDuringDiscoveryAcceptanceRejectsLateSuccess() {
),
false,
);
+ await assertCanceledWorkerReceipts(
+ fixture.run.workerUsageDirectory!,
+ events,
+ false,
+ );
const worker = [...store.workers.values()].find(
(worker) => worker.kind === "discovery",
);
@@ -2869,12 +2929,14 @@ test(testDiscoveryPhasePersistenceFailureStopsDispatch);
test(testCancellationClearsRetryWait);
test(testGenericDiagnosticsPreserveMissingResultRetries);
registerCases(testMissingDiscoveryResultResumesExistingThread, [[], [true]]);
+test(testWorkerUsageWithoutHostDirectory);
test(testInvalidArtifactsRetry);
test(testSharedReceiptSurvivesWorkerRetry);
test(testCancellationAfterCommittedAggregateRemainsCanceled);
test(testRejectedFinishDoesNotOverwriteReplacementManifest);
test(testWaiterDetachAndCancellation);
-test(testCancellationDropsUnvalidatedDiscoveryResult);
+registerCases(testCancellationDropsUnvalidatedDiscoveryResult, [[], [true]]);
+test(testDiscoveryAcceptanceFailureFinishesWorkerAsFailed);
test(testCancellationDuringDiscoveryAcceptanceRejectsLateSuccess);
test(testRegistryEvictionAndExternalFailure);
test(testStoppedPublicationFailurePreservesOriginalDiagnostic);
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_diagnostics.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_diagnostics.ts
index dcb643d8f..84e46ec09 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_diagnostics.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_diagnostics.ts
@@ -65,7 +65,8 @@ test("Standard scan retries preserve the full validation error", async () => {
if (validations++ === 0) throw validationError;
},
});
- assert.equal(outcome.status, "succeeded");
+ assert.equal(outcome.status, "validated");
+ await outcome.finish("succeeded");
assert.equal(requests.length, 2);
const retry = await readFile(requests[1].promptPath, "utf8");
const data = JSON.parse(
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
index 7e12d7272..fffc46fc2 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_executor.ts
@@ -1056,12 +1056,20 @@ async function testReportOnlyComparison() {
},
});
const input = "Compare the two supplied reports.";
+ const onThreadStarted = mock.fn();
+ const onUsage = mock.fn();
const response = await executor.compareFindings(
input,
workingDirectory,
new AbortController().signal,
{ type: "object", properties: { reviews: { type: "array" } } },
+ { attemptId: "fixture-comparison", onThreadStarted, onUsage },
);
+ assert.equal(
+ onThreadStarted.mock.calls[0]?.arguments[0],
+ "fixture-thread-id",
+ );
+ assert.equal(onUsage.mock.calls[0]?.arguments[0]?.total_tokens, 2);
assert.deepEqual(JSON.parse(response), { reviews: [] });
const invocation = await readJson(fixture.markerPath);
assert.equal(invocation.stdin, input);
@@ -1070,6 +1078,7 @@ async function testReportOnlyComparison() {
assertConfigOverrides(invocation.argv, {
model_reasoning_effort: "high",
"responses_api_metadata.codex_security_worker_role": "compare",
+ "responses_api_metadata.codex_security_attempt_id": "fixture-comparison",
"mcp_servers.cs_artifacts": undefined,
"features.shell_tool": false,
"features.image_generation": false,
@@ -1632,6 +1641,13 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
? undefined
: path.join(codexHome, `${nativeProfile}.config.toml`);
const literalDeniedPath = `/repo/literal.key"\\雪\u007f-${index}`;
+ const workerUsageDirectory = path.join(
+ fixture.root,
+ `state-${index}`,
+ "codex-home",
+ "worker-usage",
+ `scan-${index}`,
+ );
const parentSandbox = {
filesystemDenies: [
...trustedParentSandboxWithDenials.filesystemDenies,
@@ -1695,12 +1711,14 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
nativeProfile,
profilePath,
parentSandbox,
+ workerUsageDirectory,
permissionProfile: {
...deniedWorkerPermissionProfile,
filesystem: {
...deniedWorkerPermissionProfile.filesystem,
[deepPath]: { ".": "deny" },
[codexHome]: { ".": "deny" },
+ [workerUsageDirectory]: { ".": "deny" },
[literalDeniedPath]: { ".": "deny" },
},
},
@@ -1995,6 +2013,19 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
path.join(fixture.root, `selected node ${index}`, "node"),
);
+ await Promise.all(
+ settings.map(async (_, index) => {
+ const directory = path.join(
+ fixture.root,
+ `plugin-${index}`,
+ ".codex-plugin",
+ );
+ await mkdir(directory, { recursive: true });
+ await writeJson(path.join(directory, "plugin.json"), {
+ version: `9.9.${index}`,
+ });
+ }),
+ );
const executors = settings.map(
(modelSettings, index) =>
new CodexSdkWorkerExecutor({
@@ -2067,6 +2098,9 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
);
return executor.run(
workerRequest(promptPath, workerDirectories[index], {
+ attemptId: `worker-${index}-discovery-${resumeThreadId ?? "new"}`,
+ workerUsageDirectory:
+ workerConfigurations[index].workerUsageDirectory,
subagents,
resumeThreadId,
...(resumeThreadId
@@ -2150,6 +2184,12 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
workerLaunch.environment!.CODEX_SECURITY_KNOWLEDGE_BASE,
workerConfigurations[index].knowledgePath,
);
+ assert.equal(
+ selectedProvider.parentSandbox.literalFilesystemDenies.includes(
+ selectedProvider.workerUsageDirectory,
+ ),
+ false,
+ );
const invocation = await readJson(workerLaunch.markerPath);
assertFlagPair(invocation.argv, "--cd", workerDirectories[index]);
assert.equal(
@@ -2313,7 +2353,17 @@ env_key = "SYNTHETIC_GATEWAY_KEY"`,
codex_security_surface: "plugin",
codex_security_command: "scan",
codex_security_scan_mode: "deep",
+ codex_security_plugin_version: `9.9.${index}`,
...workerConfigurations[index].telemetry.responses_api_metadata,
+ codex_security_operation_id:
+ selectedProvider.telemetry.responses_api_metadata
+ ?.codex_security_operation_id ??
+ `fixture-scan-${model ?? "inherited"}`,
+ codex_security_attempt_id: `worker-${index}-discovery-${resumeThreadId ?? "new"}`,
+ ...(selectedProvider.telemetry.responses_api_metadata
+ ?.codex_security_attempt_id
+ ? { codex_security_parent_attempt_id: `parent-${index}` }
+ : {}),
codex_security_worker_role: "discovery",
},
},
@@ -3380,6 +3430,7 @@ async function testAbortPropagation() {
async function testCompletedWorkerSettlesWithoutWaitingForProcessExit() {
await completedWorkerSettlesWithoutWaitingForProcessExit();
+ await completedWorkerSettlesWithoutWaitingForProcessExit(false, true);
for (const resumed of [false, true]) {
await completedWorkerSettlesWithoutWaitingForProcessExit(true, resumed);
}
@@ -3467,6 +3518,10 @@ async function completedWorkerSettlesWithoutWaitingForProcessExit(
result.threadId,
resumed ? "fixture-resumed-thread-id" : "fixture-thread-id",
);
+ assert.equal(result.usage?.cache_write_input_tokens, 0);
+ assert.equal(result.usage?.cache_write_input_tokens_reported, false);
+ assert.equal(result.usage?.input_tokens, resumed ? 2 : 1);
+ assert.equal(result.usage?.total_tokens, resumed ? 4 : 2);
const invocation = await readJson(fixture.markerPath);
assert.equal(invocation.argv.includes("--profile"), withProfile);
assert.equal(invocation.argv.includes("resume"), resumed);
diff --git a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts
index cbaddda8e..30de1491a 100644
--- a/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts
+++ b/plugins/codex-security/mcp-app/tests/test_deep_scan_stdio_lifecycle.ts
@@ -201,7 +201,6 @@ service_tier = "ultrafast"
FAKE_CODEX_RESTART_CONTROL: restartControlPath,
FAKE_CODEX_SIGNAL_CHECKPOINT_CONTROL: signalCheckpointControlPath,
FAKE_CODEX_START_LOG: startLogPath,
- FAKE_CODEX_DENIED_HOME: codexHome,
};
const server = startServer(serverBundlePath, environment);
@@ -379,7 +378,12 @@ service_tier = "ultrafast"
startedWorker.argv.includes('model_reasoning_summary="none"'),
true,
);
- assertReadOnlyWorkerInvocation(startedWorker.argv, codexHome);
+ assertReadOnlyWorkerInvocation(
+ startedWorker.argv,
+ codexHome,
+ stateDir,
+ scanId,
+ );
assertWorkerArtifactEnvironment(
startedWorker.argv,
pluginRoot,
@@ -623,7 +627,12 @@ service_tier = "ultrafast"
failedWorker.argv.includes('model_reasoning_effort="high"'),
true,
);
- assertReadOnlyWorkerInvocation(failedWorker.argv, codexHome);
+ assertReadOnlyWorkerInvocation(
+ failedWorker.argv,
+ codexHome,
+ stateDir,
+ failedScanId,
+ );
assert.equal(activeFailureState.workers.length, 1);
assert.equal(activeFailureState.workers[0].kind, "discovery");
assert.equal(activeFailureState.workers[0].status, "running");
@@ -956,7 +965,9 @@ service_tier = "ultrafast"
resumedScanId,
]);
const { accountRateLimits: _limits, ...usage } = sealed.scan.usage;
- assert.equal(usage.coverage, "unavailable");
+ // The synthetic workers report their tokens; the parent has no usage receipt.
+ assert.equal(usage.coverage, "partial");
+ assert.ok(usage.inputTokens > 0);
assert.ok(usage.warnings.length);
assert.deepEqual(completion, {
scan: {
@@ -1053,7 +1064,12 @@ service_tier = "ultrafast"
for (const [index, execution] of executions.entries()) {
const afterRestart = index + restartStartIndex >= resumedStartIndex;
assertConfigOverrides(execution.argv, { service_tier: "default" });
- assertReadOnlyWorkerInvocation(execution.argv, codexHome);
+ assertReadOnlyWorkerInvocation(
+ execution.argv,
+ codexHome,
+ stateDir,
+ resumedScanId,
+ );
assert.equal(execution.readCoreScanReference, true);
const context = discoveryPromptContext(execution.stdin);
if (context.workerLabel) {
@@ -1415,7 +1431,12 @@ async function testCliDeepScanEngine({
["discovery-0001", "discovery-0002"],
);
for (const entry of starts) {
- assertReadOnlyWorkerInvocation(entry.argv, codexHome);
+ assertReadOnlyWorkerInvocation(
+ entry.argv,
+ codexHome,
+ environment.CODEX_SECURITY_STATE_DIR!,
+ completed.scanId,
+ );
assertFlagPair(entry.argv, "--model", "gpt-6.1-sol");
assert.ok(entry.argv.includes('model_reasoning_effort="max"'));
assert.equal(entry.hasExpectedApiKey, true);
@@ -1612,7 +1633,12 @@ function assertWorkerArtifactEnvironment(
assert.equal(env.CODEX_SECURITY_PYTHON_COMMAND, expectedPython);
}
-function assertReadOnlyWorkerInvocation(args: string[], deniedHome: string) {
+function assertReadOnlyWorkerInvocation(
+ args: string[],
+ deniedHome: string,
+ stateDirectory: string,
+ scanId: string,
+) {
assert.equal(args.includes("--sandbox"), false);
assert.equal(args.includes("--add-dir"), false);
assert.equal(
@@ -1640,7 +1666,7 @@ function assertReadOnlyWorkerInvocation(args: string[], deniedHome: string) {
overrides.map((value) => parseToml(value)),
[
parseToml(
- `permissions.codex_security_deep_scan_worker={extends=":read-only",filesystem={":root"="read",${JSON.stringify(deniedHome)}={"."="deny"}},network={enabled=false}}`,
+ `permissions.codex_security_deep_scan_worker={extends=":read-only",filesystem={":root"="read",${JSON.stringify(deniedHome)}={"."="deny"},${JSON.stringify(path.join(stateDirectory, "codex-home", "worker-usage", scanId))}={"."="deny"}},network={enabled=false}}`,
),
],
);
@@ -1749,6 +1775,8 @@ async function writeFakeCodex(executablePath: string) {
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import path from "node:path";
if (process.argv.includes('app-server')) {
+const profileOverride = process.argv.find(arg => arg.startsWith('permissions.codex_security_deep_scan_worker='));
+const workerProfile = (await import(${JSON.stringify(import.meta.resolve("smol-toml"))})).parse(profileOverride ?? '').permissions?.codex_security_deep_scan_worker;
${jsonLineInputSource(` if (message.method === 'initialized') continue;
let result;
if (message.method === 'initialize') {
@@ -1756,7 +1784,7 @@ ${jsonLineInputSource(` if (message.method === 'initialized') continue;
} else if (message.method === 'thread/read') {
result = { thread: { id: message.params.threadId, path: path.join(process.env.CODEX_HOME, message.params.threadId + '.jsonl') } };
} else if (message.method === 'config/read') {
- result = { config: { default_permissions: 'codex_security_deep_scan_worker', permissions: { codex_security_deep_scan_worker: { extends: ':read-only', filesystem: { ':root': 'read', [process.env.FAKE_CODEX_DENIED_HOME]: { '.': 'deny' } }, network: { enabled: false } } } }, origins: {}, layers: null };
+ result = { config: { default_permissions: 'codex_security_deep_scan_worker', permissions: { codex_security_deep_scan_worker: workerProfile } }, origins: {}, layers: null };
} else if (message.method === 'permissionProfile/list') {
result = { data: [{ id: 'codex_security_deep_scan_worker', description: null, allowed: true }], nextCursor: null };
} else if (message.method === 'account/read') {
diff --git a/plugins/codex-security/mcp-app/tests/test_session_decompression.ts b/plugins/codex-security/mcp-app/tests/test_session_decompression.ts
new file mode 100644
index 000000000..74b6061af
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/test_session_decompression.ts
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { importSource } from "./import-module.ts";
+
+const { createZstdDecompress } = await importSource(
+ fileURLToPath(new URL("../src/session-decompression.ts", import.meta.url)),
+);
+
+// One frame containing 128 KiB of "a", compressed with Zstandard level 3.
+const frame = Buffer.from("KLUv/aAAAAIAVQAAEGFhAQD7/znAAg==", "base64");
+const decodedFrame = Buffer.alloc(128 * 1024, "a");
+
+test("ended input waits for readable demand before expanding queued frames", async () => {
+ const stream = createZstdDecompress();
+ try {
+ stream.write(frame);
+ stream.write(frame);
+ stream.end(frame);
+
+ assert.equal(stream.readableLength, decodedFrame.length);
+ const first = stream.read(decodedFrame.length);
+ assert.deepEqual(first, decodedFrame);
+ assert.ok(
+ stream.readableLength <= decodedFrame.length,
+ "a single read must not expand every queued compressed frame",
+ );
+
+ const chunks = [first];
+ for await (const chunk of stream) chunks.push(chunk);
+ assert.deepEqual(
+ Buffer.concat(chunks),
+ Buffer.concat([decodedFrame, decodedFrame, decodedFrame]),
+ );
+ } finally {
+ stream.destroy();
+ }
+});
+
+test("decodes concatenated frames split across compressed chunks", async () => {
+ const stream = createZstdDecompress();
+ const input = Buffer.concat([frame, frame]);
+ for (let offset = 0; offset < input.length; offset += 5) {
+ stream.write(input.subarray(offset, offset + 5));
+ }
+ stream.end();
+ const chunks = [];
+ for await (const chunk of stream) chunks.push(chunk);
+ assert.deepEqual(
+ Buffer.concat(chunks),
+ Buffer.concat([decodedFrame, decodedFrame]),
+ );
+});
+
+test("reports a truncated tail after a complete concatenated frame", async () => {
+ const stream = createZstdDecompress();
+ stream.end(Buffer.concat([frame, frame.subarray(0, frame.length - 3)]));
+ await assert.rejects(async () => {
+ for await (const _chunk of stream) {
+ // Consume the complete prefix so the decoder can validate the tail.
+ }
+ }, /unexpected EOF/);
+});
+
+test("cancellation during decoded output completes the current write", async () => {
+ const stream = createZstdDecompress();
+ const cancellation = new Error("synthetic cancellation");
+ const closed = new Promise<void>((resolve) => stream.once("close", resolve));
+ let emittedError: Error | undefined;
+ let writeCompleted = false;
+ stream.on("error", (error: Error) => {
+ emittedError = error;
+ });
+ stream.once("data", () => stream.destroy(cancellation));
+ stream.write(Buffer.concat([frame, frame]), () => {
+ writeCompleted = true;
+ });
+ await closed;
+ assert.equal(emittedError, cancellation);
+ assert.equal(writeCompleted, true);
+});
diff --git a/plugins/codex-security/mcp-app/tests/test_workbench_process.ts b/plugins/codex-security/mcp-app/tests/test_workbench_process.ts
index 303f57f2f..ba3d18542 100644
--- a/plugins/codex-security/mcp-app/tests/test_workbench_process.ts
+++ b/plugins/codex-security/mcp-app/tests/test_workbench_process.ts
@@ -43,6 +43,59 @@ async function fixtureWorkbench(root: string, source: string) {
return executeWorkbench as WorkbenchModule["executeWorkbench"];
}
+await test("Python compressed-rollout reads inherit the plugin Node without Node on PATH", async () => {
+ const root = await temporaryDirectory("workbench-node-runtime-");
+ const python = await userSitePython();
+ const original = {
+ PATH: process.env.PATH,
+ CODEX_MCP_NODE_PATH: process.env.CODEX_MCP_NODE_PATH,
+ };
+ try {
+ const rollout = path.join(root, "rollout.jsonl.zst");
+ await writeFile(
+ rollout,
+ Buffer.from(
+ "KLUv/SA2sQEAeyJ0eXBlIjoic2Vzc2lvbl9tZXRhIiwicGF5bG9hZCI6eyJpZCI6ImNvbXByZXNzZWQifX0K",
+ "base64",
+ ),
+ );
+ const scripts = path.resolve(
+ import.meta.dirname,
+ "../../../../sdk/typescript/_bundled_plugin/scripts",
+ );
+ const execute = await fixtureWorkbench(
+ root,
+ `import json, os, sys
+from pathlib import Path
+sys.path.insert(0, ${JSON.stringify(scripts)})
+from workbench_scan_usage import _rollout_lines
+def main():
+ with _rollout_lines(Path(sys.argv[1])) as source:
+ contents = b"".join(source).decode("utf-8")
+ print(json.dumps({"contents": contents, "node": os.environ["CODEX_MCP_NODE_PATH"]}))
+`,
+ );
+ process.env.PATH = "";
+ for (const configured of [undefined, ""]) {
+ if (configured === undefined) delete process.env.CODEX_MCP_NODE_PATH;
+ else process.env.CODEX_MCP_NODE_PATH = configured;
+ const result = await execute(python, [rollout]);
+ assert.equal(result.node, process.execPath);
+ assert.equal(
+ result.contents,
+ '{"type":"session_meta","payload":{"id":"compressed"}}\n',
+ );
+ assert.equal(process.env.CODEX_MCP_NODE_PATH, configured);
+ }
+ } finally {
+ for (const [name, value] of Object.entries(original)) {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+ }
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
await test("workbench scalar arguments reach the Python parser literally", async () => {
const root = await temporaryDirectory("workbench-literal-arguments-");
try {
diff --git a/plugins/codex-security/mcp-app/tests/test_worker_usage_receipt.ts b/plugins/codex-security/mcp-app/tests/test_worker_usage_receipt.ts
new file mode 100644
index 000000000..65a4f7c1b
--- /dev/null
+++ b/plugins/codex-security/mcp-app/tests/test_worker_usage_receipt.ts
@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { importSource } from "./import-module.ts";
+import { fileURLToPath } from "node:url";
+
+const { workerTokenUsage } = await importSource(
+ fileURLToPath(new URL("../src/deep-scan/usage-receipt.ts", import.meta.url)),
+);
+
+test("SDK defaulted zero remains unknown while positive native and legacy writes remain known", () => {
+ const usage = { input_tokens: 10, cached_input_tokens: 2, output_tokens: 3 };
+ assert.equal(
+ workerTokenUsage({ ...usage, cache_write_input_tokens: 0 }, true)
+ .cache_write_input_tokens_reported,
+ false,
+ );
+ assert.equal(
+ workerTokenUsage({ ...usage, cache_write_input_tokens: 0 }, false)
+ .cache_write_input_tokens_reported,
+ undefined,
+ );
+ for (const writes of [
+ { cache_write_input_tokens: 4 },
+ { cache_write_input_tokens: 0, cache_write_tokens: 4 },
+ ]) {
+ const normalized = workerTokenUsage({ ...usage, ...writes }, true);
+ assert.equal(normalized.cache_write_input_tokens, 4);
+ assert.equal(normalized.cache_write_input_tokens_reported, undefined);
+ }
+});
diff --git a/plugins/codex-security/plugin-files.json b/plugins/codex-security/plugin-files.json
index 90687ea92..1329685ef 100644
--- a/plugins/codex-security/plugin-files.json
+++ b/plugins/codex-security/plugin-files.json
@@ -11,6 +11,7 @@
"examples/legacy-completed-scan/findings.json",
"examples/legacy-completed-scan/report.md",
"examples/legacy-completed-scan/scan-manifest.json",
+ "mcp/fzstd-LICENSE.txt",
"mcp/helpers.mjs",
"mcp/helpers.mjs.br.part-000",
"mcp/helpers.mjs.br.part-001",
@@ -33,6 +34,7 @@
"mcp/server.mjs.br.part-000",
"mcp/server.mjs.br.part-001",
"mcp/server.mjs.br.part-002",
+ "mcp/session-decompression.mjs",
"references/access-advisory.md",
"references/artifact-storage.md",
"references/core-scan.md",
@@ -73,6 +75,7 @@
"scripts/launch_codex_security_mcp.cmd",
"scripts/legacy_findings.py",
"scripts/posix_scan_local_files.py",
+ "scripts/read_codex_session.mjs",
"scripts/report_projection.py",
"scripts/review_state.py",
"scripts/reserved_artifact_paths.json",
diff --git a/plugins/codex-security/scripts/codex_profile.mjs b/plugins/codex-security/scripts/codex_profile.mjs
index 8ad053f1c..5dc49fcf9 100644
--- a/plugins/codex-security/scripts/codex_profile.mjs
+++ b/plugins/codex-security/scripts/codex_profile.mjs
@@ -127,8 +127,14 @@ class ProfileThread {
);
}
if (event.type === "thread.started") this.id = event.thread_id;
- if (event.type === "turn.completed" && event.usage != null)
+ if (event.type === "turn.completed" && event.usage != null) {
+ if (
+ event.usage.cache_write_input_tokens == null &&
+ event.usage.cache_write_tokens == null
+ )
+ event.usage.cache_write_input_tokens_reported = false;
event.usage.cache_write_input_tokens ??= 0;
+ }
yield event;
}
} finally {
diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.py
index 77beac07d..63a70fb0e 100644
--- a/plugins/codex-security/scripts/deep_scan_workbench.py
+++ b/plugins/codex-security/scripts/deep_scan_workbench.py
@@ -16,7 +16,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
import workbench_saved_results as saved_results
from deep_scan_config import resolve_deep_scan_setup
from workbench.handoff import require_current_continuation
-from workbench.storage import archived_deep_path, create_private_directory, saved_deep_workers
+from workbench.storage import (
+ archived_deep_path,
+ create_private_directory,
+ saved_deep_workers,
+ worker_usage_directory,
+)
from workbench_constants import PHASES
from workbench_source_scopes import capture_source_scopes
from workbench_target import directory_snapshot_regular_file_count
@@ -346,6 +351,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
else scan["user_context"]
),
"scanDir": scan["scan_dir"],
+ "workerUsageDirectory": str(worker_usage_directory(run["scan_id"])),
"schemaVersion": run["schema_version"],
"workflowVersion": run["workflow_version"],
"coordinatorGeneration": run["coordinator_generation"],
diff --git a/plugins/codex-security/scripts/read_codex_session.mjs b/plugins/codex-security/scripts/read_codex_session.mjs
new file mode 100644
index 000000000..31b50c2b4
--- /dev/null
+++ b/plugins/codex-security/scripts/read_codex_session.mjs
@@ -0,0 +1,21 @@
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+
+// The Python usage collector uses the plugin's required Node runtime to read
+// cold rollouts without requiring a separate Python compression dependency.
+try {
+ const path = process.argv[2];
+ if (!path) throw new Error("A Codex rollout path is required.");
+ // Native Node decoding can stop after the first frame. Rollouts may contain
+ // concatenated frames, and an incomplete later frame must remain an error.
+ const { createZstdDecompress } =
+ await import("../mcp/session-decompression.mjs");
+ await pipeline(
+ createReadStream(path),
+ createZstdDecompress(),
+ process.stdout,
+ );
+} catch (error) {
+ console.error(error instanceof Error ? error.message : String(error));
+ process.exitCode = 1;
+}
diff --git a/plugins/codex-security/scripts/workbench/storage.py b/plugins/codex-security/scripts/workbench/storage.py
index 90abe5cd3..119e5b163 100644
--- a/plugins/codex-security/scripts/workbench/storage.py
+++ b/plugins/codex-security/scripts/workbench/storage.py
@@ -26,6 +26,11 @@ def resolve_scan_root(scan_root: str | None) -> Path:
return Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
+def worker_usage_directory(scan_id: str) -> Path:
+ """Bind host-observed receipts beneath the persistent protected native home."""
+ return state_dir() / "codex-home" / "worker-usage" / scan_id
+
+
def archived_deep_path(scan_dir: Path, value: str | None) -> str | None:
"""Resolve old archive rows that still name the original sibling output."""
if value is None or ".previous-" not in scan_dir.name:
diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.py
index d1936c4ec..30a848fe5 100644
--- a/plugins/codex-security/scripts/workbench_db.py
+++ b/plugins/codex-security/scripts/workbench_db.py
@@ -1032,13 +1032,16 @@ def complete_scan(
def read_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
# Validation can finish after the scan's recorded completion timestamp.
- return scan_usage.collect_scan_usage(
+ usage = scan_usage.collect_scan_usage(
connection,
require_scan(connection, args.scan_id),
thread_id=args.thread_id,
validation_thread_id=args.validation_thread_id,
completed_at=now(),
)
+ if "cacheWriteInputTokens" in usage:
+ usage.setdefault("cacheWriteInputTokensReported", True)
+ return usage
def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
@@ -1053,7 +1056,7 @@ def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace
if completion["threadId"] != args.thread_id or completion["turnId"] != args.turn_id:
raise SystemExit("The scan usage belongs to a different completion turn.")
if not completion["finalized"]:
- usage = scan_usage.collect_scan_usage(
+ usage = scan_usage.collect_scan_usage_safely(
connection,
scan,
thread_id=args.thread_id,
@@ -1072,7 +1075,9 @@ def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace
f"scan_turn_{args.turn_status}",
]
usage["completion"] = {**completion, "finalized": True}
- cost_json = parse_scan_cost(json.dumps({**stored, "usage": usage}))
+ fields = scan_usage.merge_scan_usage_fields(stored, {"usage": usage})
+ fields["usage"]["completion"] = usage["completion"]
+ cost_json = parse_scan_cost(json.dumps(fields))
with connection:
connection.execute(
"UPDATE scans SET cost_json = ? WHERE id = ?", (cost_json, scan_id)
@@ -1382,26 +1387,27 @@ def complete_scan_locked(
context["targetWarnings"] = target_warnings
return context
- cost_fields = scan_usage.stored_scan_cost_fields(cost_json)
- if "usage" not in cost_fields:
- cost_fields["usage"] = scan_usage.collect_scan_usage(
- connection,
- scan,
- thread_id=thread_id,
- completed_at=completion_timestamp,
+ measured_usage = scan_usage.collect_scan_usage_safely(
+ connection,
+ scan,
+ thread_id=thread_id,
+ completed_at=completion_timestamp,
+ )
+ cost_fields = scan_usage.merge_scan_usage_fields(
+ scan_usage.stored_scan_cost_fields(cost_json), {"usage": measured_usage}
+ )
+ measured_usage = cost_fields["usage"]
+ if thread_id is not None and turn_id is not None:
+ measured_usage["completion"] = {
+ "threadId": thread_id,
+ "turnId": turn_id,
+ "finalized": False,
+ }
+ if measured_usage["coverage"] == "complete":
+ measured_usage["coverage"] = "partial"
+ measured_usage["warnings"] = sorted(
+ {*measured_usage.get("warnings", []), "turn_in_progress"}
)
- measured_usage = cost_fields["usage"]
- if thread_id is not None and turn_id is not None:
- measured_usage["completion"] = {
- "threadId": thread_id,
- "turnId": turn_id,
- "finalized": False,
- }
- if measured_usage["coverage"] == "complete":
- measured_usage["coverage"] = "partial"
- measured_usage["warnings"] = sorted(
- {*measured_usage.get("warnings", []), "turn_in_progress"}
- )
cost_json = parse_scan_cost(json.dumps(cost_fields))
connection.execute("BEGIN IMMEDIATE")
with connection:
diff --git a/plugins/codex-security/scripts/workbench_saved_results.py b/plugins/codex-security/scripts/workbench_saved_results.py
index 466d9f680..af4d506d5 100644
--- a/plugins/codex-security/scripts/workbench_saved_results.py
+++ b/plugins/codex-security/scripts/workbench_saved_results.py
@@ -1252,6 +1252,7 @@ def fail_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
scan = db.require_scan(connection, scan_id)
if scan["status"] == "failed":
connection.commit()
+ record_stopped_scan_usage(db, connection, scan_id, cost_json)
return db.scan_context(connection, scan["id"])
if scan["status"] == "complete":
raise SystemExit("A completed scan cannot be marked failed.")
@@ -1264,11 +1265,10 @@ def fail_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
updated = connection.execute(
"""
UPDATE scans
- SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?,
- cost_json = ?
+ SET status = 'failed', failure_message = ?, completed_at = ?, updated_at = ?
WHERE id = ? AND status = 'running'
""",
- (message, timestamp, timestamp, cost_json, scan["id"]),
+ (message, timestamp, timestamp, scan["id"]),
)
if updated.rowcount != 1:
raise SystemExit("Only a running scan can be marked failed.")
@@ -1279,6 +1279,7 @@ def fail_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
)
if progress_updated.rowcount != 1:
raise SystemExit("Codex Security scan progress not found.")
+ record_stopped_scan_usage(db, connection, scan_id, cost_json)
preserve_stopped_results_after_transition(db, connection, scan["id"])
return db.scan_context(connection, scan["id"])
@@ -1302,6 +1303,7 @@ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
raise SystemExit("A scan can only be canceled from its owning Codex thread.")
if scan["canceled_at"] is not None:
connection.commit()
+ record_stopped_scan_usage(db, connection, scan_id, cost_json)
return {
**db.workspace_state(connection, scan["workspace_id"]),
"canceledScanId": scan["id"],
@@ -1311,11 +1313,10 @@ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
updated = connection.execute(
"""
UPDATE scans
- SET status = 'failed', canceled_at = ?, completed_at = ?, updated_at = ?,
- cost_json = COALESCE(?, cost_json)
+ SET status = 'failed', canceled_at = ?, completed_at = ?, updated_at = ?
WHERE id = ? AND status = 'running'
""",
- (timestamp, timestamp, timestamp, cost_json, scan["id"]),
+ (timestamp, timestamp, timestamp, scan["id"]),
)
if updated.rowcount != 1:
raise SystemExit("Only a running scan can be canceled.")
@@ -1326,10 +1327,41 @@ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
)
if progress_updated.rowcount != 1:
raise SystemExit("Codex Security scan progress not found.")
+ record_stopped_scan_usage(db, connection, scan_id, cost_json)
preserve_stopped_results_after_transition(db, connection, scan["id"])
return {**db.workspace_state(connection, scan["workspace_id"]), "canceledScanId": scan["id"]}
+def record_stopped_scan_usage(
+ db: Any, connection: Any, scan_id: str, cost_json: str | None = None
+) -> None:
+ """Keep optional accounting independent of the already-persisted scan outcome."""
+
+ try:
+ scan = db.require_scan(connection, scan_id)
+ fields = db.scan_usage.merge_scan_usage_fields(
+ db.scan_usage.stored_scan_cost_fields(scan["cost_json"]),
+ db.scan_usage.stored_scan_cost_fields(cost_json),
+ )
+ fields = db.scan_usage.merge_scan_usage_fields(
+ fields,
+ {"usage": db.scan_usage.collect_scan_usage_safely(connection, scan)},
+ )
+ if fields:
+ encoded = db.parse_scan_cost(json.dumps(fields))
+ with connection:
+ connection.execute(
+ "UPDATE scans SET cost_json = ? WHERE id = ? AND status = 'failed'",
+ (encoded, scan_id),
+ )
+ except (Exception, SystemExit) as exc:
+ try:
+ print(f"Could not save stopped scan token usage: {exc}", file=sys.stderr)
+ except OSError:
+ # A closed diagnostic stream must not alter the persisted scan outcome.
+ pass
+
+
def preserve_stopped_results_after_transition(db: Any, connection: Any, scan_id: str) -> None:
"""Try to publish saved evidence after stopping a scan and record a warning if publication fails."""
try:
diff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.py
index 04eef1c1b..dc4b7a845 100644
--- a/plugins/codex-security/scripts/workbench_scan_usage.py
+++ b/plugins/codex-security/scripts/workbench_scan_usage.py
@@ -8,15 +8,20 @@ import math
import os
import re
import sqlite3
+import subprocess
import sys
+import tempfile
import uuid
from contextlib import contextmanager
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
-from typing import Any, BinaryIO, Iterator, Mapping
+from typing import Any, Mapping
from urllib.parse import quote
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from workbench.storage import worker_usage_directory
+
TOKEN_FIELDS = {
"input_tokens": "inputTokens",
"cached_input_tokens": "cachedInputTokens",
@@ -71,13 +76,27 @@ def reconcile_completed_scan_cost(
) -> None:
"""Persist authoritative SDK cost without discarding measured worker usage."""
- existing = json.loads(scan["cost_json"]) if scan["cost_json"] is not None else {}
- if isinstance(existing, dict) and "usage" in existing:
- cost_json = json.dumps(
- {**existing, "cost": json.loads(cost_json)},
- separators=(",", ":"),
- allow_nan=False,
- )
+ stored = stored_scan_cost_fields(scan["cost_json"])
+ completion = stored.get("usage", {}).get("completion")
+ native = collect_scan_usage_safely(
+ connection,
+ scan,
+ thread_id=completion["threadId"] if completion else None,
+ completed_turn_id=completion["turnId"] if completion and completion["finalized"] else None,
+ )
+ fields = merge_scan_usage_fields(stored, stored_scan_cost_fields(cost_json), {"usage": native})
+ if completion:
+ usage = {**fields["usage"], "completion": completion}
+ if not completion["finalized"]:
+ if usage["coverage"] == "complete":
+ usage["coverage"] = "partial"
+ usage["warnings"] = sorted({*usage.get("warnings", []), "turn_in_progress"})
+ fields["usage"] = usage
+ cost_json = json.dumps(
+ fields if "usage" in fields else fields["cost"],
+ separators=(",", ":"),
+ allow_nan=False,
+ )
connection.execute("BEGIN IMMEDIATE")
with connection:
connection.execute(
@@ -86,6 +105,154 @@ def reconcile_completed_scan_cost(
)
+def merge_scan_usage_fields(*observations: Mapping[str, Any]) -> dict[str, Any]:
+ """Reconcile overlapping measurements without summing the same execution twice."""
+
+ merged: dict[str, Any] = {}
+ latest_coverage: dict[str, Any] | None = None
+ rate_limits: dict[str, dict[str, Any]] = {}
+ for observation in observations:
+ if isinstance(observation.get("cost"), dict):
+ merged["cost"] = observation["cost"]
+ usage = observation.get("usage")
+ if not isinstance(usage, dict):
+ continue
+ for snapshot in usage.get("accountRateLimits", []):
+ key = snapshot["limitId"]
+ if key not in rate_limits or snapshot["observedAt"] >= rate_limits[key]["observedAt"]:
+ rate_limits[key] = snapshot
+ previous = merged.get("usage")
+ if previous is None or _usage_quality(usage) >= _usage_quality(previous):
+ merged["usage"] = usage
+ if usage.get("coverage") not in ("complete", "partial"):
+ continue
+ latest_coverage = (
+ usage if latest_coverage is None else _merge_usage_coverage(latest_coverage, usage)
+ )
+ cost = merged.get("cost")
+ usage = merged.get("usage")
+ if usage is not None and latest_coverage is not None and latest_coverage is not usage:
+ usage = {**usage}
+ for field in (
+ "coverage",
+ "coverageScope",
+ "threadCount",
+ "missingThreadCount",
+ "warnings",
+ "observedAt",
+ "completion",
+ "byRole",
+ ):
+ if field in latest_coverage:
+ usage[field] = latest_coverage[field]
+ else:
+ usage.pop(field, None)
+ # Counts describe the coverage observation, even when its scope narrows.
+ # Its whole role breakdown must still sum to the retained token subtotal.
+ if "byRole" in usage and any(
+ usage.get(field) != latest_coverage.get(field) for field in TOKEN_FIELDS.values()
+ ):
+ usage.pop("byRole")
+ merged["usage"] = usage
+ cost_warning = "cost_estimate_covers_earlier_usage"
+ if (
+ cost is not None
+ and usage is not None
+ and usage.get("coverage") in ("complete", "partial")
+ and type(usage.get("totalTokens")) is int
+ ):
+ warnings = set(usage.get("warnings", []))
+ warnings.discard(cost_warning)
+ if usage["totalTokens"] > cost["inputTokens"] + cost["outputTokens"]:
+ warnings.add(cost_warning)
+ if warnings != set(usage.get("warnings", [])):
+ updated = {**usage}
+ updated["coverage"] = (
+ "partial"
+ if warnings - {cost_warning} or usage.get("missingThreadCount", 0)
+ else "complete"
+ )
+ if warnings:
+ updated["warnings"] = sorted(warnings)
+ else:
+ updated.pop("warnings", None)
+ merged["usage"] = updated
+ if rate_limits:
+ merged["usage"] = {
+ **merged["usage"],
+ "accountRateLimits": list(rate_limits.values()),
+ }
+ return merged
+
+
+def _merge_usage_coverage(previous: dict[str, Any], observed: dict[str, Any]) -> dict[str, Any]:
+ if previous == observed:
+ return observed
+ previous_at = _timestamp(previous.get("observedAt"))
+ observed_at = _timestamp(observed.get("observedAt"))
+ if previous_at is not None and observed_at is not None and previous_at > observed_at:
+ previous, observed = observed, previous
+ previous_scope = previous.get("coverageScope")
+ observed_scope = observed.get("coverageScope")
+ covers_previous = (
+ previous_scope is not None
+ and observed_scope is not None
+ and set(previous_scope).issubset(observed_scope)
+ )
+ scope_gap = previous_scope is not None and observed_scope is not None and not covers_previous
+ unresolved_previous = (previous["coverage"] == "partial" and not covers_previous) or scope_gap
+ merged = {**observed}
+ if unresolved_previous:
+ merged["coverage"] = "partial"
+ merged["missingThreadCount"] = max(
+ previous.get("missingThreadCount", 0), observed.get("missingThreadCount", 0)
+ )
+ warnings = set(previous.get("warnings", [])) | set(observed.get("warnings", []))
+ if scope_gap:
+ # A newer subset can grow while still staying below the older
+ # aggregate. Neither subtotal proves complete usage for the union.
+ warnings.add("usage_scope_incomplete")
+ if warnings:
+ merged["warnings"] = sorted(warnings)
+ if previous.get("completion", {}).get("finalized") is False:
+ merged["completion"] = previous["completion"]
+ if previous_scope is not None and observed_scope is not None:
+ merged["coverageScope"] = sorted(set(previous_scope) | set(observed_scope))
+ elif previous_scope is not None and observed["coverage"] == "complete":
+ merged["coverageScope"] = previous_scope
+ elif unresolved_previous:
+ # An older subtotal without scope cannot prove which gaps a later
+ # collector has resolved. Retain that uncertainty across future merges.
+ merged.pop("coverageScope", None)
+ return merged
+
+
+def _usage_quality(
+ usage: Mapping[str, Any], *, observed_at: datetime | None = None
+) -> tuple[int, bool, datetime]:
+ return (
+ usage.get("totalTokens", -1),
+ usage.get("cacheWriteInputTokensReported") is not False,
+ observed_at
+ or _timestamp(usage.get("observedAt"))
+ or datetime.min.replace(tzinfo=timezone.utc),
+ )
+
+
+def collect_scan_usage_safely(
+ connection: sqlite3.Connection, scan: sqlite3.Row, **options: Any
+) -> dict[str, Any]:
+ try:
+ return collect_scan_usage(connection, scan, **options)
+ except (Exception, SystemExit) as exc:
+ try:
+ print(f"Could not collect scan token usage: {exc}", file=sys.stderr)
+ except OSError:
+ # A closed diagnostic stream must not replace the unavailable-usage result.
+ pass
+ return _unavailable_usage("usage_collection_failed")
+
+
def collect_scan_usage(
connection: sqlite3.Connection,
scan: sqlite3.Row,
@@ -109,39 +276,48 @@ def collect_scan_usage(
parent_ids.add(validation_thread_id)
warnings: set[str] = set()
worker_directories = _scan_worker_directories(connection, scan, warnings)
- if not roots and not worker_directories:
- return _unavailable_usage("scan_thread_unavailable")
-
- state_database = _codex_state_database()
- if state_database is None:
- return _unavailable_usage("codex_state_unavailable")
-
started_at = _timestamp(scan["started_at"])
observed_at = datetime.now(timezone.utc)
stopped_at = _timestamp(completed_at or scan["completed_at"]) or observed_at
if started_at is None:
return _unavailable_usage("scan_window_unavailable")
- try:
- sessions, missing_thread_ids = _discover_rollout_sessions(
- state_database,
- roots,
- warnings,
- worker_directories=worker_directories,
- scan_directory=Path(scan["scan_dir"]) if worker_directories else None,
- started_at=started_at,
- completed_at=stopped_at,
- )
- except (OSError, sqlite3.Error, ValueError):
- return _unavailable_usage("codex_state_unavailable")
+ receipts, missing_receipts, receipt_scope = _worker_usage_receipts(
+ scan, started_at, stopped_at, warnings
+ )
+ state_database = _codex_state_database()
+ sessions: list[RolloutSession] = []
+ missing_thread_ids: set[str] = set()
+ if state_database is None:
+ if not receipts:
+ return _unavailable_usage("codex_state_unavailable", warnings=warnings)
+ warnings.add("codex_state_unavailable")
+ missing_thread_ids.update(roots)
+ else:
+ try:
+ sessions, missing_thread_ids = _discover_rollout_sessions(
+ state_database,
+ roots,
+ warnings,
+ worker_directories=worker_directories,
+ scan_directory=Path(scan["scan_dir"]) if worker_directories else None,
+ started_at=started_at,
+ completed_at=stopped_at,
+ )
+ except (OSError, sqlite3.Error, ValueError):
+ if not receipts:
+ return _unavailable_usage("codex_state_unavailable", warnings=warnings)
+ warnings.add("codex_state_unavailable")
+ missing_thread_ids.update(roots)
- if not sessions:
+ if not sessions and not receipts:
return _unavailable_usage("scan_thread_unavailable", warnings=warnings)
- by_role = {role: {**_empty_token_usage(), "threadCount": 0} for role in ("parent", "workers")}
rate_limits: dict[str, dict[str, Any]] = {}
tokens_updated_at = None
accepted_thread_ids: set[str] = set()
+ measured_threads: dict[str, dict[str, int]] = {}
+ complete_native_thread_ids: set[str] = set()
excluded_thread_ids: set[str] = set()
for session in sessions:
if session.parent_thread_id in excluded_thread_ids:
@@ -185,18 +361,45 @@ def collect_scan_usage(
if usage.warnings & {"token_usage_unavailable", "token_breakdown_unavailable"}:
missing_thread_ids.add(session.thread_id)
continue
- role = by_role["parent" if session.thread_id in parent_ids else "workers"]
- _add_token_usage(role, usage.tokens)
- role["threadCount"] += 1
+ measured_threads[session.thread_id] = usage.tokens
+ if not usage.warnings:
+ complete_native_thread_ids.add(session.thread_id)
if usage.tokens_updated_at is not None:
tokens_updated_at = max(
tokens_updated_at or usage.tokens_updated_at, usage.tokens_updated_at
)
+ runtime_receipts_used = False
+ for receipt_thread_id, receipt in receipts.items():
+ native = measured_threads.get(receipt_thread_id)
+ extends_native = native is None or receipt.tokens["totalTokens"] > native["totalTokens"]
+ fills_cache_write_usage = (
+ native is not None
+ and receipt.tokens["totalTokens"] == native["totalTokens"]
+ and native.get("cacheWriteInputTokensReported") is False
+ and receipt.tokens.get("cacheWriteInputTokensReported") is not False
+ )
+ if extends_native or fills_cache_write_usage:
+ measured_threads[receipt_thread_id] = receipt.tokens
+ accepted_thread_ids.add(receipt_thread_id)
+ runtime_receipts_used = True
+ if extends_native:
+ complete_native_thread_ids.discard(receipt_thread_id)
+ # Numeric SDK subtotals cannot establish that descendants and
+ # compaction requests are present when their rollouts are absent.
+ missing_thread_ids.add(receipt_thread_id)
+ warnings.add("worker_rollout_usage_incomplete")
+ if receipt.tokens_updated_at is not None:
+ tokens_updated_at = max(
+ tokens_updated_at or receipt.tokens_updated_at, receipt.tokens_updated_at
+ )
+ unresolved_receipts = missing_receipts - complete_native_thread_ids
+ if unresolved_receipts:
+ missing_thread_ids.update(unresolved_receipts)
+ warnings.add("worker_usage_unavailable")
if not accepted_thread_ids:
return _unavailable_usage("scan_thread_unavailable", warnings=warnings)
- thread_count = sum(role["threadCount"] for role in by_role.values())
- if not thread_count:
+ if not measured_threads:
reason = (
"token_breakdown_unavailable"
if "token_breakdown_unavailable" in warnings
@@ -204,6 +407,11 @@ def collect_scan_usage(
)
return _unavailable_usage(reason, warnings=warnings, rate_limits=rate_limits)
+ by_role = {role: {**_empty_token_usage(), "threadCount": 0} for role in ("parent", "workers")}
+ for measured_id, tokens in measured_threads.items():
+ role = by_role["parent" if measured_id in parent_ids else "workers"]
+ _add_token_usage(role, tokens)
+ role["threadCount"] += 1
if any(
usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]
or usage["totalTokens"] != usage["inputTokens"] + usage["outputTokens"]
@@ -213,18 +421,28 @@ def collect_scan_usage(
"token_breakdown_unavailable", warnings=warnings, rate_limits=rate_limits
)
- if completed_turn_id is not None and tokens_updated_at is not None:
+ if (completed_turn_id is not None or runtime_receipts_used) and tokens_updated_at is not None:
stopped_at = max(stopped_at, tokens_updated_at)
result: dict[str, Any] = {
"coverage": "partial" if missing_thread_ids or warnings else "complete",
- "source": "codex_rollout",
+ "source": "codex_runtime" if runtime_receipts_used else "codex_rollout",
**{key: sum(role[key] for role in by_role.values()) for key in TOKEN_FIELDS.values()},
- "threadCount": thread_count,
+ "threadCount": len(measured_threads),
+ "coverageScope": sorted(
+ receipt_scope
+ | {f"thread:{identity}" for identity in measured_threads}
+ | {
+ identity if identity.startswith("worker-attempt:") else f"thread:{identity}"
+ for identity in missing_thread_ids
+ }
+ ),
"byRole": by_role,
"window": {"startedAt": started_at.isoformat(), "endedAt": stopped_at.isoformat()},
"observedAt": observed_at.isoformat(),
"accountRateLimits": [rate_limits[key] for key in sorted(rate_limits)],
}
+ if any(role.get("cacheWriteInputTokensReported") is False for role in by_role.values()):
+ result["cacheWriteInputTokensReported"] = False
if tokens_updated_at is not None:
result["tokensUpdatedAt"] = tokens_updated_at.isoformat()
if missing_thread_ids:
@@ -234,6 +452,79 @@ def collect_scan_usage(
return result
+def _worker_usage_receipts(
+ scan: Mapping[str, Any],
+ started_at: datetime,
+ completed_at: datetime,
+ warnings: set[str],
+) -> tuple[dict[str, RolloutUsage], set[str], set[str]]:
+ if scan["mode"] != "deep":
+ return {}, set(), set()
+ directory = worker_usage_directory(scan["id"])
+ try:
+ if directory.resolve(strict=True) != directory:
+ raise ValueError("Worker usage directory is not a canonical protected directory.")
+ except FileNotFoundError:
+ return {}, set(), set()
+ except (OSError, RuntimeError, ValueError):
+ warnings.add("worker_usage_receipt_unavailable")
+ return {}, {"worker-receipts"}, {"worker-receipts"}
+ receipts: dict[str, RolloutUsage] = {}
+ missing: set[str] = set()
+ attempts: set[str] = set()
+ scope: set[str] = set()
+ for path in sorted(directory.glob("*.json")):
+ try:
+ if _rollout_path(str(path)) is None:
+ raise ValueError("Worker usage receipt path is unavailable.")
+ receipt = json.loads(path.read_text(encoding="utf-8"))
+ if (
+ not isinstance(receipt, dict)
+ or receipt.get("schemaVersion") != 1
+ or receipt.get("source") != "codex_sdk"
+ or receipt.get("usageScope") != "thread_cumulative"
+ or receipt.get("scanId") != scan["id"]
+ or receipt.get("kind") not in ("discovery", "dedup", "compare")
+ or receipt.get("attemptId") != path.stem
+ ):
+ raise ValueError("Worker usage receipt identity is invalid.")
+ attempt_id = receipt["attemptId"]
+ begin = _timestamp(receipt.get("startedAt"))
+ observed = _timestamp(receipt.get("observedAt"))
+ if begin is None or observed is None:
+ raise ValueError("Worker usage receipt timestamps are invalid.")
+ if begin < started_at or begin > completed_at or attempt_id in attempts:
+ continue
+ attempts.add(attempt_id)
+ scope.add(f"worker-attempt:{attempt_id}")
+ thread_id = receipt.get("threadId")
+ if isinstance(thread_id, str) and thread_id:
+ scope.add(f"thread:{thread_id}")
+ tokens = _usage_counts(receipt.get("usage"))
+ if not isinstance(thread_id, str) or not thread_id or tokens is None:
+ missing.add(
+ thread_id
+ if isinstance(thread_id, str) and thread_id
+ else f"worker-attempt:{attempt_id}"
+ )
+ continue
+ previous = receipts.get(thread_id)
+ if previous is None or _usage_quality(tokens, observed_at=observed) > _usage_quality(
+ previous.tokens, observed_at=previous.tokens_updated_at
+ ):
+ receipts[thread_id] = RolloutUsage(tokens, set(), observed, {})
+ except (OSError, UnicodeError, ValueError) as exc:
+ warnings.add("worker_usage_receipt_unavailable")
+ missing.add(f"worker-attempt:{path.stem}")
+ scope.add(f"worker-attempt:{path.stem}")
+ try:
+ print(f"Could not read worker token usage: {exc}", file=sys.stderr)
+ except OSError:
+ # The receipt warning and missing-attempt scope are already retained.
+ pass
+ return receipts, missing, scope
+
+
def _scan_root_thread_ids(
connection: sqlite3.Connection,
scan: sqlite3.Row,
@@ -454,8 +745,8 @@ def _discover_rollout_sessions(
continue
if root not in roots:
try:
- with _open_rollout(path) as source:
- metadata = json.loads(source.readline())
+ with _rollout_lines(path) as source:
+ metadata = json.loads(next(source, b""))
except (OSError, ValueError):
missing_thread_ids.add(root)
warnings.add("rollout_unavailable")
@@ -570,7 +861,7 @@ def _rollout_path(value: object) -> Path | None:
@contextmanager
-def _open_rollout(path: Path, *, verify_end: bool = False) -> Iterator[BinaryIO]:
+def _rollout_lines(path: Path, *, verify_end: bool = False):
if path.suffix != ".zst":
with path.open("rb") as source:
yield source
@@ -581,18 +872,49 @@ def _open_rollout(path: Path, *, verify_end: bool = False) -> Iterator[BinaryIO]
try:
from backports import zstd
except ImportError:
- raise OSError(
- "Compressed Codex rollouts require Python 3.14+ or backports.zstd."
- ) from None
- try:
- with zstd.open(path, "rb") as source:
- yield source
- # A requested completion turn may stop parsing before the frame checksum.
- if verify_end:
- while source.read(64 * 1024):
- pass
- except (zstd.ZstdError, EOFError) as error:
- raise ValueError("Invalid compressed Codex rollout.") from error
+ zstd = None
+ if zstd is not None:
+ try:
+ with zstd.open(path, "rb") as source:
+ yield source
+ # A requested completion turn may stop parsing before the frame checksum.
+ if verify_end:
+ while source.read(64 * 1024):
+ pass
+ except (zstd.ZstdError, EOFError) as error:
+ raise ValueError("Invalid compressed Codex rollout.") from error
+ return
+ with tempfile.TemporaryFile() as errors:
+ with subprocess.Popen(
+ [
+ os.environ.get("CODEX_MCP_NODE_PATH") or "node",
+ str(Path(__file__).with_name("read_codex_session.mjs")),
+ str(path),
+ ],
+ stdout=subprocess.PIPE,
+ stderr=errors,
+ ) as child:
+ exhausted = False
+
+ def lines():
+ nonlocal exhausted
+ yield from child.stdout
+ exhausted = True
+
+ try:
+ iterator = lines()
+ yield iterator
+ if verify_end:
+ for _ in iterator:
+ pass
+ finally:
+ if not exhausted and child.poll() is None:
+ child.terminate()
+ child.stdout.close()
+ status = child.wait()
+ if exhausted and status != 0:
+ errors.seek(0)
+ raise OSError(errors.read().decode("utf-8", errors="replace"))
def _read_rollout_usage(
@@ -633,7 +955,7 @@ def _read_rollout_usage(
and (completed_turn_id is None or turn_id != completed_turn_id)
)
- with _open_rollout(session.path, verify_end=True) as source:
+ with _rollout_lines(session.path, verify_end=True) as source:
for line_number, raw_line in enumerate(source, start=1):
if not raw_line.endswith(b"\n"):
warnings.add("rollout_record_incomplete")
@@ -868,9 +1190,16 @@ def _read_rollout_usage(
)
previous_cache_writes_reported = cache_writes_reported
delta = {
- key: value if reset or value < previous[key] else value - previous[key]
- for key, value in snapshot.items()
+ key: snapshot[key] - previous[key]
+ if not reset and snapshot[key] >= previous[key]
+ else snapshot[key]
+ for key in TOKEN_FIELDS.values()
}
+ if (
+ snapshot.get("cacheWriteInputTokensReported") is False
+ or previous.get("cacheWriteInputTokensReported") is False
+ ):
+ delta["cacheWriteInputTokensReported"] = False
previous = baseline
if past_scan_end(timestamp, current_turn_id):
continue
@@ -1121,6 +1450,12 @@ def _usage_counts(usage: object) -> dict[str, int] | None:
if result["cachedInputTokens"] + result["cacheWriteInputTokens"] > result["inputTokens"]:
return None
result["totalTokens"] = result["inputTokens"] + result["outputTokens"]
+ if (
+ usage.get("cache_write_input_tokens_reported") is False
+ or usage.get("cache_write_input_tokens") is None
+ and usage.get("cache_write_tokens") is None
+ ):
+ result["cacheWriteInputTokensReported"] = False
return result
@@ -1131,6 +1466,8 @@ def _empty_token_usage() -> dict[str, int]:
def _add_token_usage(target: dict[str, int], addition: Mapping[str, int]) -> None:
for key in TOKEN_FIELDS.values():
target[key] += addition[key]
+ if addition.get("cacheWriteInputTokensReported") is False:
+ target["cacheWriteInputTokensReported"] = False
def _timestamp(value: object) -> datetime | None:
diff --git a/plugins/codex-security/scripts/workbench_validation.py b/plugins/codex-security/scripts/workbench_validation.py
index df5b1e6db..de3b72bab 100644
--- a/plugins/codex-security/scripts/workbench_validation.py
+++ b/plugins/codex-security/scripts/workbench_validation.py
@@ -108,7 +108,7 @@ def _valid_measured_scan_usage(usage: object) -> bool:
thread_count = usage.get("threadCount")
if (
coverage not in ("complete", "partial", "unavailable")
- or usage.get("source") != "codex_rollout"
+ or usage.get("source") not in ("codex_rollout", "codex_runtime")
or type(thread_count) is not int
or thread_count < 0
):
@@ -150,6 +150,7 @@ def _valid_measured_scan_usage(usage: object) -> bool:
allowed_keys = {
"coverage",
+ "coverageScope",
"source",
"threadCount",
"missingThreadCount",
@@ -160,19 +161,32 @@ def _valid_measured_scan_usage(usage: object) -> bool:
"observedAt",
"tokensUpdatedAt",
"accountRateLimits",
+ "cacheWriteInputTokensReported",
*SCAN_USAGE_TOKEN_KEYS,
}
if thread_count == 0 or not set(usage).issubset(allowed_keys):
return False
+ if "coverageScope" in usage:
+ scope = usage["coverageScope"]
+ if (
+ not isinstance(scope, list)
+ or any(not isinstance(identity, str) or not identity for identity in scope)
+ or len(set(scope)) != len(scope)
+ ):
+ return False
if (
not all(type(usage.get(key)) is int and usage[key] >= 0 for key in SCAN_USAGE_TOKEN_KEYS)
or usage["cachedInputTokens"] + usage["cacheWriteInputTokens"] > usage["inputTokens"]
+ or "cacheWriteInputTokensReported" in usage
+ and type(usage["cacheWriteInputTokensReported"]) is not bool
):
return False
missing = usage.get("missingThreadCount", 0)
if type(missing) is not int or missing < 0:
return False
- if coverage == "complete" and (warnings or missing):
+ if coverage == "complete" and (
+ any(warning != "cost_estimate_covers_earlier_usage" for warning in warnings) or missing
+ ):
return False
if coverage == "partial" and not (warnings or missing):
return False
@@ -193,8 +207,11 @@ def _valid_measured_scan_usage(usage: object) -> bool:
return False
if any(
not isinstance(role, dict)
- or set(role) != keys
+ or not keys.issubset(role)
+ or not set(role).issubset({*keys, "cacheWriteInputTokensReported"})
or any(type(role[key]) is not int or role[key] < 0 for key in keys)
+ or "cacheWriteInputTokensReported" in role
+ and type(role["cacheWriteInputTokensReported"]) is not bool
for role in roles.values()
):
return False
diff --git a/plugins/codex-security/tests/test_workbench_scan_history.py b/plugins/codex-security/tests/test_workbench_scan_history.py
index 3ecf51637..c451b658e 100644
--- a/plugins/codex-security/tests/test_workbench_scan_history.py
+++ b/plugins/codex-security/tests/test_workbench_scan_history.py
@@ -696,9 +696,16 @@ def test_cli_scan_completion_persists_authoritative_cost_after_plugin_completion
json.dumps(
{
"usage": {
- "status": "complete",
+ "source": "codex_runtime",
+ "coverage": "complete",
+ "threadCount": 1,
+ "missingThreadCount": 0,
"inputTokens": 5_000,
+ "cachedInputTokens": 0,
+ "cacheWriteInputTokens": 0,
"outputTokens": 120,
+ "reasoningOutputTokens": 0,
+ "totalTokens": 5_120,
}
}
),
diff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.py
index bc51ee690..ae5f31bc7 100644
--- a/plugins/codex-security/tests/test_workbench_scan_usage.py
+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py
@@ -16,6 +16,7 @@ from typing import Any
import pytest
from workbench_test_support import (
begin_deep_scan,
+ cancel_scan,
create_saved_workspace,
fail_scan,
initialize_git_repository,
@@ -26,6 +27,9 @@ from workbench_test_support import (
upsert_deep_worker,
write_completed_contract,
)
+from workbench_test_support import (
+ usage_counts as _counts,
+)
@pytest.fixture(scope="session")
@@ -65,6 +69,10 @@ class ScanFixture:
)
+def _worker_usage_directory(fixture: ScanFixture) -> Path:
+ return fixture.state_dir / "codex-home" / "worker-usage" / fixture.scan_id
+
+
def _start_scan(tmp_path: Path, *, mode: str = "standard") -> ScanFixture:
state_dir = tmp_path / "workbench-state"
target = tmp_path / "target"
@@ -339,23 +347,6 @@ def _state_graph(
)
-def _counts(
- input_tokens: int,
- cached_input_tokens: int,
- output_tokens: int,
- *,
- cache_write_input_tokens: int = 0,
-) -> dict[str, int]:
- return {
- "inputTokens": input_tokens,
- "cachedInputTokens": cached_input_tokens,
- "cacheWriteInputTokens": cache_write_input_tokens,
- "outputTokens": output_tokens,
- "reasoningOutputTokens": 0,
- "totalTokens": input_tokens + output_tokens,
- }
-
-
def _complete_scan(fixture: ScanFixture, *arguments: str) -> dict[str, Any]:
options: dict[str, Any] = {"relative_path": "app.py"}
if fixture.mode == "diff":
@@ -897,6 +888,26 @@ def test_scan_cost_preserves_diagnostics_for_non_scalar_coverage(workbench_api,
assert str(error.value) == "Scan cost includes invalid measured token usage."
+ "warning", ["cost_estimate_covers_earlier_usage", "token_usage_unavailable"]
+)
+def test_only_price_warning_can_accompany_complete_token_coverage(workbench_api, warning) -> None:
+ value = {
+ "usage": {
+ "coverage": "complete",
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "warnings": [warning],
+ **_counts(120, 30, 15),
+ }
+ }
+ if warning == "cost_estimate_covers_earlier_usage":
+ assert json.loads(workbench_api["parse_scan_cost"](json.dumps(value))) == value
+ else:
+ with pytest.raises(SystemExit, match="invalid measured token usage"):
+ workbench_api["parse_scan_cost"](json.dumps(value))
+
+
@pytest.mark.parametrize("cache_write_field", ["cache_write_input_tokens", "cache_write_tokens"])
def test_completion_includes_cached_and_cache_write_tokens(
tmp_path: Path,
@@ -923,6 +934,36 @@ def test_completion_includes_cached_and_cache_write_tokens(
)
[email protected]("cache_writes", [None, 0, 12])
+def test_completion_distinguishes_missing_cache_writes_from_zero(
+ tmp_path: Path, cache_writes: int | None
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ event = _token_event(counted, 120, 15, cached_input_tokens=30)
+ reported = event["payload"]["info"]["total_token_usage"]
+ if cache_writes is None:
+ reported.pop("cache_write_input_tokens")
+ else:
+ reported["cache_write_input_tokens"] = cache_writes
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": _rollout(tmp_path, "scan-parent", [event])},
+ [],
+ )
+ live = fixture.command("read-scan-usage", "--thread-id", "scan-parent")
+ assert live["cacheWriteInputTokensReported"] is (cache_writes is not None)
+ measurement = _complete_scan(fixture)["scan"]["usage"]
+ assert measurement["totalTokens"] == 135
+ assert measurement["cacheWriteInputTokens"] == (cache_writes or 0)
+ assert measurement["coverage"] == "complete"
+ if cache_writes is None:
+ assert measurement["cacheWriteInputTokensReported"] is False
+ assert measurement["byRole"]["parent"]["cacheWriteInputTokensReported"] is False
+ else:
+ assert "cacheWriteInputTokensReported" not in measurement
+
+
@pytest.mark.parametrize(
"cache_field", ["cached_input_tokens", "cache_write_input_tokens", "cache_write_tokens"]
)
@@ -1101,12 +1142,17 @@ def test_legacy_cache_refinement_survives_turn_boundaries(
parent = _rollout(tmp_path, "scan-parent", events)
result = _measure_rollout(scan_usage, parent, started, started)
- assert result.tokens == _counts(
+ expected = _counts(
150,
(7 if previous_native else 20) + (5 if current_native else 0),
20,
cache_write_input_tokens=0 if previous_native else 30,
)
+ # Native per-response receipts establish both cache counters. Legacy
+ # measurements retain their omission marker alongside the refined subtotal.
+ if not (previous_native and current_native):
+ expected["cacheWriteInputTokensReported"] = False
+ assert result.tokens == expected
assert result.warnings == set()
@@ -1509,9 +1555,7 @@ def test_usage_counts_registered_worker_when_its_parent_rollout_is_missing(
@pytest.mark.parametrize("delayed_cache_counts", [False, True])
-def test_completion_preserves_explicit_legacy_cost(
- tmp_path: Path, delayed_cache_counts: bool
-) -> None:
+def test_completion_preserves_large_legacy_cost(tmp_path: Path, delayed_cache_counts: bool) -> None:
fixture = _start_scan(tmp_path)
counted = fixture.started_at + timedelta(microseconds=1)
fixture.write_parent_rollout(
@@ -1532,7 +1576,9 @@ def test_completion_preserves_explicit_legacy_cost(
write_completed_contract(
fixture.scan_dir, fixture.scan_id, fixture.target, relative_path="app.py"
)
- completed = fixture.command("complete-scan", "--cost-json", json.dumps(cost))["scan"]
+ completed = fixture.command("complete-scan", "--cost-json", json.dumps(cost) + " " * 8192)[
+ "scan"
+ ]
assert completed["cost"] == cost
assert completed["usage"]["accountRateLimits"][0]["primary"]["usedPercent"] == 6
if delayed_cache_counts:
@@ -1543,6 +1589,85 @@ def test_completion_preserves_explicit_legacy_cost(
assert completed["usage"]["totalTokens"] == 21
+ "native_state",
+ ["complete", "missing-worker", "missing-turn", "unavailable", "unavailable-turn"],
+)
+def test_completion_reconciles_supplied_usage_with_native_evidence(
+ tmp_path: Path, native_state: str
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ events = [_token_event(counted, 15, 6), _allowance_event(counted, 6)]
+ if native_state == "missing-turn":
+ events.extend(
+ _event(counted, "event_msg", {"type": kind, "turn_id": "unmeasured-turn"})
+ for kind in ("task_started", "task_complete")
+ )
+ if native_state not in {"unavailable", "unavailable-turn"}:
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": _rollout(tmp_path, "scan-parent", events)},
+ [("scan-parent", "missing-worker")] if native_state == "missing-worker" else [],
+ )
+ runtime = {
+ "source": "codex_runtime",
+ "coverage": "complete",
+ "observedAt": counted.isoformat(),
+ "threadCount": 1,
+ "missingThreadCount": 0,
+ "coverageScope": ["thread:scan-parent"],
+ **_counts(15, 0, 6),
+ }
+ cost = {
+ "model": "gpt-5.6-sol",
+ "inputTokens": 15,
+ "cachedInputTokens": 0,
+ "cacheWriteInputTokens": 0,
+ "outputTokens": 6,
+ "estimatedUsd": 0.002,
+ }
+ arguments = ["--cost-json", json.dumps({"usage": runtime, "cost": cost})]
+ if native_state == "unavailable-turn":
+ arguments.extend(["--thread-id", "scan-parent", "--turn-id", "completion-turn"])
+ completed = _complete_scan(fixture, *arguments)["scan"]
+ assert completed["cost"] == cost
+ usage = completed["usage"]
+ if native_state == "unavailable":
+ assert usage == runtime
+ return
+ if native_state == "unavailable-turn":
+ assert usage == {
+ **runtime,
+ "coverage": "partial",
+ "warnings": ["turn_in_progress"],
+ "completion": {
+ "threadId": "scan-parent",
+ "turnId": "completion-turn",
+ "finalized": False,
+ },
+ }
+ return
+ assert usage["totalTokens"] == 21
+ assert usage["source"] == "codex_rollout"
+ assert usage["byRole"] == {
+ "parent": {**_counts(15, 0, 6), "threadCount": 1},
+ "workers": {**_counts(0, 0, 0), "threadCount": 0},
+ }
+ assert datetime.fromisoformat(usage["window"]["startedAt"]) == fixture.started_at
+ assert datetime.fromisoformat(usage["tokensUpdatedAt"]) == counted
+ assert usage["accountRateLimits"][0]["primary"]["usedPercent"] == 6
+ assert usage["coverage"] == ("complete" if native_state == "complete" else "partial")
+ if native_state == "missing-worker":
+ assert usage["missingThreadCount"] == 1
+ assert usage["coverageScope"] == ["thread:missing-worker", "thread:scan-parent"]
+ assert usage["warnings"] == ["rollout_unavailable"]
+ elif native_state == "missing-turn":
+ assert usage["warnings"] == ["token_record_missing"]
+ else:
+ assert not usage.get("warnings")
+
+
@pytest.mark.parametrize(
"worker_state",
["absent", "measured", "missing_graph_child", "missing_registered_worker", "unmeasured"],
@@ -1836,9 +1961,144 @@ def test_budget_usage_includes_final_receipts_and_validation_after_completion(
assert fixture.command("get-scan")["scan"]["usage"] == stored
[email protected]("sdk_ahead", [False, True])
+def test_cli_completion_refresh_preserves_native_detail_and_sdk_subtotal(
+ tmp_path: Path, sdk_ahead: bool
+) -> None:
+ state_dir = tmp_path / "state"
+ target = tmp_path / "target"
+ target.mkdir()
+ (target / "app.py").write_text("print('fixture')\n", encoding="utf-8")
+ scan_dir = tmp_path / "scan"
+ scan_dir.mkdir(mode=0o700)
+ environment = {
+ "CODEX_HOME": str(tmp_path / "codex-home"),
+ "CODEX_SQLITE_HOME": str(tmp_path / "codex-sqlite"),
+ "CODEX_STATE_DB": "",
+ }
+ registration = run_workbench(
+ state_dir,
+ "register-cli-scan",
+ "--repository",
+ str(target),
+ "--scan-dir",
+ str(scan_dir),
+ "--recipe-json",
+ json.dumps(
+ {
+ "repository": str(target),
+ "target": {"kind": "repository", "paths": []},
+ "mode": "standard",
+ "config": {},
+ }
+ ),
+ environment=environment,
+ )
+ scan_id = registration["scanId"]
+ thread_id = str(uuid.uuid4())
+ turn_id = "completion-turn"
+ scan_command(
+ state_dir, "set-scan-thread", scan_id, "--thread-id", thread_id, environment=environment
+ )
+ counted = datetime.now().astimezone()
+ parent = _rollout(
+ tmp_path,
+ thread_id,
+ [
+ _event(counted, "event_msg", {"type": "task_started", "turn_id": turn_id}),
+ _token_event(counted, 15, 6),
+ _allowance_event(counted, 6),
+ _event(counted, "event_msg", {"type": "task_complete", "turn_id": turn_id}),
+ ],
+ )
+ _state_graph(environment, {thread_id: parent}, [])
+ write_completed_contract(scan_dir, scan_id, target, relative_path="app.py")
+ arguments = ["--thread-id", thread_id, "--turn-id", turn_id]
+ initial = scan_command(
+ state_dir, "complete-scan", scan_id, *arguments, environment=environment
+ )["scan"]["usage"]
+ runtime = {
+ "source": "codex_runtime",
+ "coverage": "complete",
+ "observedAt": datetime.now().astimezone().isoformat(),
+ "threadCount": 1,
+ "missingThreadCount": 0,
+ "coverageScope": [f"thread:{thread_id}"],
+ **_counts(40 if sdk_ahead else 15, 0, 6),
+ }
+ refreshed = scan_command(
+ state_dir,
+ "complete-scan",
+ scan_id,
+ "--cost-json",
+ json.dumps({"usage": runtime}),
+ environment=environment,
+ )["scan"]["usage"]
+ assert refreshed["totalTokens"] == runtime["totalTokens"]
+ assert refreshed["completion"] == initial["completion"]
+ assert refreshed["coverage"] == "partial"
+ assert refreshed["warnings"] == ["turn_in_progress"]
+ assert refreshed["accountRateLimits"] == initial["accountRateLimits"]
+ if not sdk_ahead:
+ for key in ("byRole", "window", "tokensUpdatedAt", "accountRateLimits"):
+ assert refreshed[key] == initial[key]
+ finalized = scan_command(
+ state_dir, "finalize-scan-usage", scan_id, *arguments, environment=environment
+ )["scan"]["usage"]
+ assert finalized["totalTokens"] == runtime["totalTokens"]
+ assert finalized["completion"] == {**initial["completion"], "finalized": True}
+ assert finalized["coverage"] == "complete"
+ assert not finalized.get("warnings")
+ assert finalized["accountRateLimits"] == initial["accountRateLimits"]
+
+
+def test_finalized_completion_identity_survives_unknown_usage_scope(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ turn_id = "completion-turn"
+ parent = _rollout(
+ tmp_path,
+ "scan-parent",
+ [
+ _event(counted, "event_msg", {"type": "task_started", "turn_id": turn_id}),
+ _token_event(counted, 15, 6),
+ _event(counted, "event_msg", {"type": "task_complete", "turn_id": turn_id}),
+ ],
+ )
+ _state_graph(fixture.environment, {"scan-parent": parent}, [])
+ supplied = {
+ "source": "codex_runtime",
+ "coverage": "partial",
+ "threadCount": 1,
+ "missingThreadCount": 1,
+ "warnings": ["worker_usage_unavailable"],
+ "observedAt": counted.isoformat(),
+ **_counts(40, 0, 6),
+ }
+ arguments = ["--thread-id", "scan-parent", "--turn-id", turn_id]
+ _complete_scan(fixture, *arguments, "--cost-json", json.dumps({"usage": supplied}))
+ finalized = scan_command(
+ fixture.state_dir,
+ "finalize-scan-usage",
+ fixture.scan_id,
+ *arguments,
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert finalized["totalTokens"] == 46
+ assert finalized["coverage"] == "partial"
+ assert finalized["missingThreadCount"] == 1
+ assert "worker_usage_unavailable" in finalized["warnings"]
+ assert finalized["completion"] == {
+ "threadId": "scan-parent",
+ "turnId": turn_id,
+ "finalized": True,
+ }
+
+
@pytest.mark.parametrize("native", [False, True])
[email protected]("supplied_usage", [False, True])
def test_host_finalizes_exact_completion_turn_without_changing_artifacts(
- scan_usage, tmp_path: Path, native: bool
+ scan_usage, tmp_path: Path, native: bool, supplied_usage: bool
) -> None:
fixture = _start_scan(tmp_path)
counted = fixture.started_at + timedelta(microseconds=1)
@@ -1864,7 +2124,26 @@ def test_host_finalizes_exact_completion_turn_without_changing_artifacts(
{"scan-parent": parent, "scan-worker": worker},
[("scan-parent", "scan-worker")],
)
- initial = _complete_scan(fixture, "--thread-id", "scan-parent", "--turn-id", turn_id)["scan"]
+ arguments = ["--thread-id", "scan-parent", "--turn-id", turn_id]
+ if supplied_usage:
+ arguments.extend(
+ [
+ "--cost-json",
+ json.dumps(
+ {
+ "usage": {
+ "source": "codex_runtime",
+ "coverage": "complete",
+ "observedAt": counted.isoformat(),
+ "threadCount": 2,
+ "coverageScope": ["thread:scan-parent", "thread:scan-worker"],
+ **_counts(30, 0, 5),
+ }
+ }
+ ),
+ ]
+ )
+ initial = _complete_scan(fixture, *arguments)["scan"]
completion = {"threadId": "scan-parent", "turnId": turn_id, "finalized": False}
assert (
initial["usage"].items()
@@ -2054,15 +2333,825 @@ def test_host_final_usage_does_not_invent_an_unrecorded_completion_turn(tmp_path
assert finalized["completion"]["finalized"] is True
-def test_failed_scan_preserves_legacy_failure_behavior(tmp_path: Path) -> None:
[email protected]("outcome", ["failed", "canceled"])
+def test_stopped_scan_retains_measured_usage(tmp_path: Path, outcome: str) -> None:
fixture = _start_scan(tmp_path)
counted = fixture.started_at + timedelta(microseconds=1)
fixture.write_parent_rollout([_token_event(counted, 21, 8)])
- failed = fail_scan(
- fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ if outcome == "failed":
+ fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )
+ else:
+ cancel_scan(
+ fixture.state_dir, fixture.scan_id, "scan-parent", environment=fixture.environment
+ )
+ stopped = fixture.command("get-scan")["scan"]
+ assert stopped["progress"]["status"] == outcome
+ assert stopped["usage"]["totalTokens"] == 29
+ assert stopped["usage"]["coverage"] == "complete"
+ assert "cost" not in stopped
+
+
+def test_failed_scan_reconciles_runtime_subtotals_without_double_counting(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ runtime = {
+ "coverage": "partial",
+ "coverageScope": ["thread:scan-parent"],
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "missingThreadCount": 1,
+ "cacheWriteInputTokensReported": False,
+ **_counts(40, 0, 5),
+ }
+ cost = {
+ "model": "fixture-model",
+ "inputTokens": 40,
+ "cachedInputTokens": 0,
+ "cacheWriteInputTokens": 0,
+ "outputTokens": 5,
+ "estimatedUsd": 0.01,
+ }
+ for _ in range(2):
+ failed = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": runtime, "cost": cost}),
+ environment=fixture.environment,
+ )["scan"]
+ assert failed["usage"] == runtime
+ assert failed["cost"] == cost
+
+ counted = fixture.started_at + timedelta(microseconds=1)
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 50, 8)])},
+ [],
+ )
+ # A terminal retry can reconcile records flushed after the original stop.
+ reconciled = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Do not replace failure.",
+ environment=fixture.environment,
)["scan"]
+ assert reconciled["usage"]["totalTokens"] == 58
+ assert reconciled["usage"]["source"] == "codex_rollout"
+ assert reconciled["usage"]["coverage"] == "complete"
+ assert reconciled["usage"]["warnings"] == ["cost_estimate_covers_earlier_usage"]
+ assert reconciled["cost"] == cost
+ assert reconciled["failureMessage"] == "Fixture failure."
+ assert reconciled["progress"] == failed["progress"]
+ refreshed_cost = {**cost, "inputTokens": 50, "outputTokens": 8, "estimatedUsd": 0.02}
+ reconciled = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Do not replace failure.",
+ "--cost-json",
+ json.dumps(refreshed_cost),
+ environment=fixture.environment,
+ )["scan"]
+ assert reconciled["cost"] == refreshed_cost
+ assert reconciled["usage"]["coverage"] == "complete"
+ assert "cost_estimate_covers_earlier_usage" not in reconciled["usage"].get("warnings", [])
+
+
+def test_scan_accounting_failure_does_not_replace_stopped_outcome(
+ tmp_path: Path, workbench_api, monkeypatch: pytest.MonkeyPatch, capsys
+) -> None:
+ fixture = _start_scan(tmp_path)
+ context = workbench_api["_WORKBENCH_DB_CONTEXT"]
+
+ def unavailable(*args, **kwargs):
+ raise OSError("Synthetic accounting storage failure.")
+
+ monkeypatch.setattr(context.scan_usage, "collect_scan_usage", unavailable)
+ with sqlite3.connect(fixture.state_dir / "workbench.sqlite3") as connection:
+ connection.row_factory = sqlite3.Row
+ failed = context.saved_results.fail_scan_locked(
+ context,
+ connection,
+ SimpleNamespace(
+ scan_id=fixture.scan_id,
+ message="Original scan failure.",
+ claim_token=None,
+ cost_json=None,
+ ),
+ )["scan"]
assert failed["progress"]["status"] == "failed"
- assert "usage" not in failed
+ assert failed["failureMessage"] == "Original scan failure."
+ assert failed["usage"]["coverage"] == "unavailable"
+ assert failed["usage"]["warnings"] == ["usage_collection_failed"]
+ assert "Synthetic accounting storage failure." in capsys.readouterr().err
+
+
[email protected]("runtime_ahead", [False, True])
+def test_late_missing_worker_invalidates_saved_complete_coverage(
+ tmp_path: Path, runtime_ahead: bool
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 21, 8)])
+ _state_graph(fixture.environment, {"scan-parent": parent}, [])
+ arguments = (
+ (
+ "--cost-json",
+ json.dumps(
+ {
+ "usage": {
+ "coverage": "complete",
+ "coverageScope": ["thread:scan-parent"],
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "observedAt": counted.isoformat(),
+ "tokensUpdatedAt": counted.isoformat(),
+ **_counts(37, 0, 8),
+ }
+ }
+ ),
+ )
+ if runtime_ahead
+ else ()
+ )
+ complete = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ *arguments,
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert complete["coverage"] == "complete"
+ with sqlite3.connect(
+ Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite"
+ ) as connection:
+ connection.execute(
+ "INSERT INTO thread_spawn_edges (parent_thread_id, child_thread_id) VALUES (?, ?)",
+ ("scan-parent", "late-worker"),
+ )
+ partial = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert partial["totalTokens"] == complete["totalTokens"] == (45 if runtime_ahead else 29)
+ assert partial["coverage"] == "partial"
+ assert partial["missingThreadCount"] == 1
+ assert partial["coverageScope"] == ["thread:late-worker", "thread:scan-parent"]
+ assert partial["observedAt"] > complete["observedAt"]
+ assert partial["tokensUpdatedAt"] == complete["tokensUpdatedAt"]
+
+ # A delayed complete snapshot and vanished logs cannot erase the newer gap
+ # or make the retained observation appear fresh.
+ parent.unlink()
+ replayed = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": complete}),
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert replayed == partial
+
+ _rollout(tmp_path, "scan-parent", [_token_event(counted, 21, 8)])
+ worker = _rollout(
+ tmp_path,
+ "late-worker",
+ [_token_event(counted, 0, 0)],
+ parent_thread_id="scan-parent",
+ )
+ with sqlite3.connect(
+ Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite"
+ ) as connection:
+ connection.execute(
+ "INSERT INTO threads (id, rollout_path) VALUES (?, ?)", ("late-worker", str(worker))
+ )
+ resolved = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert resolved["totalTokens"] == partial["totalTokens"]
+ assert resolved["coverage"] == "complete"
+ assert resolved["threadCount"] == 2
+ if runtime_ahead:
+ assert "byRole" not in resolved
+ else:
+ assert resolved["byRole"]["parent"]["threadCount"] == 1
+ assert resolved["byRole"]["workers"]["threadCount"] == 1
+ assert resolved.get("missingThreadCount", 0) == 0
+ assert not resolved.get("warnings")
+ assert resolved["observedAt"] > partial["observedAt"]
+
+ parent.unlink()
+ worker.unlink()
+ replayed = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": partial}),
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert replayed == resolved
+
+
+def test_narrower_observations_preserve_other_thread_gaps(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 21, 8)])
+ _state_graph(fixture.environment, {"scan-parent": parent}, [])
+ runtime = {
+ "coverage": "partial",
+ "coverageScope": ["thread:scan-parent", "thread:validation", "thread:validation-child"],
+ "source": "codex_runtime",
+ "threadCount": 2,
+ "missingThreadCount": 1,
+ "observedAt": counted.isoformat(),
+ **_counts(37, 0, 8),
+ }
+ partial = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": runtime}),
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert partial["coverage"] == "partial"
+ assert partial["totalTokens"] == 45
+ assert partial["missingThreadCount"] == 1
+ assert partial["coverageScope"] == runtime["coverageScope"]
+ with sqlite3.connect(
+ Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite"
+ ) as connection:
+ connection.execute(
+ "INSERT INTO thread_spawn_edges (parent_thread_id, child_thread_id) VALUES (?, ?)",
+ ("scan-parent", "late-worker"),
+ )
+ narrower_partial = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert narrower_partial["coverage"] == "partial"
+ assert narrower_partial["coverageScope"] == [
+ "thread:late-worker",
+ *runtime["coverageScope"],
+ ]
+ worker = _rollout(
+ tmp_path,
+ "late-worker",
+ [_token_event(counted, 0, 0)],
+ parent_thread_id="scan-parent",
+ )
+ with sqlite3.connect(
+ Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite"
+ ) as connection:
+ connection.execute(
+ "INSERT INTO threads (id, rollout_path) VALUES (?, ?)", ("late-worker", str(worker))
+ )
+ narrower_complete = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert narrower_complete["coverage"] == "partial"
+ assert narrower_complete["coverageScope"] == narrower_partial["coverageScope"]
+ assert narrower_complete["totalTokens"] == 45
+
+ # Complete evidence must include every retained branch before it can clear
+ # the gap, even when its native subtotal is behind the SDK receipt.
+ for thread in ["validation", "validation-child"]:
+ path = _rollout(
+ tmp_path,
+ thread,
+ [_token_event(counted, 0, 0)],
+ parent_thread_id="scan-parent" if thread == "validation" else "validation",
+ )
+ with sqlite3.connect(
+ Path(fixture.environment["CODEX_SQLITE_HOME"]) / "state_5.sqlite"
+ ) as connection:
+ connection.execute(
+ "INSERT INTO threads (id, rollout_path) VALUES (?, ?)", (thread, str(path))
+ )
+ connection.execute(
+ "INSERT INTO thread_spawn_edges (parent_thread_id, child_thread_id) VALUES (?, ?)",
+ ("scan-parent" if thread == "validation" else "validation", thread),
+ )
+ complete = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert complete["coverage"] == "complete"
+ assert complete["totalTokens"] == 45
+ assert complete["threadCount"] == 4
+ assert "byRole" not in complete
+ assert complete["coverageScope"] == narrower_partial["coverageScope"]
+ assert not complete.get("missingThreadCount")
+ assert not complete.get("warnings")
+ parent.unlink()
+ worker.unlink()
+ # Entirely unavailable fresh reads and stale partial payloads cannot
+ # resurrect a gap covered by the newer encompassing observation.
+ replayed = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": narrower_partial}),
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert replayed == complete
+
+
+def test_stopped_scan_preserves_incomparable_scope_uncertainty(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ _state_graph(
+ fixture.environment,
+ {
+ "scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 800, 0)]),
+ "late-worker": _rollout(
+ tmp_path,
+ "late-worker",
+ [_token_event(counted, 400, 0)],
+ parent_thread_id="scan-parent",
+ ),
+ },
+ [("scan-parent", "late-worker")],
+ )
+ # SDK usage includes 800 parent + 200 independent validation tokens, while
+ # native collection sees 800 parent + 400 late-worker tokens. Neither
+ # aggregate measures the full 1,400-token execution.
+ runtime = {
+ "coverage": "complete",
+ "coverageScope": ["thread:scan-parent", "thread:validation"],
+ "source": "codex_runtime",
+ "threadCount": 2,
+ "observedAt": counted.isoformat(),
+ **_counts(1_000, 0, 0),
+ }
+ cost = {
+ "model": "fixture-model",
+ "inputTokens": 1_000,
+ "cachedInputTokens": 0,
+ "cacheWriteInputTokens": 0,
+ "outputTokens": 0,
+ "estimatedUsd": 0.01,
+ }
+ stopped = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({"usage": runtime, "cost": cost}),
+ environment=fixture.environment,
+ )["scan"]
+ usage = stopped["usage"]
+ assert usage["totalTokens"] == 1_200
+ assert usage["coverage"] == "partial"
+ assert usage["coverageScope"] == [
+ "thread:late-worker",
+ "thread:scan-parent",
+ "thread:validation",
+ ]
+ assert usage["warnings"] == [
+ "cost_estimate_covers_earlier_usage",
+ "usage_scope_incomplete",
+ ]
+ assert (
+ scan_command(
+ fixture.state_dir, "get-scan", fixture.scan_id, environment=fixture.environment
+ )["scan"]["usage"]
+ == usage
+ )
+ # Refreshing the price of this lower bound must not restore complete usage.
+ repriced = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ json.dumps({**cost, "inputTokens": 1_200, "estimatedUsd": 0.012}),
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert repriced["totalTokens"] == 1_200
+ assert repriced["coverage"] == "partial"
+ assert repriced["warnings"] == ["usage_scope_incomplete"]
+
+
+def test_large_measured_scope_survives_saved_scan_round_trip(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ runtime = {
+ "coverage": "partial",
+ "coverageScope": [f"thread:{uuid.UUID(int=index)}" for index in range(1, 401)],
+ "source": "codex_runtime",
+ "threadCount": 399,
+ "missingThreadCount": 1,
+ **_counts(400, 0, 5),
+ }
+ encoded = json.dumps({"usage": runtime})
+ assert len(encoded.encode("utf-8")) > 8192
+ stopped = fail_scan(
+ fixture.state_dir,
+ fixture.scan_id,
+ "Fixture failure.",
+ "--cost-json",
+ encoded,
+ environment=fixture.environment,
+ )["scan"]["usage"]
+ assert stopped == runtime
+ assert (
+ scan_command(
+ fixture.state_dir, "get-scan", fixture.scan_id, environment=fixture.environment
+ )["scan"]["usage"]
+ == runtime
+ )
+
+
+def test_completed_scan_reconciles_late_runtime_usage_envelopes(
+ tmp_path: Path, workbench_api: dict[str, Any]
+) -> None:
+ fixture = _start_scan(tmp_path)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 21, 8)])},
+ [],
+ )
+ _complete_scan(fixture)
+ runtime = {
+ "coverage": "complete",
+ "source": "codex_runtime",
+ "threadCount": 1,
+ **_counts(40, 0, 5),
+ }
+ for _ in range(2):
+ with sqlite3.connect(fixture.state_dir / "workbench.sqlite3") as connection:
+ connection.row_factory = sqlite3.Row
+ context = workbench_api["_WORKBENCH_DB_CONTEXT"]
+ scan = context.require_scan(connection, fixture.scan_id)
+ context.scan_usage.reconcile_completed_scan_cost(
+ connection, scan, json.dumps({"usage": runtime})
+ )
+ reconciled = scan_command(
+ fixture.state_dir,
+ "get-scan",
+ fixture.scan_id,
+ environment=fixture.environment,
+ )["scan"]
+ assert reconciled["usage"] == {
+ **runtime,
+ "coverageScope": ["thread:scan-parent"],
+ }
+ assert "cost" not in reconciled
+
+
[email protected]("mode", ["standard", "deep"])
+def test_model_artifact_worker_receipts_do_not_affect_saved_usage(
+ tmp_path: Path, mode: str
+) -> None:
+ fixture = _start_scan(tmp_path, mode=mode)
+ counted = fixture.started_at + timedelta(microseconds=1)
+ directory = fixture.scan_dir / "artifacts" / "deep_discovery" / "usage"
+ directory.mkdir(parents=True)
+ for thread_id in ["scan-parent", "unrelated-worker"]:
+ attempt_id = str(uuid.uuid4())
+ (directory / f"{attempt_id}.json").write_text(
+ json.dumps(
+ {
+ "schemaVersion": 1,
+ "source": "codex_sdk",
+ "usageScope": "thread_cumulative",
+ "scanId": fixture.scan_id,
+ "kind": "discovery",
+ "attemptId": attempt_id,
+ "threadId": thread_id,
+ "startedAt": counted.isoformat(),
+ "observedAt": counted.isoformat(),
+ "usage": _token_event(counted, 1_000_000, 0)["payload"]["info"][
+ "total_token_usage"
+ ],
+ }
+ ),
+ encoding="utf-8",
+ )
+ _state_graph(
+ fixture.environment,
+ {
+ "scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 2)]),
+ "unrelated-worker": _rollout(
+ tmp_path, "unrelated-worker", [_token_event(counted, 1_000_000, 0)]
+ ),
+ },
+ [],
+ )
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert measurement["coverage"] == "complete"
+ assert measurement["totalTokens"] == 12
+ assert measurement["threadCount"] == 1
+ assert measurement["coverageScope"] == ["thread:scan-parent"]
+
+
+def test_deep_worker_receipt_storage_is_isolated_between_scans(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ directory = _worker_usage_directory(fixture)
+ directory.mkdir(parents=True)
+ another_scan = str(uuid.uuid4())
+ unrelated_directory = directory.parent / another_scan
+ unrelated_directory.mkdir()
+ attempt_id = str(uuid.uuid4())
+ receipt = {
+ "schemaVersion": 1,
+ "source": "codex_sdk",
+ "usageScope": "thread_cumulative",
+ "scanId": another_scan,
+ "kind": "discovery",
+ "attemptId": attempt_id,
+ "threadId": "unrelated-worker",
+ "startedAt": counted.isoformat(),
+ "observedAt": counted.isoformat(),
+ "usage": _token_event(counted, 1_000_000, 0)["payload"]["info"]["total_token_usage"],
+ }
+ (unrelated_directory / f"{attempt_id}.json").write_text(json.dumps(receipt), encoding="utf-8")
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 10, 2)])},
+ [],
+ )
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert measurement["coverage"] == "complete"
+ assert measurement["totalTokens"] == 12
+ assert measurement["coverageScope"] == ["thread:scan-parent"]
+ # A misplaced host receipt also cannot attribute another scan's usage here.
+ (directory / f"{attempt_id}.json").write_text(json.dumps(receipt), encoding="utf-8")
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert measurement["totalTokens"] == 12
+ assert "thread:unrelated-worker" not in measurement["coverageScope"]
+
+
+ ("native_database", "native_worker_tokens", "unmeasured_attempt"),
+ [(False, None, True), (True, None, True), (True, 150, True), (True, 150, False)],
+)
+def test_stopped_deep_scan_reconciles_cumulative_worker_receipts(
+ tmp_path: Path,
+ native_database: bool,
+ native_worker_tokens: int | None,
+ unmeasured_attempt: bool,
+) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ timestamp = counted.isoformat()
+ directory = _worker_usage_directory(fixture)
+ directory.mkdir(parents=True)
+ for index, amount in enumerate([100, 150, None] if unmeasured_attempt else [100, 150]):
+ attempt_id = str(uuid.uuid4())
+ token_counts = (
+ _token_event(counted, amount, 0)["payload"]["info"]["total_token_usage"]
+ if amount is not None
+ else None
+ )
+ (directory / f"{attempt_id}.json").write_text(
+ json.dumps(
+ {
+ "schemaVersion": 1,
+ "source": "codex_sdk",
+ "usageScope": "thread_cumulative",
+ "scanId": fixture.scan_id,
+ "workerId": "synthetic-worker",
+ "kind": "discovery",
+ "attemptId": attempt_id,
+ "attempt": index + 1,
+ "resumed": index > 0,
+ "threadId": "receipt-worker" if amount is not None else "unmeasured-worker",
+ "startedAt": timestamp,
+ "observedAt": timestamp,
+ "outcome": "succeeded" if index == 0 else "failed",
+ "usage": token_counts,
+ }
+ ),
+ encoding="utf-8",
+ )
+ paths = {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 0, 0)])}
+ edges = []
+ if native_worker_tokens is not None:
+ paths["receipt-worker"] = _rollout(
+ tmp_path,
+ "receipt-worker",
+ [_token_event(counted, native_worker_tokens, 0)],
+ parent_thread_id="scan-parent",
+ )
+ edges.append(("scan-parent", "receipt-worker"))
+ if native_database:
+ _state_graph(fixture.environment, paths, edges)
+ for _ in range(2):
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert measurement["coverage"] == (
+ "partial" if unmeasured_attempt or native_worker_tokens is None else "complete"
+ )
+ assert measurement["totalTokens"] == 150
+ assert measurement["byRole"]["workers"]["totalTokens"] == 150
+ assert measurement["threadCount"] == (2 if native_database else 1)
+ assert measurement.get("missingThreadCount", 0) == (
+ int(unmeasured_attempt) + int(native_worker_tokens is None) + int(not native_database)
+ )
+ assert ("worker_usage_unavailable" in measurement.get("warnings", [])) == unmeasured_attempt
+ assert measurement["source"] == (
+ "codex_rollout" if native_worker_tokens is not None else "codex_runtime"
+ )
+
+
[email protected]("reverse_files", [False, True])
[email protected]("native_workers", [False, True])
+def test_worker_receipts_preserve_cumulative_totals_and_known_cache_writes(
+ tmp_path: Path, reverse_files: bool, native_workers: bool
+) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ directory = _worker_usage_directory(fixture)
+ directory.mkdir(parents=True)
+ snapshots = [
+ ("first-worker", 100, 5, True, 0),
+ ("first-worker", 150, 8, True, 1),
+ ("first-worker", 150, 12, True, 2),
+ ("first-worker", 150, 0, False, 3),
+ ("second-worker", 40, 4, True, 1),
+ ]
+ for index, (thread_id, amount, cache_writes, reported, delay) in enumerate(snapshots):
+ attempt_id = str(uuid.UUID(int=len(snapshots) - index if reverse_files else index + 1))
+ tokens = _token_event(counted, amount, 0)["payload"]["info"]["total_token_usage"]
+ tokens["cache_write_input_tokens"] = cache_writes
+ if not reported:
+ tokens["cache_write_input_tokens_reported"] = False
+ (directory / f"{attempt_id}.json").write_text(
+ json.dumps(
+ {
+ "schemaVersion": 1,
+ "source": "codex_sdk",
+ "usageScope": "thread_cumulative",
+ "scanId": fixture.scan_id,
+ "workerId": thread_id,
+ "kind": "discovery",
+ "attemptId": attempt_id,
+ "attempt": index + 1,
+ "resumed": index > 0,
+ "threadId": thread_id,
+ "startedAt": counted.isoformat(),
+ "observedAt": (counted + timedelta(microseconds=delay)).isoformat(),
+ "outcome": "succeeded",
+ "usage": tokens,
+ }
+ ),
+ encoding="utf-8",
+ )
+ paths = {"scan-parent": _rollout(tmp_path, "scan-parent", [_token_event(counted, 0, 0)])}
+ edges = []
+ if native_workers:
+ for thread_id, amount in (("first-worker", 150), ("second-worker", 40)):
+ event = _token_event(counted, amount, 0)
+ event["payload"]["info"]["total_token_usage"].pop("cache_write_input_tokens")
+ paths[thread_id] = _rollout(
+ tmp_path, thread_id, [event], parent_thread_id="scan-parent"
+ )
+ edges.append(("scan-parent", thread_id))
+ _state_graph(fixture.environment, paths, edges)
+ for _ in range(2):
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert measurement["totalTokens"] == 190
+ assert measurement["cacheWriteInputTokens"] == 16
+ assert "cacheWriteInputTokensReported" not in measurement
+ assert measurement["source"] == "codex_runtime"
+ assert measurement["threadCount"] == 3
+ assert measurement["coverage"] == ("complete" if native_workers else "partial")
+ assert measurement.get("missingThreadCount", 0) == (0 if native_workers else 2)
+
+
+ "native_state",
+ ["complete", "partial", "absent", "unknown_thread", "late_thread_id", "sdk_subtotal_larger"],
+)
+def test_stopped_deep_scan_reconciles_missing_sdk_receipts_with_native_usage(
+ tmp_path: Path, native_state: str
+) -> None:
+ fixture = _start_scan(tmp_path, mode="deep")
+ counted = fixture.started_at + timedelta(microseconds=1)
+ directory = _worker_usage_directory(fixture)
+ directory.mkdir(parents=True)
+ for amount in [None, 30] if native_state == "sdk_subtotal_larger" else [None]:
+ attempt_id = str(uuid.uuid4())
+ (directory / f"{attempt_id}.json").write_text(
+ json.dumps(
+ {
+ "schemaVersion": 1,
+ "source": "codex_sdk",
+ "usageScope": "thread_cumulative",
+ "scanId": fixture.scan_id,
+ "workerId": "synthetic-worker",
+ "kind": "discovery",
+ "attemptId": attempt_id,
+ "attempt": 1 if amount is None else 2,
+ "resumed": amount is not None,
+ "threadId": (
+ None
+ if native_state in ("unknown_thread", "late_thread_id")
+ else "receipt-worker"
+ ),
+ "startedAt": counted.isoformat(),
+ "observedAt": counted.isoformat(),
+ "outcome": "failed",
+ "usage": (
+ _token_event(counted, amount, 0)["payload"]["info"]["total_token_usage"]
+ if amount is not None
+ else None
+ ),
+ }
+ ),
+ encoding="utf-8",
+ )
+ parent = _rollout(tmp_path, "scan-parent", [_token_event(counted, 0, 0)])
+ worker = parent.with_name("receipt-worker.jsonl")
+ _state_graph(
+ fixture.environment,
+ {"scan-parent": parent, "receipt-worker": worker},
+ [("scan-parent", "receipt-worker")],
+ )
+ initial = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ assert initial["coverage"] == "partial"
+ assert "worker_usage_unavailable" in initial["warnings"]
+ attempt_scope = {f"worker-attempt:{path.stem}" for path in directory.glob("*.json")}
+ assert attempt_scope.issubset(initial["coverageScope"])
+ if native_state == "late_thread_id":
+ path = directory / f"{attempt_id}.json"
+ receipt = json.loads(path.read_text(encoding="utf-8"))
+ receipt["threadId"] = "receipt-worker"
+ path.write_text(json.dumps(receipt), encoding="utf-8")
+
+ if native_state != "absent":
+ _rollout(
+ tmp_path,
+ "receipt-worker",
+ [_token_event(counted, 20, 5)],
+ parent_thread_id="scan-parent",
+ include_task_complete=native_state != "partial",
+ )
+ for _ in range(2):
+ measurement = fail_scan(
+ fixture.state_dir, fixture.scan_id, "Fixture failure.", environment=fixture.environment
+ )["scan"]["usage"]
+ complete = native_state in ("complete", "late_thread_id")
+ assert measurement["coverage"] == ("complete" if complete else "partial")
+ assert measurement["totalTokens"] == (
+ 30 if native_state == "sdk_subtotal_larger" else 0 if native_state == "absent" else 25
+ )
+ assert measurement.get("missingThreadCount", 0) == int(not complete)
+ assert ("worker_usage_unavailable" in measurement.get("warnings", [])) == (not complete)
+ assert attempt_scope.issubset(measurement["coverageScope"])
+ if native_state == "partial":
+ assert "turn_in_progress" in measurement["warnings"]
+
+
+def test_cancel_scan_retains_runtime_usage_on_repeated_cancellation(tmp_path: Path) -> None:
+ fixture = _start_scan(tmp_path)
+ cost = {
+ "model": "fixture-model",
+ "inputTokens": 40,
+ "cachedInputTokens": 0,
+ "cacheWriteInputTokens": 0,
+ "outputTokens": 5,
+ "estimatedUsd": 0.01,
+ }
+ with sqlite3.connect(fixture.state_dir / "workbench.sqlite3") as connection:
+ connection.execute(
+ "UPDATE scans SET cost_json = ? WHERE id = ?", (json.dumps(cost), fixture.scan_id)
+ )
+ runtime = {
+ "coverage": "complete",
+ "source": "codex_runtime",
+ "threadCount": 1,
+ **_counts(40, 0, 5),
+ }
+ for _ in range(2):
+ scan_command(
+ fixture.state_dir,
+ "cancel-scan",
+ fixture.scan_id,
+ "--cost-json",
+ json.dumps({"usage": runtime}),
+ environment=fixture.environment,
+ )
+ saved = scan_command(
+ fixture.state_dir, "get-scan", fixture.scan_id, environment=fixture.environment
+ )["scan"]
+ assert saved["progress"]["status"] == "canceled"
+ assert saved["usage"] == runtime
+ assert saved["cost"] == cost
@pytest.mark.parametrize(
@@ -2072,6 +3161,7 @@ def test_failed_scan_preserves_legacy_failure_behavior(tmp_path: Path) -> None:
def test_completion_recovers_replaced_deep_worker_threads(
tmp_path: Path, worker_kind: str, legacy_archive: bool
) -> None:
+ # Compressed variants exercise the bundled Node decoder in the SDK runtime lane.
fixture = _start_scan(tmp_path, mode="deep")
fixture = replace(
fixture,
diff --git a/plugins/codex-security/tests/test_workbench_scan_usage_merge.py b/plugins/codex-security/tests/test_workbench_scan_usage_merge.py
new file mode 100644
index 000000000..5cde9a544
--- /dev/null
+++ b/plugins/codex-security/tests/test_workbench_scan_usage_merge.py
@@ -0,0 +1,177 @@
+"""Merge usage coverage across observations without losing known gaps."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from workbench_test_support import usage_counts as _counts
+
+
+ ("previous_input", "previous_output", "latest_roles"),
+ [(21, 8, True), (37, 8, True), (20, 9, True), (21, 8, False)],
+ ids=["equal-subtotal", "older-larger-subtotal", "different-token-fields", "no-latest-roles"],
+)
+def test_coverage_counts_and_roles_follow_the_latest_observation(
+ workbench_api, previous_input: int, previous_output: int, latest_roles: bool
+) -> None:
+ merge = workbench_api["_WORKBENCH_DB_CONTEXT"].scan_usage.merge_scan_usage_fields
+ previous = {
+ "coverage": "complete",
+ "coverageScope": ["thread:parent"],
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "observedAt": "2026-01-01T00:00:00Z",
+ **_counts(previous_input, 0, previous_output),
+ "byRole": {
+ "parent": {"threadCount": 1, **_counts(previous_input, 0, previous_output)},
+ "workers": {"threadCount": 0, **_counts(0, 0, 0)},
+ },
+ }
+ observed = {
+ "coverage": "complete",
+ "coverageScope": ["thread:parent", "thread:worker"],
+ "source": "codex_rollout" if latest_roles else "codex_runtime",
+ "threadCount": 2,
+ "observedAt": "2026-01-01T00:00:01Z",
+ "cacheWriteInputTokensReported": False,
+ **_counts(21, 0, 8),
+ }
+ if latest_roles:
+ observed["byRole"] = {
+ "parent": {
+ "threadCount": 1,
+ "cacheWriteInputTokensReported": False,
+ **_counts(21, 0, 8),
+ },
+ "workers": {"threadCount": 1, **_counts(0, 0, 0)},
+ }
+ for observation in [previous, observed]:
+ workbench_api["parse_scan_cost"](json.dumps({"usage": observation}))
+
+ merged = merge({"usage": previous}, {"usage": observed})
+ usage = merged["usage"]
+ assert usage["threadCount"] == 2
+ assert usage["coverage"] == "complete"
+ assert usage["coverageScope"] == observed["coverageScope"]
+ assert usage["observedAt"] == observed["observedAt"]
+ for field, value in _counts(previous_input, 0, previous_output).items():
+ assert usage[field] == value
+ if latest_roles and (previous_input, previous_output) == (21, 8):
+ assert usage["byRole"] == observed["byRole"]
+ else:
+ assert "byRole" not in usage
+ assert json.loads(workbench_api["parse_scan_cost"](json.dumps(merged))) == merged
+ assert merge({"usage": observed}, {"usage": previous}) == merged
+ assert merge(merged, {"usage": previous}) == merged
+
+
+ ("previous_threads", "previous_tokens", "new_threads", "new_tokens", "combined_tokens"),
+ [
+ (["parent", "validation"], 1_000, ["parent", "worker"], 1_200, 1_400),
+ (["parent", "validation"], 1_000, ["parent"], 1_200, 1_400),
+ (["parent", "validation", "worker"], 1_010, ["parent", "worker"], 910, 1_110),
+ (["validation"], 200, ["parent"], 800, 1_000),
+ ],
+ ids=["incomparable", "narrower-larger", "narrower-smaller", "disjoint"],
+)
+def test_newer_scoped_subtotals_need_encompassing_complete_evidence(
+ workbench_api,
+ previous_threads: list[str],
+ previous_tokens: int,
+ new_threads: list[str],
+ new_tokens: int,
+ combined_tokens: int,
+) -> None:
+ merge = workbench_api["_WORKBENCH_DB_CONTEXT"].scan_usage.merge_scan_usage_fields
+ previous = {
+ "coverage": "complete",
+ "coverageScope": [f"thread:{thread}" for thread in previous_threads],
+ "source": "codex_runtime",
+ "threadCount": len(previous_threads),
+ "observedAt": "2026-01-01T00:00:00Z",
+ **_counts(previous_tokens, 0, 0),
+ }
+ observed = {
+ "coverage": "complete",
+ "coverageScope": [f"thread:{thread}" for thread in new_threads],
+ "source": "codex_rollout",
+ "threadCount": len(new_threads),
+ "observedAt": "2026-01-01T00:00:01Z",
+ **_counts(new_tokens, 0, 0),
+ }
+ partial = merge({"usage": previous}, {"usage": observed})
+ assert partial["usage"]["totalTokens"] == max(previous_tokens, new_tokens)
+ assert partial["usage"]["coverage"] == "partial"
+ assert partial["usage"]["warnings"] == ["usage_scope_incomplete"]
+ assert partial["usage"]["coverageScope"] == sorted(
+ set(previous["coverageScope"]) | set(observed["coverageScope"])
+ )
+ assert partial["usage"]["observedAt"] == observed["observedAt"]
+ assert partial["usage"]["threadCount"] == len(new_threads)
+ assert merge({"usage": observed}, {"usage": previous}) == partial
+ assert merge(partial, {"usage": previous}) == partial
+
+ complete = {
+ **previous,
+ "coverageScope": partial["usage"]["coverageScope"],
+ "threadCount": len(partial["usage"]["coverageScope"]),
+ "observedAt": "2026-01-01T00:00:02Z",
+ **_counts(combined_tokens, 0, 0),
+ }
+ resolved = merge(partial, {"usage": complete})
+ assert resolved["usage"] == complete
+ assert merge(resolved, partial) == resolved
+ assert merge(resolved, {"usage": observed}) == resolved
+
+
+def test_legacy_partial_without_scope_does_not_claim_resolved_coverage(workbench_api) -> None:
+ merge = workbench_api["_WORKBENCH_DB_CONTEXT"].scan_usage.merge_scan_usage_fields
+ partial = {
+ "coverage": "partial",
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "missingThreadCount": 1,
+ **_counts(40, 0, 5),
+ }
+ complete = {
+ "coverage": "complete",
+ "coverageScope": ["thread:scan-parent"],
+ "source": "codex_rollout",
+ "threadCount": 1,
+ **_counts(50, 0, 8),
+ }
+ merged = merge({"usage": partial}, {"usage": complete})["usage"]
+ assert merged["coverage"] == "partial"
+ assert merged["totalTokens"] == 58
+ assert merged["missingThreadCount"] == 1
+ assert "coverageScope" not in merged
+
+
+def test_unscoped_complete_observation_keeps_known_gap_identity(workbench_api) -> None:
+ merge = workbench_api["_WORKBENCH_DB_CONTEXT"].scan_usage.merge_scan_usage_fields
+ partial = {
+ "coverage": "partial",
+ "coverageScope": ["thread:scan-parent", "thread:missing-worker"],
+ "source": "codex_runtime",
+ "threadCount": 1,
+ "missingThreadCount": 1,
+ **_counts(40, 0, 5),
+ }
+ legacy_complete = {
+ "coverage": "complete",
+ "source": "codex_runtime",
+ "threadCount": 2,
+ **_counts(50, 0, 8),
+ }
+ merged = merge({"usage": partial}, {"usage": legacy_complete})
+ assert merged["usage"]["coverage"] == "partial"
+ assert merged["usage"]["coverageScope"] == partial["coverageScope"]
+ resolved = merge(
+ merged,
+ {"usage": {**legacy_complete, "coverageScope": partial["coverageScope"]}},
+ )
+ assert resolved["usage"]["coverage"] == "complete"
+ assert not resolved["usage"].get("missingThreadCount")
diff --git a/plugins/codex-security/tests/workbench_test_support.py b/plugins/codex-security/tests/workbench_test_support.py
index c576e7f97..067ddd560 100644
--- a/plugins/codex-security/tests/workbench_test_support.py
+++ b/plugins/codex-security/tests/workbench_test_support.py
@@ -1050,3 +1050,20 @@ class ScanFixtureTestCase(TestCase):
def sha256_file(self, name: str) -> str:
return hashlib.sha256((self.scan_dir / name).read_bytes()).hexdigest()
+
+
+def usage_counts(
+ input_tokens: int,
+ cached_input_tokens: int,
+ output_tokens: int,
+ *,
+ cache_write_input_tokens: int = 0,
+) -> dict[str, int]:
+ return {
+ "inputTokens": input_tokens,
+ "cachedInputTokens": cached_input_tokens,
+ "cacheWriteInputTokens": cache_write_input_tokens,
+ "outputTokens": output_tokens,
+ "reasoningOutputTokens": 0,
+ "totalTokens": input_tokens + output_tokens,
+ }
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 8e4608cec..0b35f4de7 100644
--- a/sdk/typescript/README.md
+++ b/sdk/typescript/README.md
@@ -29,11 +29,9 @@ Supported runtimes:
- Python 3.10+ for scans, policy generation, exports, scan history, and saved
findings. Python 3.10 also needs `tomli`.
-Reading compressed Codex session logs (`.jsonl.zst`) requires Node.js 22.15.0+
-within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14, compressed sessions
-are unavailable when reading saved activity or attaching scan logs to feedback, and
-scans whose original session is compressed cannot resume. Plain `.jsonl` logs
-work on all supported runtimes.
+Compressed Codex session logs (`.jsonl.zst`) are readable on all supported Node.js
+versions. The bundled streaming decoder reads concatenated frames and reports
+truncated streams as collection errors.
### Install the CLI
@@ -429,11 +427,14 @@ and the plugin version used at launch. Missing fields stay unknown.
If `run()` rejects before you receive a registration, record the error separately
from saved scan outcomes. The caller may have missed the registration receipt.
-Use `onProgress` for scan progress and `onCost` for cost updates.
-Use `onUsageObservation` for the last reported token measurement time
+Use `onProgress` for scan progress and `onMeasurement` for observed token/cost
+subtotals, coverage, and collection time. `onCost` and `onUsage` report complete
+totals. `onUsageObservation` reports the native token measurement time
(`tokensUpdatedAt`) and account-wide allowance readings (`accountRateLimits`).
-Each reading includes its own `observedAt` timestamp and the percentage used in
-each reported window. A limit-only update can arrive before any token measurement.
+Each reading has its own `observedAt` timestamp and percentages used in each
+reported window. An allowance can arrive before any token measurement. See
+[telemetry and measurement](docs/telemetry.md) for operation receipts, collection
+controls, replay, and reporting definitions.
Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports
persisted worker sessions discovered by the SDK's existing session tracker,
diff --git a/sdk/typescript/docs/cli.md b/sdk/typescript/docs/cli.md
index b825b725a..f60adc334 100644
--- a/sdk/typescript/docs/cli.md
+++ b/sdk/typescript/docs/cli.md
@@ -1001,8 +1001,10 @@ publication uses the same request attribution; embedding requests identify
the package and version in their `User-Agent`.
These fields provide request attribution for supported inference providers, including
-Bedrock. They do not create a separate telemetry collector, record command
-starts or outcomes, or make another provider's traffic visible to OpenAI.
+Bedrock. They do not create a separate telemetry collector or make another
+provider's traffic visible to OpenAI. Local operation receipts separately record
+starts, outcomes, duration, and usage coverage; see
+[telemetry and measurement](telemetry.md).
Disable Codex usage analytics and built-in metrics with
`--codex 'analytics.enabled=false'`. The setting carries into `scan --patch`,
@@ -2163,11 +2165,10 @@ History lives in `$CODEX_SECURITY_STATE_DIR/workbench.sqlite3`, or
writable, and outside the target repository. Session logs may contain sensitive
data even though scan recipes do not store credentials.
-Codex may compress saved session logs to `.jsonl.zst`. Reading those logs requires
-Node.js 22.15.0+ within 22.x, or Node.js 24.x or 26.x. On Node.js 22.13–22.14,
-compressed sessions are unavailable to `scans logs`, feedback attachments, and
-`scans resume`. Upgrade Node.js to read or resume these sessions. Plain `.jsonl`
-logs work on all supported runtimes.
+Codex may compress saved session logs to `.jsonl.zst`. Plain and compressed logs
+work on all supported Node.js versions, including logs, feedback attachments,
+usage accounting, and saved-session discovery for resume. A bundled decoder
+reads concatenated frames and reports truncated streams as collection errors.
### Resuming an interrupted Deep Scan
diff --git a/sdk/typescript/docs/findings-service.md b/sdk/typescript/docs/findings-service.md
index 97ca71465..2f9821564 100644
--- a/sdk/typescript/docs/findings-service.md
+++ b/sdk/typescript/docs/findings-service.md
@@ -67,6 +67,21 @@ const result = await deduplicateScan("scan_example_001", {
console.log(result.duplicateGroups);
```
+Both saved-scan APIs accept `onEmbeddingUsage` for the built-in local adapter.
+It receives one observation per processed batch: model, tokenized input count
+(including chunks of long findings), provider-reported input tokens, outcome,
+and duration in milliseconds. `inputTokens: null` means usage was unavailable,
+including responses that omit usage; it does not mean zero tokens. Cached
+embeddings generate no new observations. Observers are best effort: throws,
+rejections, and pending promises do not fail or block embedding work. No finding
+text, vectors, credentials, or endpoint is included.
+
+Embedding tokens remain separate from scan model-token and cost totals. A batch
+can contain several HTTP attempts when the local adapter retries, and its
+observation only includes usage from the final response. Remote services and
+custom embedding bindings own their usage reporting; set an observer directly on
+`OpenAiFindingEmbedder` when using it in a custom binding.
+
For a different embedding provider or model, both saved-scan SDK methods accept
an `embedding` binding. Reuse the `FindingEmbedder` interface: return one
`{ model, vector }` per input finding, in input order. The adapter owns its
@@ -326,6 +341,20 @@ const receipt = await publishScanToCustom("/path/to/completed-scan", {
console.log(receipt.repositoryId, receipt.findingIds);
```
+The Linear and custom publication SDKs return a content-free `telemetry`
+summary and accept `onTelemetry` for outcomes, including preparation failure and
+cancellation. Existing Linear receipts and custom workflow results retain this
+summary. It includes an attempt ID, destination family, duration, outcome, and
+counts of selected, submitted, created, reused, acknowledged, and failed findings.
+Submitted counts describe findings handed to publication, not HTTP attempts.
+`null` denotes unknown counts; in particular, the custom bulk API acknowledges
+IDs without distinguishing creation from upsert. Unknown mutation outcomes are
+`indeterminate`, and dry runs have `outcome: "preview"` and `attempted: false`.
+Reusing a saved custom workflow receipt produces a new attempt summary with no
+submitted findings. Hosts should group repeated receipt snapshots by attempt ID
+and use the latest observation. Callback failures do not change publication
+results, and these callbacks add no network destination or separate files.
+
## Compatible endpoint contract
The retained HTTP clients use these endpoints on the supplied base URL,
@@ -373,6 +402,8 @@ the callback before each HTTP batch; the caller handles token acquisition.
Cancellation prevents a new callback or HTTP request. Direct embedder callers
still await a key callback that has already started.
Pass `fetch` as the second argument and the full endpoint URL as the third.
+The fourth argument accepts an `AbortSignal`; the fifth accepts an
+`EmbeddingUsageObserver`.
By default, the saved-scan deduplication APIs use environment credentials. A
custom SDK `embedding` binding can supply an adapter with its own credentials,
including an `OpenAiFindingEmbedder` with a renewable key callback.
diff --git a/sdk/typescript/docs/telemetry.md b/sdk/typescript/docs/telemetry.md
new file mode 100644
index 000000000..40311cc08
--- /dev/null
+++ b/sdk/typescript/docs/telemetry.md
@@ -0,0 +1,228 @@
+# Telemetry and measurement
+
+Codex Security keeps model-request attribution, native analytics, local usage
+accounting, and host-owned telemetry export separate. It does not configure a new
+remote collector.
+
+## Controls and collection
+
+Native `analytics` and `otel` settings keep their Codex semantics. Scan profiles,
+project settings, and explicit overrides keep their native precedence. Per-scan
+settings are not merged into shared credential configuration. Discovery, reducer,
+and resumed workers inherit their scan's settings. Worker runtime snapshots live
+under the credential home denied to model tools. OTel exporter configuration can
+contain authentication headers, so it is excluded from model-readable preflight
+files and saved scan recipes while remaining available to native execution.
+
+For authentication/bootstrap commands and stored-account CLI app-server startup,
+automatic inheritance covers analytics consent and request metadata. OTel
+exporters come from the selected native home or existing explicit runtime
+configuration; ambient/profile exporter settings are not copied when
+authentication selects another home. The pinned runtime cannot load a separate
+private profile for these helpers without changing authentication/state identity.
+The wrapper does not copy inherited exporter headers into arguments or
+temporarily rewrite shared settings.
+
+Request metadata includes command, surface, package/plugin versions, configured
+provider family, and scan mode when available. Wrapper operations and workers add
+opaque operation, attempt, and parent-attempt IDs. IDs are join keys, not metric
+labels. Hosted scan execution receives the same attribution in
+`request.runtime.requestMetadata`; the executor owns forwarding it to its runtime.
+Native analytics opt-out does not remove request attribution or configure an OTel
+exporter. Hosted schema and checkout preparation precede the SDK invocation;
+rejections at that boundary remain the host's responsibility to record.
+The [hosted remediation executor](./hosted-remediation.md) owns request
+attribution, durable attempt tracking, and usage reporting for
+`runHostedRemediation`.
+
+Local operational receipts are saved under `telemetry/` in the existing Codex
+Security state directory. These are local history, not an analytics upload.
+Removing that directory removes these receipts and their resume bindings.
+Receipts are never written inside the protected repository; a journal failure
+remains observable and does not override the main operation.
+Retention and remote deletion in a host's collector remain the host's
+responsibility. Existing scan output, diagnostics, and explicit feedback retain
+their existing behavior.
+
+## Operation receipts
+
+SDK `run`, `patch`, `validate`, and `generatePolicy` capture an `attempt_started`
+receipt at invocation and one `attempt_finished` receipt on settlement. Local
+initialization can delay start delivery; its occurrence time remains the original
+invocation time. Inference preparation waits for that initialization.
+CLI scans use the SDK path. Standalone CLI patch, validation, verification, and
+patch-risk assessment also record native invocation starts and outcomes. Mock
+scans and preflight-only calls are excluded. Policy generation emits its start to
+observers immediately and buffers disk persistence until policy path validation
+establishes all protected Git stores. Policy attempts rejected before that point
+are observable only through `onTelemetry`; they do not create local state.
+Finding workflows likewise defer persistence until explicit and saved artifact
+paths have been protected. Their journal cannot write into either artifact tree,
+including when the selected artifact directory occupies the journal path.
+Each receipt has a schema version, stable event ID, random operation/attempt IDs,
+occurrence and local observation times, command, surface, package version, and
+resume status. Terminal receipts add duration, outcome, a bounded failure category,
+and available numerical usage and result counts. Plugin version and configured
+provider family are added once the runtime is known.
+
+The terminal receipt embeds the last SDK measurement with its own `observedAt`
+and available `coverageScope`. Saved workbench accounting may reconcile later
+native evidence; terminal snapshots are not backfilled.
+
+The outcome is `completed`, `failed`, `canceled`, or `unresolved`. A hosted
+submission with unknown acceptance is unresolved. A start without a terminal
+receipt, including process loss, also remains unresolved when summarized.
+Completion describes operation execution; finding counts do not measure accuracy.
+A terminal `reusedResult: true` identifies a cached workflow return. The summary
+counts these as `reusedAttempts`; exclude them from new-work, finding-yield, and
+usage-coverage denominators. Older receipts without the field have unrecorded
+reuse status. Completed scans report the finding count and whether the scan
+manifest records completion. Older receipts can also contain model-reported
+reviewed surface and deferred counts.
+
+Resuming a saved scan keeps its operation ID but creates a new attempt ID.
+`usageScopeId` identifies cumulative accounting across those attempts. Do not sum
+resumed cumulative receipts. The supplied summary takes the maximum observed cost
+per usage scope; separate retry scans have separate scopes.
+
+```ts
+import {
+ readOperationTelemetry,
+ summarizeOperationTelemetry,
+} from "@openai/codex-security";
+
+const { events, parseFailures } = await readOperationTelemetry(stateDirectory);
+const summary = summarizeOperationTelemetry(events);
+console.log({ ...summary, parseFailures });
+```
+
+The reader reports corrupt/truncated records separately from usable receipts. The
+summary deduplicates event IDs, counts attempts and logical operations separately,
+retains unresolved attempts, and reports usage coverage and priced-attempt counts
+beside observed cost. Duration samples can be pooled into histograms or
+percentiles; do not average percentiles from separate groups.
+
+`onTelemetry` is an optional SDK observer for these same receipts. An observer
+cannot delay or fail a scan. It is not an acknowledgement from a remote collector.
+A host needing delivery across restarts should replay the local journal, dedupe
+by event ID, and checkpoint only after its collector acknowledges acceptance.
+Ingestion should add its own timestamp while preserving `occurredAt`.
+Journal write failures reach the warning observer; receipt collection counters
+describe local persistence only. They do not claim remote acceptance.
+
+Track collector pending, accepted, retried, dropped/expired, duplicate, and late
+records at the integration that owns delivery. Reconcile emitted event IDs against
+accepted IDs there. Local tests exercise failed writes, replay, duplicate
+terminals, corrupt tails, and unclosed attempts; they do not establish a
+production collector's loss rate.
+
+## Usage and completeness
+
+Prefer `onMeasurement` when displaying or collecting live usage:
+
+```ts
+await security.run(repository, {
+ onMeasurement(measurement) {
+ // usage and cost may be null; partial values are observed subtotals.
+ display(measurement.usage, measurement.cost, measurement.coverage);
+ },
+});
+```
+
+The observation contains `usage`, `cost`, `coverage`, `observedAt`, measured
+`threadCount`, and `missingThreadCount`. Coverage is `complete`, `partial`, or
+`unavailable`. An incompletely measured thread can contribute to both thread
+counts. Complete coverage means all discovered threads are accounted for;
+descendants absent from native metadata and worker receipts cannot be detected.
+A newly discovered worker can change complete usage to partial. The
+dashboard updates the qualifier and clears unavailable values. Existing
+`onUsage` and `onCost` observers retain their complete-only behavior; budget
+enforcement still uses known spending subtotals.
+
+Coverage applies to the tracked scan threads, including optional owner evidence
+recorded during the scan. Automatic owner reports validate that evidence without
+additional model calls. Standalone owner suggestions, finding comparisons, and
+severity-review helpers do not contribute usage to these scan/component subtotals.
+
+When available, `coverageScope` identifies every discovered thread and worker
+attempt, including missing measurements. Saved reconciliation clears a known gap
+only when newer complete evidence covers that entire scope. A newer observation
+that does not encompass the retained scope leaves the maximum reported subtotal
+partial, even when both observations individually report complete. The
+`usage_scope_incomplete` warning identifies these unreconciled scope totals;
+later encompassing complete evidence clears that uncertainty. Reconciliation
+retains the union of known identities and the largest reported missing-thread
+count. Overlapping aggregates cannot establish an exact combined missing-thread
+count. Legacy observations without a scope cannot prove that their gaps were
+resolved.
+These identities belong in local records, not metric labels.
+
+Saved success, failure, and cancellation records retain numerical usage even
+without a model price. Repeated terminal updates reconcile late observations
+without changing the saved outcome or summing overlapping receipts. Component
+and bulk receipts also keep failed/canceled usage. Legacy receipt status values
+are preserved; their additive `outcome` distinguishes cancellation.
+Bulk recovery of an already sealed scan copies the saved `usage` object with its
+original source, observation time, coverage, and scope into the receipt without
+creating a new inference attempt or live measurement.
+
+Both live and saved collectors read plain and compressed rollouts. Deep workers
+persist a receipt per attempt before validating their output, including failed
+and canceled attempts. These receipts live under
+`codex-home/worker-usage/<scanId>/` in the host's Codex Security state directory,
+with the scan and worker permission profiles protecting the host-managed store.
+Collectors bind receipts to the selected scan and attempt; model-authored scan
+artifacts cannot introduce usage totals or authorize reading another session.
+Worker receipts remain local runtime state, subject to the host's retention and
+deletion policy. The pinned native CLI reports cumulative thread usage at
+turn completion. Receipts mark this as `usageScope: "thread_cumulative"`:
+resumed attempts on the same thread are reconciled by maximum, then compared
+with the native thread total by maximum, preserving whole cumulative snapshots.
+Separate threads are summed. Missing native evidence
+keeps worker fallback usage partial, including when the native state database is
+unavailable.
+
+Missing cache-write usage is represented with
+`cache_write_input_tokens_reported: false` in SDK token usage and
+`cacheWriteInputTokensReported: false` in saved usage. Its numeric zero is a
+placeholder, not an observed zero. Worker receipts also treat SDK-defaulted zeroes
+without field-presence evidence as unknown. Known total usage remains usable. Cost is an
+estimate with its existing price provenance and uncertainty, not a billing total.
+Late saved usage can exceed an earlier supplied price estimate; the warning
+`cost_estimate_covers_earlier_usage` identifies that cost subtotal.
+
+Embedding batch usage is observed separately through `onEmbeddingUsage`. Provider
+input tokens can be unknown; local token estimates do not replace a missing
+provider receipt. Publication telemetry uses existing publication results and
+receipts, with destination family, duration, outcome, and counts. An upsert
+acknowledgement does not establish whether a finding was newly created or reused;
+those counts remain unknown when the integration cannot distinguish them.
+
+## Reporting and data selection
+
+Routine operation telemetry contains no source, prompts, model output, finding
+text, paths, repository URLs, account IDs, raw exceptions, or full configuration.
+This field selection does not redact or change existing diagnostic text.
+
+Use bounded dimensions such as command, surface, scan mode, worker role, outcome,
+and provider family. Keep correlation IDs out of metric labels. Report the
+population, sample count, missingness, and relevant version/workload cohorts with
+every comparison:
+
+- Reliability: terminal outcomes per eligible attempt, unresolved rate, and
+ eventual operation success separately.
+- Performance: attempt duration distributions, separating cancellation and
+ incomplete work.
+- Cost: all observed usage scopes, including failed attempts, divided by useful
+ completed outcomes; show partial-usage and unknown-price rates alongside.
+- Caching: cache-read/write shares only where the required breakdown is observed.
+- Worker efficiency: attempts, retries, duration, usage coverage, and accepted
+ output by role.
+- Quality: reviewed true-positive share among adjudicated findings, with review
+ coverage. Unreviewed findings are unknown. Publication and patch outcomes are
+ separate signals.
+
+The latest closed false positives used as scan context are a selected sample,
+not a false-positive-rate denominator. Recall requires held-out labeled
+evaluations or independent representative review; production finding counts
+cannot establish it.
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 5e5038649..536378f70 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -48,7 +48,8 @@
"docs/classify-severity-records.md",
"docs/hosted-scans.md",
"docs/validate-records.md",
- "docs/hosted-remediation.md"
+ "docs/hosted-remediation.md",
+ "docs/telemetry.md"
],
"publishConfig": {
"access": "public",
diff --git a/sdk/typescript/scripts/check-package.mjs b/sdk/typescript/scripts/check-package.mjs
index 44c8da8fa..f02bdf0e9 100644
--- a/sdk/typescript/scripts/check-package.mjs
+++ b/sdk/typescript/scripts/check-package.mjs
@@ -107,6 +107,7 @@ function validatePackagePaths(entries) {
"package/docs/hosted-scans.md",
"package/docs/validate-records.md",
"package/docs/hosted-remediation.md",
+ "package/docs/telemetry.md",
"package/schemas/hosted-scan-v2.fixture.json",
"package/LICENSE",
"package/bin/codex-security.mjs",
diff --git a/sdk/typescript/scripts/fixtures/package-deep-codex.mjs b/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
index eb2f8d981..7b6b55a04 100644
--- a/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
+++ b/sdk/typescript/scripts/fixtures/package-deep-codex.mjs
@@ -25,6 +25,11 @@ async function trace(event) {
async function run() {
const args = process.argv.slice(2);
+ const overrides = [];
+ for (let index = 0; index < args.length; index++) {
+ if (args[index] === "-c" || args[index] === "--config")
+ overrides.push(args[++index]);
+ }
if (args.includes("app-server")) {
await trace({ phase: "preflight", args });
const threadId = "package-sdk-owner";
@@ -74,16 +79,13 @@ async function run() {
break;
case "config/read":
result = {
- config: {
- default_permissions: "codex_security_deep_scan_worker",
- permissions: {
- codex_security_deep_scan_worker: {
- extends: ":read-only",
- filesystem: { ":root": "read" },
- network: { enabled: false },
- },
- },
- },
+ config: parse(
+ overrides
+ .filter((override) =>
+ /^(?:default_permissions=|permissions\.)/u.test(override),
+ )
+ .join("\n"),
+ ),
origins: {},
layers: null,
};
@@ -112,11 +114,6 @@ async function run() {
}
let prompt = "";
for await (const chunk of process.stdin) prompt += chunk;
- const overrides = [];
- for (let index = 0; index < args.length; index++) {
- if (args[index] === "-c" || args[index] === "--config")
- overrides.push(args[++index]);
- }
const config = parse(overrides.join("\n"));
const artifacts = config.mcp_servers.cs_artifacts;
const env = artifacts.env;
@@ -124,6 +121,25 @@ async function run() {
assert.ok(root, "The real worker must supply its bound artifact root.");
assert.equal(config.mcp_servers["codex-security"].enabled, false);
assert.notEqual(artifacts.enabled, false);
+ assert.equal(config.default_permissions, "codex_security_deep_scan_worker");
+ assert.deepEqual(
+ JSON.parse(
+ JSON.stringify(config.permissions.codex_security_deep_scan_worker),
+ ),
+ {
+ extends: ":read-only",
+ filesystem: {
+ ":root": "read",
+ [join(
+ process.env.CODEX_SECURITY_STATE_DIR,
+ "codex-home",
+ "worker-usage",
+ env.CODEX_SECURITY_SCAN_ID,
+ )]: { ".": "deny" },
+ },
+ network: { enabled: false },
+ },
+ );
const layout = env.CODEX_SECURITY_ARTIFACT_LAYOUT;
const threadId = `package-${layout}-${basename(root)}-${basename(join(root, ".."))}`;
console.log(JSON.stringify({ type: "thread.started", thread_id: threadId }));
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 09fb42d8d..96433ffcc 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -113,12 +113,14 @@ const distModules = [
"models",
"multiscan",
"mock-scan",
+ "operation-telemetry",
"owner-evidence",
"patch-publication",
"patch-tui",
"publication",
"publication-events",
"publication-store",
+ "publication-telemetry",
"publish",
"result",
"record",
@@ -131,10 +133,12 @@ const distModules = [
"scan-history-renderer",
"scan-inputs",
"scan-logs",
+ "scan-measurement",
"scan-usage-display",
"security-policy",
"security-policy-cli",
"security-policy-diff",
+ "session-lines",
"skill-authentication",
"standalone-validation-prompt",
"validation-records",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 603269bcc..b88f4359c 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -105,12 +105,14 @@ import {
readScanBudgetUsage,
ScanCostTracker,
type ScanCost,
+ type ScanUsageMeasurement,
type ParentProgressSource,
type ScanSessionEvent,
type ScanUsageObservation,
type ScanWorkerEvent,
} from "./cost.js";
import type { ScanTokenUsage } from "./cost-model.js";
+import { measuredScanCost, combineMeasurements } from "./scan-measurement.js";
import { ScanProgressTracker, type DeepScanProgress } from "./scan-progress.js";
import { findScanSession } from "./scan-logs.js";
import {
@@ -172,6 +174,7 @@ import {
AuthenticationRequiredError,
CodexSecurityError,
ConfigurationError,
+ InvalidTargetError,
IncompleteScanError,
OutputDirectoryError,
OutputDirectoryNotEmptyError,
@@ -236,6 +239,10 @@ import {
} from "./worker-progress.js";
import { CODEX_SECURITY_THREAD_SOURCES } from "./thread-source.js";
import { codexSecurityRequestContext } from "./request-metadata.js";
+import {
+ OperationTelemetry,
+ type OperationTelemetryEvent,
+} from "./operation-telemetry.js";
import {
CODEX_EXECUTABLE_VERSION,
CODEX_SDK_VERSION,
@@ -391,6 +398,12 @@ export interface ScanOptions extends ScanSettings {
parentScanId?: string;
expectedPluginVersion?: string;
onCost?: (cost: Readonly<ScanCost>, maxCostUsd?: number) => void;
+ /** Observed subtotals and coverage changes, including loss of completeness. */
+ onMeasurement?: (measurement: Readonly<ScanUsageMeasurement>) => void;
+ /** Content-free local operation receipts. Hosts own remote export and acknowledgement. */
+ onTelemetry?: (event: Readonly<OperationTelemetryEvent>) => void;
+ /** @internal Correlate composed attempts without using repository identity. */
+ telemetryContext?: { operationId: string; parentAttemptId?: string };
/** Observed tokens, including models without a price estimate. */
onUsage?: (usage: Readonly<ScanTokenUsage>) => void;
/** The last reportable token total's measurement time and latest account limits from this scan's sessions. */
@@ -444,6 +457,8 @@ export interface ValidationOptions extends Pick<
| "outputDir"
| "safetyIdentifier"
| "signal"
+ | "onTelemetry"
+ | "onObserverError"
> {
repositoryPath: string;
/** @internal Reuse the scan's captured knowledge inputs during validation. */
@@ -492,6 +507,8 @@ export interface PatchOptions extends Pick<
| "onActivity"
| "onSessionEvent"
| "onCost"
+ | "onMeasurement"
+ | "onTelemetry"
| "onReconnect"
| "onWarning"
| "onObserverError"
@@ -646,6 +663,8 @@ type ScanObserverName =
| "onAuthentication"
| "onCost"
| "onUsage"
+ | "onMeasurement"
+ | "onTelemetry"
| "onUsageObservation"
| "onOutputArchived"
| "onOutputDirReady"
@@ -704,6 +723,9 @@ interface CodexSecurityRuntimeOptions {
}
interface ClientDependencies {
+ createOperationTelemetry?: (
+ options: ConstructorParameters<typeof OperationTelemetry>[0],
+ ) => OperationTelemetry | null;
/** Explicit hosted execution; never falls back to createCodex. */
hostedScan?: {
executor: ScanExecutor;
@@ -752,6 +774,11 @@ const SAFETY_IDENTIFIER_ENV = "CODEX_SAFETY_IDENTIFIER";
const PERSONAL_TRUSTED_ACCESS_URL = "https://chatgpt.com/cyber";
const ORGANIZATIONAL_TRUSTED_ACCESS_URL =
"https://openai.com/form/enterprise-trusted-access-for-cyber/";
+
+class PolicyCostLimitExceededError extends CodexSecurityError {
+ public override name = CodexSecurityError.name;
+}
+
export class CodexSecurity {
public readonly config: Readonly<CodexSecurityConfig>;
public readonly metadata: CodexSecurityMetadata = {
@@ -767,6 +794,8 @@ export class CodexSecurity {
readonly #loginHandles = new Set<CodexLoginHandle>();
readonly #abortController = new AbortController();
#activeOperation: Promise<unknown> | null = null;
+ #operationTelemetry: OperationTelemetry | null = null;
+ #operationTelemetryStart: Promise<void> | null = null;
#runtime: PreparedRuntime | null = null;
#runtimeCredentialSource: "api_key" | "stored_credentials" | null = null;
#closed = false;
@@ -803,10 +832,19 @@ export class CodexSecurity {
...options,
severityRubric: options.severityRubric && { ...options.severityRubric },
};
- return await this.#trackOperation(() =>
- options.workflowId === undefined
- ? this.#run(repository, options)
- : this.#runWorkflow(repository, options, options.workflowId),
+ return await this.#trackOperation(
+ () =>
+ options.workflowId === undefined
+ ? this.#run(repository, options)
+ : this.#runWorkflow(repository, options, options.workflowId),
+ options.mock
+ ? undefined
+ : {
+ command: "scan",
+ repository,
+ options,
+ mode: options.mode ?? DEFAULT_SCAN_MODE,
+ },
);
}
@@ -831,8 +869,13 @@ export class CodexSecurity {
this.#dependencies.runWorkbench,
this.config.pythonPath,
);
- if (options.outputDir !== undefined)
+ const artifactRoots: string[] = [];
+ if (options.outputDir !== undefined) {
await workflow.protectArtifacts(options.outputDir);
+ artifactRoots.push(
+ await canonicalConfigPath(expandHome(options.outputDir)),
+ );
+ }
const state = await workflow.bind({
repositoryPath: local.repository,
scanRequestDigest: workflowDigest({
@@ -855,6 +898,14 @@ export class CodexSecurity {
},
}),
});
+ if (state.scanId && state.scanDir) {
+ await workflow.protectArtifacts(state.scanDir);
+ artifactRoots.push(await canonicalConfigPath(expandHome(state.scanDir)));
+ }
+ await this.#operationTelemetry?.activatePersistence([
+ ...local.protectedRoots,
+ ...artifactRoots,
+ ]);
type ScanMetadata = Pick<
ScanResultOptions,
| "threadId"
@@ -865,7 +916,6 @@ export class CodexSecurity {
| "ownerSuggestionsError"
>;
if (state.scanId && state.scanDir) {
- await workflow.protectArtifacts(state.scanDir);
let metadata = state.stages.scan.result as ScanMetadata | undefined;
let completed = state.stages.scan.status === "completed";
if (!completed) {
@@ -892,7 +942,7 @@ export class CodexSecurity {
});
metadata ??= { threadId: "", turnResult: { status: "completed" } };
await workflow.complete("scan", metadata);
- return new ScanResult({
+ const result = new ScanResult({
...contract,
scanDir: state.scanDir,
...metadata,
@@ -903,6 +953,9 @@ export class CodexSecurity {
signal,
}),
});
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.reusedResult = true;
+ return result;
}
}
await workflow.begin("scan");
@@ -932,7 +985,11 @@ export class CodexSecurity {
}
public async validate(options: ValidationOptions): Promise<ValidationResult> {
- return await this.#trackOperation(() => this.#validate(options));
+ return await this.#trackOperation(() => this.#validate(options), {
+ command: "validate",
+ repository: options.repositoryPath,
+ options,
+ });
}
async #validate(options: ValidationOptions): Promise<ValidationResult> {
@@ -941,6 +998,8 @@ export class CodexSecurity {
...(options.signal === undefined ? [] : [options.signal]),
]);
let outputDir = "";
+ let tracker: ScanCostTracker | null = null;
+ let finalUsage: unknown;
let knowledgeBase: PreparedKnowledgeBase | undefined;
let preparedPrompt:
Awaited<ReturnType<typeof prepareFindingPrompt>> | undefined;
@@ -971,6 +1030,10 @@ export class CodexSecurity {
protectedRoots,
options.workflowId !== undefined,
);
+ if (options.workflowId === undefined)
+ await this.#operationTelemetry?.activatePersistence(
+ inputs.protectedRoots,
+ );
const temporaryRoot = await realpath(tmpdir());
requireOutputOutsideRepositories(
inputs.protectedRoots,
@@ -1185,6 +1248,12 @@ export class CodexSecurity {
if (saved !== null) {
let reusable: ValidationResult | undefined;
const cached = cachedValidationSchema.safeParse(saved);
+ if (cached.success) {
+ await this.#operationTelemetry?.activatePersistence(
+ inputs.protectedRoots,
+ cached.data.assessment.outputDir,
+ );
+ }
if (
cached.success &&
(inputs.outputDir === null ||
@@ -1228,7 +1297,11 @@ export class CodexSecurity {
"Repository changed during validation.",
);
}
- if (reusable !== undefined && (await canCache())) return reusable;
+ if (reusable !== undefined && (await canCache())) {
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.reusedResult = true;
+ return reusable;
+ }
}
}
checkpoint = {
@@ -1239,6 +1312,9 @@ export class CodexSecurity {
};
}
}
+ await this.#operationTelemetry?.activatePersistence(
+ inputs.protectedRoots,
+ );
outputDir = await prepareOutputDir(
inputs.outputDir ?? undefined,
basename(inputs.repository),
@@ -1289,12 +1365,22 @@ export class CodexSecurity {
`permissions.${VALIDATION_PERMISSION_PROFILE}=${inlineToml(validationPermissions)}`,
],
);
+ tracker = new ScanCostTracker({
+ codexHome: runtime.codexHome,
+ model: scanModelConfiguration(session.effectiveConfig).model,
+ repository: inputs.repository,
+ onMeasurement: (measurement) => {
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.measurement = measurement;
+ },
+ });
const thread = codex.startThread({
threadSource: CODEX_SECURITY_THREAD_SOURCES.validation,
workingDirectory: outputDir,
skipGitRepoCheck: true,
approvalPolicy: "never",
});
+ if (thread.id !== null) tracker.start(thread.id);
preparedPrompt = await prepareFindingPrompt(finding, (findingData) =>
[
validationInstructions,
@@ -1314,11 +1400,22 @@ export class CodexSecurity {
cyberAccessProgram: options.cyberAccessProgram,
outputSchema,
});
- const { status, finalResponse, threadId } = await readCodexTurn({
+ const { status, finalResponse, threadId, usage } = await readCodexTurn({
thread,
events,
- onEvent: () => throwIfAborted(signal, outputDir),
+ onEvent: (event) => {
+ if (event.type === "turn.completed")
+ finalUsage = event["usage"] ?? null;
+ if (
+ event.type === "thread.started" &&
+ typeof event["thread_id"] === "string"
+ ) {
+ tracker?.start(event["thread_id"]);
+ }
+ throwIfAborted(signal, outputDir);
+ },
});
+ finalUsage = usage;
throwIfAborted(signal, outputDir);
if (status !== "completed") {
throw new CodexSecurityError("Finding validation did not complete.");
@@ -1369,6 +1466,9 @@ export class CodexSecurity {
throwIfAborted(signal, outputDir);
throw error;
} finally {
+ await tracker?.stop(finalUsage).catch(() => {
+ // Optional usage collection must not change validation outcomes.
+ });
await preparedPrompt?.[Symbol.asyncDispose]();
try {
await knowledgeBase?.cleanup();
@@ -1379,7 +1479,11 @@ export class CodexSecurity {
}
public async patch(options: PatchOptions): Promise<PatchResult> {
- return await this.#trackOperation(() => this.#patch(options));
+ return await this.#trackOperation(() => this.#patch(options), {
+ command: "patch",
+ repository: options.repositoryPath,
+ options,
+ });
}
async #patch(options: PatchOptions): Promise<PatchResult> {
@@ -1389,6 +1493,7 @@ export class CodexSecurity {
]);
let repository = "";
let tracker: ScanCostTracker | null = null;
+ let finalUsage: unknown;
let preparedPrompt:
Awaited<ReturnType<typeof prepareFindingPrompt>> | undefined;
const reportTrackingError = (error: unknown): void => {
@@ -1461,6 +1566,11 @@ export class CodexSecurity {
codexHome: session.runtime.codexHome,
model,
repository,
+ onMeasurement: (measurement) => {
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.measurement = measurement;
+ notifyObserver(options, "onMeasurement")(measurement);
+ },
onActivity:
options.onActivity === undefined
? undefined
@@ -1513,6 +1623,8 @@ export class CodexSecurity {
thread,
events,
onEvent: (event) => {
+ if (event.type === "turn.completed")
+ finalUsage = event["usage"] ?? null;
throwIfPatchAborted(signal, repository);
if (
event.type === "thread.started" &&
@@ -1530,6 +1642,7 @@ export class CodexSecurity {
reconnectDetails(message),
),
});
+ finalUsage = turn.usage;
throwIfPatchAborted(signal, repository);
if (turn.status !== "completed") {
throw new CodexSecurityError("Finding patch did not complete.");
@@ -1564,7 +1677,7 @@ export class CodexSecurity {
const activeTracker = tracker;
tracker = null;
if (activeTracker !== null) {
- await activeTracker.stop().catch(reportTrackingError);
+ await activeTracker.stop(finalUsage).catch(reportTrackingError);
}
}
}
@@ -1682,8 +1795,9 @@ export class CodexSecurity {
repository: string,
options: SecurityPolicyOptions = {},
): Promise<SecurityPolicyDraft> {
- return await this.#trackOperation(() =>
- this.#generatePolicy(repository, options),
+ return await this.#trackOperation(
+ () => this.#generatePolicy(repository, options),
+ { command: "policy", repository, options },
).catch(rethrowPolicyOutputError);
}
@@ -1717,6 +1831,7 @@ export class CodexSecurity {
let knowledgeBase: PreparedKnowledgeBase | null = null;
let accumulatedCost: ScanCost | null = null;
let completeCost = true;
+ const stageMeasurements = new Map<string, Readonly<ScanUsageMeasurement>>();
const warn = (message: string): void =>
notifyObserver(options, "onWarning")(message);
try {
@@ -1726,6 +1841,9 @@ export class CodexSecurity {
signal,
);
const inputs = await this.#validatePolicyInputs(target, options, signal);
+ await this.#operationTelemetry?.activatePersistence(
+ inputs.protectedRoots,
+ );
const snapshot = await readSecurityPolicySnapshot(
target,
signal,
@@ -1876,7 +1994,7 @@ export class CodexSecurity {
total.estimatedUsd > options.maxCostUsd
) {
budgetController.abort(
- new CodexSecurityError(
+ new PolicyCostLimitExceededError(
`Security-policy generation exceeded its $${options.maxCostUsd} cost limit; partial output remains at ${outputDir}.`,
),
);
@@ -1887,6 +2005,7 @@ export class CodexSecurity {
stage: SecurityPolicyStage,
prompt: string,
): Promise<SecurityPolicyStageResult> => {
+ const measurementId = randomUUID();
const thread = codex.startThread({
workingDirectory: outputDir,
additionalDirectories: policyReadRoots,
@@ -1901,6 +2020,14 @@ export class CodexSecurity {
repository: target.repository,
scanDirectory: outputDir,
maxCostUsd: options.maxCostUsd,
+ onMeasurement: (measurement) => {
+ stageMeasurements.set(measurementId, measurement);
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.measurement = combineMeasurements(
+ [...stageMeasurements.values()],
+ model.model,
+ );
+ },
onCost:
options.onCost === undefined && options.maxCostUsd === undefined
? undefined
@@ -2043,6 +2170,7 @@ export class CodexSecurity {
let maxCostUsd = options.maxCostUsd;
let latestCost: Readonly<ScanCost> | null = null;
let latestCostComplete = false;
+ let latestMeasurement: Readonly<ScanUsageMeasurement> | null = null;
let notifiedLimit: number | undefined;
let scanDir = "";
let targetPathsFile: string | null = null;
@@ -2054,7 +2182,7 @@ export class CodexSecurity {
const customValidation = {
status: "pending" as "pending" | "running" | "complete",
};
- let completionCost: ScanCost | null = null;
+ let completionCost: ScanCost | ReturnType<typeof measuredScanCost> = null;
let validationThreadId: string | undefined;
let nativeTurnFailure: string | undefined;
let scanTurnStatus: "in_progress" | "completed" | "failed" | null = null;
@@ -2298,6 +2426,7 @@ export class CodexSecurity {
const workerSnapshot: JsonObject = {
...workerRuntimeConfig,
responses_api_metadata: codexSecurityRequestContext(effectiveConfig, {
+ ...this.#operationTelemetry?.context,
surface: this.#surface,
command: "scan",
pluginVersion: runtime.plugin.version,
@@ -2469,6 +2598,10 @@ export class CodexSecurity {
};
const reportedInaccessibleSessionLogs = new Set<string>();
const warnTrackingError = (error: unknown): void => {
+ if (error instanceof AggregateError) {
+ for (const cause of error.errors) warnTrackingError(cause);
+ return;
+ }
if (
isRecord(error) &&
(error["code"] === "EACCES" || error["code"] === "EPERM") &&
@@ -2488,147 +2621,6 @@ export class CodexSecurity {
if (options.maxCostUsd !== undefined) costAbortController.abort(error);
else warnTrackingError(error);
};
- const tracker = new ScanCostTracker({
- onObservationError: warnTrackingError,
- codexHome: runtime.codexHome,
- model,
- repository: repo,
- scanDirectory: scanDir,
- maxCostUsd: options.maxCostUsd,
- readBudgetUsage:
- options.maxCostUsd === undefined
- ? undefined
- : (threadId) =>
- readScanBudgetUsage(
- (args) =>
- workbench(
- {
- ...workbenchOptions,
- signal: signal.aborted ? undefined : signal,
- },
- args,
- ),
- scanId,
- threadId,
- validationThreadId,
- directDeepScan,
- ),
- onUsage:
- options.onUsage === undefined
- ? undefined
- : (usage) => notifyObserver(options, "onUsage")(usage),
- onUsageObservation:
- options.onUsageObservation === undefined
- ? undefined
- : notifyObserver(options, "onUsageObservation"),
- onActivity:
- options.onActivity === undefined
- ? undefined
- : (activity) => notifyObserver(options, "onActivity")(activity),
- onWorkerEvent:
- options.onWorkerEvent === undefined
- ? undefined
- : (event) => notifyObserver(options, "onWorkerEvent")(event),
- onSessionEvent:
- options.onSessionEvent === undefined
- ? undefined
- : (event) => notifyObserver(options, "onSessionEvent")(event),
- onProgress:
- options.onProgress === undefined
- ? undefined
- : (progress, source) =>
- reportProgress(
- {
- ...progress,
- // Only worker counts use the last accepted parent phase.
- phase:
- mode === "deep" ||
- (source !== undefined &&
- (source.reconciled !== true || !source.worker))
- ? progress.phase
- : latestPhase,
- },
- source,
- ),
- onCost:
- options.onCost === undefined && options.maxCostUsd === undefined
- ? undefined
- : (cost, complete) => {
- latestCost = cost;
- latestCostComplete = complete;
- if (complete)
- notifyObserver(options, "onCost")(cost, maxCostUsd);
- if (
- maxCostUsd !== undefined &&
- cost.estimatedUsd > maxCostUsd
- ) {
- costAbortController.abort(
- new ScanCostLimitExceededError(maxCostUsd, cost, scanDir),
- );
- return;
- }
- const request = options.onBudgetApproaching;
- if (
- request === undefined ||
- maxCostUsd === undefined ||
- budgetSignal.aborted ||
- notifiedLimit === maxCostUsd ||
- cost.estimatedUsd < maxCostUsd * 0.8
- )
- return;
- const limit = maxCostUsd;
- notifiedLimit = limit;
- void Promise.resolve()
- .then(async () => {
- if (budgetSignal.aborted) return;
- const next = await request({
- maxCostUsd: limit,
- cost,
- signal: budgetSignal,
- });
- if (
- next === undefined ||
- budgetSignal.aborted ||
- activeScan === null
- )
- return;
- if (
- !Number.isFinite(next) ||
- next <= Math.max(limit, latestCost!.estimatedUsd)
- ) {
- throw new CodexSecurityError(
- "The new cost limit must exceed the current limit and estimated cost.",
- );
- }
- await workbench(
- { ...activeScan.options, signal: budgetSignal },
- workbenchArgs("set-scan-cost-limit", {
- scanId: activeScan.id,
- maxCostUsd: String(next),
- }),
- );
- if (budgetSignal.aborted) return;
- maxCostUsd = next;
- if (latestCostComplete)
- notifyObserver(options, "onCost")(
- latestCost!,
- maxCostUsd,
- );
- })
- .catch((error: unknown) => {
- if (!budgetSignal.aborted) {
- notifyObserver(
- options,
- "onWarning",
- )(
- `Could not increase scan cost limit: ${errorMessage(error)}`,
- );
- }
- });
- },
- onError: reportTrackingError,
- });
- costTracker = tracker;
// Saved launches reload the native file; preflight uses resolved values.
const profileName = effectiveConfig["profile"];
const inlineProfiles = effectiveConfig["profiles"];
@@ -2934,6 +2926,165 @@ export class CodexSecurity {
);
}
const scanId = registeredScanId;
+ const tracker = new ScanCostTracker({
+ codexHome: runtime.codexHome,
+ model,
+ repository: repo,
+ scanDirectory: scanDir,
+ ...(mode === "deep"
+ ? {
+ workerReceipts: {
+ directory: join(
+ await canonicalConfigPath(join(stateDirectory, "codex-home")),
+ "worker-usage",
+ scanId,
+ ),
+ scanId,
+ },
+ }
+ : {}),
+ onObservationError: warnTrackingError,
+ readBudgetUsage:
+ options.maxCostUsd === undefined
+ ? undefined
+ : (threadId) =>
+ readScanBudgetUsage(
+ (args) =>
+ workbench(
+ {
+ ...workbenchOptions,
+ signal: signal.aborted ? undefined : signal,
+ },
+ args,
+ ),
+ scanId,
+ threadId,
+ validationThreadId,
+ directDeepScan,
+ ),
+ maxCostUsd: options.maxCostUsd,
+ onMeasurement: (measurement) => {
+ latestMeasurement = measurement;
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.measurement = measurement;
+ notifyObserver(options, "onMeasurement")(measurement);
+ },
+ onUsage:
+ options.onUsage === undefined
+ ? undefined
+ : (usage) => notifyObserver(options, "onUsage")(usage),
+ onUsageObservation:
+ options.onUsageObservation === undefined
+ ? undefined
+ : notifyObserver(options, "onUsageObservation"),
+ onActivity:
+ options.onActivity === undefined
+ ? undefined
+ : (activity) => notifyObserver(options, "onActivity")(activity),
+ onWorkerEvent:
+ options.onWorkerEvent === undefined
+ ? undefined
+ : (event) => notifyObserver(options, "onWorkerEvent")(event),
+ onSessionEvent:
+ options.onSessionEvent === undefined
+ ? undefined
+ : (event) => notifyObserver(options, "onSessionEvent")(event),
+ onProgress:
+ options.onProgress === undefined
+ ? undefined
+ : (progress, source) =>
+ reportProgress(
+ {
+ ...progress,
+ // Only worker counts use the last accepted parent phase.
+ phase:
+ mode === "deep" ||
+ (source !== undefined &&
+ (source.reconciled !== true || !source.worker))
+ ? progress.phase
+ : latestPhase,
+ },
+ source,
+ ),
+ onCost:
+ options.onCost === undefined && options.maxCostUsd === undefined
+ ? undefined
+ : (cost, complete) => {
+ latestCost = cost;
+ latestCostComplete = complete;
+ if (complete)
+ notifyObserver(options, "onCost")(cost, maxCostUsd);
+ if (
+ maxCostUsd !== undefined &&
+ cost.estimatedUsd > maxCostUsd
+ ) {
+ costAbortController.abort(
+ new ScanCostLimitExceededError(maxCostUsd, cost, scanDir),
+ );
+ return;
+ }
+ const request = options.onBudgetApproaching;
+ if (
+ request === undefined ||
+ maxCostUsd === undefined ||
+ budgetSignal.aborted ||
+ notifiedLimit === maxCostUsd ||
+ cost.estimatedUsd < maxCostUsd * 0.8
+ )
+ return;
+ const limit = maxCostUsd;
+ notifiedLimit = limit;
+ void Promise.resolve()
+ .then(async () => {
+ if (budgetSignal.aborted) return;
+ const next = await request({
+ maxCostUsd: limit,
+ cost,
+ signal: budgetSignal,
+ });
+ if (
+ next === undefined ||
+ budgetSignal.aborted ||
+ activeScan === null
+ )
+ return;
+ if (
+ !Number.isFinite(next) ||
+ next <= Math.max(limit, latestCost!.estimatedUsd)
+ ) {
+ throw new CodexSecurityError(
+ "The new cost limit must exceed the current limit and estimated cost.",
+ );
+ }
+ await workbench(
+ { ...activeScan.options, signal: budgetSignal },
+ workbenchArgs("set-scan-cost-limit", {
+ scanId: activeScan.id,
+ maxCostUsd: String(next),
+ }),
+ );
+ if (budgetSignal.aborted) return;
+ maxCostUsd = next;
+ if (latestCostComplete)
+ notifyObserver(options, "onCost")(
+ latestCost!,
+ maxCostUsd,
+ );
+ })
+ .catch((error: unknown) => {
+ if (!budgetSignal.aborted) {
+ notifyObserver(
+ options,
+ "onWarning",
+ )(
+ `Could not increase scan cost limit: ${errorMessage(error)}`,
+ );
+ }
+ });
+ },
+ onError: reportTrackingError,
+ });
+ costTracker = tracker;
const targetRevision =
registeredRevision === "unversioned" ? null : registeredRevision;
const registeredFileCount = registration["scopeFileCount"];
@@ -2955,6 +3106,7 @@ export class CodexSecurity {
});
}
activeScan = { id: scanId, options: workbenchOptions };
+ await this.#operationTelemetry?.bindScan(scanId);
if (options.resumeScanId === undefined)
notifyScanLifecycle(options, registration);
notifyObserver(
@@ -3338,8 +3490,11 @@ export class CodexSecurity {
!directDeepScan &&
!this.#dependencies.hostedScan &&
!signal.aborted
- )
+ ) {
nativeTurnFailure = message;
+ if (this.#operationTelemetry !== null)
+ this.#operationTelemetry.nativeTurnFailed = true;
+ }
},
onThreadStarted: async (threadId) => {
if (resumeThreadId !== undefined && threadId !== resumeThreadId) {
@@ -3449,7 +3604,11 @@ export class CodexSecurity {
throw error;
}
reportTrackingError(error);
- return { usage, cost: estimateScanCost(model, usage) };
+ return {
+ usage,
+ cost: estimateScanCost(model, usage),
+ measurement: latestMeasurement,
+ };
});
throwIfAborted(signal, scanDir);
if (maxCostUsd !== undefined && snapshot.cost === null) {
@@ -3458,7 +3617,8 @@ export class CodexSecurity {
"Could not verify the requested scan cost limit because scan-owned token usage is incomplete.",
);
}
- completionCost = snapshot.cost;
+ completionCost =
+ measuredScanCost(snapshot.measurement) ?? snapshot.cost;
let preparation: JsonObject;
try {
preparation = await workbench(
@@ -3755,24 +3915,43 @@ export class CodexSecurity {
signal.aborted && callerCancellation === undefined
? signal.reason
: error;
- const snapshot = await costTracker?.stop().catch(() => null);
+ // Hosted terminal failures can carry the only receipt for consumed tokens.
+ const measuredExecution =
+ error instanceof ScanExecutionError && error.receiptMatchesRequest
+ ? error.result
+ : undefined;
+ if (
+ measuredExecution?.usage !== undefined &&
+ measuredExecution.sessionId !== undefined
+ ) {
+ costTracker?.start(measuredExecution.sessionId);
+ costTracker?.recordUsage(
+ measuredExecution.usage,
+ measuredExecution.sessionId,
+ );
+ }
+ const snapshot = await costTracker
+ ?.stop(measuredExecution?.usage)
+ .catch(() => null);
if (artifactRestorationFailure !== null) throw artifactRestorationFailure;
const terminalTurnStatus = terminalScanTurnStatus();
+ const verifiedCost = snapshot?.measurement.cost;
if (
failure instanceof ScanCostLimitExceededError &&
- snapshot?.cost &&
- snapshot.cost.estimatedUsd > failure.cost.estimatedUsd
+ verifiedCost &&
+ verifiedCost.estimatedUsd > failure.cost.estimatedUsd
) {
failure = new ScanCostLimitExceededError(
failure.maxCostUsd,
- snapshot.cost,
+ verifiedCost,
scanDir,
);
}
if (
failure instanceof ScanCostLimitExceededError &&
- snapshot?.cost &&
- snapshot.cost.estimatedUsd > failure.maxCostUsd &&
+ snapshot &&
+ verifiedCost &&
+ verifiedCost.estimatedUsd > failure.maxCostUsd &&
(customValidation.status !== "running" ||
validationThreadId !== undefined) &&
budgetRecovery !== null &&
@@ -3788,7 +3967,9 @@ export class CodexSecurity {
"--scan-id",
activeScan.id,
"--cost-json",
- JSON.stringify(snapshot.cost),
+ JSON.stringify(
+ measuredScanCost(snapshot.measurement) ?? verifiedCost,
+ ),
`--message=${failure.message}`,
],
);
@@ -3890,6 +4071,9 @@ export class CodexSecurity {
}).catch(() => undefined);
}
try {
+ const measured =
+ measuredScanCost(snapshot?.measurement ?? latestMeasurement) ??
+ snapshot?.cost;
await stopRegisteredScan(
workbench,
activeScan,
@@ -3900,9 +4084,10 @@ export class CodexSecurity {
: priorTurnFailure === undefined &&
explicitlyCanceled(callerCancellation),
priorTurnFailure ?? failure,
- failure instanceof ScanCostLimitExceededError
- ? failure.cost
- : snapshot?.cost,
+ measured ??
+ (failure instanceof ScanCostLimitExceededError
+ ? failure.cost
+ : snapshot?.cost),
);
activeScan = null;
} catch {}
@@ -4136,22 +4321,144 @@ export class CodexSecurity {
this.#runtimeCredentialSource = source;
}
- async #trackOperation<T>(operation: () => Promise<T>): Promise<T> {
+ async #trackOperation<T>(
+ operation: () => Promise<T>,
+ telemetry?: {
+ command: OperationTelemetryEvent["command"];
+ repository: string;
+ options: ScanOptions;
+ mode?: ScanMode;
+ },
+ ): Promise<T> {
this.#requireOpen();
if (this.#activeOperation !== null) {
throw new CodexSecurityError(
"A Codex Security operation is already in progress.",
);
}
+ const callerSignal = telemetry?.options.signal
+ ? AbortSignal.any([
+ this.#abortController.signal,
+ telemetry.options.signal,
+ ])
+ : this.#abortController.signal;
const activeOperation = Promise.withResolvers<void>();
this.#activeOperation = activeOperation.promise;
- try {
- return await operation();
- } finally {
+ let journal: OperationTelemetry | null = null;
+ let journalStarted: Promise<void> | null = null;
+ let invoked = false;
+ const release = () => {
if (this.#activeOperation === activeOperation.promise) {
+ this.#operationTelemetry = null;
+ this.#operationTelemetryStart = null;
this.#activeOperation = null;
}
activeOperation.resolve();
+ };
+ try {
+ if (telemetry !== undefined) {
+ try {
+ journal = (
+ this.#dependencies.createOperationTelemetry ??
+ ((options) => new OperationTelemetry(options))
+ )({
+ directory: codexSecurityStateDirectory(
+ this.#dependencies.environment,
+ ),
+ protectedRepository: expandHome(
+ telemetry.repository,
+ this.#dependencies.environment,
+ ),
+ protectedOutput:
+ telemetry.options.outputDir === undefined
+ ? undefined
+ : expandHome(telemetry.options.outputDir),
+ command: telemetry.command,
+ deferPersistence:
+ telemetry.command === "policy" ||
+ (telemetry.command === "scan" &&
+ telemetry.options.workflowId !== undefined) ||
+ (telemetry.command === "validate" &&
+ (telemetry.options.workflowId !== undefined ||
+ Boolean(telemetry.options.knowledgeBasePaths?.length))),
+ surface: this.#surface,
+ mode: telemetry.mode,
+ resumeScanId: telemetry.options.resumeScanId,
+ context: telemetry.options.telemetryContext,
+ onEvent: notifyObserver(telemetry.options, "onTelemetry"),
+ onError: (error) =>
+ notifyObserver(
+ telemetry.options,
+ "onWarning",
+ )(`Could not save operation telemetry: ${errorMessage(error)}`),
+ });
+ this.#operationTelemetry = journal;
+ journalStarted =
+ journal?.start().catch((error: unknown) => {
+ notifyObserver(
+ telemetry.options,
+ "onWarning",
+ )(`Could not start operation telemetry: ${errorMessage(error)}`);
+ }) ?? null;
+ this.#operationTelemetryStart = journalStarted;
+ } catch (error) {
+ notifyObserver(
+ telemetry.options,
+ "onWarning",
+ )(`Could not start operation telemetry: ${errorMessage(error)}`);
+ }
+ }
+ // Preserve synchronous serialization and operation-slot registration.
+ const pending = operation();
+ invoked = true;
+ const result = await pending;
+ await journalStarted;
+ await journal?.finish(
+ "completed",
+ result instanceof ScanResult
+ ? {
+ findingCount: result.findings.findings.length,
+ artifactComplete: result.manifest.scan.status === "completed",
+ }
+ : telemetry?.command === "validate"
+ ? {
+ validationDisposition: (result as ValidationResult).disposition,
+ }
+ : {},
+ );
+ return result;
+ } catch (error) {
+ const status = journal?.nativeTurnFailed
+ ? "failed"
+ : hostedScanFailureStatus(error, callerSignal);
+ const canceled = status === "canceled";
+ if (!invoked) release();
+ await journalStarted;
+ await journal?.finish(
+ status === "acceptance_unknown"
+ ? "unresolved"
+ : canceled
+ ? "canceled"
+ : "failed",
+ {
+ failureCategory: canceled
+ ? "canceled"
+ : error instanceof ScanCostLimitExceededError ||
+ error instanceof PolicyCostLimitExceededError
+ ? "budget"
+ : error instanceof AuthenticationRequiredError
+ ? "authentication"
+ : error instanceof ConfigurationError
+ ? "configuration"
+ : error instanceof InvalidTargetError ||
+ error instanceof OutputDirectoryError
+ ? "input"
+ : "execution",
+ },
+ );
+ throw error;
+ } finally {
+ release();
}
}
@@ -4168,6 +4475,20 @@ export class CodexSecurity {
environment: ProcessEnvironment;
codexOptions: CodexOptions & { nativeProfile?: string };
}> {
+ const requestContext = codexSecurityRequestContext(
+ config ?? session.sessionConfig,
+ {
+ surface: this.#surface,
+ command,
+ pluginVersion: session.runtime.plugin.version,
+ mode,
+ ...this.#operationTelemetry?.context,
+ },
+ );
+ this.#operationTelemetry?.describe({
+ pluginVersion: session.runtime.plugin.version,
+ providerFamily: requestContext.metadata["codex_security_provider"],
+ });
const hosted = this.#dependencies.hostedScan;
if (hosted !== undefined) {
const environment = {
@@ -4210,6 +4531,7 @@ export class CodexSecurity {
stateDirectory: runtimePaths["CODEX_SECURITY_STATE_DIR"]!,
outputDirectory: runtimePaths["CODEX_SECURITY_SCAN_DIR"]!,
environment,
+ requestMetadata: requestContext.metadata,
},
};
// A transport failure is terminal; only the host can reconcile
@@ -4231,13 +4553,16 @@ export class CodexSecurity {
});
}
if (result.requestId !== request.requestId)
- throw new ScanExecutionError({
- ...result,
- requestId: request.requestId,
- status: "acceptance_unknown",
- message:
- "Execution response does not match the active request.",
- });
+ throw new ScanExecutionError(
+ {
+ ...result,
+ status: "acceptance_unknown",
+ message:
+ "Execution response does not match the active request.",
+ },
+ undefined,
+ { receiptMatchesRequest: false },
+ );
if (result.status !== "completed")
throw new ScanExecutionError(result);
id = result.sessionId!;
@@ -4313,15 +4638,6 @@ export class CodexSecurity {
...configOverrides,
];
}
- const requestContext = codexSecurityRequestContext(
- config ?? sessionConfig,
- {
- surface: this.#surface,
- command,
- pluginVersion: runtime.plugin.version,
- mode,
- },
- );
delete sdkCodexConfig["responses_api_metadata"];
const configuredCodexPath = environmentValue(
this.#dependencies.environment,
@@ -4385,6 +4701,8 @@ export class CodexSecurity {
temporaryRoot?: string,
deepScan = false,
): Promise<PreparedSession> {
+ if (this.#operationTelemetryStart !== null)
+ await this.#operationTelemetryStart;
if (this.#dependencies.hostedScan !== undefined) {
// Hosted scans use only the explicitly selected bundle and configuration.
// No local auth, Codex subprocess, provider profile, or ambient config.
@@ -6259,7 +6577,7 @@ async function stopRegisteredScan(
options: ScanOptions,
canceled: boolean,
error: unknown,
- cost?: Readonly<ScanCost> | null,
+ cost?: Readonly<ScanCost> | ReturnType<typeof measuredScanCost>,
): Promise<void> {
const cleanupOptions = { ...activeScan.options, signal: undefined };
const costArgs = cost ? ["--cost-json", JSON.stringify(cost)] : [];
@@ -6660,6 +6978,12 @@ export function scanPreflightCodexConfig(config: JsonObject): JsonObject {
};
const executionConfig = (source: JsonObject): JsonObject => {
const result: JsonObject = {};
+ // OTel exporters can contain credentials. Native runtime settings retain
+ // them; model-readable preflight files and saved recipes must not.
+ for (const key of ["analytics", "responses_api_metadata"]) {
+ if (Object.hasOwn(source, key))
+ result[key] = structuredClone(source[key]!);
+ }
if (typeof source["daybreak"] === "boolean") {
result["daybreak"] = source["daybreak"];
}
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index 4bdc6b970..b3d239c88 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -1,10 +1,12 @@
#!/usr/bin/env node
import { classificationRunsSchema } from "./severity-review.js";
import { severityRubricSchema } from "./severity-rubric.js";
+import { explicitlyCanceled } from "./scan-executor.js";
import { workbenchArgs } from "./workbench-arguments.js";
import { listenForAbort } from "./cli-signals.js";
import { appServerCyberAccessProgram } from "./cli-daybreak.js";
import {
+ providerPreflightCommand,
restoreProviderProfile,
withCodexPreflightLock,
} from "./provider-profile.js";
@@ -183,6 +185,7 @@ import {
} from "./bulk-scan-discovery.js";
import {
DEFAULT_CODEX_CONFIG,
+ deepMerge,
EXTERNAL_CODEX_PROVIDERS,
isExternalModelProvider,
mergeCodexOverrides,
@@ -320,6 +323,10 @@ import {
type ScanMatchingBatch,
} from "./scan-comparison.js";
import { scanActivitiesFromEvent } from "./scan-activity.js";
+import {
+ OperationTelemetry,
+ type OperationTelemetryEvent,
+} from "./operation-telemetry.js";
import { codexSecurityRequestContext } from "./request-metadata.js";
import {
CODEX_SECURITY_THREAD_SOURCES,
@@ -1213,6 +1220,7 @@ interface SkillCommandOutput {
readonly modelProvider?: string;
readonly codexOverrides?: JsonObject;
readonly command: "validate" | "patch" | "verify-fix";
+ readonly telemetryCommand?: OperationTelemetryEvent["command"];
readonly stdout: Writable;
readonly stderr: Writable;
readonly appServer?: {
@@ -1565,6 +1573,85 @@ export async function runCodexSkillCommand(
command: CodexCommand = resolveCodexCommand(),
processEnvironment: NodeJS.ProcessEnv = process.env,
input?: string,
+): Promise<number> {
+ let journal: OperationTelemetry | null = null;
+ if (output !== undefined) {
+ try {
+ journal = new OperationTelemetry({
+ directory: codexSecurityStateDirectory(processEnvironment),
+ protectedRepository: output.directory ?? output.appServer?.directory,
+ command: output.telemetryCommand ?? output.command,
+ surface: "cli",
+ onError: (error) => {
+ void writeCliOutput(
+ output.stderr,
+ `codex-security: Could not save operation telemetry: ${errorMessage(error)}\n`,
+ ).catch(() => {});
+ },
+ });
+ await journal.start();
+ args = [
+ ...args,
+ ...Object.entries({
+ codex_security_operation_id: journal.operationId,
+ codex_security_attempt_id: journal.attemptId,
+ }).flatMap(([key, value]) => [
+ "--config",
+ `responses_api_metadata.${key}=${inlineToml(value)}`,
+ ]),
+ ];
+ } catch (error) {
+ void writeCliOutput(
+ output.stderr,
+ `codex-security: Could not start operation telemetry: ${errorMessage(error)}\n`,
+ ).catch(() => {});
+ }
+ }
+ try {
+ const status = await runCodexSkillProcess(
+ args,
+ output,
+ command,
+ processEnvironment,
+ input,
+ );
+ const canceled =
+ (status === 130 || status === 143) &&
+ (!output?.signal?.aborted || explicitlyCanceled(output.signal));
+ await journal?.finish(
+ status === 0 ? "completed" : canceled ? "canceled" : "failed",
+ status === 0
+ ? {}
+ : { failureCategory: canceled ? "canceled" : "execution" },
+ );
+ return status;
+ } catch (error) {
+ const signal = output?.signal;
+ const canceled =
+ explicitlyCanceled(signal) &&
+ (Object.is(error, signal?.reason) ||
+ (error instanceof Error && error.name === "AbortError"));
+ await journal?.finish(canceled ? "canceled" : "failed", {
+ failureCategory: canceled
+ ? "canceled"
+ : error instanceof AuthenticationRequiredError
+ ? "authentication"
+ : error instanceof ConfigurationError
+ ? "configuration"
+ : error instanceof InvalidTargetError
+ ? "input"
+ : "execution",
+ });
+ throw error;
+ }
+}
+
+async function runCodexSkillProcess(
+ args: readonly string[],
+ output: SkillCommandOutput | undefined,
+ command: CodexCommand,
+ processEnvironment: NodeJS.ProcessEnv,
+ input?: string,
): Promise<number> {
let releaseCredentialHome: (() => Promise<void>) | undefined;
try {
@@ -1659,7 +1746,13 @@ export async function runCodexSkillCommand(
output.signal?.throwIfAborted();
if (
!credentialsAvailable &&
- !(await accountStatus(command, selected, output.signal)).authenticated
+ !(
+ await accountStatus(
+ await providerPreflightCommand(command, resolved.config),
+ selected,
+ output.signal,
+ )
+ ).authenticated
) {
throw new AuthenticationRequiredError(NO_CREDENTIALS_MESSAGE);
}
@@ -1678,7 +1771,7 @@ export async function runCodexSkillCommand(
try {
args = [
...args,
- ...(await skillDaybreakConfigOverrides(
+ ...(await skillStartupConfigOverrides(
args,
command,
selected,
@@ -1924,9 +2017,9 @@ export async function runCodexSkillCommand(
/**
* Stored auth switches homes. Native origins preserve ambient settings at
- * app-server startup, where model discovery gates cannot be set per thread.
+ * app-server startup, including telemetry controls and model discovery gates.
*/
-async function skillDaybreakConfigOverrides(
+async function skillStartupConfigOverrides(
args: readonly string[],
command: CodexCommand,
environment: NodeJS.ProcessEnv,
@@ -1948,7 +2041,15 @@ async function skillDaybreakConfigOverrides(
ambientFeatures[key],
]),
];
- if (settings.every(([, value]) => value === undefined)) return [];
+ // App-server has no private profile-file option. Keep inherited exporter
+ // credentials in their native home rather than exposing them in arguments or
+ // temporarily changing shared settings while other scans are running.
+ const telemetryKeys = ["analytics", "responses_api_metadata"] as const;
+ if (
+ settings.every(([, value]) => value === undefined) &&
+ telemetryKeys.every((key) => ambientConfig[key] === undefined)
+ )
+ return [];
const nativeEnvironment = Object.fromEntries(
Object.entries(environment).filter(
(entry): entry is [string, string] => entry[1] !== undefined,
@@ -1963,25 +2064,43 @@ async function skillDaybreakConfigOverrides(
),
).href
);
- const response = (await withCodexPreflightLock(
- nativeEnvironment,
- signal,
- () =>
+ // A private user-file layer applies consent before native startup without
+ // sharing it across scans or overriding native project/CLI precedence.
+ const preflightHome = await mkdtemp(
+ join(configuredCodexHome(environment), ".startup-"),
+ );
+ let response: JsonObject;
+ try {
+ const preflightConfig = await readCodexHomeConfig(environment);
+ for (const key of telemetryKeys) {
+ const value = ambientConfig[key];
+ if (value === undefined) delete preflightConfig[key];
+ else preflightConfig[key] = value;
+ }
+ await writeCodexConfig(join(preflightHome, "config.toml"), preflightConfig);
+ const preflightEnvironment = {
+ ...nativeEnvironment,
+ CODEX_HOME: preflightHome,
+ };
+ response = (await withCodexPreflightLock(preflightEnvironment, signal, () =>
native.readDeepScanRuntimeConfigWithOrigins({
codexPath: command.command,
appServerArgs: args,
cwd: directory,
configOverrides: [],
- env: nativeEnvironment,
+ env: preflightEnvironment,
signal,
context: "helper",
}),
- )) as JsonObject;
+ )) as JsonObject;
+ } finally {
+ await rm(preflightHome, { recursive: true, force: true });
+ }
const origins = response["origins"];
const layers = response["layers"];
const malformed = () =>
new CodexSecurityError(
- "Codex did not return configuration origins for Daybreak settings.",
+ "Codex did not return configuration origins for inherited startup settings.",
);
if (!isJsonObject(origins) || !Array.isArray(layers)) throw malformed();
const userLayer = layers.findIndex((layer) => {
@@ -2010,6 +2129,26 @@ async function skillDaybreakConfigOverrides(
}
overrides.push("--config", `${key}=${inlineToml(value)}`);
}
+ for (const key of telemetryKeys) {
+ const value = ambientConfig[key];
+ if (value === undefined) continue;
+ let inherited: JsonObject = { [key]: value };
+ // Native layers are already filtered for project trust and supported keys.
+ // Preserve their precedence and literal metadata keys as whole tables.
+ for (const layer of layers.slice(0, userLayer).reverse()) {
+ if (
+ !isJsonObject(layer) ||
+ layer["disabledReason"] != null ||
+ !isJsonObject(layer["config"])
+ )
+ continue;
+ const override = layer["config"][key];
+ if (override !== undefined) {
+ inherited = deepMerge(inherited, { [key]: override });
+ }
+ }
+ overrides.push("--config", `${key}=${inlineToml(inherited[key]!)}`);
+ }
return overrides;
}
@@ -6063,6 +6202,7 @@ export async function main(
cost:
(scan["cost"] as unknown as ScanCost | undefined) ??
null,
+ usage: scan["usage"] as JsonObject | undefined,
};
}
if (status !== "running" || scan["mode"] !== "deep")
@@ -6117,6 +6257,9 @@ export async function main(
return await security.run(recipe.repository!, {
...pickScanSettings(recipe),
knowledgeBaseSnapshot: prompts.knowledgeBaseSnapshot,
+ telemetryContext: prompts.telemetryContext,
+ onTelemetry: prompts.onTelemetry,
+ onMeasurement: prompts.onMeasurement,
resumeScanId: scan.scanId,
outputDir: scanDir,
safetyIdentifier: recipe.safetyIdentifier,
@@ -9421,6 +9564,7 @@ async function runSkill(
],
{
command: verify ? "verify-fix" : patch || assess ? "patch" : "validate",
+ ...(assess ? { telemetryCommand: "assess-patch-risk" as const } : {}),
signal: options.signal,
auth: options.auth ?? "auto",
directory,
@@ -9987,7 +10131,10 @@ async function executeScan(
let deepProgress: DeepScanProgress | null = null;
let deepConsolidating = false;
let runningCost: Readonly<ScanCost> | null = null;
+ let costUpdateCount = 0;
+ let usageUpdateCount = 0;
let runningUsage: Readonly<ScanTokenUsage> | null = null;
+ let runningCoverage: "complete" | "partial" | "unavailable" | null = null;
let usageFreshness: string | null = null;
let accountLimits: string | null = null;
let maxCostUsd = arguments_.maxCostUsd;
@@ -10261,9 +10408,12 @@ async function executeScan(
runningCost !== null
? formatScanCostTokens(runningCost)
: formatTokenUsage(runningUsage);
- if (tokens !== null) details.push(`Tokens: ${tokens}`);
+ const coverageNote = runningCoverage === "partial" ? " (partial)" : "";
+ if (tokens !== null) details.push(`Tokens: ${tokens}${coverageNote}`);
+ else if (runningCoverage === "unavailable")
+ details.push("Usage unavailable");
if (showCost && runningCost !== null) {
- details.push(`Cost: ${formatScanCost(runningCost)}`);
+ details.push(`Cost: ${formatScanCost(runningCost)}${coverageNote}`);
}
if (tokens !== null)
details.push(usageFreshness ?? USAGE_TIME_UNAVAILABLE);
@@ -10318,6 +10468,56 @@ async function executeScan(
archiveExisting: arguments_.archiveExisting,
parentScanId: arguments_.parentScanId,
expectedPluginVersion: arguments_.expectedPluginVersion,
+ onTelemetry: (event) =>
+ diagnostic("telemetry.operation", {
+ event_id: event.eventId,
+ operation_id: event.operationId,
+ attempt_id: event.attemptId,
+ type: event.type,
+ outcome: event.outcome,
+ duration_ms: event.durationMs,
+ failure_category: event.failureCategory,
+ usage_coverage: event.measurement?.coverage,
+ }),
+ onMeasurement: async (measurement) => {
+ const previous = runningCoverage;
+ runningCoverage = measurement.coverage;
+ runningUsage = measurement.usage;
+ runningCost = measurement.cost;
+ diagnostic("usage.observed", {
+ coverage: measurement.coverage,
+ observed_at: measurement.observedAt,
+ thread_count: measurement.threadCount,
+ missing_thread_count: measurement.missingThreadCount,
+ input_tokens: measurement.usage?.input_tokens,
+ output_tokens: measurement.usage?.output_tokens,
+ });
+ if (dashboard !== null) {
+ dashboard.setMeasurement(measurement);
+ } else if (measurement.coverage !== "complete") {
+ progress?.stopTimer();
+ if (previous !== measurement.coverage) {
+ progress?.stage(
+ measurement.coverage === "partial"
+ ? "Usage is partial; showing the observed subtotal."
+ : "Usage is unavailable.",
+ );
+ }
+ progress?.startTimer(runningMessage());
+ } else if (previous !== null && previous !== "complete") {
+ const priorUsageUpdateCount = usageUpdateCount;
+ const priorCostUpdateCount = costUpdateCount;
+ // A recovered coverage label can change without a legacy totals update.
+ await Promise.resolve();
+ if (
+ usageUpdateCount !== priorUsageUpdateCount ||
+ costUpdateCount !== priorCostUpdateCount
+ )
+ return;
+ progress?.stopTimer();
+ progress?.startTimer(runningMessage());
+ }
+ },
onUsageObservation: async (observation) => {
if (dashboard !== null) {
dashboard.setUsageObservation(observation);
@@ -10335,20 +10535,22 @@ async function executeScan(
}
},
onUsage: async (usage) => {
+ usageUpdateCount += 1;
runningUsage = usage;
if (dashboard !== null) {
dashboard.setUsage(usage);
return;
}
- const priorCost = runningCost;
+ const priorCostUpdateCount = costUpdateCount;
// The tracker queues usage before cost; let the paired cost update render once.
await Promise.resolve();
- if (runningCost !== priorCost) return;
+ if (costUpdateCount !== priorCostUpdateCount) return;
progress?.stopTimer();
progress?.stage(`Tokens: ${formatTokenUsage(usage)}.`);
progress?.startTimer(runningMessage());
},
onCost: (cost, limit = maxCostUsd) => {
+ costUpdateCount += 1;
if (limit !== maxCostUsd && limit !== undefined) {
dashboard?.note(`Total cost limit increased to ${formatUsd(limit)}.`);
}
diff --git a/sdk/typescript/src/component-scan.ts b/sdk/typescript/src/component-scan.ts
index 605726d86..49d8f405d 100644
--- a/sdk/typescript/src/component-scan.ts
+++ b/sdk/typescript/src/component-scan.ts
@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
import { notify } from "./value.js";
import { writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -29,6 +30,7 @@ import {
import type {
ScanCost,
ScanSessionEvent,
+ ScanUsageMeasurement,
ScanUsageObservation,
} from "./cost.js";
import type { ScanTokenUsage } from "./cost-model.js";
@@ -57,7 +59,8 @@ export interface ComponentScanOptions {
planOnly?: boolean;
workers?: number;
config?: CodexSecurityConfig;
- scanOptions?: Omit<ScanSettings, "target" | "outputDir">;
+ scanOptions?: Omit<ScanSettings, "target" | "outputDir"> &
+ Pick<ScanOptions, "onMeasurement">;
signal?: AbortSignal;
createSecurity?: (
config: CodexSecurityConfig,
@@ -83,9 +86,12 @@ export interface ComponentReceipt {
status: "pending" | "started" | "completed" | "failed";
outputDir: string;
scanId?: string;
+ operationId?: string;
threatModelPath?: string;
findingCount?: number;
cost?: Readonly<ScanCost>;
+ measurement?: Readonly<ScanUsageMeasurement>;
+ outcome?: "completed" | "failed" | "canceled";
error?: string;
}
@@ -98,6 +104,7 @@ type ComponentScanUpdate =
| { type: "session"; value: ScanSessionEvent }
| { type: "cost"; value: Readonly<ScanCost> }
| { type: "usage"; value: Readonly<ScanTokenUsage> }
+ | { type: "measurement"; value: Readonly<ScanUsageMeasurement> }
| { type: "usage-observation"; value: Readonly<ScanUsageObservation> }
| { type: "workers"; value: ScanWorkerStatus }
| { type: "warning"; value: string };
@@ -212,12 +219,14 @@ export async function runComponentScans(
(component, index) => ({
...component,
id: `component-${index + 1}`,
+ operationId: randomUUID(),
status: "pending",
outputDir: join(output, `component-${index + 1}`),
}),
);
notify(() => options.onPlan?.(receipts.map(copyReceipt)));
const results = new Map<string, ScanResult>();
+ const parentAttemptId = randomUUID();
let next = 0;
const settled = await Promise.allSettled(
Array.from({ length: Math.min(workers, receipts.length) }, async () => {
@@ -273,6 +282,17 @@ export async function runComponentScans(
target: receipt.paths.map((path) => resolve(repository, path)),
outputDir: receipt.outputDir,
signal: options.signal,
+ telemetryContext: {
+ operationId: receipt.operationId!,
+ parentAttemptId,
+ },
+ onMeasurement: (measurement) => {
+ receipt.measurement = measurement;
+ if (measurement.cost !== null) receipt.cost = measurement.cost;
+ else delete receipt.cost;
+ notify(() => options.scanOptions?.onMeasurement?.(measurement));
+ emit({ type: "measurement", value: measurement });
+ },
});
if (result.manifest.scan.status !== "completed")
throw new Error(`Component scan ${result.manifest.scan.status}.`);
@@ -281,10 +301,12 @@ export async function runComponentScans(
receipt.findingCount = result.findings.findings.length;
if (result.cost !== null) receipt.cost = result.cost;
receipt.status = "completed";
+ receipt.outcome = "completed";
if (result.threatModelPath !== null)
receipt.threatModelPath = result.threatModelPath;
} catch (error) {
receipt.status = "failed";
+ receipt.outcome = options.signal?.aborted ? "canceled" : "failed";
receipt.error = errorMessage(error);
if (!options.signal?.aborted) {
const path = await readThreatModelPath(receipt.outputDir, {
@@ -306,6 +328,7 @@ export async function runComponentScans(
for (const receipt of receipts) {
if (receipt.status === "pending" || receipt.status === "started") {
receipt.status = "failed";
+ receipt.outcome = options.signal?.aborted ? "canceled" : "failed";
receipt.error = options.signal?.aborted
? "Scan canceled."
: "Component scan did not finish.";
@@ -361,6 +384,7 @@ export async function runComponentScans(
await writeJson(summary.summaryPath, {
...summary,
repository,
+ attemptId: parentAttemptId,
components: receipts,
});
await writeFile(
diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.ts
index 0de6591c4..580511537 100644
--- a/sdk/typescript/src/cost.ts
+++ b/sdk/typescript/src/cost.ts
@@ -1,13 +1,22 @@
-import { parseJson } from "./value.js";
+import { isSafeNonNegativeInteger, parseJson } from "./value.js";
import type { JsonObject } from "./config.js";
import { workbenchArgs } from "./workbench-arguments.js";
import { createHash } from "node:crypto";
-import { open, readdir, stat } from "node:fs/promises";
-import { join } from "node:path";
+import {
+ lstat,
+ open,
+ readFile,
+ readdir,
+ realpath,
+ stat,
+} from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
import { StringDecoder } from "node:string_decoder";
import { isDeepStrictEqual } from "node:util";
import { z } from "zod";
import { isRecord } from "./record.js";
+import { errorMessage } from "./errors.js";
+import { sessionLines } from "./session-lines.js";
import {
estimateScanCost,
tokenUsage,
@@ -52,6 +61,25 @@ export async function readScanBudgetUsage(
const usage = Object.values(counts).every(Number.isSafeInteger)
? tokenUsage(counts)
: null;
+ const scope = result["coverageScope"];
+ const warnings = result["warnings"];
+ const ownership = {
+ ...(Array.isArray(warnings) &&
+ warnings.length > 0 &&
+ warnings.every((item): item is string => typeof item === "string")
+ ? { warnings }
+ : {}),
+ ...(isSafeNonNegativeInteger(result["threadCount"])
+ ? { threadCount: result["threadCount"] }
+ : {}),
+ ...(isSafeNonNegativeInteger(result["missingThreadCount"])
+ ? { missingThreadCount: result["missingThreadCount"] }
+ : {}),
+ ...(Array.isArray(scope) &&
+ scope.every((item): item is string => typeof item === "string")
+ ? { coverageScope: scope }
+ : {}),
+ };
const roles = result["byRole"];
const workers = isRecord(roles) ? roles["workers"] : undefined;
const coverage = result["coverage"];
@@ -60,16 +88,23 @@ export async function readScanBudgetUsage(
usage === null ||
usage.total_tokens !== result["totalTokens"]
)
- return { usage: null, complete: false };
+ return { ...ownership, usage: null, complete: false };
const hasWorkers =
isRecord(workers) &&
typeof workers["threadCount"] === "number" &&
workers["threadCount"] > 0;
- // The workbench sums known cache writes but does not record which receipts omitted them.
return {
- usage: { ...usage, cache_write_input_tokens_reported: false },
+ ...ownership,
+ // Older workbenches sum cache writes without tracking omitted counters.
+ usage:
+ result["cacheWriteInputTokensReported"] === true
+ ? usage
+ : { ...usage, cache_write_input_tokens_reported: false },
complete: coverage === "complete" && (!requireWorkerUsage || hasWorkers),
+ ...(requireWorkerUsage && !hasWorkers
+ ? { missingThreadCount: Math.max(1, ownership.missingThreadCount ?? 0) }
+ : {}),
};
}
@@ -130,6 +165,8 @@ function createSessionReasoning(id: string, text = "") {
return { id, text, raw: false, activity: null as ScanActivity | null };
}
+type SessionObservation<T> = { position: number; value: T };
+
interface SessionProgress {
update: ScanProgress;
order?: number;
@@ -278,14 +315,28 @@ interface StreamedProgressItem {
}
type SessionUsage = ReturnType<typeof createSessionUsage> & {
- events?: Record<string, unknown>[];
+ events?: SessionObservation<Record<string, unknown>>[];
};
+type WorkerReceipt = {
+ threadId: string | null;
+ usage: ScanTokenUsage | null;
+};
+
+function sessionObservation<T>(
+ session: SessionUsage,
+ value: T,
+): SessionObservation<T> {
+ return { position: session.eventPosition, value };
+}
+
interface ScanCostTrackerOptions {
codexHome: string;
model: string;
repository?: string;
scanDirectory?: string;
+ /** Host-bound store outside model-writable scan artifacts, for Deep scans only. */
+ workerReceipts?: { directory: string; scanId: string };
maxCostUsd?: number;
readBudgetUsage?: (
threadId: string,
@@ -294,6 +345,7 @@ interface ScanCostTrackerOptions {
/** Incomplete costs are measured subtotals, usable for spending limits only. */
onCost?: (cost: Readonly<ScanCost>, complete: boolean) => void;
onUsage?: (usage: Readonly<ScanTokenUsage>) => void;
+ onMeasurement?: (measurement: Readonly<ScanUsageMeasurement>) => void;
onUsageObservation?: (observation: ScanUsageObservation) => void;
onActivity?: (activity: ScanActivity) => void;
onProgress?: (progress: ScanProgress, source?: ParentProgressSource) => void;
@@ -303,9 +355,23 @@ interface ScanCostTrackerOptions {
onObservationError?: (error: unknown) => void;
}
-interface ScanCostSnapshot {
+export interface ScanUsageMeasurement {
+ usage: Readonly<ScanTokenUsage> | null;
+ cost: Readonly<ScanCost> | null;
+ coverage: "complete" | "partial" | "unavailable";
+ observedAt: string;
+ threadCount: number;
+ missingThreadCount: number;
+ /** Known thread/attempt identities for reconciling coverage, not metric labels. */
+ coverageScope?: string[];
+ /** Workbench diagnostic codes explaining coverage or price completeness. */
+ warnings?: string[];
+}
+
+export interface ScanCostSnapshot {
usage: unknown;
cost: ScanCost | null;
+ measurement: ScanUsageMeasurement;
}
const COST_POLL_INTERVAL_MS = 100;
@@ -317,6 +383,7 @@ function createSessionUsage(observeUsage: boolean) {
decoder: new StringDecoder("utf8"),
pendingLine: [] as string[],
unreadable: false,
+ compressedRead: false,
threadId: null as string | null,
parentThreadId: null as string | null,
workingDirectory: null as string | null,
@@ -330,8 +397,9 @@ function createSessionUsage(observeUsage: boolean) {
: null,
responseUsage: null as ScanTokenUsage | null,
responseIds: new Set<string>(),
+ eventPosition: 0,
calls: new Map<string, ScanActivity>(),
- activities: [] as ScanActivity[],
+ activities: [] as SessionObservation<ScanActivity>[],
progress: [] as SessionProgress[],
position: 0,
completions: [] as SessionCompletion[],
@@ -366,8 +434,18 @@ export class ScanCostTracker {
#lastBudgetPoll = -Infinity;
readonly #sessions = new Map<string, SessionUsage>();
readonly #receipts = new Map<string, ScanTokenUsage | null>();
+ readonly #workerReceipts = new Map<string, WorkerReceipt>();
readonly #workers = new Map<string, number>();
readonly #workerProgress = new Map<string, number>();
+ readonly #reportedSessionPositions = new Map<
+ string,
+ {
+ events: number;
+ activities: number;
+ progress: number;
+ source: SessionUsage;
+ }
+ >();
readonly #liveParentProgress = new Set<string>();
readonly #liveParentItems: StreamedProgressItem[] = [];
#liveParentEvents = new WeakMap<
@@ -422,9 +500,21 @@ export class ScanCostTracker {
#observingWorkers = true;
#timer: NodeJS.Timeout | null = null;
#pending: Promise<void> = Promise.resolve();
- #snapshot: ScanCostSnapshot = { usage: null, cost: null };
+ #snapshot: ScanCostSnapshot = {
+ usage: null,
+ cost: null,
+ measurement: {
+ usage: null,
+ cost: null,
+ coverage: "unavailable",
+ observedAt: new Date().toISOString(),
+ threadCount: 0,
+ missingThreadCount: 0,
+ },
+ };
#lastCost: string | null = null;
#lastUsage: string | null = null;
+ #lastMeasurement: string | null = null;
#lastObservation: ScanUsageObservation | null = null;
#highestFilesCompleted = 0;
#expectedFilesTotal: number | undefined;
@@ -1836,7 +1926,9 @@ export class ScanCostTracker {
let retainedWorker: OrderedProgress | null = null;
// Reconsider compact worker receipts under the proven inventory. Keep an
// oversized receipt available without counting it as reviewed coverage.
- for (const session of this.#sessions.values()) {
+ for (const {
+ source: session,
+ } of this.#reportedSessionPositions.values()) {
if (session.threadId === null || session.threadId === this.#threadId)
continue;
for (const [total, pending] of session.pendingWorkerProgress) {
@@ -2251,6 +2343,7 @@ export class ScanCostTracker {
this.#options.maxCostUsd === undefined &&
this.#options.onCost === undefined &&
this.#options.onUsage === undefined &&
+ this.#options.onMeasurement === undefined &&
this.#options.onUsageObservation === undefined &&
this.#options.onActivity === undefined &&
this.#options.onProgress === undefined &&
@@ -2286,32 +2379,56 @@ export class ScanCostTracker {
public async refresh(polling = false): Promise<ScanCostSnapshot> {
const update = this.#pending.then(async () => {
- const { readBudgetUsage } = this.#options;
- if (readBudgetUsage === undefined) return this.#readSessions();
- if (this.#threadId === null) return;
- if (
- this.#options.onActivity ||
- this.#options.onProgress ||
- this.#options.onWorkerEvent ||
- this.#options.onSessionEvent ||
- this.#options.onUsageObservation
- ) {
- await this.#readSessions().catch((error) =>
- this.#options.onObservationError?.(error),
+ try {
+ await this.#refreshUsage(polling);
+ } catch (error) {
+ const previous = this.#snapshot.measurement;
+ this.#setSnapshot(
+ previous.usage,
+ previous.cost,
+ false,
+ previous.threadCount,
+ Math.max(1, previous.missingThreadCount),
+ previous,
);
+ throw error;
}
- // Reading the indexed graph is more expensive than tailing session activity.
- // Always get fresh usage when stopping, even after a recent live poll.
- if (polling && performance.now() - this.#lastBudgetPoll < 1_000) return;
- const measured = await readBudgetUsage(this.#threadId);
- this.#lastBudgetPoll = performance.now();
- this.#updateCost(measured.usage, measured.complete);
});
this.#pending = update.catch(() => {});
await update;
return this.#snapshot;
}
+ async #refreshUsage(polling: boolean): Promise<void> {
+ const { readBudgetUsage } = this.#options;
+ if (readBudgetUsage === undefined) return this.#readSessions();
+ if (this.#threadId === null) return;
+ if (
+ this.#options.onActivity ||
+ this.#options.onProgress ||
+ this.#options.onWorkerEvent ||
+ this.#options.onSessionEvent ||
+ this.#options.onUsageObservation
+ ) {
+ await this.#readSessions().catch((error) =>
+ this.#options.onObservationError?.(error),
+ );
+ }
+ // Reading the indexed graph is more expensive than tailing session activity.
+ // Always get fresh usage when stopping, even after a recent live poll.
+ if (polling && performance.now() - this.#lastBudgetPoll < 1_000) return;
+ const measured = await readBudgetUsage(this.#threadId);
+ this.#lastBudgetPoll = performance.now();
+ this.#updateCost(
+ measured.usage,
+ measured.complete,
+ measured.threadCount ?? (measured.usage === null ? 0 : 1),
+ measured.missingThreadCount ??
+ (measured.complete || measured.warnings?.length ? 0 : 1),
+ measured,
+ );
+ }
+
public async stop(fallbackUsage?: unknown): Promise<ScanCostSnapshot> {
clearInterval(this.#timer ?? undefined);
this.#timer = null;
@@ -2324,12 +2441,14 @@ export class ScanCostTracker {
if (
this.#options.readBudgetUsage ||
this.#receipts.size > 0 ||
- this.#snapshot.usage !== null
+ this.#snapshot.measurement.usage !== null ||
+ this.#snapshot.measurement.missingThreadCount > 0
)
return this.#snapshot;
const cost = estimateScanCost(this.#options.model, fallbackUsage);
- this.#snapshot = { usage: fallbackUsage ?? null, cost };
- this.#reportUsage(tokenUsage(fallbackUsage));
+ const usage = tokenUsage(fallbackUsage);
+ this.#setSnapshot(usage, cost, usage !== null, usage === null ? 0 : 1, 0);
+ this.#reportUsage(usage);
this.#reportCost(cost);
return this.#snapshot;
}
@@ -2341,6 +2460,7 @@ export class ScanCostTracker {
this.#options.onActivity === undefined
? undefined
: this.#options.repository;
+ const collectionErrors: unknown[] = [];
const progressThread =
this.#options.onProgress === undefined ? undefined : this.#threadId;
const observeHealthySessions =
@@ -2350,33 +2470,59 @@ export class ScanCostTracker {
this.#options.onSessionEvent !== undefined ||
this.#options.onWorkerEvent !== undefined);
const unreadable = new Map<SessionUsage, unknown>();
- let blocked: [SessionUsage, unknown] | undefined;
- try {
- for await (const path of sessionFiles(
- join(this.#options.codexHome, "sessions"),
- )) {
- let session = this.#sessions.get(path);
- if (session === undefined) {
- session = createSessionUsage(observeUsage);
- this.#sessions.set(path, session);
- }
- try {
- await readSessionUsage(path, session, repository, progressThread);
- } catch (error) {
- if (session.threadId === null) {
- if (!observeHealthySessions || !isBlockedLogRead(error))
- throw error;
- blocked ??= [session, error];
+ let blockingReadError: unknown;
+ directories: for (const directory of ["sessions", "archived_sessions"]) {
+ try {
+ for await (const path of sessionFiles(
+ join(this.#options.codexHome, directory),
+ true,
+ )) {
+ let session = this.#sessions.get(path);
+ if (session === undefined) {
+ session = createSessionUsage(observeUsage);
+ this.#sessions.set(path, session);
+ }
+ try {
+ await readSessionUsage(
+ path,
+ session,
+ repository,
+ progressThread,
+ undefined,
+ true,
+ );
+ } catch (error) {
+ if (session.threadId !== null) unreadable.set(session, error);
+ else if (isRecord(error) && typeof error["syscall"] === "string") {
+ blockingReadError ??= error;
+ if (!observeHealthySessions || !isBlockedLogRead(error))
+ break directories;
+ } else if (
+ directory !== "archived_sessions" ||
+ !path.endsWith(".zst")
+ ) {
+ collectionErrors.push(error);
+ }
+ // A damaged cold archive with no readable identity cannot be
+ // attributed to this scan. Registered threads still require usage.
}
- unreadable.set(session, error);
}
+ } catch (error) {
+ // Retain the blocking read if traversal also stops on a later entry.
+ if (blockingReadError === undefined) collectionErrors.push(error);
}
- } catch (error) {
- // Traversal stopped. Preserve the read error that already blocked this poll.
- if (!blocked) throw error;
}
- const included = new Set([this.#threadId, ...this.#receipts.keys()]);
+ const workerReceipts = await readWorkerReceipts(
+ this.#options.workerReceipts,
+ this.#workerReceipts,
+ );
+ collectionErrors.push(...workerReceipts.errors);
+ const included = new Set([
+ this.#threadId,
+ ...this.#receipts.keys(),
+ ...workerReceipts.usages.keys(),
+ ]);
if (this.#options.scanDirectory !== undefined) {
const scanStartedAt =
[...this.#sessions.values()].find(
@@ -2416,32 +2562,66 @@ export class ScanCostTracker {
}
}
} while (included.size !== previousSize);
- blocked ??= unreadable
- .entries()
- .find(
- ([session]) =>
- session.threadId !== null && included.has(session.threadId),
- );
- if (blocked && !observeHealthySessions) throw blocked[1];
+ for (const [session, error] of unreadable) {
+ if (session.threadId !== null && included.has(session.threadId)) {
+ if (isBlockedLogRead(error)) blockingReadError ??= error;
+ else collectionErrors.push(error);
+ }
+ }
+ if (blockingReadError !== undefined)
+ collectionErrors.unshift(blockingReadError);
- const usages = new Map(this.#receipts);
- for (const [path, session] of this.#sessions) {
- const threadId = session.threadId;
+ const usages = new Map<string, ScanTokenUsage | null>(
+ [...included].map((threadId) => [
+ threadId,
+ this.#receipts.get(threadId) ?? null,
+ ]),
+ );
+ for (const [threadId, receipt] of workerReceipts.usages) {
+ const current = usages.get(threadId);
if (
- threadId === null ||
- !included.has(threadId) ||
- unreadable.has(session)
+ receipt !== null &&
+ receipt.total_tokens > (current?.total_tokens ?? -1)
)
- continue;
- if (
+ usages.set(threadId, receipt);
+ }
+ // SDK totals retain measured usage when a rollout is unavailable.
+ // Native rollouts also establish descendant coverage.
+ const incomplete = new Set(workerReceipts.usages.keys());
+ for (const [path, tracked] of this.#sessions) {
+ const threadId = tracked.threadId;
+ if (threadId === null || !included.has(threadId)) continue;
+ let session = tracked;
+ const observe =
+ !unreadable.has(tracked) &&
+ (blockingReadError === undefined || observeHealthySessions);
+ if (observe && path.endsWith(".zst") && !tracked.compressedRead) {
+ // The metadata pass associates this archive with the scan. A full read
+ // starts at the beginning, including when retrying a partial decode.
+ const archive: SessionUsage = createSessionUsage(observeUsage);
+ if (this.#options.onSessionEvent !== undefined) archive.events = [];
+ try {
+ await readSessionUsage(path, archive, repository, progressThread);
+ } catch (error) {
+ collectionErrors.push(error);
+ }
+ if (
+ archive.threadId === threadId &&
+ archive.eventPosition >= tracked.eventPosition
+ ) {
+ session = archive;
+ this.#sessions.set(path, archive);
+ }
+ } else if (
+ observe &&
this.#options.onSessionEvent !== undefined &&
session.events === undefined
) {
+ const replay: SessionUsage = createSessionUsage(false);
+ replay.events = [];
try {
- // Replay event history through the already-read snapshot without
- // replacing its authoritative progress, usage, or partial-line decoder.
- const replay: SessionUsage = createSessionUsage(false);
- replay.events = [];
+ // Replay raw events only through the tracked snapshot. Keep its progress,
+ // usage and decoder so a failed read cannot replace authoritative state.
await readSessionUsage(
path,
replay,
@@ -2451,7 +2631,6 @@ export class ScanCostTracker {
);
if (replay.offset === session.offset) {
session.events = replay.events;
- // At stop there is no next poll to read usage appended during replay.
if (this.#timer === null)
await readSessionUsage(
path,
@@ -2462,11 +2641,31 @@ export class ScanCostTracker {
);
}
} catch (error) {
- if (!observeHealthySessions) throw error;
- blocked ??= [session, error];
- continue;
+ collectionErrors.push(error);
}
}
+ const receipt = usages.get(threadId);
+ if (
+ session.usage !== null &&
+ session.usage.total_tokens >=
+ (workerReceipts.usages.get(threadId)?.total_tokens ?? 0)
+ )
+ incomplete.delete(threadId);
+ // A discovered thread without a receipt has unknown usage, not zero.
+ // Retain it so a parent-only subtotal cannot appear to be complete.
+ if (receipt === undefined) usages.set(threadId, null);
+ if (
+ session.usage !== null &&
+ (session.usage.total_tokens > (receipt?.total_tokens ?? -1) ||
+ // Worker receipts retain field presence; the SDK may default to zero.
+ (session.usage.total_tokens === receipt?.total_tokens &&
+ (receipt.cache_write_input_tokens_reported === false ||
+ (receipt === this.#receipts.get(threadId) &&
+ receipt.cache_write_input_tokens === 0))))
+ ) {
+ usages.set(threadId, session.usage);
+ }
+ if (!observe) continue;
let worker: number | undefined;
if (threadId !== this.#threadId) {
worker = this.#workers.get(threadId);
@@ -2477,7 +2676,18 @@ export class ScanCostTracker {
this.#options.onWorkerEvent?.({ kind: "observed", worker });
}
}
- for (const event of session.events?.splice(0) ?? []) {
+ // Archives and compressed copies retain the same append-only event order.
+ // A new rollout for the same thread has a new initial metadata timestamp.
+ const eventStream = JSON.stringify([threadId, session.startedAt]);
+ const reported = this.#reportedSessionPositions.get(eventStream) ?? {
+ events: 0,
+ activities: 0,
+ progress: 0,
+ source: session,
+ };
+ for (const { position, value: event } of session.events?.splice(0) ??
+ []) {
+ if (position <= reported.events) continue;
this.#options.onSessionEvent?.({
threadId,
parentThreadId: session.parentThreadId,
@@ -2485,91 +2695,191 @@ export class ScanCostTracker {
event,
});
}
+ // A failed replay can leave activity/progress available without raw events.
+ if (session.events !== undefined)
+ reported.events = Math.max(reported.events, session.eventPosition);
if (worker !== undefined) {
- for (const activity of session.activities.splice(0)) {
+ for (const { position, value: activity } of session.activities.splice(
+ 0,
+ )) {
+ if (position <= reported.activities) continue;
this.#options.onActivity?.({
...activity,
id: `${threadId}:${activity.id}`,
worker,
});
}
+ reported.activities = Math.max(
+ reported.activities,
+ session.eventPosition,
+ );
}
- let unresolvedCommand: UnresolvedParentCommand | undefined;
- let inventoryWitness: ProgressOrder | undefined;
- if (threadId === this.#threadId) {
- this.#parentSession = session;
- for (const saved of session.progress)
- if (saved.order !== undefined && !saved.duplicate)
- this.#rememberParentFact(savedProgress(saved));
- this.#matchParentCompletions();
- inventoryWitness = this.#reconcileParentProgress();
- unresolvedCommand = this.#unresolvedParentCommand();
- }
- const reviewWasUnpositioned =
- this.#parentInventoryBoundary?.reviewed !== true;
- this.#reportSessionProgress(
- session,
- threadId === this.#threadId,
- unresolvedCommand,
- inventoryWitness,
- );
- // Fresh saved facts are observed at their source-loop position, so initial
- // inventory notifications keep their order. Recover after the batch too:
- // a later accepted parent may have hidden an eligible earlier receipt.
- if (threadId === this.#threadId) {
- // A newly admitted review locates inventories parked earlier in this
- // batch. Reconsider them before the final refresh returns.
- if (
- reviewWasUnpositioned &&
- this.#parentInventoryBoundary?.reviewed === true
- )
- this.#reportSessionProgress(
- session,
- true,
- unresolvedCommand,
- inventoryWitness,
- );
- this.#reconcileParentProgress();
- }
- const receipt = usages.get(threadId);
- // A discovered thread without a receipt has unknown usage, not zero.
- // Retain it so a parent-only subtotal cannot appear to be complete.
- if (receipt === undefined) usages.set(threadId, null);
- if (
- session.usage !== null &&
- (session.usage.total_tokens > (receipt?.total_tokens ?? -1) ||
- // The SDK inserts zero when the final receipt omits cache writes.
- (session.usage.total_tokens === receipt?.total_tokens &&
- receipt.cache_write_input_tokens === 0))
- ) {
- usages.set(threadId, session.usage);
+ if (session === reported.source || session.position > reported.progress) {
+ if (session !== reported.source) {
+ // An archive can continue an existing rollout. Keep admitted marker
+ // state and process only the suffix unique to this copy.
+ const prior = reported.source;
+ session.progress = prior.progress
+ .filter((marker) => marker.position <= reported.progress)
+ .concat(
+ session.progress.filter(
+ (marker) => marker.position > reported.progress,
+ ),
+ );
+ session.completions = prior.completions
+ .filter((completion) => completion.position <= reported.progress)
+ .concat(
+ session.completions.filter(
+ (completion) => completion.position > reported.progress,
+ ),
+ );
+ session.latestWorkerProgress = prior.latestWorkerProgress;
+ session.pendingWorkerProgress = prior.pendingWorkerProgress;
+ session.filesCompleted = prior.filesCompleted;
+ session.filesTotal = prior.filesTotal;
+ reported.source = session;
+ }
+ reported.progress = session.position;
+ let unresolvedCommand: UnresolvedParentCommand | undefined;
+ let inventoryWitness: ProgressOrder | undefined;
+ if (threadId === this.#threadId) {
+ this.#parentSession = session;
+ for (const saved of session.progress)
+ if (saved.order !== undefined && !saved.duplicate)
+ this.#rememberParentFact(savedProgress(saved));
+ this.#matchParentCompletions();
+ inventoryWitness = this.#reconcileParentProgress();
+ unresolvedCommand = this.#unresolvedParentCommand();
+ }
+ const reviewWasUnpositioned =
+ this.#parentInventoryBoundary?.reviewed !== true;
+ this.#reportSessionProgress(
+ session,
+ threadId === this.#threadId,
+ unresolvedCommand,
+ inventoryWitness,
+ );
+ // Fresh saved facts are observed at their source-loop position, so initial
+ // inventory notifications keep their order. Recover after the batch too:
+ // a later accepted parent may have hidden an eligible earlier receipt.
+ if (threadId === this.#threadId) {
+ // A newly admitted review locates inventories parked earlier in this
+ // batch. Reconsider them before the final refresh returns.
+ if (
+ reviewWasUnpositioned &&
+ this.#parentInventoryBoundary?.reviewed === true
+ )
+ this.#reportSessionProgress(
+ session,
+ true,
+ unresolvedCommand,
+ inventoryWitness,
+ );
+ this.#reconcileParentProgress();
+ }
}
+ this.#reportedSessionPositions.set(eventStream, reported);
}
- // Healthy sessions can report activity even when a read blocks the total.
- if (blocked) throw blocked[1];
let usage: ScanTokenUsage | null = null;
- let complete = true;
- for (const value of usages.values()) {
+ let missingThreadCount = workerReceipts.unknownAttempts;
+ let threadCount = 0;
+ for (const [threadId, value] of usages) {
if (value === null) {
- complete = false;
+ missingThreadCount += 1;
continue;
}
+ threadCount += 1;
+ if (incomplete.has(threadId)) missingThreadCount += 1;
usage = addTokenUsage(usage, value);
}
+ if (collectionErrors.length > 0)
+ missingThreadCount = Math.max(1, missingThreadCount);
+ const complete = missingThreadCount === 0 && usage !== null;
if (observeUsage) this.#reportUsageObservation(usages, complete);
if (this.#options.readBudgetUsage === undefined)
- this.#updateCost(usage, complete);
+ this.#updateCost(
+ usage,
+ complete,
+ threadCount,
+ missingThreadCount,
+ {
+ coverageScope:
+ collectionErrors.length === 0
+ ? [
+ ...[...included].map((id) => `thread:${id}`),
+ ...[...workerReceipts.attemptIds].map(
+ (id) => `worker-attempt:${id}`,
+ ),
+ ].sort()
+ : undefined,
+ },
+ // A blocking read leaves a native-only subtotal unconfirmed until the retry.
+ blockingReadError === undefined ||
+ this.#receipts.size > 0 ||
+ workerReceipts.usages.size > 0,
+ );
+ // Preserve measured usage and every diagnostic when several logs fail together.
+ if (collectionErrors.length === 1) throw collectionErrors[0];
+ if (collectionErrors.length > 1)
+ throw new AggregateError(
+ collectionErrors,
+ collectionErrors.map(errorMessage).join("\n"),
+ );
}
- #updateCost(usage: ScanTokenUsage | null, complete: boolean): void {
- if (!complete) this.#snapshot = { usage: null, cost: null };
- if (usage === null) return;
+ #updateCost(
+ usage: ScanTokenUsage | null,
+ complete: boolean,
+ threadCount: number,
+ missingThreadCount: number,
+ details?: Pick<ScanUsageMeasurement, "coverageScope" | "warnings">,
+ reportCost = true,
+ ): void {
const cost = estimateScanCost(this.#options.model, usage);
- if (complete) {
- this.#snapshot = { usage, cost };
- this.#reportUsage(usage);
- }
- this.#reportCost(cost, complete);
+ this.#setSnapshot(
+ usage,
+ cost,
+ complete,
+ threadCount,
+ missingThreadCount,
+ details,
+ );
+ if (complete) this.#reportUsage(usage);
+ if (reportCost) this.#reportCost(cost, complete);
+ }
+
+ #setSnapshot(
+ usage: ScanTokenUsage | null,
+ cost: ScanCost | null,
+ complete: boolean,
+ threadCount: number,
+ missingThreadCount: number,
+ details?: Pick<ScanUsageMeasurement, "coverageScope" | "warnings">,
+ ): void {
+ const data = {
+ usage,
+ cost,
+ coverage:
+ usage === null ? "unavailable" : complete ? "complete" : "partial",
+ threadCount,
+ missingThreadCount,
+ ...(details?.coverageScope === undefined
+ ? {}
+ : { coverageScope: details.coverageScope }),
+ ...(details?.warnings === undefined
+ ? {}
+ : { warnings: details.warnings }),
+ } as const;
+ const measurement = { ...data, observedAt: new Date().toISOString() };
+ this.#snapshot = {
+ usage: complete ? usage : null,
+ cost: complete ? cost : null,
+ measurement,
+ };
+ const signature = JSON.stringify(data);
+ if (signature === this.#lastMeasurement) return;
+ this.#lastMeasurement = signature;
+ this.#options.onMeasurement?.(measurement);
}
#reportUsageObservation(
@@ -2594,8 +2904,8 @@ export class ScanCostTracker {
tokensUpdatedAt = session.tokensUpdatedAt;
}
}
- if (!complete) {
- // The display retains the last complete aggregate while a worker is unmeasured.
+ if (!complete && this.#lastUsage !== null) {
+ // Keep the last complete total's time while a worker is unmeasured.
tokensUpdatedAt = this.#lastObservation?.tokensUpdatedAt ?? null;
} else if (
usages
@@ -2922,6 +3232,91 @@ export class ScanCostTracker {
}
}
+async function readWorkerReceipts(
+ store: ScanCostTrackerOptions["workerReceipts"],
+ retained: Map<string, WorkerReceipt>,
+): Promise<{
+ usages: Map<string, ScanTokenUsage | null>;
+ unknownAttempts: number;
+ attemptIds: Set<string>;
+ errors: unknown[];
+}> {
+ const usages = new Map<string, ScanTokenUsage | null>();
+ const attempts = new Set<string>();
+ const result = {
+ usages,
+ unknownAttempts: 0,
+ attemptIds: attempts,
+ errors: [] as unknown[],
+ };
+ if (store === undefined) return result;
+ const { directory, scanId } = store;
+ try {
+ const directoryInfo = await lstat(directory);
+ if (
+ !directoryInfo.isDirectory() ||
+ relative(resolve(directory), await realpath(directory)) !== ""
+ )
+ throw new Error(
+ `Worker usage directory must use a canonical directory: ${directory}`,
+ );
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
+ if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+ let receipt: unknown;
+ try {
+ receipt = JSON.parse(
+ await readFile(join(directory, entry.name), "utf8"),
+ );
+ } catch (error) {
+ if (isMissingFile(error)) continue;
+ throw error;
+ }
+ if (
+ !isRecord(receipt) ||
+ receipt["schemaVersion"] !== 1 ||
+ receipt["source"] !== "codex_sdk" ||
+ receipt["usageScope"] !== "thread_cumulative" ||
+ receipt["scanId"] !== scanId ||
+ typeof receipt["attemptId"] !== "string" ||
+ entry.name !== `${receipt["attemptId"]}.json` ||
+ attempts.has(receipt["attemptId"])
+ )
+ continue;
+ attempts.add(receipt["attemptId"]);
+ retained.set(receipt["attemptId"], {
+ threadId:
+ typeof receipt["threadId"] === "string" ? receipt["threadId"] : null,
+ usage: tokenUsage(receipt["usage"]),
+ });
+ }
+ } catch (error) {
+ if (!isMissingFile(error)) result.errors.push(error);
+ }
+ // As with native sessions, a later read failure cannot erase observed usage.
+ // Keep attempts separate so a worker's initial unknown identity can resolve.
+ for (const [attemptId, { threadId, usage }] of retained) {
+ attempts.add(attemptId);
+ if (threadId === null) {
+ result.unknownAttempts += 1;
+ continue;
+ }
+ const existing = usages.get(threadId) ?? null;
+ // Native SDK completions include earlier turns of a resumed thread.
+ usages.set(
+ threadId,
+ usage !== null &&
+ (existing === null ||
+ usage.total_tokens > existing.total_tokens ||
+ (usage.total_tokens === existing.total_tokens &&
+ existing.cache_write_input_tokens_reported === false &&
+ usage.cache_write_input_tokens_reported !== false))
+ ? usage
+ : existing,
+ );
+ }
+ return result;
+}
+
export async function* sessionFiles(
directory: string,
compressed = false,
@@ -2953,13 +3348,29 @@ async function readSessionUsage(
repository?: string,
progressThread?: string,
throughOffset?: number | "file-size",
+ metadataOnly = false,
): Promise<void> {
if (session.unreadable) return;
+ if (path.endsWith(".zst")) {
+ if (session.compressedRead) return;
+ if (metadataOnly && session.threadId !== null) return;
+ try {
+ for await (const line of sessionLines(path)) {
+ readSessionEvent(line, session, repository, progressThread);
+ if (metadataOnly && session.threadId !== null) return;
+ }
+ } catch (error) {
+ if (isMissingFile(error)) return;
+ throw error;
+ }
+ session.compressedRead = true;
+ return;
+ }
let file;
try {
- const size = (await stat(path)).size;
- if (size === session.offset) return;
- if (throughOffset === "file-size") throughOffset = size;
+ const metadata = await stat(path);
+ if (metadata.isFile() && metadata.size === session.offset) return;
+ if (throughOffset === "file-size") throughOffset = metadata.size;
file = await open(path, "r");
} catch (error) {
if (isMissingFile(error)) return;
@@ -3012,11 +3423,13 @@ function readSessionEvent(
if (line.length === 0) return;
const event = parseJson(() => line);
if (!isRecord(event) || !isRecord(event["payload"])) return;
+ session.eventPosition += 1;
const payload = event["payload"];
if (event["type"] === "session_meta") {
if (session.threadId !== null) {
session.replaying = payload["id"] !== session.threadId;
- if (!session.replaying) session.events?.push(event);
+ if (!session.replaying)
+ session.events?.push(sessionObservation(session, event));
return;
}
if (typeof payload["id"] === "string") {
@@ -3027,7 +3440,7 @@ function readSessionEvent(
}
session.startedAt = sessionStartedAt(payload["timestamp"]);
session.parentThreadId = sessionParentThreadId(payload);
- session.events?.push(event);
+ session.events?.push(sessionObservation(session, event));
return;
}
if (session.replaying) {
@@ -3041,11 +3454,11 @@ function readSessionEvent(
sessionOwnsTurn(session, payload)
) {
session.replaying = false;
- session.events?.push(event);
+ session.events?.push(sessionObservation(session, event));
}
return;
}
- session.events?.push(event);
+ session.events?.push(sessionObservation(session, event));
const position = ++session.position;
if (event["type"] === "token_usage_record") {
const responseId = payload["response_id"];
@@ -3175,7 +3588,7 @@ function readSessionEvent(
if (activity.status === "running") {
session.calls.set(activity.id, activity);
}
- session.activities.push(activity);
+ session.activities.push(sessionObservation(session, activity));
return;
}
if (
@@ -3185,10 +3598,12 @@ function readSessionEvent(
) {
const call = session.calls.get(payload["call_id"]);
if (call !== undefined) {
- session.activities.push({
- ...call,
- status: payload["status"] === "failed" ? "failed" : "completed",
- });
+ session.activities.push(
+ sessionObservation(session, {
+ ...call,
+ status: payload["status"] === "failed" ? "failed" : "completed",
+ }),
+ );
session.calls.delete(call.id);
}
}
@@ -3299,7 +3714,7 @@ function readSessionEvent(
!session.prose.has(`${activity.kind}:${activity.description}`)
) {
session.prose.add(`${activity.kind}:${activity.description}`);
- session.activities.push(activity);
+ session.activities.push(sessionObservation(session, activity));
}
return;
}
@@ -3428,7 +3843,7 @@ function recordReasoningActivity(
}
reasoning.activity = activity;
session.prose.add(`${activity.kind}:${activity.description}`);
- session.activities.push(activity);
+ session.activities.push(sessionObservation(session, activity));
}
const PERSISTED_OUTPUT_GAP =
@@ -3711,7 +4126,7 @@ function sessionProgressUpdates(
return scanProgressUpdatesFromText(output);
}
-function addTokenUsage(
+export function addTokenUsage(
previous: ScanTokenUsage | null,
next: ScanTokenUsage,
): ScanTokenUsage {
diff --git a/sdk/typescript/src/custom-publish.ts b/sdk/typescript/src/custom-publish.ts
index 71aca4b25..1432c920c 100644
--- a/sdk/typescript/src/custom-publish.ts
+++ b/sdk/typescript/src/custom-publish.ts
@@ -8,6 +8,11 @@ import {
scanArtifactDigest,
workflowDestination,
} from "./finding-workflow.js";
+import {
+ PublicationTelemetryRecorder,
+ type PublicationTelemetry,
+ type PublicationTelemetryObserver,
+} from "./publication-telemetry.js";
export interface PublishScanToCustomOptions {
/** Resume publication within the named local findings workflow. */
@@ -18,6 +23,8 @@ export interface PublishScanToCustomOptions {
dryRun?: boolean;
expectedScanId?: string;
signal?: AbortSignal;
+ /** Best-effort content-free outcome accounting, including preparation failures. */
+ onTelemetry?: PublicationTelemetryObserver;
}
export interface CustomPublicationResult {
@@ -27,6 +34,13 @@ export interface CustomPublicationResult {
findingCount: number;
dryRun?: true;
findings?: Finding[];
+ telemetry?: PublicationTelemetry;
+}
+
+interface CustomPublicationDependencies {
+ fetch?: FindingsRequest;
+ environment?: NodeJS.ProcessEnv;
+ runWorkbench?: typeof runWorkbench;
}
/** Publish complete, sealed findings to a findings API without changing scan artifacts. */
@@ -41,11 +55,40 @@ export async function publishScanToCustom(
export async function publishScanToCustomInternal(
scanDirectory: string,
options: PublishScanToCustomOptions,
- dependencies: {
- fetch?: FindingsRequest;
- environment?: NodeJS.ProcessEnv;
- runWorkbench?: typeof runWorkbench;
- } = {},
+ dependencies: CustomPublicationDependencies = {},
+): Promise<CustomPublicationResult> {
+ const telemetry = new PublicationTelemetryRecorder(
+ "custom",
+ options.onTelemetry,
+ );
+ try {
+ const result = await publishScanToCustomAttempt(
+ scanDirectory,
+ options,
+ dependencies,
+ telemetry,
+ );
+ telemetry.notify(result.telemetry!);
+ return result;
+ } catch (error) {
+ telemetry.notify(
+ telemetry.snapshot(
+ telemetry.outcome === "indeterminate"
+ ? "indeterminate"
+ : options.signal?.aborted
+ ? "canceled"
+ : "failed",
+ ),
+ );
+ throw error;
+ }
+}
+
+async function publishScanToCustomAttempt(
+ scanDirectory: string,
+ options: PublishScanToCustomOptions,
+ dependencies: CustomPublicationDependencies,
+ telemetry: PublicationTelemetryRecorder,
): Promise<CustomPublicationResult> {
const { contract, scanDirectory: canonicalDirectory } =
await loadContractWithScanDirectory(scanDirectory, {
@@ -54,26 +97,47 @@ export async function publishScanToCustomInternal(
expectedScanId: options.expectedScanId,
});
const { manifest, findings } = contract;
+ telemetry.counts.selected = findings.findings.length;
if (findings.findings.length === 0 && options.workflowId === undefined) {
throw new CodexSecurityError(
"The completed scan has no findings to publish.",
);
}
const repositoryId = manifest.scan.target.targetId;
+ let invoked = false;
const publish = async (): Promise<CustomPublicationResult> => {
- const findingIds = options.dryRun
- ? findings.findings.map((finding) => finding.findingId)
- : await new FindingsClient(
+ invoked = true;
+ const client = options.dryRun
+ ? null
+ : new FindingsClient(
options.findingsUrl,
options.signal,
dependencies.fetch,
- ).publish(findings.findings, repositoryId);
+ );
+ if (client !== null) {
+ telemetry.attempted = true;
+ telemetry.counts.submitted = findings.findings.length;
+ // The bulk API acknowledges IDs; it does not distinguish inserts from upserts.
+ telemetry.counts.created = null;
+ telemetry.counts.reused = null;
+ telemetry.counts.acknowledged = null;
+ telemetry.counts.failed = null;
+ telemetry.outcome = "indeterminate";
+ }
+ const findingIds =
+ client === null
+ ? findings.findings.map((finding) => finding.findingId)
+ : await client.publish(findings.findings, repositoryId);
+ telemetry.outcome = options.dryRun ? "preview" : "completed";
+ telemetry.counts.acknowledged = options.dryRun ? 0 : findingIds.length;
+ telemetry.counts.failed = 0;
return {
scanId: manifest.scan.id,
repositoryId,
findingIds,
findingCount: findingIds.length,
...(options.dryRun ? { dryRun: true, findings: findings.findings } : {}),
+ telemetry: telemetry.snapshot(),
};
};
if (options.workflowId === undefined || options.dryRun)
@@ -91,5 +155,8 @@ export async function publishScanToCustomInternal(
destination: workflowDestination(options.findingsUrl),
});
await workflow.complete("scan", null);
- return await workflow.run("publish", publish);
+ const result = await workflow.run("publish", publish);
+ if (invoked) return result;
+ telemetry.counts.reused = result.findingCount;
+ return { ...result, telemetry: telemetry.snapshot("completed") };
}
diff --git a/sdk/typescript/src/deduplication/local.ts b/sdk/typescript/src/deduplication/local.ts
index ff7df1e46..8075e07b3 100644
--- a/sdk/typescript/src/deduplication/local.ts
+++ b/sdk/typescript/src/deduplication/local.ts
@@ -19,6 +19,7 @@ import {
EMBEDDING_DIMENSIONS,
EMBEDDINGS_URL,
type FindingEmbedder,
+ type EmbeddingUsageObserver,
} from "../server/embeddings.js";
import { retryDelay, waitForRetry } from "./retry.js";
@@ -48,6 +49,7 @@ export class LocalDeduplication {
private readonly signal?: AbortSignal,
private readonly workbench: typeof runWorkbench = runWorkbench,
embedding?: FindingEmbeddingBinding,
+ onEmbeddingUsage?: EmbeddingUsageObserver,
) {
const endpoint =
environmentEntry(environment, "CODEX_SECURITY_EMBEDDINGS_URL") ||
@@ -64,6 +66,7 @@ export class LocalDeduplication {
embeddingRequest,
endpoint,
signal,
+ onEmbeddingUsage,
),
};
// The digest keeps endpoint/namespace details out of persisted cache keys.
diff --git a/sdk/typescript/src/deduplication/scan.ts b/sdk/typescript/src/deduplication/scan.ts
index ba016e8f8..0c3d38bcd 100644
--- a/sdk/typescript/src/deduplication/scan.ts
+++ b/sdk/typescript/src/deduplication/scan.ts
@@ -44,6 +44,7 @@ import {
} from "./checkpointed-review.js";
import { normalizeRepository } from "../targets.js";
import { LocalDeduplication, type FindingEmbeddingBinding } from "./local.js";
+import type { EmbeddingUsageObserver } from "../server/embeddings.js";
import { configuredCodexHome, readCodexHomeConfig } from "../auth.js";
import { CodexSecurityError } from "../errors.js";
import { comparisonEnvironment } from "../scan-comparison.js";
@@ -69,6 +70,8 @@ export interface DeduplicateScanOptions {
concurrency?: number;
/** Best-effort progress and native review diagnostics; observer failures are ignored. */
onDiagnostic?: DeduplicationDiagnosticObserver;
+ /** Built-in local embedding batch usage; excluded from scan model-token totals. */
+ onEmbeddingUsage?: EmbeddingUsageObserver;
signal?: AbortSignal;
}
@@ -207,6 +210,7 @@ async function deduplicateResolvedScan(
options.signal,
workbench,
options.embedding,
+ options.onEmbeddingUsage,
)
: undefined;
const client =
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index cea990f49..c7a4c9d57 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -90,6 +90,7 @@ export type {
ScanAccountRateLimitWindow,
ScanCost,
ScanSessionEvent,
+ ScanUsageMeasurement,
ScanUsageObservation,
ScanWorkerEvent,
} from "./cost.js";
@@ -202,11 +203,19 @@ export type {
} from "./deduplication/scan.js";
export type { DeduplicationRefusal } from "./deduplication/deduplication.js";
export type { FindingEmbeddingBinding } from "./deduplication/local.js";
+export type {
+ PublicationTelemetry,
+ PublicationTelemetryObserver,
+} from "./publication-telemetry.js";
export type {
DeduplicationDiagnostic,
DeduplicationDiagnosticObserver,
} from "./deduplication/diagnostics.js";
-export type { FindingEmbedder } from "./server/embeddings.js";
+export type {
+ FindingEmbedder,
+ EmbeddingUsageObservation,
+ EmbeddingUsageObserver,
+} from "./server/embeddings.js";
export {
ExternalPublicationError,
prepareExternalPublication,
@@ -328,6 +337,16 @@ export type {
ValidationReviewRequest,
} from "./validation-records.js";
+export {
+ readOperationTelemetry,
+ summarizeOperationTelemetry,
+} from "./operation-telemetry.js";
+export type {
+ OperationTelemetryEvent,
+ OperationOutcome,
+ OperationFailureCategory,
+} from "./operation-telemetry.js";
+
export { prepareLocalExternalImport } from "./external-findings-import.js";
export {
normalizeOpenGrepFindings,
diff --git a/sdk/typescript/src/multiscan.ts b/sdk/typescript/src/multiscan.ts
index a6f2ad2c5..7fffcc375 100644
--- a/sdk/typescript/src/multiscan.ts
+++ b/sdk/typescript/src/multiscan.ts
@@ -21,10 +21,10 @@ import { hostname } from "node:os";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { promisify } from "node:util";
import Papa from "papaparse";
-import type { CodexSecurity } from "./api.js";
-import type { CodexSecurityConfig } from "./config.js";
+import type { CodexSecurity, ScanOptions } from "./api.js";
+import type { CodexSecurityConfig, JsonObject } from "./config.js";
import { ContractSchemaError, loadContract } from "./contract.js";
-import type { ScanCost } from "./cost.js";
+import type { ScanCost, ScanUsageMeasurement } from "./cost.js";
import { deepScanOptions } from "./deep-config.js";
import { readThreatModelPath } from "./artifact-export.js";
import {
@@ -70,9 +70,13 @@ type MultiscanTask = ReturnType<typeof parseInventory>[number];
interface MultiscanReceipt extends MultiscanTask {
status: "completed" | "failed";
attempt: number;
+ operationId?: string;
outputDir: string;
threatModelPath?: string;
cost?: ScanCost;
+ measurement?: Readonly<ScanUsageMeasurement>;
+ usage?: JsonObject;
+ outcome?: "completed" | "failed" | "canceled";
error?: string;
warnings?: string[];
policyFailed?: boolean;
@@ -103,10 +107,18 @@ export interface MultiscanOptions extends ScanPromptSettings {
maxAttempts: number;
recoverScan?(
scanDir: string,
- prompts: ScanPromptSettings & {
- knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;
- },
- ): Promise<Pick<ScanResult, "manifest" | "cost" | "findings"> | undefined>;
+ prompts: ScanPromptSettings &
+ Pick<ScanOptions, "onMeasurement" | "onTelemetry"> & {
+ knowledgeBaseSnapshot?: KnowledgeBaseSnapshot;
+ /** @internal Preserve correlation when the resumed SDK has no saved binding. */
+ telemetryContext?: { operationId: string; parentAttemptId?: string };
+ },
+ ): Promise<
+ | (Pick<ScanResult, "manifest" | "cost" | "findings"> & {
+ usage?: JsonObject;
+ })
+ | undefined
+ >;
maxCostUsd?: number;
// Prompts are shared across modes and prepared from the top-level options.
scanOptionsByMode?: Partial<
@@ -415,6 +427,7 @@ async function runCampaign(
if (task === undefined) return;
const knowledge = knowledgeByMode[task.mode];
const history = receipts.get(task.id.toLowerCase());
+ let operationId = history?.scan?.operationId;
let maxAttempt = history?.maxAttempt ?? 0;
const nextAttempt = () => {
if (maxAttempt === Number.MAX_SAFE_INTEGER)
@@ -449,6 +462,17 @@ async function runCampaign(
const runWarnings: string[] = [];
let attemptPolicyFailed: boolean | undefined;
let cost: Readonly<ScanCost> | null = null;
+ let measurement: Readonly<ScanUsageMeasurement> | null = null;
+ let savedUsage: JsonObject | undefined;
+ const observers: Pick<ScanOptions, "onMeasurement" | "onTelemetry"> = {
+ onMeasurement: (value) => {
+ measurement = value;
+ cost = value.cost;
+ },
+ onTelemetry: (event) => {
+ operationId = event.operationId;
+ },
+ };
let threatModelPath: string | null | undefined;
let exhaustedBudget = false;
let requiresRecovery = false;
@@ -457,7 +481,9 @@ async function runCampaign(
await ensureOutputDirectory(artifactRoot);
let result:
| (Pick<ScanResult, "manifest" | "cost" | "findings"> &
- Partial<Pick<ScanResult, "threatModelPath">>)
+ Partial<Pick<ScanResult, "threatModelPath">> & {
+ usage?: JsonObject;
+ })
| undefined;
if (
options.recoverScan !== undefined &&
@@ -494,6 +520,10 @@ async function runCampaign(
result = await options.recoverScan(scanDir, {
...options,
knowledgeBaseSnapshot: knowledge?.snapshot,
+ ...observers,
+ ...(operationId === undefined
+ ? {}
+ : { telemetryContext: { operationId } }),
});
attemptedResume = result !== undefined;
}
@@ -550,6 +580,7 @@ async function runCampaign(
const scanPrompt = [options.scanPrompt?.trim(), task.prompt]
.filter(Boolean)
.join("\n\n");
+ operationId ??= randomUUID();
result = await security.run(checkout, {
...scanSettings,
knowledgeBaseSnapshot: knowledge?.snapshot,
@@ -560,6 +591,7 @@ async function runCampaign(
? { knowledgeBasePaths: options.knowledgeBasePaths }
: {}),
mode: task.mode,
+ telemetryContext: { operationId },
outputDir: scanDir,
...(scanPrompt ? { scanPrompt } : {}),
...(options.validationPrompt === undefined
@@ -571,6 +603,7 @@ async function runCampaign(
...(options.maxCostUsd === undefined
? {}
: { maxCostUsd: options.maxCostUsd }),
+ ...observers,
onWarning: (warning) => {
runWarnings.push(warning);
notifyProgress(options, {
@@ -587,6 +620,7 @@ async function runCampaign(
}
threatModelPath = result.threatModelPath;
cost = result.cost;
+ savedUsage = result.usage;
const failureSeverity = scanSettings?.failureSeverity;
if (failureSeverity !== undefined) {
attemptPolicyFailed = result.findings.findings.some((finding) =>
@@ -597,7 +631,9 @@ async function runCampaign(
throw new Error(`Multiscan scan ${result.manifest.scan.status}.`);
} catch (error) {
if (error instanceof AttemptNumberExhaustedError) throw error;
- if (options.signal?.aborted === true) options.signal.throwIfAborted();
+ // Recovery retains its resumable attempt and checkout; SDK telemetry records cancellation.
+ if (options.signal?.aborted && options.recoverScan !== undefined)
+ options.signal.throwIfAborted();
if (error instanceof ScanCostLimitExceededError) {
cost = error.cost;
exhaustedBudget = true;
@@ -621,7 +657,7 @@ async function runCampaign(
threatModelPath = await readThreatModelPath(scanDir, {
pythonPath: options.config.pythonPath,
protectedRoot,
- signal: options.signal,
+ signal: options.signal?.aborted ? undefined : options.signal,
});
const recoveryCheckout =
options.recoverScan !== undefined && failure === undefined
@@ -631,9 +667,13 @@ async function runCampaign(
...task,
status,
attempt,
+ ...(operationId === undefined ? {} : { operationId }),
outputDir: scanDir,
...(threatModelPath === null ? {} : { threatModelPath }),
...(cost === null ? {} : { cost }),
+ ...(measurement === null ? {} : { measurement }),
+ ...(savedUsage === undefined ? {} : { usage: savedUsage }),
+ outcome: options.signal?.aborted ? "canceled" : status,
...(reportedError === undefined ? {} : { error: reportedError }),
...(recoveryCheckout !== undefined
? { cleanupPending: "recovery-checkout" }
@@ -649,6 +689,7 @@ async function runCampaign(
appendReceipt(ledger, receiptLine),
);
await receiptTail;
+ options.signal?.throwIfAborted();
if (recoveryCheckout !== undefined) {
reportedError = await removeCheckout(recoveryCheckout);
}
diff --git a/sdk/typescript/src/operation-telemetry.ts b/sdk/typescript/src/operation-telemetry.ts
new file mode 100644
index 000000000..cbbf01814
--- /dev/null
+++ b/sdk/typescript/src/operation-telemetry.ts
@@ -0,0 +1,437 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+ appendFile,
+ mkdir,
+ readFile,
+ readdir,
+ writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import type { ScanUsageMeasurement } from "./cost.js";
+import {
+ canonicalConfigPath,
+ requireOutputOutsideRepositories,
+ requireSecureOutputAncestry,
+} from "./runtime.js";
+import { gitProtectionRoots } from "./targets.js";
+import { VERSION } from "./version.js";
+
+export type OperationOutcome =
+ "completed" | "failed" | "canceled" | "unresolved";
+export type OperationFailureCategory =
+ | "configuration"
+ | "authentication"
+ | "input"
+ | "budget"
+ | "execution"
+ | "canceled";
+
+/** Content-free operational receipts. IDs are for joins, never metric labels. */
+export interface OperationTelemetryEvent {
+ schemaVersion: 1;
+ eventId: string;
+ operationId: string;
+ attemptId: string;
+ parentAttemptId?: string;
+ /** Resumed scans share a cumulative measurement scope; never sum those receipts. */
+ usageScopeId: string;
+ occurredAt: string;
+ observedAt: string;
+ type: "attempt_started" | "attempt_finished";
+ command:
+ | "scan"
+ | "patch"
+ | "validate"
+ | "policy"
+ | "verify-fix"
+ | "assess-patch-risk";
+ surface: "cli" | "sdk";
+ packageVersion: string;
+ mode?: "standard" | "deep";
+ resumed: boolean;
+ /** True when this call returned a saved result without starting new work. */
+ reusedResult?: boolean;
+ outcome?: OperationOutcome;
+ failureCategory?: OperationFailureCategory;
+ durationMs?: number;
+ measurement?: Readonly<ScanUsageMeasurement>;
+ findingCount?: number;
+ reviewedSurfaceCount?: number;
+ deferredCount?: number;
+ pluginVersion?: string;
+ providerFamily?: string;
+ validationDisposition?:
+ "reportable" | "suppressed" | "not_applicable" | "deferred";
+ artifactComplete?: boolean;
+ collection: { persisted: number; writeFailures: number };
+}
+
+interface OperationTelemetryOptions {
+ directory: string;
+ protectedRepository?: string;
+ protectedOutput?: string;
+ command: OperationTelemetryEvent["command"];
+ surface: OperationTelemetryEvent["surface"];
+ mode?: OperationTelemetryEvent["mode"];
+ resumeScanId?: string;
+ deferPersistence?: boolean;
+ context?: { operationId: string; parentAttemptId?: string };
+ onEvent?: (event: Readonly<OperationTelemetryEvent>) => void;
+ onError?: (error: unknown) => void;
+}
+
+/** Local journal only. Export, acknowledgement and retention belong to the host. */
+export class OperationTelemetry {
+ readonly attemptId = randomUUID();
+ operationId: string;
+ measurement: Readonly<ScanUsageMeasurement> | undefined;
+ reusedResult = false;
+ nativeTurnFailed = false;
+ readonly #started = performance.now();
+ readonly #startedAt = new Date().toISOString();
+ readonly #options: OperationTelemetryOptions;
+ readonly #directory: string;
+ #persisted = 0;
+ #writeFailures = 0;
+ #ready = false;
+ #runtime: Pick<OperationTelemetryEvent, "pluginVersion" | "providerFamily"> =
+ {};
+ #finished = false;
+ #usageScopeId: string = this.attemptId;
+ #deferred: boolean;
+ #startedEvent: OperationTelemetryEvent | undefined;
+
+ constructor(options: OperationTelemetryOptions) {
+ this.#options = options;
+ this.operationId = options.context?.operationId ?? randomUUID();
+ this.#directory = join(options.directory, "telemetry");
+ this.#deferred = options.deferPersistence === true;
+ }
+
+ get context() {
+ return {
+ operationId: this.operationId,
+ attemptId: this.attemptId,
+ ...(this.#options.context?.parentAttemptId === undefined
+ ? {}
+ : { parentAttemptId: this.#options.context.parentAttemptId }),
+ };
+ }
+
+ async start(): Promise<void> {
+ if (!this.#deferred) await this.#preparePersistence();
+ await this.#emit("attempt_started");
+ }
+
+ /** Callers establish repository and artifact protection before any writes. */
+ async activatePersistence(
+ protectedRoots: readonly string[],
+ savedOutput?: string,
+ ): Promise<void> {
+ if (!this.#deferred || this.#finished) return;
+ this.#deferred = false;
+ await this.#preparePersistence(protectedRoots, savedOutput);
+ if (this.#startedEvent !== undefined) {
+ const event = {
+ ...this.#startedEvent,
+ ...this.context,
+ usageScopeId: this.#usageScopeId,
+ collection: {
+ persisted: this.#persisted + (this.#ready ? 1 : 0),
+ writeFailures: this.#writeFailures,
+ },
+ };
+ if (this.#ready) await this.#persist(event);
+ if (this.#options.resumeScanId !== undefined) this.#notify(event);
+ }
+ this.#startedEvent = undefined;
+ }
+
+ async #preparePersistence(
+ additionalRoots: readonly string[] = [],
+ savedOutput?: string,
+ ): Promise<void> {
+ try {
+ const protectedRoots = [...additionalRoots];
+ for (const output of [this.#options.protectedOutput, savedOutput]) {
+ if (output !== undefined)
+ protectedRoots.push(await canonicalConfigPath(output));
+ }
+ if (this.#options.protectedRepository !== undefined) {
+ const repository = await canonicalConfigPath(
+ this.#options.protectedRepository,
+ );
+ protectedRoots.push(
+ repository,
+ ...(await gitProtectionRoots(this.#options.protectedRepository)),
+ );
+ }
+ if (protectedRoots.length > 0) {
+ requireOutputOutsideRepositories(
+ protectedRoots,
+ await canonicalConfigPath(this.#directory),
+ "runtime",
+ );
+ }
+ await requireSecureOutputAncestry(this.#directory);
+ await mkdir(this.#directory, { recursive: true, mode: 0o700 });
+ this.#ready = true;
+ if (this.#options.resumeScanId !== undefined) {
+ try {
+ const saved = JSON.parse(
+ await readFile(
+ this.#bindingPath(this.#options.resumeScanId),
+ "utf8",
+ ),
+ ) as { operationId: string; usageScopeId: string };
+ this.operationId = saved.operationId;
+ this.#usageScopeId = saved.usageScopeId;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+ this.#error(error);
+ }
+ }
+ } catch (error) {
+ this.#error(error);
+ }
+ }
+
+ async bindScan(scanId: string): Promise<void> {
+ if (!this.#ready) return;
+ try {
+ await writeFile(
+ this.#bindingPath(scanId),
+ JSON.stringify({
+ ...this.context,
+ usageScopeId: this.#usageScopeId,
+ }),
+ {
+ mode: 0o600,
+ },
+ );
+ } catch (error) {
+ this.#error(error);
+ }
+ }
+
+ describe(
+ runtime: Pick<OperationTelemetryEvent, "pluginVersion" | "providerFamily">,
+ ): void {
+ this.#runtime = runtime;
+ }
+
+ async finish(
+ outcome: OperationOutcome,
+ details: Pick<
+ OperationTelemetryEvent,
+ | "failureCategory"
+ | "findingCount"
+ | "artifactComplete"
+ | "reviewedSurfaceCount"
+ | "deferredCount"
+ | "validationDisposition"
+ > = {},
+ ): Promise<void> {
+ if (this.#finished) return;
+ this.#finished = true;
+ if (
+ this.#startedEvent !== undefined &&
+ this.#options.resumeScanId !== undefined
+ ) {
+ this.#notify(this.#startedEvent);
+ this.#startedEvent = undefined;
+ }
+ await this.#emit("attempt_finished", {
+ outcome,
+ reusedResult: this.reusedResult,
+ durationMs: Math.max(0, performance.now() - this.#started),
+ ...(this.measurement === undefined
+ ? {}
+ : { measurement: this.measurement }),
+ ...this.#runtime,
+ ...details,
+ });
+ }
+
+ #bindingPath(scanId: string): string {
+ return join(
+ this.#directory,
+ `${createHash("sha256").update(scanId).digest("hex")}.binding.json`,
+ );
+ }
+
+ #error(error: unknown): void {
+ this.#writeFailures++;
+ try {
+ this.#options.onError?.(error);
+ } catch {}
+ }
+
+ async #persist(event: OperationTelemetryEvent): Promise<void> {
+ try {
+ await appendFile(
+ join(this.#directory, `${this.attemptId}.jsonl`),
+ `${JSON.stringify(event)}\n`,
+ { mode: 0o600 },
+ );
+ this.#persisted++;
+ } catch (error) {
+ this.#error(error);
+ event.collection = {
+ persisted: this.#persisted,
+ writeFailures: this.#writeFailures,
+ };
+ }
+ }
+
+ async #emit(
+ type: OperationTelemetryEvent["type"],
+ details: Partial<OperationTelemetryEvent> = {},
+ ): Promise<void> {
+ const time = new Date().toISOString();
+ const event: OperationTelemetryEvent = {
+ schemaVersion: 1,
+ eventId: `${this.attemptId}:${type}`,
+ ...this.context,
+ usageScopeId: this.#usageScopeId,
+ occurredAt: type === "attempt_started" ? this.#startedAt : time,
+ observedAt: time,
+ type,
+ command: this.#options.command,
+ surface: this.#options.surface,
+ packageVersion: VERSION,
+ ...(this.#options.mode === undefined ? {} : { mode: this.#options.mode }),
+ resumed: this.#options.resumeScanId !== undefined,
+ ...details,
+ collection: {
+ persisted: this.#persisted + (this.#ready ? 1 : 0),
+ writeFailures: this.#writeFailures,
+ },
+ };
+ if (this.#ready) await this.#persist(event);
+ else if (this.#deferred && type === "attempt_started") {
+ this.#startedEvent = event;
+ // Resume identity is restored only after the caller protects output paths.
+ if (this.#options.resumeScanId !== undefined) return;
+ }
+ this.#notify(event);
+ }
+
+ #notify(event: OperationTelemetryEvent): void {
+ // Observers cannot delay or fail the operation. Replay uses the same event ID.
+ void Promise.resolve()
+ .then(() => this.#options.onEvent?.(event))
+ .catch(() => {});
+ }
+}
+
+/** Read durable receipts, retaining explicit evidence of truncated/corrupt records. */
+export async function readOperationTelemetry(stateDirectory: string): Promise<{
+ events: OperationTelemetryEvent[];
+ parseFailures: number;
+}> {
+ const directory = join(stateDirectory, "telemetry");
+ const events: OperationTelemetryEvent[] = [];
+ let parseFailures = 0;
+ const names = await readdir(directory).catch(
+ (error: NodeJS.ErrnoException) => {
+ if (error.code === "ENOENT") return [];
+ throw error;
+ },
+ );
+ for (const name of names.filter((name) => name.endsWith(".jsonl")).sort()) {
+ for (const line of (await readFile(join(directory, name), "utf8")).split(
+ "\n",
+ )) {
+ if (!line) continue;
+ try {
+ const event = JSON.parse(line) as OperationTelemetryEvent;
+ if (
+ event.schemaVersion !== 1 ||
+ typeof event.eventId !== "string" ||
+ typeof event.attemptId !== "string" ||
+ typeof event.operationId !== "string" ||
+ typeof event.usageScopeId !== "string" ||
+ !["attempt_started", "attempt_finished"].includes(event.type) ||
+ ((event.type === "attempt_finished" || event.outcome !== undefined) &&
+ !["completed", "failed", "canceled", "unresolved"].includes(
+ event.outcome ?? "",
+ )) ||
+ (event.measurement !== undefined &&
+ !["complete", "partial", "unavailable"].includes(
+ event.measurement?.coverage,
+ ))
+ ) {
+ parseFailures++;
+ } else events.push(event);
+ } catch {
+ parseFailures++;
+ }
+ }
+ }
+ return { events, parseFailures };
+}
+
+/** Attempts without a terminal receipt remain unresolved, including process loss. */
+export function summarizeOperationTelemetry(
+ events: readonly OperationTelemetryEvent[],
+) {
+ const seen = new Set<string>();
+ const attempts = new Map<string, OperationTelemetryEvent>();
+ let duplicates = 0;
+ for (const event of events) {
+ if (seen.has(event.eventId)) {
+ duplicates++;
+ continue;
+ }
+ seen.add(event.eventId);
+ const previous = attempts.get(event.attemptId);
+ if (
+ previous?.type !== "attempt_finished" ||
+ event.type === "attempt_finished"
+ )
+ attempts.set(event.attemptId, event);
+ }
+ const operations = new Map<string, boolean>();
+ const outcomes = { completed: 0, failed: 0, canceled: 0, unresolved: 0 };
+ const usageCoverage = { complete: 0, partial: 0, unavailable: 0 };
+ const durationMs: number[] = [];
+ let observedCostUsd = 0;
+ let pricedAttempts = 0;
+ let reusedAttempts = 0;
+ const costsByScope = new Map<string, number>();
+ for (const event of attempts.values()) {
+ operations.set(
+ event.operationId,
+ operations.get(event.operationId) === true ||
+ event.outcome === "completed",
+ );
+ outcomes[event.outcome ?? "unresolved"]++;
+ if (event.reusedResult === true) reusedAttempts++;
+ else usageCoverage[event.measurement?.coverage ?? "unavailable"]++;
+ if (event.durationMs !== undefined) durationMs.push(event.durationMs);
+ if (event.measurement?.cost != null) {
+ costsByScope.set(
+ event.usageScopeId,
+ Math.max(
+ costsByScope.get(event.usageScopeId) ?? 0,
+ event.measurement.cost.estimatedUsd,
+ ),
+ );
+ pricedAttempts++;
+ }
+ }
+ for (const cost of costsByScope.values()) observedCostUsd += cost;
+ return {
+ operations: operations.size,
+ successfulOperations: [...operations.values()].filter(Boolean).length,
+ attempts: attempts.size,
+ outcomes,
+ usageCoverage,
+ durationMs,
+ observedCostUsd,
+ pricedAttempts,
+ reusedAttempts,
+ duplicates,
+ };
+}
diff --git a/sdk/typescript/src/provider-profile.ts b/sdk/typescript/src/provider-profile.ts
index bd357db67..ad6eeadb2 100644
--- a/sdk/typescript/src/provider-profile.ts
+++ b/sdk/typescript/src/provider-profile.ts
@@ -35,7 +35,7 @@ export interface ProviderProfile {
cleanup(): Promise<void>;
}
-/** Native no-turn commands need provider metadata when managed policy selects it. */
+/** Keep provider metadata, analytics consent, and attribution on no-turn commands. */
export async function providerPreflightCommand(
command: CodexCommand,
config: JsonObject,
@@ -54,6 +54,12 @@ export async function providerPreflightCommand(
}
if (resolved["model_provider"] !== undefined)
overrides.push(`model_provider=${inlineToml(resolved["model_provider"])}`);
+ // These commands cannot load a private profile while preserving their auth
+ // home. Exporter headers stay in native configuration, never copied into argv.
+ for (const key of ["analytics", "responses_api_metadata"]) {
+ const value = resolved[key];
+ if (value !== undefined) overrides.push(`${key}=${inlineToml(value)}`);
+ }
if (overrides.length === 0) return command;
return {
...command,
diff --git a/sdk/typescript/src/publication-telemetry.ts b/sdk/typescript/src/publication-telemetry.ts
new file mode 100644
index 000000000..b44df33ef
--- /dev/null
+++ b/sdk/typescript/src/publication-telemetry.ts
@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+
+/** Content-free publication accounting, also stored on existing publication receipts. */
+export interface PublicationTelemetry {
+ schemaVersion: 1;
+ attemptId: string;
+ destination: "linear" | "custom";
+ startedAt: string;
+ observedAt: string;
+ /** Elapsed time through this snapshot; receipt persistence may follow. */
+ durationMs: number;
+ attempted: boolean;
+ outcome: "completed" | "failed" | "canceled" | "indeterminate" | "preview";
+ counts: {
+ /** Null when preparation did not determine the selected findings. */
+ selected: number | null;
+ /** Findings handed to publication; this is not an HTTP request count. */
+ submitted: number;
+ /** Confirmed creations, excluding unverified mutations; null when not reported. */
+ created: number | null;
+ /** Confirmed reuse; null when remote upserts do not distinguish existing records. */
+ reused: number | null;
+ /** Findings acknowledged by the destination, whether new or already present. */
+ acknowledged: number | null;
+ /** Reconciled failures; null when the mutation outcome is unknown. */
+ failed: number | null;
+ };
+}
+
+export type PublicationTelemetryObserver = (
+ telemetry: Readonly<PublicationTelemetry>,
+) => void;
+
+/** Enrich receipts and notify an optional host; no transport or additional storage. */
+export class PublicationTelemetryRecorder {
+ readonly attemptId = randomUUID();
+ readonly startedAt = new Date().toISOString();
+ readonly started = performance.now();
+ attempted = false;
+ counts: PublicationTelemetry["counts"] = {
+ selected: null,
+ submitted: 0,
+ created: 0,
+ reused: 0,
+ acknowledged: 0,
+ failed: 0,
+ };
+ outcome: PublicationTelemetry["outcome"] = "failed";
+
+ constructor(
+ private readonly destination: PublicationTelemetry["destination"],
+ private readonly observer?: PublicationTelemetryObserver,
+ ) {}
+
+ snapshot(outcome = this.outcome): PublicationTelemetry {
+ return Object.freeze({
+ schemaVersion: 1,
+ attemptId: this.attemptId,
+ destination: this.destination,
+ startedAt: this.startedAt,
+ observedAt: new Date().toISOString(),
+ durationMs: Math.max(0, performance.now() - this.started),
+ attempted: this.attempted,
+ outcome,
+ counts: Object.freeze({ ...this.counts }),
+ });
+ }
+
+ notify(telemetry: PublicationTelemetry): void {
+ void Promise.resolve()
+ .then(() => this.observer?.(telemetry))
+ .catch(() => {});
+ }
+}
diff --git a/sdk/typescript/src/publish.ts b/sdk/typescript/src/publish.ts
index 7dcb2f5b8..9bd05f2e6 100644
--- a/sdk/typescript/src/publish.ts
+++ b/sdk/typescript/src/publish.ts
@@ -1,4 +1,9 @@
import { findingEntry, notify } from "./value.js";
+import {
+ PublicationTelemetryRecorder,
+ type PublicationTelemetry,
+ type PublicationTelemetryObserver,
+} from "./publication-telemetry.js";
import type { CodexSecuritySurface } from "./api.js";
import { codexSecurityRequestContext } from "./request-metadata.js";
import {
@@ -80,6 +85,8 @@ export interface PublishScanOptions extends Pick<
dryRun?: boolean;
skipExisting?: boolean;
onProgress?: (event: PublishScanProgress) => void;
+ /** Best-effort content-free outcome accounting, including preparation failures. */
+ onTelemetry?: PublicationTelemetryObserver;
}
export type PublishScanProgress =
@@ -130,6 +137,7 @@ export interface PublishScanResult {
issues?: PreparedPublicationIssue[];
indeterminate?: boolean;
warnings?: string[];
+ telemetry?: PublicationTelemetry;
}
export type CheckScanPublicationOptions = Pick<
@@ -239,6 +247,42 @@ export async function publishScanInternal(
scanDirectory: string,
options: PublishScanOptions,
dependencies: PublishScanDependencies = {},
+): Promise<PublishScanResult> {
+ const telemetry = new PublicationTelemetryRecorder(
+ "linear",
+ options.onTelemetry,
+ );
+ try {
+ const result = await publishScanAttempt(
+ scanDirectory,
+ options,
+ dependencies,
+ telemetry,
+ );
+ result.telemetry ??= telemetry.snapshot(
+ options.dryRun ? "preview" : "completed",
+ );
+ telemetry.notify(result.telemetry);
+ return result;
+ } catch (error) {
+ telemetry.notify(
+ telemetry.snapshot(
+ telemetry.outcome === "indeterminate"
+ ? "indeterminate"
+ : options.signal?.aborted
+ ? "canceled"
+ : "failed",
+ ),
+ );
+ throw error;
+ }
+}
+
+async function publishScanAttempt(
+ scanDirectory: string,
+ options: PublishScanOptions,
+ dependencies: PublishScanDependencies,
+ telemetry: PublicationTelemetryRecorder,
): Promise<PublishScanResult> {
options.signal?.throwIfAborted();
const environment = dependencies.environment ?? process.env;
@@ -249,6 +293,7 @@ export async function publishScanInternal(
{ ...options, environment },
);
let prepared = preparedScan;
+ telemetry.counts.selected = preparedScan.issues.length;
options.signal?.throwIfAborted();
const result: PublishScanResult = {
scanId: prepared.scanId,
@@ -267,6 +312,7 @@ export async function publishScanInternal(
dependencies.inspectPublicationStore ?? inspectPublicationStore
)(preparedScan, environment, options.signal);
result.counts.skipped = result.skipped.length;
+ telemetry.counts.reused = result.skipped.length;
const recorded = new Set(result.skipped.map((issue) => issue.findingId));
prepared = {
...preparedScan,
@@ -276,7 +322,22 @@ export async function publishScanInternal(
};
options.signal?.throwIfAborted();
}
- const saveReceipt = dependencies.writeReceipt ?? writePublicationReceipt;
+ const saveReceipt = async (
+ receipt: PublishScanResult,
+ environment: NodeJS.ProcessEnv,
+ ) => {
+ receipt.telemetry = telemetry.snapshot(
+ receipt.indeterminate
+ ? "indeterminate"
+ : options.signal?.aborted
+ ? "canceled"
+ : telemetry.outcome,
+ );
+ await (dependencies.writeReceipt ?? writePublicationReceipt)(
+ receipt,
+ environment,
+ );
+ };
if (options.dryRun) {
return { ...result, dryRun: true, issues: prepared.issues };
}
@@ -325,6 +386,12 @@ export async function publishScanInternal(
total: prepared.issues.length,
});
let invocation: PublicationCodexResult | undefined;
+ telemetry.attempted = true;
+ telemetry.counts.submitted = prepared.issues.length;
+ telemetry.counts.created = null;
+ telemetry.counts.acknowledged = null;
+ telemetry.counts.failed = null;
+ telemetry.outcome = "indeterminate";
if (linearClient !== undefined) {
await publishLinearApiIssues(
prepared,
@@ -340,6 +407,7 @@ export async function publishScanInternal(
{
surface: dependencies.surface ?? "sdk",
command: "publish",
+ attemptId: telemetry.attemptId,
// Native Codex resolves provider and metadata from all its config layers.
providerResolved: false,
},
@@ -436,6 +504,16 @@ export async function publishScanInternal(
}
result.failed = handoffResults.failed;
result.counts.failed = result.failed.length;
+ telemetry.counts.created = handoffResults.created.length;
+ telemetry.counts.acknowledged = handoffResults.created.length;
+ telemetry.counts.failed = handoffResults.indeterminate
+ ? null
+ : handoffResults.failed.length;
+ telemetry.outcome = handoffResults.indeterminate
+ ? "indeterminate"
+ : handoffResults.failed.length > 0
+ ? "failed"
+ : "completed";
if (progressObserver !== undefined) {
const outcomes = new Map(
[...handoffResults.created, ...handoffResults.failed].map(findingEntry),
diff --git a/sdk/typescript/src/request-metadata.ts b/sdk/typescript/src/request-metadata.ts
index 6d9c3bd97..31e6b24d0 100644
--- a/sdk/typescript/src/request-metadata.ts
+++ b/sdk/typescript/src/request-metadata.ts
@@ -8,6 +8,9 @@ interface RequestContextOptions {
surface: CodexSecuritySurface;
command: string;
pluginVersion?: string;
+ operationId?: string;
+ attemptId?: string;
+ parentAttemptId?: string;
mode?: ScanMode;
/** False when this caller leaves provider selection to native config layers. */
providerResolved?: boolean;
@@ -26,6 +29,15 @@ export function codexSecurityRequestContext(
codex_security_surface: context.surface,
codex_security_command: context.command,
codex_security_package_version: VERSION,
+ ...(context.operationId === undefined
+ ? {}
+ : { codex_security_operation_id: context.operationId }),
+ ...(context.attemptId === undefined
+ ? {}
+ : { codex_security_attempt_id: context.attemptId }),
+ ...(context.parentAttemptId === undefined
+ ? {}
+ : { codex_security_parent_attempt_id: context.parentAttemptId }),
...(context.pluginVersion === undefined
? {}
: { codex_security_plugin_version: context.pluginVersion }),
diff --git a/sdk/typescript/src/runtime.ts b/sdk/typescript/src/runtime.ts
index 57f993513..812e95985 100644
--- a/sdk/typescript/src/runtime.ts
+++ b/sdk/typescript/src/runtime.ts
@@ -1742,7 +1742,17 @@ export async function runWorkbench(
: WORKBENCH_SCRIPT_PROGRAM),
script,
],
- pluginHelperEnvironment(node?.environment ?? options.environment),
+ pluginHelperEnvironment({
+ ...(node?.environment ?? options.environment),
+ // Python's compressed-rollout reader needs the selected Node even when
+ // this SDK was launched by absolute path without Node on PATH.
+ ...(!native &&
+ !process.versions["bun"] &&
+ environmentValue(options.environment, "CODEX_MCP_NODE_PATH") ===
+ undefined
+ ? { CODEX_MCP_NODE_PATH: process.execPath }
+ : {}),
+ }),
// The SDK owns configuration normalization; the helper receives its resolved location.
nativeLocalDedupe
? `{"stateDirectory":${JSON.stringify(stateDirectory)},"payload":${input ?? "null"}}`
diff --git a/sdk/typescript/src/scan-dashboard.ts b/sdk/typescript/src/scan-dashboard.ts
index 91aa35345..d99a11642 100644
--- a/sdk/typescript/src/scan-dashboard.ts
+++ b/sdk/typescript/src/scan-dashboard.ts
@@ -17,6 +17,7 @@ import {
formatUsd,
type ScanCost,
type ScanSessionEvent,
+ type ScanUsageMeasurement,
type ScanUsageObservation,
} from "./cost.js";
import {
@@ -173,6 +174,7 @@ export class ScanDashboard {
#publicationProgress: { completed: number; total: number } | null = null;
#cost: Readonly<ScanCost> | null = null;
#tokens: string | null = null;
+ #usageCoverage: ScanUsageMeasurement["coverage"] | null = null;
#usageFreshness: string | null = null;
#accountLimits: string | null = null;
#chatGptAuth = false;
@@ -511,7 +513,9 @@ export class ScanDashboard {
);
}
}
- if (receipt.cost !== undefined) dashboard.setCost(receipt.cost);
+ if (receipt.measurement !== undefined)
+ dashboard.setMeasurement(receipt.measurement);
+ else if (receipt.cost !== undefined) dashboard.setCost(receipt.cost);
component.receipt = { ...receipt };
this.#refresh();
}
@@ -553,6 +557,9 @@ export class ScanDashboard {
case "usage":
dashboard.setUsage(event.value);
break;
+ case "measurement":
+ dashboard.setMeasurement(event.value);
+ break;
case "usage-observation":
dashboard.setUsageObservation(event.value);
break;
@@ -594,13 +601,23 @@ export class ScanDashboard {
cost: Readonly<ScanCost>,
maxCostUsd = this.#options.maxCostUsd,
): void {
+ this.#usageCoverage = "complete";
this.#cost = cost;
this.#tokens = formatScanCostTokens(cost);
this.#options.maxCostUsd = maxCostUsd;
this.#refresh();
}
+ public setMeasurement(measurement: Readonly<ScanUsageMeasurement>): void {
+ this.#usageCoverage = measurement.coverage;
+ this.#cost = measurement.cost;
+ this.#tokens =
+ measurement.usage === null ? null : formatTokenUsage(measurement.usage);
+ this.#refresh();
+ }
+
public setUsage(usage: Readonly<ScanTokenUsage>): void {
+ this.#usageCoverage = "complete";
this.#tokens = formatTokenUsage(usage);
this.#refresh();
}
@@ -983,8 +1000,8 @@ export class ScanDashboard {
);
const costWidth = Math.max(
8,
- ...this.#components.map(({ dashboard }) =>
- dashboard.#cost === null ? 1 : formatScanCost(dashboard.#cost).length,
+ ...this.#components.map(
+ ({ dashboard }) => dashboard.#componentCostLabel().length,
),
);
const nameAndStatusWidth =
@@ -1018,7 +1035,7 @@ export class ScanDashboard {
receipt.findingCount === undefined
? "—"
: formatCount(receipt.findingCount),
- dashboard.#cost === null ? "—" : formatScanCost(dashboard.#cost),
+ dashboard.#componentCostLabel(),
),
);
if (table.length === 0) table.push(` ${this.#stage}…`);
@@ -1058,6 +1075,12 @@ export class ScanDashboard {
);
}
+ #componentCostLabel(): string {
+ return this.#cost === null
+ ? "—"
+ : `${formatScanCost(this.#cost)}${this.#usageCoverage === "partial" ? " (partial)" : ""}`;
+ }
+
#componentCostLines(): string[] {
if (!this.#showCost) return [];
const costs = this.#components.flatMap(({ dashboard }) =>
@@ -1065,7 +1088,7 @@ export class ScanDashboard {
);
return wrapActivity(
" COST ",
- `${costs.length === 0 ? "waiting for usage" : formatScanCosts(costs)} · component scans only`,
+ `${costs.length === 0 ? "waiting for usage" : formatScanCosts(costs)}${this.#components.some(({ dashboard }) => dashboard.#usageCoverage !== "complete") ? " (partial)" : ""} · component scans only`,
this.#width(),
);
}
@@ -1100,15 +1123,15 @@ export class ScanDashboard {
return { footer: [], details: [] };
}
const width = this.#width();
+ const tokens =
+ this.#usageCoverage === "unavailable"
+ ? "usage unavailable"
+ : `${this.#tokens ?? "waiting for usage"}${this.#usageCoverage === "partial" ? " (partial)" : ""}`;
const limits =
this.#accountLimits ??
(this.#chatGptAuth ? ACCOUNT_LIMITS_UNAVAILABLE : null);
const lines = [
- ...wrapActivity(
- " TOKENS ",
- this.#tokens ?? "waiting for usage",
- width,
- ),
+ ...wrapActivity(" TOKENS ", tokens, width),
...this.#costLines(),
...(this.#tokens === null
? []
@@ -1155,7 +1178,11 @@ export class ScanDashboard {
? "waiting for usage"
: `— / ${formatUsd(this.#options.maxCostUsd)}`
: `${formatScanCost(this.#cost)}${this.#options.maxCostUsd === undefined ? "" : `; short-context budget baseline: ${formatUsd(this.#cost.estimatedUsd)} / ${formatUsd(this.#options.maxCostUsd)} · ${budgetBar(this.#cost.estimatedUsd, this.#options.maxCostUsd)}`}`;
- return wrapActivity(" COST ", cost, this.#width());
+ return wrapActivity(
+ " COST ",
+ `${cost}${this.#usageCoverage === "partial" ? " (partial)" : this.#usageCoverage === "unavailable" ? " (usage unavailable)" : ""}`,
+ this.#width(),
+ );
}
#activityLines(width: number): DashboardActivityLine[] {
diff --git a/sdk/typescript/src/scan-executor.ts b/sdk/typescript/src/scan-executor.ts
index 6fef92bb3..84a214011 100644
--- a/sdk/typescript/src/scan-executor.ts
+++ b/sdk/typescript/src/scan-executor.ts
@@ -28,6 +28,8 @@ export interface ScanExecutionRequest {
outputDirectory: string;
/** Runtime context only. Credentials belong to the host executor. */
environment: Record<string, string>;
+ /** Per-attempt attribution; IDs are for correlation, not metric labels. */
+ requestMetadata?: Readonly<Record<string, string>>;
};
}
@@ -101,9 +103,13 @@ export interface ScanExecutor {
/** Carries the exact execution outcome even when finalization cannot complete. */
export class ScanExecutionError extends CodexSecurityError {
+ /** Foreign receipts remain available for reconciliation, not accounting. */
+ readonly receiptMatchesRequest: boolean;
+
constructor(
public readonly result: ScanExecutionResult,
message?: string,
+ options: { receiptMatchesRequest?: boolean } = {},
) {
super(
message ??
@@ -111,6 +117,7 @@ export class ScanExecutionError extends CodexSecurityError {
result.error?.message ??
`Hosted execution ${result.status}.`,
);
+ this.receiptMatchesRequest = options.receiptMatchesRequest ?? true;
}
}
diff --git a/sdk/typescript/src/scan-logs.ts b/sdk/typescript/src/scan-logs.ts
index 0b94e1620..9f08cc55f 100644
--- a/sdk/typescript/src/scan-logs.ts
+++ b/sdk/typescript/src/scan-logs.ts
@@ -1,9 +1,6 @@
-import { createReadStream } from "node:fs";
import { basename, dirname, join, relative } from "node:path";
-import { createInterface } from "node:readline";
-import { pipeline } from "node:stream";
import { isDeepStrictEqual } from "node:util";
-import zlib from "node:zlib";
+import { sessionLines } from "./session-lines.js";
import { isRecord } from "./record.js";
import { sessionFiles } from "./cost.js";
import { CodexSecurityError } from "./errors.js";
@@ -69,17 +66,10 @@ export function readSavedScanLogs(
});
}
-// Codex can compress cold rollouts to `.jsonl.zst`. Node 22.13 and 22.14 lack
-// zstd, so they still read plain rollouts only.
-const readsCompressedSessions = typeof zlib.createZstdDecompress === "function";
-
type SessionLog = NonNullable<Awaited<ReturnType<typeof findScanSession>>>;
async function* scanSessions(codexHome: string, directory = "sessions") {
- for await (const path of sessionFiles(
- join(codexHome, directory),
- readsCompressedSessions,
- )) {
+ for await (const path of sessionFiles(join(codexHome, directory), true)) {
for await (const first of sessionEvents(path)) {
if (first["type"] !== "session_meta" || !isRecord(first["payload"])) {
break;
@@ -282,13 +272,8 @@ async function extendsSessionLog(
async function* sessionEvents(
path: string,
): AsyncGenerator<Record<string, unknown>> {
- const file = createReadStream(path);
- const stream = path.endsWith(".zst")
- ? pipeline(file, zlib.createZstdDecompress(), () => {})
- : file;
- const lines = createInterface({ input: stream, crlfDelay: Infinity });
try {
- for await (const line of lines) {
+ for await (const line of sessionLines(path)) {
if (line.trim() === "") continue;
try {
const event: unknown = JSON.parse(line);
@@ -299,8 +284,5 @@ async function* sessionEvents(
}
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
- } finally {
- lines.close();
- stream.destroy();
}
}
diff --git a/sdk/typescript/src/scan-measurement.ts b/sdk/typescript/src/scan-measurement.ts
new file mode 100644
index 000000000..178cda879
--- /dev/null
+++ b/sdk/typescript/src/scan-measurement.ts
@@ -0,0 +1,94 @@
+import { addTokenUsage, type ScanUsageMeasurement } from "./cost.js";
+import {
+ estimateScanCost,
+ tokenUsage,
+ type ScanTokenUsage,
+} from "./cost-model.js";
+
+export function measurementFromUsage(
+ value: unknown,
+ model: string,
+): ScanUsageMeasurement {
+ const usage = tokenUsage(value);
+ return {
+ usage,
+ cost: estimateScanCost(model, usage),
+ coverage: usage === null ? "unavailable" : "complete",
+ observedAt: new Date().toISOString(),
+ threadCount: usage === null ? 0 : 1,
+ missingThreadCount: usage === null ? 1 : 0,
+ };
+}
+
+/** Only for disjoint stage invocations, not cumulative observations of one thread. */
+export function combineMeasurements(
+ values: readonly Readonly<ScanUsageMeasurement>[],
+ model: string,
+): ScanUsageMeasurement {
+ let usage: ScanTokenUsage | null = null;
+ for (const value of values) {
+ if (value.usage !== null) usage = addTokenUsage(usage, value.usage);
+ }
+ const warnings = [
+ ...new Set(values.flatMap((value) => value.warnings ?? [])),
+ ].sort();
+ return {
+ ...measurementFromUsage(usage, model),
+ ...(warnings.length ? { warnings } : {}),
+ coverage:
+ usage === null
+ ? "unavailable"
+ : values.every((value) => value.coverage === "complete")
+ ? "complete"
+ : "partial",
+ threadCount: values.reduce((sum, value) => sum + value.threadCount, 0),
+ missingThreadCount: values.reduce(
+ (sum, value) => sum + value.missingThreadCount,
+ 0,
+ ),
+ ...(values.every((value) => value.coverageScope !== undefined)
+ ? {
+ coverageScope: [
+ ...new Set(values.flatMap((value) => value.coverageScope!)),
+ ].sort(),
+ }
+ : {}),
+ };
+}
+
+/** Workbench envelope keeps usage even when the selected model has no price. */
+export function measuredScanCost(
+ measurement: Readonly<ScanUsageMeasurement> | null,
+) {
+ if (measurement?.usage == null) return null;
+ const tokens = measurement.usage;
+ return {
+ usage: {
+ source: "codex_runtime",
+ coverage: measurement.coverage,
+ observedAt: measurement.observedAt,
+ threadCount: measurement.threadCount,
+ missingThreadCount: measurement.missingThreadCount,
+ // The workbench accepts up to 32 diagnostic codes across all stages.
+ ...(measurement.warnings?.length
+ ? { warnings: measurement.warnings.slice(0, 32) }
+ : {}),
+ ...(measurement.coverageScope === undefined
+ ? {}
+ : { coverageScope: measurement.coverageScope }),
+ inputTokens: tokens.input_tokens,
+ cachedInputTokens: tokens.cached_input_tokens,
+ cacheWriteInputTokens: tokens.cache_write_input_tokens,
+ ...(tokens.cache_write_input_tokens_reported === undefined
+ ? {}
+ : {
+ cacheWriteInputTokensReported:
+ tokens.cache_write_input_tokens_reported,
+ }),
+ outputTokens: tokens.output_tokens,
+ reasoningOutputTokens: tokens.reasoning_output_tokens,
+ totalTokens: tokens.total_tokens,
+ },
+ ...(measurement.cost === null ? {} : { cost: measurement.cost }),
+ };
+}
diff --git a/sdk/typescript/src/security-policy.ts b/sdk/typescript/src/security-policy.ts
index 50fe1ed14..6efd3445a 100644
--- a/sdk/typescript/src/security-policy.ts
+++ b/sdk/typescript/src/security-policy.ts
@@ -61,6 +61,7 @@ export interface SecurityPolicyOptions extends Pick<
| "onAuthentication"
| "onOutputDirReady"
| "onCost"
+ | "onTelemetry"
| "onWarning"
| "onObserverError"
> {
diff --git a/sdk/typescript/src/server/api.ts b/sdk/typescript/src/server/api.ts
index 036d1ad58..3654725bb 100644
--- a/sdk/typescript/src/server/api.ts
+++ b/sdk/typescript/src/server/api.ts
@@ -1,4 +1,8 @@
export { OpenAiFindingEmbedder } from "./embeddings.js";
-export type { FindingEmbedder } from "./embeddings.js";
+export type {
+ FindingEmbedder,
+ EmbeddingUsageObservation,
+ EmbeddingUsageObserver,
+} from "./embeddings.js";
export { SqliteFindingsStore } from "./sqlite-store.js";
export type { FindingEmbedding, FindingsStore } from "./storage.js";
diff --git a/sdk/typescript/src/server/embeddings.ts b/sdk/typescript/src/server/embeddings.ts
index c9bdef116..9ded9398a 100644
--- a/sdk/typescript/src/server/embeddings.ts
+++ b/sdk/typescript/src/server/embeddings.ts
@@ -16,6 +16,22 @@ export interface FindingEmbedder {
embed(findings: readonly Finding[]): Promise<FindingEmbedding[]>;
}
+/** One embedding batch, separate from scan model-token accounting. */
+export interface EmbeddingUsageObservation {
+ model: string;
+ /** Number of tokenized inputs in this batch, including chunks of long findings. */
+ inputCount: number;
+ /** Provider-reported input tokens; null means the response did not supply them. */
+ inputTokens: number | null;
+ /** Batch request and decoding outcome; final vector pooling belongs to embed(). */
+ outcome: "completed" | "failed" | "canceled";
+ durationMs: number;
+}
+
+export type EmbeddingUsageObserver = (
+ observation: Readonly<EmbeddingUsageObservation>,
+) => void;
+
interface Chunk {
findingIndex: number;
tokens: number[];
@@ -33,6 +49,7 @@ export class OpenAiFindingEmbedder implements FindingEmbedder {
) => Promise<Response> = fetch,
private readonly url: string = EMBEDDINGS_URL,
private readonly signal?: AbortSignal,
+ private readonly onUsage?: EmbeddingUsageObserver,
) {}
async embed(findings: readonly Finding[]): Promise<FindingEmbedding[]> {
@@ -81,6 +98,34 @@ export class OpenAiFindingEmbedder implements FindingEmbedder {
private async embedChunks(
chunks: Chunk[],
vectors: number[][],
+ ): Promise<void> {
+ const started = performance.now();
+ let inputTokens: number | null = null;
+ let outcome: EmbeddingUsageObservation["outcome"] = "failed";
+ try {
+ await this.requestChunks(chunks, vectors, (tokens) => {
+ inputTokens = tokens;
+ });
+ outcome = "completed";
+ } finally {
+ const observation = Object.freeze({
+ model: EMBEDDING_MODEL,
+ inputCount: chunks.length,
+ inputTokens,
+ outcome: this.signal?.aborted ? ("canceled" as const) : outcome,
+ durationMs: Math.max(0, performance.now() - started),
+ });
+ // Optional observers must neither reject nor delay embedding work.
+ void Promise.resolve()
+ .then(() => this.onUsage?.(observation))
+ .catch(() => {});
+ }
+ }
+
+ private async requestChunks(
+ chunks: Chunk[],
+ vectors: number[][],
+ onUsage: (inputTokens: number) => void,
): Promise<void> {
let response: Response;
try {
@@ -119,13 +164,24 @@ export class OpenAiFindingEmbedder implements FindingEmbedder {
);
}
- let payload: { model?: unknown; data?: unknown } | null;
+ let payload: {
+ model?: unknown;
+ data?: unknown;
+ usage?: { prompt_tokens?: unknown };
+ } | null;
try {
payload = (await response.json()) as typeof payload;
} catch {
this.signal?.throwIfAborted();
throw invalidEmbeddingResponse();
}
+ const inputTokens = payload?.usage?.prompt_tokens;
+ if (
+ typeof inputTokens === "number" &&
+ Number.isSafeInteger(inputTokens) &&
+ inputTokens >= 0
+ )
+ onUsage(inputTokens);
if (
payload?.model !== EMBEDDING_MODEL ||
!Array.isArray(payload.data) ||
diff --git a/sdk/typescript/src/session-lines.ts b/sdk/typescript/src/session-lines.ts
new file mode 100644
index 000000000..6d6f66a6c
--- /dev/null
+++ b/sdk/typescript/src/session-lines.ts
@@ -0,0 +1,34 @@
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { pipeline, type Transform } from "node:stream";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { bundledPluginRoot } from "./runtime.js";
+
+/** Plain and cold compressed rollouts have the same newline-delimited format. */
+export async function* sessionLines(path: string): AsyncGenerator<string> {
+ const decompressor = path.endsWith(".zst")
+ ? await sessionDecompressor()
+ : null;
+ const file = createReadStream(path);
+ const stream =
+ decompressor !== null ? pipeline(file, decompressor, () => {}) : file;
+ const lines = createInterface({ input: stream, crlfDelay: Infinity });
+ try {
+ yield* lines;
+ } finally {
+ lines.close();
+ stream.destroy();
+ }
+}
+
+async function sessionDecompressor(): Promise<Transform> {
+ // Decode every concatenated frame and reject truncated tails. Native Node
+ // Zstandard streams can finish successfully after only the first frame.
+ const decoder = (await import(
+ pathToFileURL(
+ join(await bundledPluginRoot(), "mcp", "session-decompression.mjs"),
+ ).href
+ )) as { createZstdDecompress: () => Transform };
+ return decoder.createZstdDecompress();
+}
diff --git a/sdk/typescript/src/skill-authentication.ts b/sdk/typescript/src/skill-authentication.ts
index 3c7517fea..f56527a2f 100644
--- a/sdk/typescript/src/skill-authentication.ts
+++ b/sdk/typescript/src/skill-authentication.ts
@@ -124,6 +124,7 @@ export function resolveSkillAuthentication(
configOverrides = modelProviderConfigOverride(overrides);
}
return {
+ config,
authentication,
provider,
providerConfiguration,
diff --git a/sdk/typescript/tests-ts/api-attribution-concurrency.test.ts b/sdk/typescript/tests-ts/api-attribution-concurrency.test.ts
index d530487e2..fb801a34e 100644
--- a/sdk/typescript/tests-ts/api-attribution-concurrency.test.ts
+++ b/sdk/typescript/tests-ts/api-attribution-concurrency.test.ts
@@ -239,6 +239,8 @@ describe("delegated scan attribution", () => {
codex_security_package_version: VERSION,
codex_security_provider: "openai",
codex_security_scan_mode: mode,
+ codex_security_operation_id: expect.any(String),
+ codex_security_attempt_id: expect.any(String),
});
const deepConfigPath =
options.env?.["CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH"];
diff --git a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
index 9da22ea6e..8778aa026 100644
--- a/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
+++ b/sdk/typescript/tests-ts/api-direct-deep-scan.test.ts
@@ -146,7 +146,17 @@ test.each([undefined, "Summarize the completed scan."])(
expect(result.turnResult.finalResponse).toBe(finalReport);
expect(result.cost?.inputTokens).toBe(100);
expect(JSON.parse(completionReceipt!)).toMatchObject({
- inputTokens: 100,
+ cost: { inputTokens: 100, outputTokens: 10 },
+ usage: {
+ source: "codex_runtime",
+ coverage: "complete",
+ inputTokens: 100,
+ outputTokens: 10,
+ totalTokens: 110,
+ threadCount: 2,
+ missingThreadCount: 0,
+ coverageScope: ["thread:discovery-session", "thread:engine-session"],
+ },
});
expect(result.toJSON()["turn"]).toMatchObject({
finalResponse: finalReport,
diff --git a/sdk/typescript/tests-ts/api-operation-registration.test.ts b/sdk/typescript/tests-ts/api-operation-registration.test.ts
index 99a3a4559..c826b0be1 100644
--- a/sdk/typescript/tests-ts/api-operation-registration.test.ts
+++ b/sdk/typescript/tests-ts/api-operation-registration.test.ts
@@ -1,14 +1,24 @@
-import { expect, spyOn, test } from "bun:test";
+import { afterEach, expect, spyOn, test } from "bun:test";
import { CodexSecurity } from "../src/api.js";
import * as targets from "../src/targets.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
-function client() {
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "operation-registration-",
+);
+afterEach(cleanup);
+
+async function client() {
const forbidden = () => {
throw new Error("Unexpected runtime or model boundary");
};
return new CodexSecurity(
{},
- { environment: {}, createCodex: forbidden, prepareRuntime: forbidden },
+ {
+ environment: { CODEX_SECURITY_STATE_DIR: await temporaryDirectory() },
+ createCodex: forbidden,
+ prepareRuntime: forbidden,
+ },
{ surface: "sdk" },
);
}
@@ -16,7 +26,7 @@ function client() {
test.each(["validate", "patch"] as const)(
"%s reserves its operation before serializing a finding",
async (method) => {
- const security = client();
+ const security = await client();
const gate = Promise.withResolvers<void>();
const signals: AbortSignal[] = [];
const normalize = spyOn(targets, "normalizeRepository").mockImplementation(
@@ -66,7 +76,7 @@ test.each(["validate", "patch"] as const)(
);
test("a synchronous operation callback failure permits same-turn retry", async () => {
- await using security = client();
+ await using security = await client();
const failure = new Error("Synthetic option getter");
const pending = security
.run("/synthetic-never-read", {
@@ -95,7 +105,7 @@ test("a synchronous operation callback failure permits same-turn retry", async (
});
test("an asynchronously rejected operation owns its slot until settlement", async () => {
- await using security = client();
+ await using security = await client();
const failure = new Error("Synthetic finding serialization");
const pending = security
.validate({
diff --git a/sdk/typescript/tests-ts/api-patch-usage.test.ts b/sdk/typescript/tests-ts/api-patch-usage.test.ts
new file mode 100644
index 000000000..cc9d3040d
--- /dev/null
+++ b/sdk/typescript/tests-ts/api-patch-usage.test.ts
@@ -0,0 +1,207 @@
+import { Codex } from "@openai/codex-sdk";
+import { afterEach, expect, test } from "bun:test";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { estimateScanCost, type ScanUsageMeasurement } from "../src/cost.js";
+import { ScanInterruptedError } from "../src/errors.js";
+import {
+ OperationTelemetry,
+ readOperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
+import { TestClient } from "./support/api-client.js";
+import { preparedRuntime } from "./support/api-events.js";
+import { nodeCommand } from "./support/shell.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "codex-security-patch-usage-",
+);
+afterEach(cleanup);
+
+const receipt = {
+ input_tokens: 100,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 10,
+ reasoning_output_tokens: 0,
+};
+const noChange = {
+ status: "no_change",
+ changedFiles: [],
+ verificationReport: "The synthetic finding is already safe.",
+ reason: null,
+};
+
+test.each([
+ "invalid JSON",
+ "invalid schema",
+ "valid no_change",
+ "canceled after completion",
+ "canceled on completion",
+ "nonzero exit after completion",
+ "nonzero exit before completion",
+ "null usage",
+ "absent usage",
+] as const)("preserves completed SDK patch usage with %s", async (ending) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const codexHome = join(root, "codex-home");
+ const state = join(root, "state");
+ await mkdir(repository);
+ await mkdir(codexHome);
+ const controller = new AbortController();
+ const observed: Readonly<OperationTelemetryEvent>[] = [];
+ const measurements: Readonly<ScanUsageMeasurement>[] = [];
+ const model = "gpt-5.6-terra";
+ const environment = {
+ CODEX_SECURITY_STATE_DIR: state,
+ OPENAI_API_KEY: "synthetic-patch-usage-key",
+ };
+ const usage =
+ ending === "null usage"
+ ? null
+ : ending === "absent usage" || ending === "nonzero exit before completion"
+ ? undefined
+ : receipt;
+ const response =
+ ending === "invalid JSON"
+ ? "not JSON"
+ : JSON.stringify(
+ ending === "invalid schema"
+ ? { ...noChange, verificationReport: " " }
+ : noChange,
+ );
+ const canceled =
+ ending === "canceled after completion" ||
+ ending === "canceled on completion";
+ const failedExit = ending.startsWith("nonzero exit");
+ const childScript = join(root, "patch-child.mjs");
+ await writeFile(
+ childScript,
+ [
+ "for await (const _chunk of process.stdin) {}",
+ "const send = (event) => console.log(JSON.stringify(event));",
+ 'send({ type: "thread.started", thread_id: "patch-usage-thread" });',
+ `send(${JSON.stringify({ type: "item.completed", item: { id: "result", type: "agent_message", text: response } })});`,
+ ...(ending === "nonzero exit before completion"
+ ? []
+ : [`send(${JSON.stringify({ type: "turn.completed", usage })});`]),
+ ...(canceled
+ ? ["setInterval(() => {}, 1_000);", "await new Promise(() => {});"]
+ : failedExit
+ ? [
+ 'process.stderr.write("Synthetic patch child exit diagnostic.\\n");',
+ "process.exit(17);",
+ ]
+ : ["process.exit(0);"]),
+ ].join("\n"),
+ );
+ let executions = 0;
+ await using client = new TestClient(
+ { codexOverrides: { model, analytics: { enabled: false } } },
+ {
+ environment,
+ prepareRuntime: async () => ({
+ ...preparedRuntime(codexHome),
+ environment,
+ }),
+ resolvePluginPython: async () => "/managed/python",
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ createCodex: (options) => {
+ const codex = new Codex({
+ ...options,
+ codexPathOverride: nodeCommand().command,
+ env: {
+ ...options.env,
+ NODE_OPTIONS: `--import=${pathToFileURL(childScript).href}`,
+ },
+ });
+ return {
+ startThread: (options) => {
+ const thread = codex.startThread(options);
+ const runStreamed = thread.runStreamed.bind(thread);
+ thread.runStreamed = async (...args) => {
+ executions++;
+ const { events } = await runStreamed(...args);
+ return {
+ events: (async function* () {
+ for await (const event of events) {
+ if (
+ event.type === "turn.completed" &&
+ ending === "canceled on completion"
+ ) {
+ controller.abort(new Error("Synthetic cancellation."));
+ }
+ yield event;
+ if (
+ event.type === "turn.completed" &&
+ ending === "canceled after completion"
+ ) {
+ controller.abort(new Error("Synthetic cancellation."));
+ }
+ }
+ })(),
+ };
+ };
+ return thread;
+ },
+ };
+ },
+ },
+ );
+ const pending = client.patch({
+ repositoryPath: repository,
+ finding: "Synthetic candidate finding.",
+ auth: "api-key",
+ signal: controller.signal,
+ onTelemetry: (event) => observed.push(event),
+ onMeasurement: (measurement) => measurements.push(measurement),
+ });
+ const invalid = ending === "invalid JSON" || ending === "invalid schema";
+ if (canceled) {
+ await expect(pending).rejects.toBeInstanceOf(ScanInterruptedError);
+ } else if (failedExit) {
+ await expect(pending).rejects.toThrow(
+ "Codex Exec exited with code 17: Synthetic patch child exit diagnostic.",
+ );
+ } else if (invalid) {
+ await expect(pending).rejects.toThrow(
+ "Finding patch returned an invalid result.",
+ );
+ } else {
+ expect(await pending).toMatchObject({
+ status: "no_change",
+ threadId: "patch-usage-thread",
+ cost: estimateScanCost(model, usage),
+ });
+ }
+ expect(executions).toBe(1);
+ await expect(access(join(codexHome, "sessions"))).rejects.toHaveProperty(
+ "code",
+ "ENOENT",
+ );
+ const saved = await readOperationTelemetry(state);
+ expect(saved.parseFailures).toBe(0);
+ expect(saved.events.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed.map((event) => event.eventId)).toEqual(
+ saved.events.map((event) => event.eventId),
+ );
+ const terminal = saved.events.at(-1)!;
+ expect(terminal.outcome).toBe(
+ canceled ? "canceled" : invalid || failedExit ? "failed" : "completed",
+ );
+ expect(terminal.measurement).toEqual(measurements.at(-1));
+ expect(terminal.measurement).toMatchObject({
+ usage:
+ usage == null
+ ? null
+ : { input_tokens: 100, output_tokens: 10, total_tokens: 110 },
+ coverage: usage == null ? "unavailable" : "complete",
+ cost: estimateScanCost(model, usage),
+ });
+});
diff --git a/sdk/typescript/tests-ts/api-policy.test.ts b/sdk/typescript/tests-ts/api-policy.test.ts
index dad43b350..ef4bc4282 100644
--- a/sdk/typescript/tests-ts/api-policy.test.ts
+++ b/sdk/typescript/tests-ts/api-policy.test.ts
@@ -24,12 +24,17 @@ import { afterEach, describe, expect, spyOn, test, mock } from "bun:test";
import { parse as parseToml } from "smol-toml";
import { scanRuntimeCodexConfig } from "../src/api.js";
import {
+ CodexSecurityError,
InvalidTargetError,
OutputDirectoryNotEmptyError,
securityPolicyDiff,
writeCodexConfig,
type SecurityPolicyStage,
} from "../src/index.js";
+import {
+ readOperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
import { preparedRuntime } from "./support/api-events.js";
import { InternalSecurity } from "./support/internal-security.js";
import type { PluginPythonOptions } from "../src/runtime.js";
@@ -1828,18 +1833,41 @@ describe("CodexSecurity policy API", () => {
test("enforces one cost budget across stages and preserves completed evidence", async () => {
const f = await setup();
- await expect(
- f.security.generatePolicy(f.repository, {
+ const observed: OperationTelemetryEvent[] = [];
+ try {
+ const result = f.security.generatePolicy(f.repository, {
outputDir: f.outputDir,
maxCostUsd: 0.001,
- }),
- ).rejects.toThrow("cost limit");
- expect(f.threads).toHaveLength(2);
- expect(
- await readFile(join(f.outputDir, "project-spec.md"), "utf8"),
- ).toContain("src/service.ts:1");
- expect(await readdir(f.repository)).toEqual([]);
- await f.security.close();
+ onTelemetry: (event) => observed.push(event),
+ });
+ await expect(result).rejects.toBeInstanceOf(CodexSecurityError);
+ await expect(result).rejects.toMatchObject({
+ name: CodexSecurityError.name,
+ message: `Security-policy generation exceeded its $0.001 cost limit; partial output remains at ${f.outputDir}.`,
+ });
+ expect(f.threads).toHaveLength(2);
+ expect(
+ await readFile(join(f.outputDir, "project-spec.md"), "utf8"),
+ ).toContain("src/service.ts:1");
+ expect(await readdir(f.repository)).toEqual([]);
+ const saved = await readOperationTelemetry(join(f.root, "state"));
+ expect(saved.parseFailures).toBe(0);
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]).toMatchObject({
+ command: "policy",
+ outcome: "failed",
+ failureCategory: "budget",
+ });
+ expect(saved.events.map((event) => event.eventId)).toEqual(
+ observed.map((event) => event.eventId),
+ );
+ expect(saved.events.at(-1)).toEqual(observed.at(-1));
+ } finally {
+ await f.security.close();
+ }
});
test("stops a policy stage at its measured budget while worker usage is missing", async () => {
@@ -1864,6 +1892,7 @@ describe("CodexSecurity policy API", () => {
{ parent: "policy-architecture" },
);
const costs = mock();
+ const observed: OperationTelemetryEvent[] = [];
const cancellation = new AbortController();
const timeout = setTimeout(
() => cancellation.abort(new Error("Policy budget was not enforced.")),
@@ -1876,11 +1905,17 @@ describe("CodexSecurity policy API", () => {
maxCostUsd: 0.004,
signal: cancellation.signal,
onCost: costs,
+ onTelemetry: (event) => observed.push(event),
}),
).rejects.toThrow("exceeded its $0.004 cost limit");
expect(interruptedStage).toBe("architecture");
expect(f.threads).toHaveLength(1);
expect(costs).not.toHaveBeenCalled();
+ expect(observed.at(-1)).toMatchObject({
+ command: "policy",
+ outcome: "failed",
+ failureCategory: "budget",
+ });
await expect(
readFile(join(f.outputDir, "project-spec.md")),
).rejects.toMatchObject({ code: "ENOENT" });
@@ -1925,6 +1960,7 @@ describe("CodexSecurity policy API", () => {
test("allows unavailable usage unless an explicit cost limit needs verification", async () => {
for (const limited of [false, true]) {
+ const observed: OperationTelemetryEvent[] = [];
const f = await setup({
stream: async function* (stage) {
for await (const event of events(stage)) {
@@ -1940,9 +1976,15 @@ describe("CodexSecurity policy API", () => {
const result = f.security.generatePolicy(f.repository, {
outputDir: f.outputDir,
...(limited ? { maxCostUsd: 1 } : {}),
+ onTelemetry: (event) => observed.push(event),
});
if (limited) await expect(result).rejects.toThrow("cost limit");
else expect((await result).cost).toBeNull();
+ expect(observed.at(-1)).toMatchObject({
+ command: "policy",
+ outcome: limited ? "failed" : "completed",
+ ...(limited ? { failureCategory: "execution" } : {}),
+ });
await f.security.close();
}
});
diff --git a/sdk/typescript/tests-ts/api-preflight-config.test.ts b/sdk/typescript/tests-ts/api-preflight-config.test.ts
index cd0859655..4b1dd8725 100644
--- a/sdk/typescript/tests-ts/api-preflight-config.test.ts
+++ b/sdk/typescript/tests-ts/api-preflight-config.test.ts
@@ -414,6 +414,14 @@ describe("CodexSecurity preflight configuration", () => {
model_reasoning_effort: "high",
openai_base_url:
"https://synthetic-user:[email protected]/v1?token=synthetic-root-token",
+ otel: {
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://otel.example.test/v1/logs",
+ headers: { Authorization: "Bearer SYNTHETIC_ROOT_OTEL_AUTH" },
+ },
+ },
+ },
features: {
plugins: true,
goals: true,
@@ -427,6 +435,16 @@ describe("CodexSecurity preflight configuration", () => {
model: "profile-model",
openai_base_url:
"https://synthetic-user:[email protected]/v1?token=synthetic-profile-token",
+ otel: {
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://otel.example.test/v1/logs",
+ headers: {
+ Authorization: "Bearer SYNTHETIC_PROFILE_OTEL_AUTH",
+ },
+ },
+ },
+ },
features: { goals: true, secret: "PROFILE_SECRET" },
agents: { max_threads: 4, token: "PROFILE_AGENT_TOKEN" },
shell_environment_policy: { set: { SECRET: "PROFILE_ENV_SECRET" } },
@@ -507,6 +525,8 @@ describe("CodexSecurity preflight configuration", () => {
"PROJECT_TOKEN",
"MCP_TOKEN",
"SHELL_SECRET",
+ "SYNTHETIC_ROOT_OTEL_AUTH",
+ "SYNTHETIC_PROFILE_OTEL_AUTH",
]) {
expect(serialized).not.toContain(secret);
}
diff --git a/sdk/typescript/tests-ts/api-time-budget.test.ts b/sdk/typescript/tests-ts/api-time-budget.test.ts
index 3731282d9..057b58680 100644
--- a/sdk/typescript/tests-ts/api-time-budget.test.ts
+++ b/sdk/typescript/tests-ts/api-time-budget.test.ts
@@ -179,9 +179,11 @@ test("explicit cancellation remains authoritative with an advisory allowance", a
signal: controller.signal,
}),
).rejects.toBeInstanceOf(ScanInterruptedError);
- expect(state.commands).toContain("cancel-scan");
- expect(state.commands).not.toContain("fail-scan");
- expect(state.commands).not.toContain("complete-scan");
+ expect(
+ state.commands.filter((command) =>
+ ["cancel-scan", "fail-scan", "complete-scan"].includes(command),
+ ),
+ ).toEqual(["cancel-scan"]);
});
test("preflight exposes the effective Deep limit in minutes and leaves Standard unset", async () => {
diff --git a/sdk/typescript/tests-ts/api-usage.test.ts b/sdk/typescript/tests-ts/api-usage.test.ts
index a7f9b9417..ced2beaf1 100644
--- a/sdk/typescript/tests-ts/api-usage.test.ts
+++ b/sdk/typescript/tests-ts/api-usage.test.ts
@@ -4,7 +4,11 @@ import { appendFile, mkdir } from "node:fs/promises";
import { join } from "node:path";
import { setImmediate } from "node:timers/promises";
import type { ThreadEvent } from "@openai/codex-sdk";
-import { readScanBudgetUsage, ScanCostTracker } from "../src/cost.js";
+import {
+ readScanBudgetUsage,
+ ScanCostTracker,
+ type ScanUsageMeasurement,
+} from "../src/cost.js";
import { ScanCostLimitExceededError } from "../src/errors.js";
import { copyCompletedScan } from "./plugin-root.js";
import {
@@ -167,6 +171,108 @@ test.each([false, true])(
},
);
+test.each([false, true])(
+ "persists unpriced usage and reports complete-to-partial coverage on terminal cancellation=%p",
+ async (cancel) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const codexHome = join(root, "home");
+ const scanDir = join(root, "scan");
+ await mkdir(repository);
+ await mkdir(scanDir, { mode: 0o700 });
+ await writeSession(codexHome, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 5,
+ });
+ const observed: Readonly<ScanUsageMeasurement>[] = [];
+ const observerErrors = mock();
+ const observerFailure = new Error("Synthetic measurement observer failure");
+ const saved: readonly string[][] = [];
+ const controller = new AbortController();
+ const complete = Promise.withResolvers<void>();
+ const client = new TestClient(
+ { codexOverrides: { model: "synthetic-unpriced-model" } },
+ {
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (_options, args, input) => {
+ if (args[0] === "fail-scan" || args[0] === "cancel-scan") {
+ (saved as string[][]).push([...args]);
+ }
+ return mockWorkbench(args, input);
+ },
+ createCodex: () => ({
+ startThread: () => ({
+ id: null,
+ runStreamed: async () => ({
+ events: (async function* (): AsyncGenerator<ThreadEvent> {
+ yield { type: "thread.started", thread_id: "scan-thread" };
+ await complete.promise;
+ await writeSession(
+ codexHome,
+ "missing-worker",
+ {},
+ { parent: "scan-thread" },
+ );
+ if (cancel)
+ controller.abort(new Error("Synthetic cancellation"));
+ throw new Error("Synthetic execution failure");
+ })(),
+ }),
+ }),
+ }),
+ },
+ );
+ try {
+ await expect(
+ client.run(repository, {
+ signal: controller.signal,
+ onMeasurement: (measurement) => {
+ observed.push(measurement);
+ if (measurement.coverage === "complete") complete.resolve();
+ throw observerFailure;
+ },
+ onObserverError: observerErrors,
+ }),
+ ).rejects.toThrow();
+ expect(observed.map((value) => value.coverage)).toEqual([
+ "complete",
+ "partial",
+ ]);
+ expect(observerErrors).toHaveBeenCalledTimes(2);
+ expect(observerErrors).toHaveBeenNthCalledWith(
+ 1,
+ "onMeasurement",
+ observerFailure,
+ );
+ expect(observerErrors).toHaveBeenNthCalledWith(
+ 2,
+ "onMeasurement",
+ observerFailure,
+ );
+ expect(observed.at(-1)).toMatchObject({
+ cost: null,
+ usage: { input_tokens: 100, output_tokens: 5 },
+ missingThreadCount: 1,
+ });
+ expect(saved).toHaveLength(1);
+ expect(saved[0]![0]).toBe(cancel ? "cancel-scan" : "fail-scan");
+ const args = saved[0]!;
+ const receipt = JSON.parse(args[args.indexOf("--cost-json") + 1]!);
+ expect(receipt).toMatchObject({
+ usage: {
+ source: "codex_runtime",
+ coverage: "partial",
+ inputTokens: 100,
+ outputTokens: 5,
+ },
+ });
+ expect(receipt.cost).toBeUndefined();
+ } finally {
+ await client.close();
+ }
+ },
+);
+
test.each([false, true])(
"completes with an unmeasured worker only when no budget was requested (budgeted=%p)",
async (budgeted) => {
diff --git a/sdk/typescript/tests-ts/api-validation-persistence.test.ts b/sdk/typescript/tests-ts/api-validation-persistence.test.ts
index 15d89b6ab..551a83cba 100644
--- a/sdk/typescript/tests-ts/api-validation-persistence.test.ts
+++ b/sdk/typescript/tests-ts/api-validation-persistence.test.ts
@@ -3,6 +3,7 @@ import {
chmod,
mkdir,
readFile,
+ readdir,
realpath,
rm,
stat,
@@ -13,6 +14,10 @@ import { type ThreadEvent } from "@openai/codex-sdk";
import { describe, expect, test } from "bun:test";
import { OutputDirectoryError, ScanInterruptedError } from "../src/index.js";
import { resolveCodexProfile, type JsonObject } from "../src/config.js";
+import {
+ readOperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
import { runWorkbench } from "../src/runtime.js";
import { reviewSqliteHome } from "../src/deduplication/codex-review.js";
@@ -249,13 +254,22 @@ describe("CodexSecurity finding validation", () => {
yield* validationEvents();
}
const fixture = await persistedValidationClient(events);
+ fixture.enableTelemetry();
await using client = fixture.client;
const workflowId = await fixture.bindWorkflow(
"explicit-validation-evidence",
);
- const request = { ...fixture.options, workflowId };
+ const request = {
+ ...fixture.options,
+ workflowId,
+ outputDir: join(fixture.stateDirectory, "telemetry"),
+ };
const first = await client.validate(request);
expect(await client.validate(request)).toEqual(first);
+ expect(await client.validate({ ...request, outputDir: undefined })).toEqual(
+ first,
+ );
+ expect(await readdir(first.outputDir)).toEqual(["proof.txt"]);
expect(modelCalls).toBe(1);
if (process.platform !== "win32") {
await chmod(first.outputDir, 0o770);
@@ -270,6 +284,16 @@ describe("CodexSecurity finding validation", () => {
expect(await readFile(join(first.outputDir, "proof.txt"), "utf8")).toBe(
"Changed evidence.\n",
);
+ const regenerated = await client.validate({
+ ...request,
+ outputDir: undefined,
+ });
+ expect(regenerated.outputDir).not.toBe(first.outputDir);
+ expect(modelCalls).toBe(2);
+ expect(await readdir(first.outputDir)).toEqual(["proof.txt"]);
+ expect(await readFile(join(first.outputDir, "proof.txt"), "utf8")).toBe(
+ "Changed evidence.\n",
+ );
});
test.each(["empty", "nonempty"])(
@@ -389,15 +413,20 @@ describe("CodexSecurity finding validation", () => {
yield* validationEvents();
}
const original = await persistedValidationClient(events);
+ original.enableTelemetry();
usePersistedValidationWorkbench(original, () => targetChanged);
await using originalClient = original.client;
await original.bindWorkflow("validation-retry");
+ const finished: Readonly<OperationTelemetryEvent>[] = [];
const request = {
...original.options,
outputDir: undefined,
scanId: "recorded-scan",
workflowId: "validation-retry",
safetyIdentifier: "synthetic-validation-first",
+ onTelemetry: (event: Readonly<OperationTelemetryEvent>) => {
+ if (event.type === "attempt_finished") finished.push(event);
+ },
};
const first = await originalClient.validate(request);
await expect(
@@ -410,6 +439,7 @@ describe("CodexSecurity finding validation", () => {
PLUGIN_ROOT,
original.root,
);
+ resumed.enableTelemetry();
usePersistedValidationWorkbench(resumed, () => targetChanged);
await using client = resumed.client;
expect(await client.validate(request)).toEqual(first);
@@ -421,6 +451,17 @@ describe("CodexSecurity finding validation", () => {
"scan target changed",
);
expect(modelCalls).toBe(3);
+ expect(finished.map((event) => event.reusedResult)).toEqual([
+ false,
+ false,
+ true,
+ false,
+ false,
+ ]);
+ const { events: journal } = await readOperationTelemetry(
+ original.stateDirectory,
+ );
+ expect(journal.filter((event) => event.reusedResult)).toHaveLength(1);
});
test("separates persisted validation by model and access program across clients", async () => {
diff --git a/sdk/typescript/tests-ts/api-validation-usage.test.ts b/sdk/typescript/tests-ts/api-validation-usage.test.ts
new file mode 100644
index 000000000..54eb6c8f9
--- /dev/null
+++ b/sdk/typescript/tests-ts/api-validation-usage.test.ts
@@ -0,0 +1,361 @@
+import { Codex } from "@openai/codex-sdk";
+import { afterEach, describe, expect, test } from "bun:test";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { estimateScanCost } from "../src/cost.js";
+import type { ThreadEvent } from "@openai/codex-sdk";
+import { ScanInterruptedError } from "../src/errors.js";
+import {
+ OperationTelemetry,
+ readOperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
+import { TestClient } from "./support/api-client.js";
+import { preparedRuntime } from "./support/api-events.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { nodeCommand } from "./support/shell.js";
+import { writeSession } from "./support/usage-rollout.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "codex-security-validation-usage-",
+);
+afterEach(cleanup);
+
+const parentUsage = {
+ input_tokens: 10,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 3,
+ reasoning_output_tokens: 0,
+};
+const childUsage = { ...parentUsage, input_tokens: 90, output_tokens: 7 };
+const assessment = {
+ disposition: "reportable",
+ report: "Synthetic validation assessment.",
+};
+type ValidationEnding = "completed" | "failed" | "canceled" | "invalid";
+
+async function validationFixture({
+ ending = "completed",
+ child = childUsage,
+}: {
+ ending?: ValidationEnding;
+ child?: Record<string, number>;
+} = {}) {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const codexHome = join(root, "codex-home");
+ await mkdir(repository);
+ await mkdir(codexHome);
+ const controller = new AbortController();
+ const telemetry: Readonly<OperationTelemetryEvent>[] = [];
+ const environment = {
+ CODEX_SECURITY_STATE_DIR: join(root, "state"),
+ OPENAI_API_KEY: "synthetic-validation-key",
+ };
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await writeSession(codexHome, "validation-parent", parentUsage);
+ await writeSession(codexHome, "validation-child", child, {
+ parent: "validation-parent",
+ });
+ yield { type: "thread.started", thread_id: "validation-parent" };
+ if (ending === "canceled") {
+ controller.abort();
+ throw controller.signal.reason;
+ }
+ if (ending === "failed") {
+ yield {
+ type: "turn.failed",
+ error: { message: "Synthetic validation failure." },
+ };
+ return;
+ }
+ yield {
+ type: "item.completed",
+ item: {
+ id: "assessment",
+ type: "agent_message",
+ text: ending === "invalid" ? "not JSON" : JSON.stringify(assessment),
+ },
+ };
+ yield { type: "turn.completed", usage: parentUsage };
+ }
+ const client = new TestClient(
+ {
+ codexOverrides: {
+ model: "test-model",
+ model_reasoning_effort: "high",
+ approval_policy: "never",
+ analytics: { enabled: false },
+ },
+ },
+ {
+ environment,
+ prepareRuntime: async () => ({
+ ...preparedRuntime(codexHome),
+ environment,
+ }),
+ resolvePluginPython: async () => "/managed/python",
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ createCodex: () => ({
+ startThread: () => ({
+ id: null,
+ runStreamed: async () => ({ events: events() }),
+ }),
+ }),
+ },
+ );
+ return {
+ client,
+ options: {
+ repositoryPath: repository,
+ finding: "Synthetic candidate finding",
+ outputDir: join(root, "validation"),
+ signal: controller.signal,
+ auth: "api-key" as const,
+ onTelemetry: (event: Readonly<OperationTelemetryEvent>) =>
+ telemetry.push(event),
+ },
+ terminal() {
+ expect(telemetry.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ return telemetry.at(-1)!;
+ },
+ };
+}
+
+describe("standalone validation usage", () => {
+ test("includes native child threads in the terminal measurement", async () => {
+ const fixture = await validationFixture();
+ await using client = fixture.client;
+ expect(await client.validate(fixture.options)).toMatchObject(assessment);
+ expect(fixture.terminal()).toMatchObject({
+ outcome: "completed",
+ measurement: {
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ usage: { input_tokens: 100, output_tokens: 10, total_tokens: 110 },
+ },
+ });
+ });
+
+ test("keeps parent usage partial when a known child has no usage", async () => {
+ const fixture = await validationFixture({ child: {} });
+ await using client = fixture.client;
+ expect(await client.validate(fixture.options)).toMatchObject(assessment);
+ expect(fixture.terminal()).toMatchObject({
+ outcome: "completed",
+ measurement: {
+ coverage: "partial",
+ threadCount: 1,
+ missingThreadCount: 1,
+ usage: { input_tokens: 10, output_tokens: 3, total_tokens: 13 },
+ },
+ });
+ });
+
+ test.each(["failed", "canceled", "invalid"] as const)(
+ "retains native parent and child usage after a %s validation",
+ async (ending) => {
+ const fixture = await validationFixture({ ending });
+ await using client = fixture.client;
+ await expect(client.validate(fixture.options)).rejects.toThrow(
+ ending === "canceled"
+ ? ScanInterruptedError
+ : ending === "failed"
+ ? "Synthetic validation failure."
+ : "Finding validation returned an invalid result.",
+ );
+ expect(fixture.terminal()).toMatchObject({
+ outcome: ending === "canceled" ? "canceled" : "failed",
+ measurement: {
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ usage: { input_tokens: 100, output_tokens: 10, total_tokens: 110 },
+ },
+ });
+ },
+ );
+});
+
+const completionUsage = {
+ input_tokens: 100,
+ cached_input_tokens: 20,
+ cache_write_input_tokens: 7,
+ output_tokens: 10,
+ reasoning_output_tokens: 3,
+};
+
+test.each([
+ "invalid JSON",
+ "invalid schema",
+ "valid assessment",
+ "canceled after completion",
+ "canceled on completion",
+ "nonzero exit after completion",
+ "nonzero exit before completion",
+ "null usage",
+ "absent usage",
+] as const)(
+ "preserves completed SDK validation usage with %s",
+ async (ending) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const codexHome = join(root, "codex-home");
+ const state = join(root, "state");
+ await mkdir(repository);
+ await mkdir(codexHome);
+ const controller = new AbortController();
+ const observed: Readonly<OperationTelemetryEvent>[] = [];
+ const model = "gpt-5.6-terra";
+ const environment = {
+ CODEX_SECURITY_STATE_DIR: state,
+ OPENAI_API_KEY: "synthetic-validation-usage-key",
+ };
+ const usage =
+ ending === "null usage"
+ ? null
+ : ending === "absent usage" ||
+ ending === "nonzero exit before completion"
+ ? undefined
+ : completionUsage;
+ const response =
+ ending === "invalid JSON"
+ ? "not JSON"
+ : JSON.stringify(
+ ending === "invalid schema"
+ ? { ...assessment, disposition: "invalid" }
+ : assessment,
+ );
+ const canceled =
+ ending === "canceled after completion" ||
+ ending === "canceled on completion";
+ const failedExit = ending.startsWith("nonzero exit");
+ const childScript = join(root, "validation-child.mjs");
+ await writeFile(
+ childScript,
+ [
+ "for await (const _chunk of process.stdin) {}",
+ "const send = (event) => console.log(JSON.stringify(event));",
+ 'send({ type: "thread.started", thread_id: "validation-usage-thread" });',
+ `send(${JSON.stringify({ type: "item.completed", item: { id: "result", type: "agent_message", text: response } })});`,
+ ...(ending === "nonzero exit before completion"
+ ? []
+ : [`send(${JSON.stringify({ type: "turn.completed", usage })});`]),
+ ...(canceled
+ ? ["setInterval(() => {}, 1_000);", "await new Promise(() => {});"]
+ : failedExit
+ ? [
+ 'process.stderr.write("Synthetic validation child exit diagnostic.\\n");',
+ "process.exit(17);",
+ ]
+ : ["process.exit(0);"]),
+ ].join("\n"),
+ );
+ let executions = 0;
+ await using client = new TestClient(
+ { codexOverrides: { model, analytics: { enabled: false } } },
+ {
+ environment,
+ prepareRuntime: async () => ({
+ ...preparedRuntime(codexHome),
+ environment,
+ }),
+ resolvePluginPython: async () => "/managed/python",
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ createCodex: (options) => {
+ const codex = new Codex({
+ ...options,
+ codexPathOverride: nodeCommand().command,
+ env: {
+ ...options.env,
+ NODE_OPTIONS: `--import=${pathToFileURL(childScript).href}`,
+ },
+ });
+ return {
+ startThread: (options) => {
+ const thread = codex.startThread(options);
+ const runStreamed = thread.runStreamed.bind(thread);
+ thread.runStreamed = async (...args) => {
+ executions++;
+ const { events } = await runStreamed(...args);
+ return {
+ events: (async function* () {
+ for await (const event of events) {
+ if (
+ event.type === "turn.completed" &&
+ ending === "canceled on completion"
+ ) {
+ controller.abort(new Error("Synthetic cancellation."));
+ }
+ yield event;
+ if (
+ event.type === "turn.completed" &&
+ ending === "canceled after completion"
+ ) {
+ controller.abort(new Error("Synthetic cancellation."));
+ }
+ }
+ })(),
+ };
+ };
+ return thread;
+ },
+ };
+ },
+ },
+ );
+ const pending = client.validate({
+ repositoryPath: repository,
+ finding: "Synthetic candidate finding.",
+ auth: "api-key",
+ signal: controller.signal,
+ onTelemetry: (event) => observed.push(event),
+ });
+ const invalid = ending === "invalid JSON" || ending === "invalid schema";
+ if (canceled) {
+ await expect(pending).rejects.toBeInstanceOf(ScanInterruptedError);
+ } else if (failedExit) {
+ await expect(pending).rejects.toThrow(
+ "Codex Exec exited with code 17: Synthetic validation child exit diagnostic.",
+ );
+ } else if (invalid) {
+ await expect(pending).rejects.toThrow(
+ "Finding validation returned an invalid result.",
+ );
+ } else {
+ expect(await pending).toMatchObject({
+ ...assessment,
+ threadId: "validation-usage-thread",
+ });
+ }
+ expect(executions).toBe(1);
+ await expect(access(join(codexHome, "sessions"))).rejects.toHaveProperty(
+ "code",
+ "ENOENT",
+ );
+ const saved = await readOperationTelemetry(state);
+ expect(saved.parseFailures).toBe(0);
+ expect(saved.events.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed.map((event) => event.eventId)).toEqual(
+ saved.events.map((event) => event.eventId),
+ );
+ const terminal = saved.events.at(-1)!;
+ expect(terminal.outcome).toBe(
+ canceled ? "canceled" : invalid || failedExit ? "failed" : "completed",
+ );
+ expect(terminal.measurement).toMatchObject({
+ usage: usage == null ? null : { ...completionUsage, total_tokens: 110 },
+ coverage: usage == null ? "unavailable" : "complete",
+ cost: estimateScanCost(model, usage),
+ });
+ },
+);
diff --git a/sdk/typescript/tests-ts/api-validation.test.ts b/sdk/typescript/tests-ts/api-validation.test.ts
index cd66aaaf2..f9e69d86b 100644
--- a/sdk/typescript/tests-ts/api-validation.test.ts
+++ b/sdk/typescript/tests-ts/api-validation.test.ts
@@ -95,6 +95,7 @@ describe("CodexSecurity finding validation", () => {
destination === "state" ? storage : join(root, "state"),
OPENAI_API_KEY: "synthetic-validation-key",
},
+ createOperationTelemetry: undefined,
prepareRuntime,
resolvePluginPython: async () => "/managed/python",
createCodex,
diff --git a/sdk/typescript/tests-ts/api-workflow.test.ts b/sdk/typescript/tests-ts/api-workflow.test.ts
index 438cbf02e..636de8a23 100644
--- a/sdk/typescript/tests-ts/api-workflow.test.ts
+++ b/sdk/typescript/tests-ts/api-workflow.test.ts
@@ -3,6 +3,11 @@ import { dirname, join } from "node:path";
import { Database } from "bun:sqlite";
import { afterEach, expect, mock, spyOn, test } from "bun:test";
import type { ScanOptions } from "../src/index.js";
+import {
+ OperationTelemetry,
+ readOperationTelemetry,
+ summarizeOperationTelemetry,
+} from "../src/operation-telemetry.js";
import { runWorkbench } from "../src/runtime.js";
import * as runtime from "../src/runtime.js";
import * as ownerArtifacts from "../src/scan-owner-suggestions.js";
@@ -98,6 +103,7 @@ test.each([
return TestClient.withDependencies({
environment,
...scanRuntimeDependencies(codexHome, scanDir),
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
runWorkbench: async (options, args, input) => {
if (args[0] === "finding-workflow") {
const payload = JSON.parse(input!);
@@ -201,6 +207,35 @@ test.each([
expect(await readFile(ownerPath, "utf8")).toBe("{}\n");
}
expect(modelCalls).toBe(scenario === "scan-interrupted" ? 2 : 1);
+ const { events } = await readOperationTelemetry(
+ environment.CODEX_SECURITY_STATE_DIR,
+ );
+ const starts = events.filter((event) => event.type === "attempt_started");
+ expect(starts).toHaveLength(2);
+ const terminal = events.filter(
+ (event) => event.type === "attempt_finished",
+ );
+ expect(terminal).toHaveLength(2);
+ for (const start of starts) {
+ expect(
+ terminal.find((event) => event.attemptId === start.attemptId),
+ ).toMatchObject({ operationId: start.operationId });
+ }
+ expect(summarizeOperationTelemetry(events).reusedAttempts).toBe(
+ scenario === "scan-interrupted" ? 0 : 1,
+ );
+ const reused = terminal.find((event) => event.reusedResult === true);
+ if (scenario === "scan-interrupted") {
+ expect(terminal.every((event) => event.reusedResult === false)).toBe(
+ true,
+ );
+ } else {
+ expect(reused).toMatchObject({
+ outcome: "completed",
+ findingCount: result.findings.findings.length,
+ });
+ expect(reused?.measurement).toBeUndefined();
+ }
expect(
(await new FindingWorkflow(workflowId, environment).get())?.stages.scan
.status,
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 7fdfbb4cf..05f345f62 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -61,6 +61,10 @@ import {
classifyConnectionFailure,
initialCredentialsAvailable,
} from "../src/api.js";
+import {
+ OperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
import {
DEFAULT_CODEX_CONFIG,
OPENROUTER_CODEX_PROVIDER,
@@ -1498,14 +1502,32 @@ describe("CodexSecurity orchestration", () => {
{
profile: "cloud",
analytics: { enabled: true },
- otel: { environment: "synthetic-root" },
+ otel: {
+ environment: "synthetic-root",
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://otel.example.test/v1/logs",
+ headers: { Authorization: "Bearer synthetic-otel-root" },
+ },
+ },
+ },
responses_api_metadata: { custom_attribution: "root" },
model_context_window: 64_000,
model_auto_compact_token_limit: 48_000,
profiles: {
cloud: {
analytics: { enabled: false },
- otel: { environment: "synthetic-selected" },
+ otel: {
+ environment: "synthetic-selected",
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://otel.example.test/v1/logs",
+ headers: {
+ Authorization: "Bearer synthetic-otel-selected",
+ },
+ },
+ },
+ },
responses_api_metadata: {
custom_attribution: "selected",
codex_security_integration: "github_action",
@@ -1630,6 +1652,11 @@ describe("CodexSecurity orchestration", () => {
resolvePluginPython: async () => "/managed/python",
prepareOutputDir: async () => scanDir,
repositoryRevision: async () => "deadbeef",
+ runWorkbench: async (_options, args, input) => {
+ if (args[0] === "register-cli-scan")
+ expect(input).not.toContain("synthetic-otel-");
+ return mockWorkbench(args, input);
+ },
createCodex: (options: CodexOptions) => ({
startThread: (threadOptions: ThreadOptions) => ({
id: null,
@@ -1665,6 +1692,9 @@ describe("CodexSecurity orchestration", () => {
await readFile(deepConfigPath, "utf8"),
)["worker_runtime"] as JsonObject;
const selected = resolveCodexProfile(overrides);
+ expect((options.config as JsonObject)["otel"]).toEqual(
+ selected["otel"],
+ );
expect(workerConfig["analytics"]).toEqual(
selected["analytics"],
);
@@ -1789,6 +1819,9 @@ describe("CodexSecurity orchestration", () => {
const config = parseToml(
await readFile(configPath!, "utf8"),
) as JsonObject;
+ expect(JSON.stringify(config)).not.toContain(
+ "synthetic-otel-",
+ );
expect(resolveCodexProfile(config)).toMatchObject({
...expectedModel,
model_reasoning_summary: expected,
@@ -3013,7 +3046,27 @@ if __name__ == "__main__":
"complete-scan",
"--scan-id",
"scan_example_001",
+ "--cost-json",
+ expect.any(String),
]);
+ const completionReceipt = JSON.parse(commands[4]![4]!);
+ expect(completionReceipt).toMatchObject({
+ usage: {
+ source: "codex_runtime",
+ coverage: "complete",
+ observedAt: expect.any(String),
+ threadCount: 1,
+ missingThreadCount: 0,
+ coverageScope: ["thread:thread-1"],
+ inputTokens: 10,
+ cachedInputTokens: 2,
+ cacheWriteInputTokens: 0,
+ outputTokens: 3,
+ reasoningOutputTokens: 1,
+ totalTokens: 13,
+ },
+ });
+ expect(completionReceipt).not.toHaveProperty("cost");
await client.close();
});
@@ -3789,7 +3842,7 @@ if __name__ == "__main__":
test.each([true, false])(
"records a native failure only when its terminal event preceded cancellation (failure first: %p)",
async (failureFirst) => {
- const { repository, codexHome, scanDir } = await scanDirectories();
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
const controller = new AbortController();
const message = "Synthetic native turn failure";
async function* events(): AsyncGenerator<ThreadEvent> {
@@ -3801,9 +3854,15 @@ if __name__ == "__main__":
if (failureFirst) controller.abort();
}
}
+ const telemetry: Readonly<OperationTelemetryEvent>[] = [];
let stopped: readonly string[] | undefined;
await using client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
+ createOperationTelemetry: (options) =>
+ new OperationTelemetry({
+ ...options,
+ directory: join(root, "journal"),
+ }),
createCodex: codexFactory(async () => ({ events: events() })),
runWorkbench: async (_options, args, input) => {
if (args[0] === "fail-scan" || args[0] === "cancel-scan")
@@ -3812,8 +3871,19 @@ if __name__ == "__main__":
},
});
await expect(
- client.run(repository, { signal: controller.signal }),
+ client.run(repository, {
+ signal: controller.signal,
+ onTelemetry: (event) => telemetry.push(event),
+ }),
).rejects.toThrow();
+ expect(
+ telemetry.filter((event) => event.type === "attempt_finished"),
+ ).toEqual([
+ expect.objectContaining({
+ outcome: failureFirst ? "failed" : "canceled",
+ failureCategory: failureFirst ? "execution" : "canceled",
+ }),
+ ]);
expect(controller.signal.aborted).toBe(true);
expect(stopped?.[0]).toBe(failureFirst ? "fail-scan" : "cancel-scan");
if (failureFirst) expect(stopped).toContain(`--message=${message}`);
@@ -3868,8 +3938,14 @@ if __name__ == "__main__":
await writeFile(join(codexHome, "sessions"), "not a directory");
const commands: string[] = [];
const warnings: string[] = [];
+ const telemetry: Readonly<OperationTelemetryEvent>[] = [];
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
+ createOperationTelemetry: (options) =>
+ new OperationTelemetry({
+ ...options,
+ directory: join(root, "telemetry-state"),
+ }),
runWorkbench: async (
_options: unknown,
args: readonly string[],
@@ -3884,6 +3960,7 @@ if __name__ == "__main__":
const scan = client.run(repository, {
...(enforceCostLimit ? { maxCostUsd: 1 } : {}),
onActivity: () => {},
+ onTelemetry: (event) => telemetry.push(event),
onWarning: (warning) => warnings.push(warning),
});
await expect(scan).resolves.toMatchObject({ threadId: "thread-1" });
@@ -3893,6 +3970,11 @@ if __name__ == "__main__":
expect(commands.includes("read-scan-usage")).toBe(enforceCostLimit);
expect(commands).toContain("complete-scan");
expect(commands).not.toContain("cancel-scan");
+ expect(
+ telemetry.filter((event) => event.type === "attempt_finished"),
+ ).toMatchObject([
+ { outcome: "completed", findingCount: 1, artifactComplete: true },
+ ]);
await client.close();
},
);
@@ -14336,11 +14418,12 @@ if __name__ == "__main__":
const { root, repository, codexHome, scanDir } = await scanDirectories();
const usages: unknown[] = [];
const observerErrors: string[] = [];
+ const commands: Array<readonly string[]> = [];
const client = new TestClient(
{ codexOverrides: { model: "synthetic-unpriced-model" } },
{
...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: recordingWorkbench([]),
+ runWorkbench: recordingWorkbench(commands),
createCodex: completedCodex(root),
},
);
@@ -14358,6 +14441,20 @@ if __name__ == "__main__":
expect.objectContaining({ input_tokens: 10, output_tokens: 3 }),
]);
expect(observerErrors).toEqual(["onUsage"]);
+ const completion = commands.find((args) => args[0] === "complete-scan");
+ const costIndex = completion?.indexOf("--cost-json") ?? -1;
+ expect(costIndex).toBeGreaterThan(0);
+ const receipt = JSON.parse(completion![costIndex + 1]!);
+ expect(receipt).toMatchObject({
+ usage: {
+ coverage: "complete",
+ threadCount: 1,
+ inputTokens: 10,
+ outputTokens: 3,
+ totalTokens: 13,
+ },
+ });
+ expect(receipt.cost).toBeUndefined();
} finally {
await client.close();
}
@@ -14415,9 +14512,16 @@ if __name__ == "__main__":
expect(completion).toBeDefined();
const costIndex = completion?.indexOf("--cost-json") ?? -1;
expect(costIndex).toBeGreaterThan(0);
- expect(JSON.parse(completion?.[costIndex + 1] ?? "null")).toEqual(
- result.cost,
- );
+ expect(JSON.parse(completion?.[costIndex + 1] ?? "null")).toMatchObject({
+ cost: result.cost,
+ usage: {
+ coverage: "complete",
+ threadCount: 1,
+ inputTokens: 10,
+ outputTokens: 3,
+ totalTokens: 13,
+ },
+ });
await client.close();
});
@@ -15158,10 +15262,12 @@ if __name__ == "__main__":
})!;
const client = TestClient.withDependencies({
...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: recordingWorkbench(
- commands,
- measuredScanUsage(1_250, 200, 30),
- ),
+ runWorkbench: recordingWorkbench(commands, {
+ ...measuredScanUsage(1_250, 200, 30),
+ threadCount: 2,
+ byRole: { workers: { threadCount: 1 } },
+ cacheWriteInputTokensReported: false,
+ }),
createCodex: codexFactory(runStreamed),
});
@@ -15210,16 +15316,34 @@ if __name__ == "__main__":
"scan_example_001",
`--message=Scan stopped: short-context budget baseline $0.00488 exceeded the $0.004 limit; estimated cost $0.00488–$0.01156 (standard, context unknown, cache writes unknown); scan output directory: ${scanDir}.`,
"--cost-json",
- JSON.stringify(cost),
+ expect.any(String),
]);
+ expect(JSON.parse(commands.at(-1)![5]!)).toMatchObject({
+ usage: {
+ source: "codex_runtime",
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ inputTokens: 1_250,
+ cachedInputTokens: 200,
+ outputTokens: 30,
+ totalTokens: 1_280,
+ },
+ cost,
+ });
expect(commands.some((args) => args[0] === "complete-scan")).toBe(false);
await expect(stat(scanDir)).resolves.toBeDefined();
await client.close();
});
- test.each(["completed", "failed", "unavailable"] as const)(
- "recovers exhausted deep-scan budget when completion is %s",
- async (completion) => {
+ test.each([
+ ["completed", false],
+ ["failed", false],
+ ["unavailable", false],
+ ["completed", true],
+ ] as const)(
+ "recovers exhausted deep-scan budget when completion is %s (missing worker=%p)",
+ async (completion, missingWorker) => {
const { root, repository, codexHome, scanDir } = await scanDirectories();
const commands: Array<readonly string[]> = [];
const warnings: string[] = [];
@@ -15251,6 +15375,13 @@ if __name__ == "__main__":
cached_input_tokens: 200,
output_tokens: 30,
});
+ if (missingWorker)
+ await writeUsageSession(
+ codexHome,
+ "missing-worker",
+ {},
+ { parent: "scan-thread" },
+ );
await (options.signal.aborted
? undefined
: once(options.signal, "abort"));
@@ -15276,7 +15407,13 @@ if __name__ == "__main__":
}
if (args[0] === "fail-scan") return { scan: { lifecycle: terminal } };
if (args[0] === "read-scan-usage")
- return measuredScanUsage(1_250, 200, 30);
+ return {
+ ...measuredScanUsage(1_250, 200, 30),
+ coverage: missingWorker ? "partial" : "complete",
+ threadCount: 1,
+ missingThreadCount: missingWorker ? 1 : 0,
+ cacheWriteInputTokensReported: false,
+ };
if (args[0] !== "complete-budget-exhausted-scan") {
return mockWorkbench(args, input);
}
@@ -15354,7 +15491,8 @@ if __name__ == "__main__":
expect(recovered.review).not.toHaveProperty("status");
expect(recovered.findings.findings).toHaveLength(1);
expect(recovered.threadId).toBe("scan-thread");
- expect(recovered.cost?.estimatedUsd).toBe(0.00488);
+ if (missingWorker) expect(recovered.cost).toBeNull();
+ else expect(recovered.cost?.estimatedUsd).toBe(0.00488);
expect(warnings).toEqual([
`Scan stopped: short-context budget baseline $0.00488 exceeded the $0.004 limit; estimated cost $0.00488–$0.01156 (standard, context unknown, cache writes unknown); scan output directory: ${scanDir}.`,
]);
@@ -15378,6 +15516,19 @@ if __name__ == "__main__":
(args) => args[0] === "complete-budget-exhausted-scan",
);
expect(recovery?.includes("--cost-json")).toBe(true);
+ const costIndex = recovery!.indexOf("--cost-json");
+ expect(JSON.parse(recovery![costIndex + 1]!)).toMatchObject({
+ usage: {
+ coverage: missingWorker ? "partial" : "complete",
+ threadCount: 1,
+ missingThreadCount: missingWorker ? 1 : 0,
+ inputTokens: 1_250,
+ cachedInputTokens: 200,
+ outputTokens: 30,
+ totalTokens: 1_280,
+ },
+ cost: { estimatedUsd: 0.00488 },
+ });
expect(recovery?.some((value) => value.startsWith("--message="))).toBe(
true,
);
diff --git a/sdk/typescript/tests-ts/cli-authentication.test.ts b/sdk/typescript/tests-ts/cli-authentication.test.ts
index 276f482e3..492a44630 100644
--- a/sdk/typescript/tests-ts/cli-authentication.test.ts
+++ b/sdk/typescript/tests-ts/cli-authentication.test.ts
@@ -59,11 +59,14 @@ const GATEWAY_CONFIGURATION = [
].join("\n");
let stateDirectory: string;
+let skillDirectory: string;
beforeEach(async () => {
stateDirectory = await realpath(
await temporaryDirectory("codex-security-cli-authentication-"),
);
+ skillDirectory = join(stateDirectory, "selected-directory");
+ await mkdir(skillDirectory, { mode: 0o700 });
});
afterEach(async () => {
@@ -1898,6 +1901,7 @@ describe("skill authentication", () => {
{
command: "validate",
auth: "auto",
+ directory: skillDirectory,
stdout: stdout.stream,
stderr: stderr.stream,
},
@@ -2140,6 +2144,7 @@ describe("skill authentication", () => {
{
command: "validate",
auth: "auto",
+ directory: skillDirectory,
stdout: capture().stream,
stderr: capture().stream,
},
@@ -2201,6 +2206,7 @@ describe("skill authentication", () => {
{
command: "validate",
auth,
+ directory: skillDirectory,
stdout: stdout.stream,
stderr: capture().stream,
},
@@ -2232,7 +2238,17 @@ describe("skill authentication", () => {
join(environment.CODEX_HOME, "config.toml"),
'model = "unrelated-model"',
);
- expect((await run()).args).toEqual([process.execPath]);
+ expect((await run()).args).toEqual([
+ process.execPath,
+ "--config",
+ expect.stringMatching(
+ /^responses_api_metadata\.codex_security_operation_id="[^"]+"$/u,
+ ),
+ "--config",
+ expect.stringMatching(
+ /^responses_api_metadata\.codex_security_attempt_id="[^"]+"$/u,
+ ),
+ ]);
expect(
parseToml(await readFile(join(runtimeHome, "config.toml"), "utf8")),
).toEqual({
@@ -2342,10 +2358,12 @@ if (basename(process.argv[1] ?? "") === "login" && process.argv[2] === "status")
unauthorized
? 'console.error("401 Unauthorized"); process.exit(1)'
: 'console.log(JSON.stringify({type:"item.completed",item:{type:"agent_message",text:"done"}}))',
+ "--",
],
{
command: "validate",
auth: "chatgpt",
+ directory: skillDirectory,
stdout: capture().stream,
stderr: stderr.stream,
},
diff --git a/sdk/typescript/tests-ts/cli-show-cost.test.ts b/sdk/typescript/tests-ts/cli-show-cost.test.ts
index eb6e2249d..de924624d 100644
--- a/sdk/typescript/tests-ts/cli-show-cost.test.ts
+++ b/sdk/typescript/tests-ts/cli-show-cost.test.ts
@@ -141,37 +141,163 @@ test("headless scan reports account limits independently of token receipts", asy
expect(JSON.parse(stdout.text())).toEqual(result.toJSON());
});
-test.each([
+const plainProgressModes = [
{ name: "headless", args: ["--headless"], tty: true, environment: {} },
{ name: "CI", args: [], tty: true, environment: { CI: "true" } },
{ name: "non-TTY", args: [], tty: false, environment: {} },
-])("shows live unpriced usage in $name scans", async (mode) => {
- const { stderr, runCli } = createCliTest(main, { stderr: mode.tty });
- const unpriced = new ScanResult({
- ...result,
- turnResult: {
- ...result.turnResult,
- model: "synthetic-unpriced-model",
- usage: observedUsage,
- },
- });
- expect(unpriced.cost).toBeNull();
- const deps = dependencies({ environment: mode.environment });
- deps.createSecurity = () =>
- fakeSecurity(async (_repository, options = {}) => {
- options.onScanStarted?.();
- await Promise.resolve().then(() => options.onUsage?.(observedUsage));
- expect(stderr.text()).toContain("1,280 total");
- expect(stderr.text()).not.toContain("REPORT");
- options.onScanStarted?.();
- const progress = stderr.text().trim().split("\n").at(-1);
- expect(progress).toContain("1,280 total");
- expect(progress).toContain("Usage report time unavailable");
- return unpriced;
+];
+
+test.each(plainProgressModes)(
+ "shows live unpriced usage in $name scans",
+ async (mode) => {
+ const { stderr, runCli } = createCliTest(main, { stderr: mode.tty });
+ const unpriced = new ScanResult({
+ ...result,
+ turnResult: {
+ ...result.turnResult,
+ model: "synthetic-unpriced-model",
+ usage: observedUsage,
+ },
});
- expect(await runCli(["scan", ".", ...mode.args], deps)).toBe(0);
- expect(stderr.text().split("REPORT")[1]).toContain("1,280 total");
-});
+ expect(unpriced.cost).toBeNull();
+ const deps = dependencies({ environment: mode.environment });
+ deps.createSecurity = () =>
+ fakeSecurity(async (_repository, options = {}) => {
+ options.onScanStarted?.();
+ await Promise.resolve().then(() => options.onUsage?.(observedUsage));
+ expect(stderr.text()).toContain("1,280 total");
+ expect(stderr.text()).not.toContain("REPORT");
+ options.onScanStarted?.();
+ const progress = stderr.text().trim().split("\n").at(-1);
+ expect(progress).toContain("1,280 total");
+ expect(progress).toContain("Usage report time unavailable");
+ return unpriced;
+ });
+ expect(await runCli(["scan", ".", ...mode.args], deps)).toBe(0);
+ expect(stderr.text().split("REPORT")[1]).toContain("1,280 total");
+ },
+);
+
+test.each(
+ plainProgressModes.flatMap((mode) =>
+ [false, true].map((priced) => ({ ...mode, priced })),
+ ),
+)(
+ "refreshes successive partial subtotals in $name scans (priced: $priced)",
+ async (mode) => {
+ const { stderr, runCli } = createCliTest(main, { stderr: mode.tty });
+ const deps = dependencies({ environment: mode.environment });
+ const updates: Array<{ total: number; output: string }> = [];
+ deps.createSecurity = () =>
+ fakeSecurity(async (_repository, options = {}) => {
+ options.onScanStarted?.();
+ for (const total of [100, 200, 300]) {
+ const usage: ScanTokenUsage = {
+ input_tokens: total - 20,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ cache_write_input_tokens_reported: true,
+ output_tokens: 20,
+ reasoning_output_tokens: 0,
+ total_tokens: total,
+ };
+ const offset = stderr.text().length;
+ options.onMeasurement?.({
+ usage,
+ cost: mode.priced ? fakeResult([], "complete", usage).cost : null,
+ coverage: "partial",
+ observedAt: "2026-01-01T00:00:00Z",
+ threadCount: 1,
+ missingThreadCount: 1,
+ });
+ updates.push({ total, output: stderr.text().slice(offset) });
+ }
+ return result;
+ });
+ expect(await runCli(["scan", ".", "--show-cost", ...mode.args], deps)).toBe(
+ 0,
+ );
+ const displayedCosts = new Set<string>();
+ for (const { total, output } of updates) {
+ expect(output).toContain(`${total} total (partial)`);
+ const cost = output.split(" | Cost: ")[1];
+ if (mode.priced) {
+ expect(cost).toContain("(partial)");
+ displayedCosts.add(cost!);
+ } else {
+ expect(cost).toBeUndefined();
+ }
+ }
+ expect(stderr.text().match(/Usage is partial/g)).toHaveLength(1);
+ expect(displayedCosts.size).toBe(mode.priced ? 3 : 0);
+ },
+);
+
+test.each(
+ plainProgressModes.flatMap((mode) =>
+ [false, true].flatMap((priced) =>
+ [false, true].map((changed) => ({ ...mode, priced, changed })),
+ ),
+ ),
+)(
+ "clears recovered usage coverage in $name scans (priced: $priced, changed: $changed)",
+ async (mode) => {
+ const { stderr, runCli } = createCliTest(main, { stderr: mode.tty });
+ const deps = dependencies({ environment: mode.environment });
+ let recovery = "";
+ const recoveredUsage = {
+ ...observedUsage,
+ input_tokens: observedUsage.input_tokens + (mode.changed ? 100 : 0),
+ total_tokens: observedUsage.total_tokens + (mode.changed ? 100 : 0),
+ };
+ deps.createSecurity = () =>
+ fakeSecurity(async (_repository, options = {}) => {
+ options.onScanStarted?.();
+ const measurement = {
+ usage: observedUsage,
+ cost: mode.priced ? result.cost : null,
+ coverage: "complete" as const,
+ observedAt: "2026-01-01T00:00:00Z",
+ threadCount: 1,
+ missingThreadCount: 0,
+ };
+ const initial = options.onMeasurement?.(measurement);
+ const usage = options.onUsage?.(observedUsage);
+ if (mode.priced) options.onCost?.(result.cost!);
+ await Promise.all([initial, usage]);
+ await options.onMeasurement?.({
+ ...measurement,
+ coverage: "partial",
+ missingThreadCount: 1,
+ });
+ const offset = stderr.text().length;
+ const cost = mode.priced
+ ? fakeResult([], "complete", recoveredUsage).cost
+ : null;
+ const observed = options.onMeasurement?.({
+ ...measurement,
+ usage: recoveredUsage,
+ cost,
+ threadCount: 2,
+ });
+ const updatedUsage = mode.changed
+ ? options.onUsage?.(recoveredUsage)
+ : undefined;
+ if (cost !== null) options.onCost?.(cost);
+ await Promise.all([observed, updatedUsage]);
+ recovery = stderr.text().slice(offset);
+ return result;
+ });
+ expect(await runCli(["scan", ".", "--show-cost", ...mode.args], deps)).toBe(
+ 0,
+ );
+ expect(recovery).toContain(
+ `${recoveredUsage.total_tokens.toLocaleString("en-US")} total`,
+ );
+ expect(recovery).not.toContain("(partial)");
+ expect(recovery.match(/Running scan/g)).toHaveLength(1);
+ },
+);
test.each(
[[], ["--show-cost"], ["--max-cost", "20"], ["--max-cost", "0.001"]].map(
@@ -185,6 +311,16 @@ test.each(
deps.createSecurity = () =>
fakeSecurity(async (_repository, options = {}) => {
options.onScanStarted?.();
+ const beforeMeasurement = stderr.text();
+ options.onMeasurement?.({
+ usage: observedUsage,
+ cost: result.cost!,
+ coverage: "complete",
+ observedAt: new Date().toISOString(),
+ threadCount: 1,
+ missingThreadCount: 0,
+ });
+ expect(stderr.text()).toBe(beforeMeasurement);
if (delivery === "direct") {
const observed = options.onUsage?.(observedUsage);
options.onCost?.(result.cost!);
diff --git a/sdk/typescript/tests-ts/cli-skill-native-config.test.ts b/sdk/typescript/tests-ts/cli-skill-native-config.test.ts
index 015b03970..5140e25e7 100644
--- a/sdk/typescript/tests-ts/cli-skill-native-config.test.ts
+++ b/sdk/typescript/tests-ts/cli-skill-native-config.test.ts
@@ -1,5 +1,6 @@
import { execFileSync, spawn } from "node:child_process";
import { once } from "node:events";
+import { watch } from "node:fs";
import {
mkdir,
mkdtemp,
@@ -13,6 +14,7 @@ import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { createInterface } from "node:readline";
import { expect, test } from "bun:test";
+import { parse as parseToml } from "smol-toml";
import { runCodexSkillCommand } from "../src/cli.js";
import {
inlineToml,
@@ -24,6 +26,7 @@ import {
resolveCodexCommand,
} from "../src/runtime.js";
import { capture } from "./cli-fixtures.js";
+import { readOperationTelemetry } from "../src/operation-telemetry.js";
const modelCatalog = fileURLToPath(
new URL("./fixtures/native-skill-model-catalog.json", import.meta.url),
@@ -35,8 +38,6 @@ const nativeConfigArgs = [
"--disable",
"plugins",
"--config",
- "analytics.enabled=false",
- "--config",
`model_catalog_json=${inlineToml(modelCatalog)}`,
];
@@ -230,7 +231,7 @@ test.each([
const stdout = capture();
const stderr = capture();
const status = await runCodexSkillCommand(
- nativeConfigArgs,
+ [...nativeConfigArgs, "--config", "analytics.enabled=false"],
{
command,
auth: "chatgpt",
@@ -278,10 +279,16 @@ async function withStoredApiKey(
ambientHome: string;
sharedHome: string;
repository: string;
- run: (overrides?: JsonObject) => Promise<{
+ run: (
+ overrides?: JsonObject,
+ options?: { inheritAnalytics?: boolean; auth?: "auto" | "api-key" },
+ ) => Promise<{
daybreak: boolean | null;
daybreakEnabled: boolean | null;
daybreakFeatures: Record<string, boolean | null>;
+ analytics: JsonObject | null;
+ otel: JsonObject | null;
+ requestMetadata: JsonObject | null;
}>;
}) => Promise<void>,
): Promise<void> {
@@ -318,12 +325,15 @@ async function withStoredApiKey(
ambientHome,
sharedHome,
repository,
- run: async (overrides = {}) => {
+ run: async (overrides = {}, options = {}) => {
const stdout = capture();
const stderr = capture();
const status = await runCodexSkillCommand(
[
...nativeConfigArgs,
+ ...(options.inheritAnalytics
+ ? []
+ : ["--config", "analytics.enabled=false"]),
...Object.entries(overrides).flatMap(([key, value]) => [
"--config",
`${key}=${inlineToml(value)}`,
@@ -331,7 +341,7 @@ async function withStoredApiKey(
],
{
command,
- auth: "auto",
+ auth: options.auth ?? "auto",
codexOverrides: overrides,
directory: repository,
stdout: stdout.stream,
@@ -349,7 +359,12 @@ async function withStoredApiKey(
},
},
{ command: process.execPath },
- environment,
+ {
+ ...environment,
+ ...(options.auth === "api-key"
+ ? { OPENAI_API_KEY: "SYNTHETIC_KEY" }
+ : {}),
+ },
);
expect(status, stderr.text()).toBe(0);
return JSON.parse(stdout.text());
@@ -360,6 +375,183 @@ async function withStoredApiKey(
}
}
+test.each(["patch", "verify-fix"] as const)(
+ "%s preserves consent and private-home exporters without copying inherited headers",
+ async (command) => {
+ await withStoredApiKey(
+ command,
+ async ({
+ root,
+ environment,
+ ambientHome,
+ sharedHome,
+ repository,
+ run,
+ }) => {
+ environment["SYNTHETIC_CONFIG_OBSERVATIONS"] = join(
+ root,
+ "native-config.jsonl",
+ );
+ const configPath = join(ambientHome, "config.toml");
+ const privateOtel = {
+ environment: "synthetic-shared",
+ exporter: "none",
+ log_user_prompt: false,
+ };
+ await writeCodexConfig(join(sharedHome, "config.toml"), {
+ otel: privateOtel,
+ });
+ const telemetry = {
+ analytics: { enabled: false },
+ otel: {
+ environment: "synthetic-selected",
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://telemetry.example.test/v1/logs",
+ protocol: "json",
+ headers: {
+ Authorization: "Bearer synthetic-selected-exporter",
+ },
+ },
+ },
+ log_user_prompt: false,
+ },
+ responses_api_metadata: {
+ "team.tag": "selected",
+ root_only: "root",
+ selected_only: "selected",
+ },
+ };
+ await writeCodexConfig(configPath, {
+ analytics: { enabled: true },
+ otel: {
+ environment: "synthetic-root",
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://telemetry.example.test/v1/logs",
+ protocol: "json",
+ headers: { Authorization: "Bearer synthetic-root-exporter" },
+ },
+ },
+ },
+ responses_api_metadata: { "team.tag": "root", root_only: "root" },
+ projects: { [repository]: { trust_level: "trusted" } },
+ profile: "selected",
+ profiles: { selected: telemetry },
+ });
+ // Compare actual native project precedence, including ignored telemetry
+ // keys, instead of reimplementing which project settings Codex permits.
+ await writeCodexConfig(join(repository, ".codex", "config.toml"), {
+ analytics: { enabled: false },
+ otel: { environment: "synthetic-project", exporter: "none" },
+ responses_api_metadata: { "project.tag": "project" },
+ });
+ const inherited = await run({}, { inheritAnalytics: true });
+ const records = await readOperationTelemetry(
+ environment["CODEX_SECURITY_STATE_DIR"]!,
+ );
+ expect(records.events.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(records.events[1]).toMatchObject({
+ command,
+ outcome: "completed",
+ });
+ expect(inherited.requestMetadata).toMatchObject({
+ codex_security_operation_id: records.events[0]!.operationId,
+ codex_security_attempt_id: records.events[0]!.attemptId,
+ });
+ expect(inherited).toMatchObject({
+ analytics: telemetry.analytics,
+ otel: privateOtel,
+ requestMetadata: telemetry.responses_api_metadata,
+ });
+ const launches = (
+ await readFile(environment["SYNTHETIC_CONFIG_OBSERVATIONS"], "utf8")
+ )
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ expect(launches.length).toBeGreaterThanOrEqual(2);
+ for (const launch of launches) {
+ expect(launch.analytics).toEqual(telemetry.analytics);
+ expect(launch.otel).toMatchObject(privateOtel);
+ expect(JSON.stringify(launch.args)).not.toContain(
+ "synthetic-selected-exporter",
+ );
+ expect(JSON.stringify(launch.args)).not.toContain(
+ "synthetic-root-exporter",
+ );
+ expect(launch.metadata).toMatchObject(
+ telemetry.responses_api_metadata,
+ );
+ }
+ const explicit = {
+ analytics: { enabled: false },
+ otel: { environment: "synthetic-explicit", exporter: "none" },
+ responses_api_metadata: {
+ "team.tag": "explicit",
+ codex_security_command: command,
+ },
+ };
+ const configured = await run(explicit, { inheritAnalytics: true });
+ expect(configured).toMatchObject({
+ analytics: explicit.analytics,
+ otel: { ...privateOtel, ...explicit.otel },
+ requestMetadata: {
+ ...telemetry.responses_api_metadata,
+ ...explicit.responses_api_metadata,
+ },
+ });
+ const shared = parseToml(
+ await readFile(join(sharedHome, "config.toml"), "utf8"),
+ );
+ expect(shared["otel"]).toEqual(privateOtel);
+ for (const key of ["analytics", "responses_api_metadata"])
+ expect(shared).not.toHaveProperty(key);
+
+ // A subsequent invocation must not retain the earlier ambient profile.
+ await writeCodexConfig(configPath, {
+ analytics: { enabled: false },
+ otel: { environment: "synthetic-next", exporter: "none" },
+ });
+ const next = await run({}, { inheritAnalytics: true });
+ expect(next.otel).toMatchObject(privateOtel);
+ expect(next.requestMetadata ?? {}).not.toHaveProperty("selected_only");
+ },
+ );
+ },
+);
+
+test("stored and API-key patches preserve consent while exporters follow their selected native home", async () => {
+ await withStoredApiKey("patch", async ({ ambientHome, run }) => {
+ await writeCodexConfig(join(ambientHome, "config.toml"), {
+ analytics: { enabled: false },
+ otel: {
+ environment: "synthetic-auth-independent",
+ exporter: "none",
+ log_user_prompt: false,
+ },
+ responses_api_metadata: { "team.tag": "synthetic-ambient" },
+ });
+ const stored = await run({}, { inheritAnalytics: true });
+ const apiKey = await run({}, { inheritAnalytics: true, auth: "api-key" });
+ expect(stored.analytics).toEqual(apiKey.analytics);
+ expect(stored.otel?.["environment"]).not.toBe("synthetic-auth-independent");
+ expect(apiKey.otel?.["environment"]).toBe("synthetic-auth-independent");
+ expect(stored.requestMetadata).toMatchObject({
+ "team.tag": "synthetic-ambient",
+ });
+ expect(apiKey.requestMetadata).toMatchObject({
+ "team.tag": "synthetic-ambient",
+ });
+ expect(stored.requestMetadata?.["codex_security_attempt_id"]).not.toBe(
+ apiKey.requestMetadata?.["codex_security_attempt_id"],
+ );
+ });
+});
+
test.each([
["patch", true],
["patch", false],
@@ -430,7 +622,14 @@ test("patch clears removed ambient Daybreak settings on the next stored API-key
daybreakFeatures: disabledDaybreakFeatures,
});
await writeCodexConfig(configPath, {});
- expect(await run()).toEqual(baseline);
+ const next = await run();
+ expect({ ...next, requestMetadata: undefined }).toEqual({
+ ...baseline,
+ requestMetadata: undefined,
+ });
+ expect(next.requestMetadata?.["codex_security_attempt_id"]).not.toBe(
+ baseline.requestMetadata?.["codex_security_attempt_id"],
+ );
});
});
@@ -484,6 +683,13 @@ test.each(["omitted", "omitted with changed gates", "explicit"] as const)(
api_key_cyber_access_programs: true,
api_key_model_discovery: true,
},
+ analytics: { enabled: false },
+ otel: {
+ environment: "synthetic-worker",
+ exporter: "none",
+ log_user_prompt: false,
+ },
+ responses_api_metadata: { "synthetic.tag": "worker" },
};
await writeCodexConfig(scanConfig, {});
await writeCodexConfig(workerConfig, { worker_runtime: workerRuntime });
@@ -549,6 +755,7 @@ test.each(["omitted", "omitted with changed gates", "explicit"] as const)(
cli_auth_credentials_store: "file",
features: { plugins: false },
analytics: { enabled: false },
+ otel: { environment: "synthetic-shared", exporter: "none" },
};
await writeCodexConfig(join(sharedHome, "config.toml"), workerConfig);
// The first worker initializes the executor's per-scan snapshot.
@@ -559,6 +766,12 @@ test.each(["omitted", "omitted with changed gates", "explicit"] as const)(
expect(baseline.daybreak).toBe(
settings === "explicit" ? false : null,
);
+ expect(baseline.telemetry).toEqual({
+ analyticsEnabled: false,
+ environment:
+ settings === "explicit" ? "synthetic-worker" : "synthetic-shared",
+ metadataTag: settings === "explicit" ? "worker" : null,
+ });
if (settings === "explicit")
expect(baseline.daybreakFeatures).toEqual(
workerRuntime["features"],
@@ -573,6 +786,9 @@ test.each(["omitted", "omitted with changed gates", "explicit"] as const)(
await writeCodexConfig(join(ambientHome, "config.toml"), {
daybreak: true,
...(features === undefined ? {} : { features }),
+ analytics: { enabled: false },
+ otel: { environment: "synthetic-patch", exporter: "none" },
+ responses_api_metadata: { "synthetic.tag": "patch" },
});
expect(await run()).toMatchObject({
daybreak: true,
@@ -609,3 +825,53 @@ test.each(["omitted", "omitted with changed gates", "explicit"] as const)(
);
},
);
+
+test.each([
+ ["AbortError", "canceled", "canceled", false],
+ ["TimeoutError", "failed", "execution", false],
+ ["AbortError", "canceled", "canceled", true],
+ ["TimeoutError", "failed", "execution", true],
+] as const)(
+ "records %s as %s/%s in the skill receipt (after launch: %p)",
+ async (name, outcome, failureCategory, afterLaunch) => {
+ const state = await mkdtemp(join(tmpdir(), "skill-startup-journal-"));
+ try {
+ const reason = new DOMException("fixture stop", name);
+ const controller = new AbortController();
+ const readyDir = join(state, "child");
+ await mkdir(readyDir);
+ const script = join(state, "child.mjs");
+ await writeFile(
+ script,
+ `import { writeFileSync } from "node:fs"; writeFileSync(${JSON.stringify(join(readyDir, "ready"))}, ""); setTimeout(() => {}, 10000);`,
+ );
+ const watcher = watch(readyDir, () => controller.abort(reason));
+ try {
+ if (!afterLaunch) controller.abort(reason);
+ const result = runCodexSkillCommand(
+ [script],
+ {
+ command: "patch",
+ stdout: capture().stream,
+ stderr: capture().stream,
+ signal: controller.signal,
+ },
+ { command: process.execPath },
+ { ...process.env, CODEX_SECURITY_STATE_DIR: state },
+ );
+ if (afterLaunch) expect(await result).toBe(143);
+ else await expect(result).rejects.toBe(reason);
+ } finally {
+ watcher.close();
+ }
+ const record = await readOperationTelemetry(state);
+ expect(record.events.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(record.events[1]).toMatchObject({ outcome, failureCategory });
+ } finally {
+ await rm(state, { recursive: true, force: true });
+ }
+ },
+);
diff --git a/sdk/typescript/tests-ts/cli-skills.test.ts b/sdk/typescript/tests-ts/cli-skills.test.ts
index 0c85e8188..2f10467a9 100644
--- a/sdk/typescript/tests-ts/cli-skills.test.ts
+++ b/sdk/typescript/tests-ts/cli-skills.test.ts
@@ -3,13 +3,14 @@ import { execFileSync, spawn } from "node:child_process";
import { mkdir, rm, symlink, writeFile } from "node:fs/promises";
import * as filesystem from "node:fs/promises";
import { join, posix, resolve, win32 } from "node:path";
+import { Writable } from "node:stream";
import { setTimeout as delay } from "node:timers/promises";
-import { describe, expect, spyOn, test, mock } from "bun:test";
+import { afterEach, describe, expect, spyOn, test, mock } from "bun:test";
import { parse as parseToml } from "smol-toml";
import {
main,
readSkillCommandOutput,
- runCodexSkillCommand,
+ runCodexSkillCommand as runNativeSkillCommand,
skillCommandFailure,
} from "../src/cli.js";
import type { LinearClientFactory } from "../src/linear.js";
@@ -19,6 +20,7 @@ import { PLUGIN_ROOT } from "./plugin-root.js";
import { capture, dependencies, type OnCodex } from "./cli-fixtures.js";
import { runTestInSubprocess } from "./support/test-subprocess.js";
import {
+ createApiTestFixtures,
scopedTemporaryDirectory,
temporaryDirectory,
} from "./support/temporary-directories.js";
@@ -29,6 +31,28 @@ import {
runCapturedCli,
} from "./support/cli-run.js";
+const skillState = createApiTestFixtures("cli-skill-process-state-");
+afterEach(skillState.cleanup);
+
+async function runCodexSkillCommand(
+ ...[args, output, command, environment, input]: Parameters<
+ typeof runNativeSkillCommand
+ >
+): Promise<number> {
+ return await runNativeSkillCommand(
+ args,
+ output,
+ command,
+ {
+ ...(environment ?? process.env),
+ CODEX_SECURITY_STATE_DIR:
+ environment?.["CODEX_SECURITY_STATE_DIR"] ??
+ (await skillState.temporaryDirectory()),
+ },
+ input,
+ );
+}
+
function linearIssue(identifier: string, comments: string[] = []) {
const nodes = comments.map((body, index) => ({
body,
@@ -1338,7 +1362,7 @@ describe("CLI skill commands", () => {
["-e", source],
{ command: "validate", stdout: stdout.stream, stderr: stderr.stream },
{ command: process.execPath },
- process.env,
+ undefined,
input,
),
).resolves.toBe(0);
@@ -1346,6 +1370,51 @@ describe("CLI skill commands", () => {
expect(stderr.text()).toBe("");
});
+ test.each(["save", "start"] as const)(
+ "ignores asynchronous stderr failures while reporting telemetry %s errors",
+ async (phase) => {
+ if (
+ runTestInSubprocess(
+ import.meta.path,
+ `ignores asynchronous stderr failures while reporting telemetry ${phase} errors`,
+ )
+ ) {
+ return;
+ }
+ const directory = await temporaryDirectory("telemetry-warning-");
+ const stdout = capture();
+ let diagnostic = "";
+ const stderr = new Writable({
+ write(chunk, _encoding, callback) {
+ diagnostic += chunk.toString();
+ callback(new Error("Synthetic broken diagnostic stream"));
+ },
+ });
+ try {
+ await writeFile(join(directory, "telemetry"), "occupied");
+ const environment = {
+ CODEX_SECURITY_STATE_DIR:
+ phase === "save" ? directory : join(directory, "invalid\nstate"),
+ };
+ const source =
+ 'process.stdout.write(JSON.stringify({type:"item.completed",item:{type:"agent_message",text:"Synthetic command result"}})+"\\n")';
+ await expect(
+ runCodexSkillCommand(
+ ["-e", source],
+ { command: "validate", stdout: stdout.stream, stderr },
+ { command: process.execPath },
+ environment,
+ ),
+ ).resolves.toBe(0);
+ expect(stdout.text()).toBe("Synthetic command result\n");
+ expect(diagnostic).toContain(`Could not ${phase} operation telemetry:`);
+ } finally {
+ stderr.destroy();
+ await rm(directory, { recursive: true, force: true });
+ }
+ },
+ );
+
test("preserves the selected Codex home from copied Windows environments", async () => {
const configuredHome = "./synthetic home with spaces";
const source = `
@@ -1942,6 +2011,7 @@ const status = await runCodexSkillCommand(
[${JSON.stringify(child)}],
{ command: "validate", stdout: process.stdout, stderr: process.stderr },
{ command: process.execPath },
+ { ...process.env, CODEX_SECURITY_STATE_DIR: ${JSON.stringify(join(directory, "state"))} },
);
process.exit(status);
`,
diff --git a/sdk/typescript/tests-ts/codex-process-cancellation.test.ts b/sdk/typescript/tests-ts/codex-process-cancellation.test.ts
index df7d64253..2702bff76 100644
--- a/sdk/typescript/tests-ts/codex-process-cancellation.test.ts
+++ b/sdk/typescript/tests-ts/codex-process-cancellation.test.ts
@@ -35,11 +35,20 @@ test.each([
"a running skill child honors controller abort (%s)",
async (reason, status) => {
const controller = new AbortController();
- using observed = spyOn(childProcess, "spawn");
+ const spawned = Promise.withResolvers<ReturnType<typeof spawn>>();
+ const originalSpawn = childProcess.spawn;
+ using _observer = spyOn(childProcess, "spawn").mockImplementation(((
+ ...args: Parameters<typeof originalSpawn>
+ ) => {
+ const child = originalSpawn(...args);
+ spawned.resolve(child);
+ return child;
+ }) as typeof originalSpawn);
const run = runCodexSkillCommand(
[
"-e",
"process.on('SIGTERM', () => {}); process.stdout.write('{}\\n'); setTimeout(() => process.exit(1), 4000);",
+ "--",
],
{
command: "verify-fix",
@@ -48,8 +57,9 @@ test.each([
stderr: process.stderr,
},
{ command: node },
+ { ...process.env, CODEX_SECURITY_STATE_DIR: await temporaryDirectory() },
);
- const child = observed.mock.results[0]!.value as ReturnType<typeof spawn>;
+ const child = await spawned.promise;
try {
await once(child.stdout!, "data");
controller.abort(reason === "SIGINT" ? reason : undefined);
diff --git a/sdk/typescript/tests-ts/component-scan.test.ts b/sdk/typescript/tests-ts/component-scan.test.ts
index 35bf2c910..8426f00c9 100644
--- a/sdk/typescript/tests-ts/component-scan.test.ts
+++ b/sdk/typescript/tests-ts/component-scan.test.ts
@@ -355,6 +355,98 @@ test("links independently scoped saved models including a failed component", asy
expect(summary).toMatchObject({ completed: 1, failed: 1 });
});
+test("retains unpriced partial usage for failed components without a progress observer", async () => {
+ const paths = await fixture();
+ const measurement = {
+ coverage: "partial" as const,
+ cost: null,
+ observedAt: "2026-10-01T00:00:00.000Z",
+ threadCount: 1,
+ missingThreadCount: 1,
+ usage: {
+ input_tokens: 100,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ cache_write_input_tokens_reported: false,
+ output_tokens: 5,
+ reasoning_output_tokens: 0,
+ total_tokens: 105,
+ },
+ };
+ const result = await scan(paths, {
+ components: components.slice(0, 1),
+ createSecurity: client(async (_repository, options) => {
+ options.onMeasurement?.(measurement);
+ throw new Error("Synthetic component failure");
+ }),
+ });
+ expect(await json(result.summaryPath!)).toMatchObject({
+ components: [{ status: "failed", outcome: "failed", measurement }],
+ });
+});
+
+test.each([
+ ["caller only", false, "observe", "observe"],
+ ["both observers", true, "observe", "observe"],
+ ["throwing caller", true, "throw", "observe"],
+ ["rejecting caller", true, "reject", "observe"],
+ ["throwing component observer", true, "observe", "throw"],
+ ["rejecting component observer", true, "observe", "reject"],
+] as const)(
+ "preserves the caller measurement observer with %s",
+ async (_label, withEvents, callerBehavior, eventBehavior) => {
+ const paths = await fixture();
+ const measurement = {
+ coverage: "unavailable" as const,
+ cost: null,
+ observedAt: "2026-10-01T00:00:00.000Z",
+ threadCount: 0,
+ missingThreadCount: 1,
+ usage: null,
+ };
+ const callerMeasurements: unknown[] = [];
+ const componentMeasurements: unknown[] = [];
+ const result = await scan(paths, {
+ components: components.slice(0, 1),
+ scanOptions: {
+ onMeasurement: (value) => {
+ callerMeasurements.push(value);
+ if (callerBehavior === "throw")
+ throw new Error("Synthetic caller observer failure.");
+ if (callerBehavior === "reject")
+ return Promise.reject(
+ new Error("Synthetic caller observer rejection."),
+ );
+ },
+ },
+ ...(withEvents
+ ? {
+ onScanEvent: (event: ComponentScanEvent) => {
+ if (event.type !== "measurement") return;
+ componentMeasurements.push(event.value);
+ if (eventBehavior === "throw")
+ throw new Error("Synthetic component observer failure.");
+ if (eventBehavior === "reject")
+ return Promise.reject(
+ new Error("Synthetic component observer rejection."),
+ );
+ },
+ }
+ : {}),
+ createSecurity: client(async (repository, options) => {
+ options.onMeasurement?.(measurement);
+ return completed(repository, options, []);
+ }),
+ });
+ expect(result).toMatchObject({ completed: 1, failed: 0 });
+ expect(callerMeasurements).toEqual([measurement]);
+ expect(componentMeasurements).toEqual(withEvents ? [measurement] : []);
+ expect(await json(result.summaryPath!)).toMatchObject({
+ components: [{ status: "completed", outcome: "completed", measurement }],
+ });
+ },
+);
+
test("omits a failed component's stale model link while retaining its model", async () => {
const paths = await fixture();
execFileSync("git", ["-C", paths.repository, "init", "--quiet"]);
diff --git a/sdk/typescript/tests-ts/cost-node.test.ts b/sdk/typescript/tests-ts/cost-node.test.ts
new file mode 100644
index 000000000..823a7f546
--- /dev/null
+++ b/sdk/typescript/tests-ts/cost-node.test.ts
@@ -0,0 +1,145 @@
+import { execFile } from "node:child_process";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { zstdCompressSync } from "node:zlib";
+import { afterEach, beforeAll, expect, test } from "bun:test";
+import { PLUGIN_ROOT } from "./plugin-root.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { writeSession } from "./support/usage-rollout.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "codex-security-cost-node-",
+);
+afterEach(cleanup);
+
+let moduleSource: string;
+beforeAll(async () => {
+ const { stdout } = await promisify(execFile)(
+ process.execPath,
+ [
+ "build",
+ fileURLToPath(new URL("../src/cost.ts", import.meta.url)),
+ "--target=node",
+ "--format=esm",
+ ],
+ { encoding: "utf8" },
+ );
+ moduleSource = stdout;
+});
+
+for (const capabilities of ["native", "without zstd"]) {
+ test.each([
+ ["complete", false],
+ ["complete", true],
+ ["truncated", false],
+ ["truncated", true],
+ ] as const)(
+ `accounts for every compressed frame in Node with ${capabilities} capabilities (%s; session events=%p)`,
+ async (tail, observeSessionEvents) => {
+ const root = await temporaryDirectory();
+ const home = join(root, "home");
+ await writeSession(home, "parent", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ const frame = (records: unknown[]) =>
+ zstdCompressSync(
+ `${records.map((record) => JSON.stringify(record)).join("\n")}\n`,
+ );
+ const usage = (input: number, output: number) => ({
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: { input_tokens: input, output_tokens: output },
+ },
+ },
+ });
+ const firstFrame = frame([
+ {
+ type: "session_meta",
+ payload: { id: "worker", parent_thread_id: "parent" },
+ },
+ usage(900, 90),
+ ]);
+ const lastFrame = frame([usage(1_900, 190)]);
+ await writeFile(
+ join(home, "sessions", "rollout-worker.jsonl.zst"),
+ Buffer.concat([
+ firstFrame,
+ tail === "truncated"
+ ? lastFrame.subarray(0, lastFrame.length - 3)
+ : lastFrame,
+ ]),
+ );
+
+ for (const relativePath of [
+ ".codex-plugin/plugin.json",
+ "mcp/session-decompression.mjs",
+ ]) {
+ const destination = join(root, "_bundled_plugin", relativePath);
+ await mkdir(dirname(destination), { recursive: true });
+ await copyFile(join(PLUGIN_ROOT, relativePath), destination);
+ }
+ const module = join(root, "dist", "cost.mjs");
+ await mkdir(dirname(module), { recursive: true });
+ await writeFile(module, moduleSource);
+ const { stdout } = await promisify(execFile)(
+ "node",
+ [
+ "--input-type=module",
+ "--eval",
+ `
+ import zlib from "node:zlib";
+ if (${JSON.stringify(capabilities)} === "without zstd") {
+ delete zlib.createZstdDecompress;
+ }
+ const { ScanCostTracker } = await import(${JSON.stringify(pathToFileURL(module).href)});
+ let measurement;
+ const tracker = new ScanCostTracker({
+ codexHome: ${JSON.stringify(home)},
+ model: "gpt-5.6-sol",
+ onMeasurement: (value) => { measurement = value; },
+ onError: () => {},
+ ${observeSessionEvents ? "onSessionEvent: () => {}," : ""}
+ });
+ tracker.start("parent");
+ let error = null;
+ try {
+ await tracker.stop();
+ } catch (caught) {
+ error = String(caught);
+ }
+ console.log(JSON.stringify({ measurement, error }));
+ `,
+ ],
+ { encoding: "utf8" },
+ );
+ const result = JSON.parse(stdout);
+ if (tail === "truncated") {
+ expect(result.error).not.toBeNull();
+ expect(result.measurement.coverage).toBe("partial");
+ expect(result.measurement.missingThreadCount).toBeGreaterThan(0);
+ expect(result.measurement.usage).toMatchObject({
+ input_tokens: 1_000,
+ output_tokens: 100,
+ });
+ expect(result.measurement.cost).toMatchObject({
+ inputTokens: 1_000,
+ outputTokens: 100,
+ });
+ } else {
+ expect(result.error).toBeNull();
+ expect(result.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ usage: { input_tokens: 2_000, output_tokens: 200 },
+ cost: { inputTokens: 2_000, outputTokens: 200 },
+ });
+ }
+ },
+ );
+}
diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.ts
index aaf880f1d..238db1766 100644
--- a/sdk/typescript/tests-ts/cost.test.ts
+++ b/sdk/typescript/tests-ts/cost.test.ts
@@ -7,17 +7,21 @@ import { runNodePython } from "./support/python-probe.js";
import * as filesystem from "node:fs/promises";
import { appendFile, writeFile } from "node:fs/promises";
import { basename, dirname, join, parse, sep } from "node:path";
+import zlib from "node:zlib";
import { Codex } from "@openai/codex-sdk";
import { afterEach, describe, expect, spyOn, test } from "bun:test";
import {
estimateScanCost,
+ readScanBudgetUsage,
ScanCostTracker,
type ScanSessionEvent,
type ScanUsageObservation,
type ScanWorkerEvent,
+ type ScanUsageMeasurement,
} from "../src/cost.js";
import type { ScanActivity } from "../src/scan-activity.js";
import { formatTokenUsage, tokenUsage } from "../src/cost-model.js";
+import { measuredScanCost } from "../src/scan-measurement.js";
import { readScanLogs } from "../src/scan-logs.js";
import { sessionParentThreadId } from "../src/scan-sessions.js";
import type { ScanProgress } from "../src/worker-progress.js";
@@ -61,6 +65,34 @@ async function waitFor(check: () => boolean): Promise<void> {
afterEach(cleanup);
+test("warning-only budget measurements keep the reason for partial coverage in terminal receipts", async () => {
+ const tracker = new ScanCostTracker({
+ model: "synthetic-unpriced-model",
+ codexHome: await codexHome(),
+ readBudgetUsage: (threadId) =>
+ readScanBudgetUsage(
+ async () => ({
+ ...ownedPythonUsage,
+ threadCount: 1,
+ coverage: "partial",
+ coverageScope: ["thread:primary"],
+ warnings: ["turn_interrupted"],
+ }),
+ "scan",
+ threadId,
+ ),
+ });
+ tracker.start("primary");
+ const { measurement } = await tracker.stop();
+ expect(measuredScanCost(measurement)?.usage).toMatchObject({
+ coverage: "partial",
+ threadCount: 1,
+ missingThreadCount: 0,
+ warnings: ["turn_interrupted"],
+ totalTokens: ownedPythonUsage.totalTokens,
+ });
+});
+
test("a partial owned subtotal includes spending absent from local session logs", async () => {
const home = await codexHome();
const observed: Array<[number, boolean]> = [];
@@ -69,19 +101,42 @@ test("a partial owned subtotal includes spending absent from local session logs"
codexHome: home,
model: "gpt-5.6-sol",
maxCostUsd: 1,
- readBudgetUsage: async () => ({
- usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },
- complete,
- }),
+ readBudgetUsage: (threadId) =>
+ readScanBudgetUsage(
+ async () => ({
+ ...ownedPythonUsage,
+ coverage: complete ? "complete" : "partial",
+ threadCount: complete ? 2 : 1,
+ missingThreadCount: complete ? 0 : 1,
+ coverageScope: ["thread:primary", "thread:worker"],
+ cacheWriteInputTokensReported: complete,
+ }),
+ "scan",
+ threadId,
+ ),
onCost: (cost, coverage) => observed.push([cost.inputTokens, coverage]),
});
tracker.start("primary");
try {
- await tracker.refresh();
+ const partial = await tracker.refresh();
+ expect(partial.measurement).toMatchObject({
+ coverage: "partial",
+ threadCount: 1,
+ missingThreadCount: 1,
+ coverageScope: ["thread:primary", "thread:worker"],
+ usage: { ...ownedSdkUsage, cache_write_input_tokens_reported: false },
+ });
expect(observed).toEqual([[ownedSdkUsage.input_tokens, false]]);
complete = true;
// The SDK's parent receipt omits the detached worker's usage.
const final = await tracker.stop({ input_tokens: 1, output_tokens: 1 });
+ expect(final.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ coverageScope: ["thread:primary", "thread:worker"],
+ });
+ expect(final.measurement.usage).toEqual(ownedSdkUsage);
expect(final.cost?.inputTokens).toBe(ownedSdkUsage.input_tokens);
expect(observed.at(-1)).toEqual([ownedSdkUsage.input_tokens, true]);
} finally {
@@ -2081,7 +2136,11 @@ describe("scan cost", () => {
onUsageObservation: (observation) => observations.push(observation),
});
tracker.start(scanThreadId);
- expect((await tracker.stop()).usage).toEqual(ownedSdkUsage);
+ expect((await tracker.stop()).measurement).toMatchObject({
+ coverage: "partial",
+ usage: ownedSdkUsage,
+ missingThreadCount: 1,
+ });
expect(observations).toEqual([
{
tokensUpdatedAt: "2026-07-26T12:02:00.250Z",
@@ -3121,6 +3180,328 @@ describe("live scan cost tracking", () => {
expect(events).toHaveLength(6);
});
+ for (const compressed of [false, true]) {
+ test
+ .skipIf(compressed && typeof zlib.zstdCompressSync !== "function")
+ .each(["initial copies", "copy", "move"] as const)(
+ `forwards archived session events once after %s (compressed=${compressed})`,
+ async (mode) => {
+ const { home, worker } = await workerSessionFixture();
+ const message = {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "Checking the next file." }],
+ },
+ };
+ const call = {
+ type: "response_item",
+ payload: {
+ type: "function_call",
+ name: "exec_command",
+ call_id: "call-one",
+ arguments: '{"cmd":"pwd"}',
+ },
+ };
+ // Identical messages at different positions are separate real events.
+ await appendFile(worker, jsonLines([message, call, message]) + "\n");
+ const contents = await filesystem.readFile(worker);
+ const expected = contents
+ .toString()
+ .trimEnd()
+ .split("\n")
+ .map((line) => JSON.parse(line) as Record<string, unknown>);
+ const archive = join(home, "archived_sessions");
+ await filesystem.mkdir(archive);
+ const archived = join(archive, "rollout-worker.jsonl");
+ const copy = () =>
+ writeFile(
+ `${archived}${compressed ? ".zst" : ""}`,
+ compressed ? zlib.zstdCompressSync(contents) : contents,
+ );
+ if (mode === "initial copies") await copy();
+ const events: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ onSessionEvent: (event) => events.push(event),
+ });
+ const workerEvents = () =>
+ events
+ .filter((event) => event.threadId === "worker-thread")
+ .map((event) => event.event);
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+ if (mode !== "initial copies") await copy();
+ if (mode === "move") await filesystem.unlink(worker);
+ await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+
+ // Resuming cold history materializes the same bytes before appending.
+ if (compressed) await writeFile(archived, contents);
+ const continuation = [
+ message,
+ {
+ type: "response_item",
+ payload: {
+ type: "function_call_output",
+ call_id: "call-one",
+ output: "/synthetic/repository",
+ },
+ },
+ ];
+ await appendFile(archived, jsonLines(continuation) + "\n");
+ expected.push(...continuation);
+ await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+
+ // A lagging copy catching up must not replay the new suffix.
+ if (mode !== "move") {
+ await appendFile(worker, jsonLines(continuation) + "\n");
+ await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+ }
+ const latest = [
+ message,
+ legacyUsageRecord({ input_tokens: 400, output_tokens: 40 }),
+ ];
+ await appendFile(
+ mode === "move" ? archived : worker,
+ jsonLines(latest) + "\n",
+ );
+ expected.push(...latest);
+ const snapshot = await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+ expect(snapshot.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ usage: { input_tokens: 500, output_tokens: 50 },
+ });
+ await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+ }
+
+ test("forwards a new rollout generation for an existing thread", async () => {
+ const home = await codexHome();
+ const usage = { input_tokens: 100, output_tokens: 10 };
+ await writeSession(home, "scan-thread", usage);
+ const worker = await writeSession(home, "worker-thread", usage, {
+ parent: "scan-thread",
+ timestamp: "2026-07-26T12:00:00.000Z",
+ });
+ const events: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ onSessionEvent: (event) => events.push(event),
+ });
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ const oldEvents = events
+ .filter((event) => event.threadId === "worker-thread")
+ .map((event) => event.event);
+ expect(oldEvents).toHaveLength(2);
+ // Revert keeps the thread ID but creates a new rollout and timestamp.
+ const metadata = oldEvents[0]!;
+ const newEvents = [
+ {
+ ...metadata,
+ payload: {
+ ...(metadata["payload"] as Record<string, unknown>),
+ timestamp: "2026-07-26T12:01:00.000Z",
+ },
+ },
+ oldEvents[1]!,
+ ];
+ await writeFile(
+ `${worker.slice(0, -6)}_reverted.jsonl`,
+ jsonLines(newEvents) + "\n",
+ );
+ await tracker.refresh();
+ await tracker.refresh();
+ expect(
+ events
+ .filter((event) => event.threadId === "worker-thread")
+ .map((event) => event.event),
+ ).toEqual([...oldEvents, ...newEvents]);
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test("retains parent progress order when an archived copy continues the rollout", async () => {
+ const { home, parent } = await workerSessionFixture();
+ const phases: ScanProgress["phase"][] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => phases.push(update.phase),
+ });
+ const archive = join(home, "archived_sessions");
+ await filesystem.mkdir(archive);
+ const copy = join(archive, "rollout-parent.jsonl");
+ await appendSessionItem(parent, progressMessage(2, 8, "attack_path"));
+ await filesystem.copyFile(parent, copy);
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(2, 8, "validation"));
+ await tracker.refresh();
+ await appendSessionItem(copy, progressMessage(2, 8, "validation"));
+ await appendSessionItem(copy, progressMessage(2, 8, "reporting"));
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(2, 8, "reporting"));
+ await tracker.refresh();
+ expect(phases).toEqual(["attack_path", "validation", "reporting"]);
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test("does not replay stale worker activity or progress from archived copies", async () => {
+ const { home, worker } = await workerSessionFixture();
+ const otherWorker = await writeSession(
+ home,
+ "second-worker",
+ { input_tokens: 100, output_tokens: 10 },
+ { parent: "scan-thread" },
+ );
+ await appendSessionItem(worker, {
+ type: "function_call",
+ name: "exec_command",
+ call_id: "call-one",
+ arguments: '{"cmd":"pwd"}',
+ });
+ await appendSessionItem(worker, progressMessage(1, 8));
+ const stale = await filesystem.readFile(worker);
+ const activities: ScanActivity[] = [];
+ const progress: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ repository: "/synthetic/repository",
+ expectedFilesTotal: 16,
+ onActivity: (activity) => activities.push(activity),
+ onProgress: (update) => progress.push(update),
+ });
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ await appendSessionItem(worker, {
+ type: "function_call_output",
+ call_id: "call-one",
+ output: "/synthetic/repository",
+ });
+ await appendSessionItem(worker, progressMessage(3, 8));
+ await tracker.refresh();
+ const archive = join(home, "archived_sessions");
+ await filesystem.mkdir(archive);
+ await writeFile(join(archive, "rollout-worker.jsonl"), stale);
+ await tracker.refresh();
+ await appendSessionItem(otherWorker, progressMessage(1, 8));
+ await tracker.refresh();
+ expect({
+ toolStatuses: activities
+ .filter((activity) => activity.id === "worker-thread:call-one")
+ .map((activity) => activity.status),
+ completedFiles: progress.map((update) => update.filesCompleted),
+ }).toEqual({
+ toolStatuses: ["running", "completed"],
+ completedFiles: [1, 3, 4],
+ });
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test("recovers raw session events after their replay read fails", async () => {
+ const { home, worker } = await workerSessionFixture();
+ await appendSessionItem(worker, {
+ type: "function_call",
+ name: "exec_command",
+ call_id: "call-one",
+ arguments: '{"cmd":"pwd"}',
+ });
+ await appendSessionItem(worker, progressMessage(1));
+ const expected = (await filesystem.readFile(worker, "utf8"))
+ .trimEnd()
+ .split("\n")
+ .map((line) => JSON.parse(line) as Record<string, unknown>);
+ let denied = true;
+ let reads = 0;
+ const opened = filesystem.open;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof filesystem.open>) => {
+ if (String(args[0]) === worker && ++reads > 1 && denied) {
+ throw Object.assign(new Error("Synthetic replay read failure"), {
+ code: "EACCES",
+ syscall: "open",
+ path: worker,
+ });
+ }
+ return await opened(...args);
+ },
+ );
+ const events: ScanSessionEvent[] = [];
+ const activities: ScanActivity[] = [];
+ const progress: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ repository: "/synthetic/repository",
+ onSessionEvent: (event) => events.push(event),
+ onActivity: (activity) => activities.push(activity),
+ onProgress: (update) => progress.push(update),
+ });
+ const workerEvents = () =>
+ events
+ .filter((event) => event.threadId === "worker-thread")
+ .map((event) => event.event);
+ const toolStatuses = () =>
+ activities
+ .filter((activity) => activity.id === "worker-thread:call-one")
+ .map((activity) => activity.status);
+ tracker.start("scan-thread");
+ try {
+ await expect(tracker.refresh()).rejects.toMatchObject({ code: "EACCES" });
+ expect(workerEvents()).toEqual([]);
+ expect(toolStatuses()).toEqual(["running"]);
+ expect(progress.map((update) => update.filesCompleted)).toEqual([1]);
+
+ denied = false;
+ const snapshot = await tracker.refresh();
+ expect(workerEvents()).toEqual(expected);
+ expect(toolStatuses()).toEqual(["running"]);
+ expect(progress.map((update) => update.filesCompleted)).toEqual([1]);
+ expect(snapshot.measurement).toMatchObject({
+ coverage: "complete",
+ usage: { input_tokens: 200, output_tokens: 20 },
+ });
+ const continuation = [
+ {
+ type: "response_item",
+ payload: {
+ type: "function_call_output",
+ call_id: "call-one",
+ output: "/synthetic/repository",
+ },
+ },
+ { type: "response_item", payload: progressMessage(0) },
+ { type: "response_item", payload: progressMessage(2) },
+ ];
+ await appendFile(worker, jsonLines(continuation) + "\n");
+ await tracker.refresh();
+ await tracker.refresh();
+ expect(workerEvents()).toEqual([...expected, ...continuation]);
+ expect(toolStatuses()).toEqual(["running", "completed"]);
+ expect(progress.map((update) => update.filesCompleted)).toEqual([1, 2]);
+ } finally {
+ denied = false;
+ opening.mockRestore();
+ await tracker.stop();
+ }
+ });
+
test.each(["parent", "main"] as const)(
"replays early worker events when the %s session arrives later",
async (missing) => {
@@ -3899,8 +4280,8 @@ describe("live scan cost tracking", () => {
const python = readPythonRolloutUsage(BUNDLED_PLUGIN_ROOT, rolloutPath);
expect({
- trackedUsage: tracked.usage,
- estimatedUsd: tracked.cost?.estimatedUsd,
+ trackedUsage: tracked.measurement.usage,
+ estimatedUsd: tracked.measurement.cost?.estimatedUsd,
python,
}).toMatchObject({
trackedUsage: ownedSdkUsage,
@@ -3910,6 +4291,8 @@ describe("live scan cost tracking", () => {
warnings: [],
},
});
+ expect(tracked.measurement.coverage).toBe("partial");
+ expect(tracked.measurement.missingThreadCount).toBe(1);
expect(observedCosts.length).toBeGreaterThan(0);
expect(observedCosts.every((cost) => cost < maxCostUsd)).toBe(true);
const forwardedTurnIds = forwardedEvents.flatMap(({ event }) => {
@@ -6285,9 +6668,11 @@ describe("live scan cost tracking", () => {
await writeSession(home, "scan-thread", parentUsage);
const costs: Array<[number, boolean]> = [];
const usages: unknown[] = [];
+ const measurements: Readonly<ScanUsageMeasurement>[] = [];
const tracker = costTracker(home, {
onCost: (cost, complete) => costs.push([cost.estimatedUsd, complete]),
onUsage: (usage) => usages.push(usage),
+ onMeasurement: (measurement) => measurements.push(measurement),
});
tracker.start("scan-thread");
expect((await tracker.refresh()).cost?.estimatedUsd).toBe(6);
@@ -6300,9 +6685,16 @@ describe("live scan cost tracking", () => {
parent: "scan-thread",
},
);
- expect(await tracker.refresh()).toEqual({ usage: null, cost: null });
+ expect(await tracker.refresh()).toMatchObject({ usage: null, cost: null });
expect(costs.at(-1)).toEqual([6, false]);
expect(usages).toHaveLength(1);
+ expect(measurements.at(-1)).toMatchObject({
+ coverage: "partial",
+ threadCount: 1,
+ missingThreadCount: 1,
+ usage: { input_tokens: 1_000_000 },
+ coverageScope: ["thread:scan-thread", "thread:worker-thread"],
+ });
await appendFile(
worker,
@@ -6314,6 +6706,12 @@ describe("live scan cost tracking", () => {
total_tokens: 1_100_000,
});
expect(costs.at(-1)).toEqual([6, true]);
+ expect(measurements.at(-1)).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ coverageScope: ["thread:scan-thread", "thread:worker-thread"],
+ });
expect(usages).toHaveLength(1);
await appendFile(
@@ -6336,6 +6734,664 @@ describe("live scan cost tracking", () => {
expect(usages).toHaveLength(2);
});
+ test.skipIf(typeof zlib.zstdCompressSync !== "function").each([true, false])(
+ "counts compressed independent workers in active and archived sessions once (native=%p)",
+ async (native) => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scans", "compressed");
+ const parentUsage = { input_tokens: 100, output_tokens: 10 };
+ await writeSession(home, "scan-thread", parentUsage, {
+ timestamp: "2026-07-26T12:00:00Z",
+ });
+ const worker = await writeSession(
+ home,
+ "compressed-worker",
+ {
+ input_tokens: 900,
+ output_tokens: 90,
+ },
+ {
+ cwd: join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "workers",
+ "one",
+ "output",
+ ),
+ timestamp: "2026-07-26T12:01:00Z",
+ },
+ );
+ await appendFile(
+ worker,
+ jsonLines([
+ {
+ type: "event_msg",
+ timestamp: "2026-07-26T12:03:00Z",
+ payload: {
+ type: "token_count",
+ info: null,
+ rate_limits: { primary: { used_percent: 5 } },
+ },
+ },
+ ]) + "\n",
+ );
+ const compressed = zlib.zstdCompressSync(
+ await filesystem.readFile(worker),
+ );
+ await writeFile(`${worker}.zst`, compressed);
+ const archive = join(home, "archived_sessions");
+ await filesystem.mkdir(archive);
+ await writeFile(join(archive, "rollout-copy.jsonl.zst"), compressed);
+ await writeFile(
+ join(archive, "rollout-damaged.jsonl.zst"),
+ compressed.subarray(0, 3),
+ );
+ await writeFile(
+ join(archive, "rollout-unrelated.jsonl.zst"),
+ zlib.zstdCompressSync(
+ Buffer.from(
+ JSON.stringify({
+ type: "session_meta",
+ payload: { id: "unrelated-history" },
+ }) +
+ "\nnot a valid event; unrelated historical bodies must not be parsed\n",
+ ),
+ ),
+ );
+ await filesystem.unlink(worker);
+ const observations: ScanUsageObservation[] = [];
+ const tracker = costTracker(home, {
+ scanDirectory,
+ maxCostUsd: 10,
+ onUsageObservation: (value) => observations.push(value),
+ });
+ tracker.start("scan-thread");
+ const original = Object.getOwnPropertyDescriptor(
+ zlib,
+ "createZstdDecompress",
+ );
+ if (!native)
+ Object.defineProperty(zlib, "createZstdDecompress", {
+ value: undefined,
+ });
+ let snapshot;
+ try {
+ snapshot = await tracker.stop(parentUsage);
+ } finally {
+ if (original)
+ Object.defineProperty(zlib, "createZstdDecompress", original);
+ }
+ expect(snapshot.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ usage: { input_tokens: 1_000, output_tokens: 100 },
+ });
+ expect(snapshot.cost?.inputTokens).toBe(1_000);
+ expect(observations).toEqual([
+ {
+ tokensUpdatedAt: null,
+ accountRateLimits: [
+ {
+ limitId: "codex",
+ observedAt: "2026-07-26T12:03:00.000Z",
+ primary: { usedPercent: 5, windowMinutes: null, resetsAt: null },
+ secondary: null,
+ },
+ ],
+ },
+ ]);
+ },
+ );
+
+ for (const compressed of [false, true]) {
+ test
+ .skipIf(compressed && typeof zlib.zstdCompressSync !== "function")
+ .each([false, true])(
+ `retains SDK budget receipts when a rollout changes after enumeration (compressed=${compressed}, missing=%p)`,
+ async (missing) => {
+ const home = await codexHome();
+ const costs: number[] = [];
+ const tracker = costTracker(home, {
+ maxCostUsd: 0.003,
+ onCost: (cost) => costs.push(cost.estimatedUsd),
+ });
+ tracker.start("scan-thread");
+ await tracker.stop();
+ const plain = await writeSession(home, "scan-thread", {
+ input_tokens: 1_000,
+ output_tokens: 0,
+ });
+ const contents = await filesystem.readFile(plain);
+ const path = `${plain}${compressed ? ".zst" : ""}`;
+ const encoded = compressed ? zlib.zstdCompressSync(contents) : contents;
+ if (compressed) {
+ await writeFile(path, encoded);
+ await filesystem.rm(plain);
+ }
+ let changed = false;
+ const originalRead = filesystem.readdir;
+ const reading = spyOn(filesystem, "readdir").mockImplementation(
+ async (...args) => {
+ const entries = await Reflect.apply(originalRead, filesystem, args);
+ if (!changed && args[0] === dirname(path)) {
+ changed = true;
+ await filesystem.rm(path);
+ if (!missing) await filesystem.mkdir(path);
+ }
+ return entries;
+ },
+ );
+ const originalStat = filesystem.stat;
+ const stating = spyOn(filesystem, "stat").mockImplementation(
+ async (...args: unknown[]) => {
+ const result = await Reflect.apply(originalStat, filesystem, args);
+ // Windows directories can report zero bytes, like an unread empty file.
+ if (args[0] === path && result.isDirectory()) result.size = 0;
+ return result;
+ },
+ );
+ try {
+ const stopped = tracker.stop({ input_tokens: 500, output_tokens: 0 });
+ if (missing) {
+ expect(await stopped).toMatchObject({
+ usage: { input_tokens: 500 },
+ cost: { estimatedUsd: 0.002 },
+ measurement: { coverage: "complete" },
+ });
+ await writeFile(path, encoded);
+ expect(await tracker.stop()).toMatchObject({
+ usage: { input_tokens: 1_000 },
+ cost: { estimatedUsd: 0.004 },
+ measurement: { coverage: "complete" },
+ });
+ expect(costs).toEqual([0.002, 0.004]);
+ } else {
+ await expect(stopped).rejects.toMatchObject({ code: "EISDIR" });
+ expect(costs).toEqual([0.002]);
+ }
+ expect(changed).toBe(true);
+ } finally {
+ reading.mockRestore();
+ stating.mockRestore();
+ await tracker.stop().catch(() => {});
+ }
+ },
+ );
+ }
+
+ test.each([false, true])(
+ "retains SDK usage after a collection error with prior native usage=%p",
+ async (previouslyMeasured) => {
+ const home = await codexHome();
+ if (previouslyMeasured) {
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ await writeSession(
+ home,
+ "worker-thread",
+ { input_tokens: 200, output_tokens: 20 },
+ { parent: "scan-thread" },
+ );
+ }
+ const measurements: Readonly<ScanUsageMeasurement>[] = [];
+ const tracker = costTracker(home, {
+ onMeasurement: (measurement) => measurements.push(measurement),
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const originalRead = filesystem.readdir;
+ const failure = Object.assign(new Error("Session directory unreadable"), {
+ code: "EACCES",
+ });
+ const read = spyOn(filesystem, "readdir").mockImplementation(
+ async (...args) => {
+ if (args[0] === join(home, "sessions")) throw failure;
+ return Reflect.apply(originalRead, filesystem, args);
+ },
+ );
+ const usage = {
+ input_tokens: previouslyMeasured ? 1_200 : 1_000,
+ output_tokens: previouslyMeasured ? 120 : 100,
+ };
+ try {
+ await expect(
+ tracker.stop({ input_tokens: 1_000, output_tokens: 100 }),
+ ).rejects.toBe(failure);
+ expect(measurements.at(-1)).toMatchObject({
+ coverage: "partial",
+ threadCount: previouslyMeasured ? 2 : 1,
+ missingThreadCount: 1,
+ usage,
+ cost: estimateScanCost("gpt-5.6-sol", usage),
+ });
+ } finally {
+ read.mockRestore();
+ await tracker.stop().catch(() => {});
+ }
+ },
+ );
+
+ test.each([
+ ["reported zero", { cache_write_input_tokens: 0 }, {}, 0],
+ ["missing writes", {}, { cache_write_input_tokens: 12 }, 12],
+ [
+ "defaulted zero",
+ {
+ cache_write_input_tokens: 0,
+ cache_write_input_tokens_reported: false,
+ },
+ { cache_write_input_tokens: 12 },
+ 12,
+ ],
+ ] as const)(
+ "preserves worker receipt provenance for %s during native reconciliation",
+ async (_name, receiptWrites, nativeWrites, expectedWrites) => {
+ const home = await codexHome();
+ const scanId = "receipt-provenance";
+ const directory = join(home, "worker-usage", scanId);
+ await filesystem.mkdir(directory, { recursive: true });
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ cache_write_input_tokens: 0,
+ output_tokens: 10,
+ });
+ const workerUsage = { input_tokens: 200, output_tokens: 20 };
+ await writeFile(
+ join(directory, "worker-attempt.json"),
+ JSON.stringify({
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId,
+ attemptId: "worker-attempt",
+ threadId: "worker-thread",
+ usage: { ...workerUsage, ...receiptWrites },
+ }),
+ );
+ await writeSession(
+ home,
+ "worker-thread",
+ { ...workerUsage, ...nativeWrites },
+ { parent: "scan-thread" },
+ );
+ const tracker = costTracker(home, {
+ workerReceipts: { directory, scanId },
+ });
+ tracker.start("scan-thread");
+ const snapshot = await tracker.stop();
+ expect(snapshot.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ });
+ expect(snapshot.usage).toMatchObject({
+ input_tokens: 300,
+ cache_write_input_tokens: expectedWrites,
+ output_tokens: 30,
+ });
+ expect(snapshot.usage).not.toHaveProperty(
+ "cache_write_input_tokens_reported",
+ );
+ expect(snapshot.cost).not.toHaveProperty("cacheWriteInputTokensReported");
+ },
+ );
+
+ test("retains cumulative resumed worker receipts without counting earlier turns twice", async () => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scans", "receipts");
+ const scanId = "receipts";
+ const receipts = join(home, "worker-usage", scanId);
+ await filesystem.mkdir(receipts, { recursive: true });
+ const parentUsage = { input_tokens: 100, output_tokens: 10 };
+ await writeSession(home, "scan-thread", parentUsage);
+ for (const [attemptId, input] of [
+ ["first", 100],
+ ["second", 150],
+ ] as const) {
+ await writeFile(
+ join(receipts, `${attemptId}.json`),
+ JSON.stringify({
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId,
+ attemptId,
+ threadId: "resumed-worker",
+ usage: { input_tokens: input, output_tokens: 10 },
+ }),
+ );
+ }
+ const measurements: Readonly<ScanUsageMeasurement>[] = [];
+ const tracker = costTracker(home, {
+ scanDirectory,
+ workerReceipts: { directory: receipts, scanId },
+ onMeasurement: (measurement) => measurements.push(measurement),
+ });
+ tracker.start("scan-thread");
+ const partial = await tracker.refresh();
+ expect(partial).toMatchObject({
+ usage: null,
+ cost: null,
+ measurement: {
+ coverage: "partial",
+ threadCount: 2,
+ missingThreadCount: 1,
+ usage: { input_tokens: 250, output_tokens: 20 },
+ coverageScope: [
+ "thread:resumed-worker",
+ "thread:scan-thread",
+ "worker-attempt:first",
+ "worker-attempt:second",
+ ],
+ },
+ });
+ // Re-reading the same durable attempts does not increment their usage.
+ expect((await tracker.refresh()).measurement.usage).toEqual(
+ partial.measurement.usage,
+ );
+ const resumed = costTracker(home, {
+ scanDirectory,
+ workerReceipts: { directory: receipts, scanId },
+ });
+ resumed.start("scan-thread");
+ expect((await resumed.stop(parentUsage)).measurement).toEqual(
+ expect.objectContaining({
+ coverage: "partial",
+ usage: partial.measurement.usage,
+ coverageScope: partial.measurement.coverageScope,
+ }),
+ );
+ await writeSession(home, "resumed-worker", {
+ input_tokens: 150,
+ output_tokens: 10,
+ });
+ expect((await tracker.stop(parentUsage)).measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 2,
+ missingThreadCount: 0,
+ usage: { input_tokens: 250, output_tokens: 20 },
+ coverageScope: partial.measurement.coverageScope,
+ });
+ expect(measurements.map((measurement) => measurement.coverage)).toEqual([
+ "partial",
+ "complete",
+ ]);
+ });
+
+ test.each([
+ "EIO",
+ "ENOENT",
+ "invalid",
+ "missing-file",
+ "missing-directory",
+ ] as const)(
+ "retains measured worker receipts through %s collection failures",
+ async (failure) => {
+ const home = await codexHome();
+ const scanId = "receipt-recovery";
+ const directory = join(home, "worker-usage", scanId);
+ await filesystem.mkdir(directory, { recursive: true });
+ const save = async (
+ attemptId: string,
+ threadId: string | null,
+ usage: { input_tokens: number; output_tokens: number } | null,
+ ) =>
+ writeFile(
+ join(directory, `${attemptId}.json`),
+ JSON.stringify({
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId,
+ attemptId,
+ threadId,
+ usage,
+ }),
+ );
+ await save("earlier", "worker", { input_tokens: 500, output_tokens: 5 });
+ await save("latest", "worker", {
+ input_tokens: 1_000,
+ output_tokens: 10,
+ });
+ await save("unknown", null, null);
+ const measurements: Readonly<ScanUsageMeasurement>[] = [];
+ const tracker = costTracker(home, {
+ workerReceipts: { directory, scanId },
+ maxCostUsd: 1,
+ onMeasurement: (measurement) => measurements.push(measurement),
+ });
+ tracker.start("scan-thread");
+ const before = (
+ await tracker.stop({ input_tokens: 100, output_tokens: 1 })
+ ).measurement;
+ expect(before).toMatchObject({
+ coverage: "partial",
+ threadCount: 2,
+ missingThreadCount: 2,
+ usage: { total_tokens: 1_111 },
+ cost: { inputTokens: 1_100, outputTokens: 11, estimatedUsd: 0.00462 },
+ });
+ const latest = join(directory, "latest.json");
+ const originalRead = filesystem.readFile;
+ const reading =
+ failure === "EIO" || failure === "ENOENT"
+ ? spyOn(filesystem, "readFile").mockImplementation((async (
+ ...args: Parameters<typeof filesystem.readFile>
+ ) => {
+ if (args[0] === latest)
+ throw Object.assign(new Error(`Synthetic receipt ${failure}`), {
+ code: failure,
+ });
+ return Reflect.apply(originalRead, filesystem, args);
+ }) as typeof filesystem.readFile)
+ : null;
+ let moved = false;
+ try {
+ if (failure === "invalid") await writeFile(latest, "{invalid");
+ if (failure === "missing-file") await filesystem.rm(latest);
+ if (failure === "missing-directory") {
+ await filesystem.rename(directory, `${directory}-unavailable`);
+ moved = true;
+ }
+ const update = tracker.refresh();
+ if (failure === "EIO")
+ await expect(update).rejects.toMatchObject({ code: "EIO" });
+ else if (failure === "invalid")
+ await expect(update).rejects.toBeInstanceOf(SyntaxError);
+ else await update;
+ expect(measurements.at(-1)).toMatchObject({
+ coverage: "partial",
+ threadCount: 2,
+ missingThreadCount: 2,
+ usage: before.usage,
+ cost: before.cost,
+ });
+ expect(measurements.at(-1)?.coverageScope).toEqual(
+ failure === "EIO" || failure === "invalid"
+ ? undefined
+ : before.coverageScope,
+ );
+ reading?.mockRestore();
+ if (moved) {
+ await filesystem.rename(`${directory}-unavailable`, directory);
+ moved = false;
+ }
+ await save("latest", "worker", {
+ input_tokens: 1_200,
+ output_tokens: 12,
+ });
+ await save("unknown", "other-worker", {
+ input_tokens: 0,
+ output_tokens: 0,
+ });
+ await writeSession(home, "worker", {
+ input_tokens: 1_200,
+ output_tokens: 12,
+ });
+ await writeSession(home, "other-worker", {
+ input_tokens: 0,
+ output_tokens: 0,
+ });
+ const recovered = (await tracker.stop()).measurement;
+ expect(recovered).toMatchObject({
+ coverage: "complete",
+ threadCount: 3,
+ missingThreadCount: 0,
+ usage: {
+ input_tokens: 1_300,
+ output_tokens: 13,
+ total_tokens: 1_313,
+ },
+ cost: { inputTokens: 1_300, outputTokens: 13, estimatedUsd: 0.00546 },
+ coverageScope: [
+ "thread:other-worker",
+ "thread:scan-thread",
+ "thread:worker",
+ "worker-attempt:earlier",
+ "worker-attempt:latest",
+ "worker-attempt:unknown",
+ ],
+ });
+ await filesystem.rm(latest);
+ expect((await tracker.stop()).measurement).toMatchObject({
+ coverage: "complete",
+ missingThreadCount: 0,
+ usage: recovered.usage,
+ cost: recovered.cost,
+ coverageScope: recovered.coverageScope,
+ });
+ } finally {
+ reading?.mockRestore();
+ if (moved)
+ await filesystem.rename(`${directory}-unavailable`, directory);
+ await tracker.stop().catch(() => {});
+ }
+ },
+ );
+
+ test.each(["standard", "deep"])(
+ "%s scans ignore model-written worker receipts for budgets and session events",
+ async (mode) => {
+ const home = await codexHome();
+ const scanId = "owned-scan";
+ const scanDirectory = join(home, "scans", scanId);
+ const artifacts = join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "usage",
+ );
+ await filesystem.mkdir(artifacts, { recursive: true });
+ const usage = { input_tokens: 100, output_tokens: 10 };
+ await writeSession(home, "scan-thread", usage);
+ const foreign = await writeSession(home, "foreign-thread", {
+ input_tokens: 999_999,
+ output_tokens: 999_999,
+ });
+ await appendSessionItem(foreign, {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "Unrelated session output." }],
+ });
+ for (const [attemptId, threadId, receiptUsage] of [
+ [
+ "forged-cost",
+ "scan-thread",
+ { input_tokens: 1_000_000_000, output_tokens: 0 },
+ ],
+ ["forged-membership", "foreign-thread", null],
+ ] as const) {
+ await writeFile(
+ join(artifacts, `${attemptId}.json`),
+ JSON.stringify({
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId,
+ attemptId,
+ threadId,
+ usage: receiptUsage,
+ }),
+ );
+ }
+ const events: ScanSessionEvent[] = [];
+ let budgetExceeded = false;
+ const tracker = costTracker(home, {
+ scanDirectory,
+ ...(mode === "deep"
+ ? {
+ workerReceipts: {
+ directory: join(home, "worker-usage", scanId),
+ scanId,
+ },
+ }
+ : {}),
+ onCost: (cost) => {
+ budgetExceeded ||= cost.estimatedUsd > 1;
+ },
+ onSessionEvent: (event) => events.push(event),
+ });
+ tracker.start("scan-thread");
+ const result = await tracker.stop(usage);
+ expect(result.measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 1,
+ usage: tokenUsage(usage),
+ coverageScope: ["thread:scan-thread"],
+ });
+ expect(budgetExceeded).toBe(false);
+ expect(events.every((event) => event.threadId === "scan-thread")).toBe(
+ true,
+ );
+ },
+ );
+
+ test("binds protected worker receipts to the scan and durable attempt", async () => {
+ const home = await codexHome();
+ const scanId = "owned-scan";
+ const directory = join(home, "worker-usage", scanId);
+ const unrelated = join(home, "worker-usage", "other-scan");
+ await filesystem.mkdir(directory, { recursive: true });
+ await filesystem.mkdir(unrelated, { recursive: true });
+ const usage = { input_tokens: 100, output_tokens: 10 };
+ await writeSession(home, "scan-thread", usage);
+ const receipt = {
+ schemaVersion: 1,
+ source: "codex_sdk",
+ usageScope: "thread_cumulative",
+ scanId: "other-scan",
+ attemptId: "other-attempt",
+ threadId: "unrelated-worker",
+ usage: { input_tokens: 1_000_000, output_tokens: 0 },
+ };
+ await writeFile(
+ join(unrelated, "other-attempt.json"),
+ JSON.stringify(receipt),
+ );
+ await writeFile(
+ join(directory, "other-attempt.json"),
+ JSON.stringify(receipt),
+ );
+ await writeFile(
+ join(directory, "wrong-attempt.json"),
+ JSON.stringify({ ...receipt, scanId }),
+ );
+ const tracker = costTracker(home, {
+ workerReceipts: { directory, scanId },
+ });
+ tracker.start("scan-thread");
+ expect((await tracker.stop(usage)).measurement).toMatchObject({
+ coverage: "complete",
+ threadCount: 1,
+ usage: tokenUsage(usage),
+ coverageScope: ["thread:scan-thread"],
+ });
+ });
+
test("keeps independent Deep worker usage unknown until a receipt supplies it", async () => {
const home = await codexHome();
const scanDirectory = join(home, "scans", "current");
@@ -6362,7 +7418,7 @@ describe("live scan cost tracking", () => {
);
const tracker = costTracker(home, { scanDirectory });
tracker.start("scan-thread");
- expect(await tracker.refresh()).toEqual({ usage: null, cost: null });
+ expect(await tracker.refresh()).toMatchObject({ usage: null, cost: null });
tracker.recordUsage({ input_tokens: 50, output_tokens: 5 }, "deep-worker");
expect((await tracker.stop(parentUsage)).usage).toMatchObject({
@@ -6390,8 +7446,48 @@ describe("live scan cost tracking", () => {
output_tokens: 0,
});
if (source === "unknown")
- expect(snapshot).toEqual({ usage: null, cost: null });
+ expect(snapshot).toMatchObject({ usage: null, cost: null });
else expect(snapshot.cost?.inputTokens).toBe(1_500);
+ expect(snapshot.measurement.coverageScope).toEqual([
+ "thread:scan-thread",
+ "thread:validation-thread",
+ ]);
},
);
+
+ test("includes a separate validation root and its missing child in coverage scope", async () => {
+ const home = await codexHome();
+ await writeSession(home, "validation-thread", {
+ input_tokens: 500,
+ output_tokens: 0,
+ });
+ await writeSession(
+ home,
+ "validation-child",
+ {},
+ {
+ parent: "validation-thread",
+ },
+ );
+ const tracker = costTracker(home);
+ tracker.start("scan-thread");
+ tracker.recordUsage(
+ { input_tokens: 500, output_tokens: 0 },
+ "validation-thread",
+ );
+ const snapshot = await tracker.stop({
+ input_tokens: 1_000,
+ output_tokens: 0,
+ });
+ expect(snapshot.measurement).toMatchObject({
+ coverage: "partial",
+ missingThreadCount: 1,
+ usage: { input_tokens: 1_500 },
+ coverageScope: [
+ "thread:scan-thread",
+ "thread:validation-child",
+ "thread:validation-thread",
+ ],
+ });
+ });
});
diff --git a/sdk/typescript/tests-ts/custom-publish.test.ts b/sdk/typescript/tests-ts/custom-publish.test.ts
index 881a605ea..1b76f1eae 100644
--- a/sdk/typescript/tests-ts/custom-publish.test.ts
+++ b/sdk/typescript/tests-ts/custom-publish.test.ts
@@ -1,11 +1,13 @@
import { chmod, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
+import { setImmediate as nextTurn } from "node:timers/promises";
import { afterEach, expect, test, mock } from "bun:test";
import { publishScanToCustomInternal as publishScanToCustom } from "../src/custom-publish.js";
import type { FindingsDocument } from "../src/models.js";
import { copyCompletedScanFixture } from "./plugin-root.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
import { rejecting } from "./support/errors.js";
+import type { PublicationTelemetry } from "../src/publication-telemetry.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures(
"custom-publish-",
@@ -26,6 +28,7 @@ test("publishes complete sealed findings with their repository ID to a custom ba
const { scan, source, document } = await fixture();
const controller = new AbortController();
const ids = document.findings.map((finding) => finding.findingId);
+ const observations: PublicationTelemetry[] = [];
const fetchMock = mock(async (url: URL, options: RequestInit) => {
expect(String(url)).toBe("http://synthetic.test/service/v1/bulk/findings");
expect(options).toEqual({
@@ -45,6 +48,7 @@ test("publishes complete sealed findings with their repository ID to a custom ba
findingsUrl: "http://synthetic.test/service",
expectedScanId: document.scanId,
signal: controller.signal,
+ onTelemetry: (event) => observations.push(event),
},
{
fetch: fetchMock,
@@ -55,28 +59,100 @@ test("publishes complete sealed findings with their repository ID to a custom ba
repositoryId: "target_sha256_example",
findingIds: ids,
findingCount: ids.length,
+ telemetry: expect.objectContaining({
+ destination: "custom",
+ outcome: "completed",
+ attempted: true,
+ counts: {
+ selected: ids.length,
+ submitted: ids.length,
+ created: null,
+ reused: null,
+ acknowledged: ids.length,
+ failed: 0,
+ },
+ }),
});
+ expect(observations).toEqual([result.telemetry!]);
+ expect(Object.keys(result.telemetry!).sort()).toEqual([
+ "attemptId",
+ "attempted",
+ "counts",
+ "destination",
+ "durationMs",
+ "observedAt",
+ "outcome",
+ "schemaVersion",
+ "startedAt",
+ ]);
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(await readFile(join(scan, "findings.json"), "utf8")).toBe(source);
});
-test("dry-run previews the complete upload without HTTP or credentials", async () => {
+test.each(["http://localhost:3000", "synthetic-invalid-url"])(
+ "dry-run previews the complete upload without HTTP or credentials (%s)",
+ async (findingsUrl) => {
+ const { scan, document } = await fixture();
+ const result = await publishScanToCustom(
+ scan,
+ { findingsUrl, dryRun: true },
+ {
+ fetch: rejecting("dry-run must not send a request"),
+ },
+ );
+ expect(result).toEqual({
+ scanId: document.scanId,
+ repositoryId: "target_sha256_example",
+ findingIds: document.findings.map((finding) => finding.findingId),
+ findingCount: document.findings.length,
+ dryRun: true,
+ findings: document.findings,
+ telemetry: expect.objectContaining({
+ destination: "custom",
+ outcome: "preview",
+ attempted: false,
+ counts: {
+ selected: document.findings.length,
+ submitted: 0,
+ created: 0,
+ reused: 0,
+ acknowledged: 0,
+ failed: 0,
+ },
+ }),
+ });
+ },
+);
+
+test("invalid publication URLs report a local failure before any submission", async () => {
const { scan, document } = await fixture();
- const result = await publishScanToCustom(
- scan,
- { findingsUrl: "http://localhost:3000", dryRun: true },
- {
- fetch: rejecting("dry-run must not send a request"),
- },
- );
- expect(result).toEqual({
- scanId: document.scanId,
- repositoryId: "target_sha256_example",
- findingIds: document.findings.map((finding) => finding.findingId),
- findingCount: document.findings.length,
- dryRun: true,
- findings: document.findings,
- });
+ const observations: PublicationTelemetry[] = [];
+ const fetchMock = mock(rejecting("Invalid URL must not send a request"));
+ await expect(
+ publishScanToCustom(
+ scan,
+ {
+ findingsUrl: "synthetic-invalid-url",
+ onTelemetry: (event) => observations.push(event),
+ },
+ { fetch: fetchMock },
+ ),
+ ).rejects.toThrow(TypeError);
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(observations).toEqual([
+ expect.objectContaining({
+ outcome: "failed",
+ attempted: false,
+ counts: {
+ selected: document.findings.length,
+ submitted: 0,
+ created: 0,
+ reused: 0,
+ acknowledged: 0,
+ failed: 0,
+ },
+ }),
+ ]);
});
test("does not retry failed uploads or report incomplete receipts as successful", async () => {
@@ -90,19 +166,111 @@ test("does not retry failed uploads or report incomplete receipts as successful"
const fetchMock = mock(async () => {
return Response.json(receipt, { status });
});
+ const observed: PublicationTelemetry[] = [];
await expect(
publishScanToCustom(
scan,
- { findingsUrl: "http://synthetic.test" },
+ {
+ findingsUrl: "http://synthetic.test",
+ onTelemetry: (event) => observed.push(event),
+ },
{
fetch: fetchMock,
},
),
).rejects.toThrow(message);
expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(observed).toEqual([
+ expect.objectContaining({
+ outcome: "indeterminate",
+ attempted: true,
+ counts: expect.objectContaining({
+ acknowledged: null,
+ created: null,
+ failed: null,
+ }),
+ }),
+ ]);
}
});
+test("keeps an aborted upload outcome indeterminate after submission", async () => {
+ const { scan } = await fixture();
+ const controller = new AbortController();
+ const reason = new Error("Synthetic upload cancellation");
+ const observed: PublicationTelemetry[] = [];
+ const fetchMock = mock(async () => {
+ controller.abort(reason);
+ throw reason;
+ });
+ await expect(
+ publishScanToCustom(
+ scan,
+ {
+ findingsUrl: "http://synthetic.test",
+ signal: controller.signal,
+ onTelemetry: (event) => observed.push(event),
+ },
+ { fetch: fetchMock },
+ ),
+ ).rejects.toBe(reason);
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(observed).toEqual([
+ expect.objectContaining({
+ outcome: "indeterminate",
+ attempted: true,
+ counts: expect.objectContaining({ acknowledged: null, failed: null }),
+ }),
+ ]);
+});
+
+test.each(["failed", "canceled"] as const)(
+ "observes custom publication %s before preparation without replacing the error",
+ async (outcome) => {
+ const controller = new AbortController();
+ const reason = new Error("Synthetic cancellation");
+ if (outcome === "canceled") controller.abort(reason);
+ const observed: PublicationTelemetry[] = [];
+ const result = publishScanToCustom("/synthetic/missing/scan", {
+ findingsUrl: "http://synthetic.test",
+ signal: controller.signal,
+ onTelemetry: (event) => {
+ observed.push(event);
+ throw new Error("Synthetic observer failure");
+ },
+ });
+ await expect(result).rejects.toThrow();
+ expect(observed).toEqual([
+ expect.objectContaining({
+ outcome,
+ attempted: false,
+ counts: expect.objectContaining({ selected: null, submitted: 0 }),
+ }),
+ ]);
+ },
+);
+
+test.each(["throw", "reject", "pending"] as const)(
+ "publication telemetry observers do not change preview results (%s)",
+ async (behavior) => {
+ const { scan } = await fixture();
+ const observer = mock(() => {
+ if (behavior === "throw") throw new Error("Synthetic observer failure");
+ if (behavior === "reject")
+ return Promise.reject(new Error("Synthetic observer rejection"));
+ return new Promise<void>(() => {});
+ });
+ const result = await publishScanToCustom(scan, {
+ findingsUrl: "http://synthetic.test",
+ dryRun: true,
+ onTelemetry: observer,
+ });
+ await nextTurn();
+ expect(result.telemetry?.outcome).toBe("preview");
+ expect(observer).toHaveBeenCalledTimes(1);
+ },
+);
+
test("rejects mismatched or changed sealed artifacts before publication, including dry-run", async () => {
const { scan, source } = await fixture();
const dependencies = {
diff --git a/sdk/typescript/tests-ts/direct-deep-scan.test.ts b/sdk/typescript/tests-ts/direct-deep-scan.test.ts
index fe4b46310..c9458b204 100644
--- a/sdk/typescript/tests-ts/direct-deep-scan.test.ts
+++ b/sdk/typescript/tests-ts/direct-deep-scan.test.ts
@@ -323,7 +323,16 @@ test("preserves complete worker usage and cost after direct engine completion",
parent: "engine-session",
},
);
- assert.deepEqual(await tracker.refresh(), { usage: null, cost: null });
+ const partial = await tracker.refresh();
+ assert.equal(partial.usage, null);
+ assert.equal(partial.cost, null);
+ assert.partialDeepStrictEqual(partial.measurement, {
+ usage: running.usage,
+ cost: running.cost,
+ coverage: "partial",
+ threadCount: 3,
+ missingThreadCount: 1,
+ });
tracker.recordUsage(
{
input_tokens: 0,
@@ -345,7 +354,15 @@ test("preserves complete worker usage and cost after direct engine completion",
total_tokens: 1_660,
});
assert.notEqual(running.cost, null);
- assert.deepEqual(final, running);
+ assert.deepEqual(final.usage, running.usage);
+ assert.deepEqual(final.cost, running.cost);
+ assert.partialDeepStrictEqual(final.measurement, {
+ usage: running.usage,
+ cost: running.cost,
+ coverage: "complete",
+ threadCount: 4,
+ missingThreadCount: 0,
+ });
assert.equal(final.cost?.cacheWriteInputTokensReported, undefined);
assert.equal((await events.next()).done, true);
});
diff --git a/sdk/typescript/tests-ts/finding-embeddings.test.ts b/sdk/typescript/tests-ts/finding-embeddings.test.ts
index b466be0a8..4cb265a67 100644
--- a/sdk/typescript/tests-ts/finding-embeddings.test.ts
+++ b/sdk/typescript/tests-ts/finding-embeddings.test.ts
@@ -10,6 +10,7 @@ import {
EMBEDDING_DIMENSIONS,
EMBEDDING_MODEL,
OpenAiFindingEmbedder,
+ type EmbeddingUsageObservation,
} from "../src/server/embeddings.js";
import { PLUGIN_ROOT } from "./plugin-root.js";
import { VERSION } from "../src/version.js";
@@ -32,6 +33,7 @@ test.each(["headers", "body"])(
async (stage) => {
const controller = new AbortController();
const canceled = new Error("Synthetic cancellation");
+ const observations: EmbeddingUsageObservation[] = [];
const embedder = new OpenAiFindingEmbedder(
"synthetic-key",
async (_url, init) => {
@@ -49,8 +51,18 @@ test.each(["headers", "body"])(
},
undefined,
controller.signal,
+ (observation) => observations.push(observation),
);
await expect(embedder.embed([example])).rejects.toBe(canceled);
+ expect(observations).toEqual([
+ {
+ model: EMBEDDING_MODEL,
+ inputCount: 1,
+ inputTokens: null,
+ outcome: "canceled",
+ durationMs: expect.any(Number),
+ },
+ ]);
},
);
@@ -222,6 +234,7 @@ test("splits bulk requests at the provider token budget and renews credentials p
const finding: Finding = { ...example, summary: " evidence".repeat(8000) };
const requests: number[][][] = [];
let credentials = 0;
+ const observations: EmbeddingUsageObservation[] = [];
const embedder = new OpenAiFindingEmbedder(
async () => `synthetic-key-${++credentials}`,
async (_url, init) => {
@@ -238,8 +251,14 @@ test("splits bulk requests at the provider token budget and renews credentials p
return Response.json({
model: EMBEDDING_MODEL,
data: input.map((_, index) => ({ index, embedding: vector() })),
+ usage: {
+ prompt_tokens: input.reduce((sum, tokens) => sum + tokens.length, 0),
+ },
});
},
+ undefined,
+ undefined,
+ (observation) => observations.push(observation),
);
const result = await embedder.embed(
Array.from({ length: 40 }, () => finding),
@@ -248,8 +267,113 @@ test("splits bulk requests at the provider token budget and renews credentials p
expect(credentials).toBe(2);
expect(result).toHaveLength(40);
expect(result.every((embedding) => embedding.vector[0] === 1)).toBe(true);
+ expect(observations).toEqual(
+ requests.map((input) => ({
+ model: EMBEDDING_MODEL,
+ inputCount: input.length,
+ inputTokens: input.reduce((sum, tokens) => sum + tokens.length, 0),
+ outcome: "completed",
+ durationMs: expect.any(Number),
+ })),
+ );
});
+test.each([
+ { usage: { prompt_tokens: 17 }, inputTokens: 17 },
+ { usage: { prompt_tokens: 0 }, inputTokens: 0 },
+ { usage: undefined, inputTokens: null },
+ { usage: { prompt_tokens: -1 }, inputTokens: null },
+])(
+ "reports provider token usage and missingness (%j)",
+ async ({ usage, inputTokens }) => {
+ const observations: EmbeddingUsageObservation[] = [];
+ const embedder = new OpenAiFindingEmbedder(
+ "synthetic-key",
+ async () =>
+ Response.json({
+ model: EMBEDDING_MODEL,
+ data: [{ index: 0, embedding: vector() }],
+ usage,
+ }),
+ undefined,
+ undefined,
+ (observation) => observations.push(observation),
+ );
+ await embedder.embed([example]);
+ expect(observations).toEqual([
+ {
+ model: EMBEDDING_MODEL,
+ inputCount: 1,
+ inputTokens,
+ outcome: "completed",
+ durationMs: expect.any(Number),
+ },
+ ]);
+ expect(observations[0]!.durationMs).toBeGreaterThanOrEqual(0);
+ },
+);
+
+test.each(["throw", "reject", "pending"] as const)(
+ "embedding usage observer failures do not affect results (%s)",
+ async (failure) => {
+ const observer = mock(() => {
+ if (failure === "throw") throw new Error("Synthetic observer failure");
+ if (failure === "reject")
+ return Promise.reject(new Error("Synthetic observer rejection"));
+ return new Promise<void>(() => {});
+ });
+ const embedder = new OpenAiFindingEmbedder(
+ "synthetic-key",
+ async () =>
+ Response.json({
+ model: EMBEDDING_MODEL,
+ data: [{ index: 0, embedding: vector() }],
+ }),
+ undefined,
+ undefined,
+ observer,
+ );
+ expect(await embedder.embed([example])).toHaveLength(1);
+ await nextTurn();
+ expect(observer).toHaveBeenCalledTimes(1);
+ },
+);
+
+test.each(["transport", "http", "vectors"] as const)(
+ "reports failed embedding batches without discarding reported usage (%s)",
+ async (failure) => {
+ const observations: EmbeddingUsageObservation[] = [];
+ const embedder = new OpenAiFindingEmbedder(
+ "synthetic-key",
+ async () => {
+ if (failure === "transport")
+ throw new Error("Synthetic transport failure");
+ if (failure === "http") return new Response(null, { status: 503 });
+ return Response.json({
+ model: EMBEDDING_MODEL,
+ data: [],
+ usage: { prompt_tokens: 23 },
+ });
+ },
+ undefined,
+ undefined,
+ (observation) => observations.push(observation),
+ );
+ await expect(embedder.embed([example])).rejects.toMatchObject({
+ code: "embedding_failed",
+ });
+ expect(observations).toEqual([
+ {
+ model: EMBEDDING_MODEL,
+ inputCount: 1,
+ inputTokens: failure === "vectors" ? 23 : null,
+ outcome: "failed",
+ durationMs: expect.any(Number),
+ },
+ ]);
+ },
+);
+
test("does not resolve credentials for empty input or reuse a key after renewal fails", async () => {
for (const failure of ["throw", "empty"]) {
let credentials = 0;
diff --git a/sdk/typescript/tests-ts/finding-workflow-integration.test.ts b/sdk/typescript/tests-ts/finding-workflow-integration.test.ts
index 035a726e4..0be701d18 100644
--- a/sdk/typescript/tests-ts/finding-workflow-integration.test.ts
+++ b/sdk/typescript/tests-ts/finding-workflow-integration.test.ts
@@ -342,6 +342,24 @@ test("reuses publication after dedupe failure and persists a successful empty du
environment,
fetch: request,
});
+ const reused = await publishScanToCustomInternal(scanDir, options, {
+ environment,
+ fetch: rejecting("A completed publication must reuse its saved receipt"),
+ });
+ expect(reused.telemetry).toMatchObject({
+ destination: "custom",
+ outcome: "completed",
+ attempted: false,
+ counts: {
+ selected: document.findings.length,
+ submitted: 0,
+ created: 0,
+ reused: document.findings.length,
+ acknowledged: 0,
+ failed: 0,
+ },
+ });
+ expect(reused.telemetry!.attemptId).not.toBe(receipt.telemetry!.attemptId);
await expect(
deduplicateScanInternal(document.scanId, options, {
environment,
diff --git a/sdk/typescript/tests-ts/finding-workflow-publication.test.ts b/sdk/typescript/tests-ts/finding-workflow-publication.test.ts
index ef455a1f0..0d891d97c 100644
--- a/sdk/typescript/tests-ts/finding-workflow-publication.test.ts
+++ b/sdk/typescript/tests-ts/finding-workflow-publication.test.ts
@@ -179,7 +179,20 @@ test("failed publication records its error, dry-run does not advance it, and ret
},
...publicationBinding(id, document.scanId, scanDir),
begin,
- { request: { id, action: "complete", stage: "publish", result } },
+ {
+ request: {
+ id,
+ action: "complete",
+ stage: "publish",
+ result: {
+ ...result,
+ telemetry: expect.objectContaining({
+ destination: "custom",
+ outcome: "completed",
+ }),
+ },
+ },
+ },
]);
await expect(
publishScanToCustomInternal(scanDir, options, {
@@ -199,7 +212,15 @@ test("failed publication records its error, dry-run does not advance it, and ret
fetch: rejecting("Dry-run must not publish"),
},
),
- ).toEqual({ ...result, dryRun: true, findings: document.findings });
+ ).toEqual({
+ ...result,
+ dryRun: true,
+ findings: document.findings,
+ telemetry: expect.objectContaining({
+ outcome: "preview",
+ attempted: false,
+ }),
+ });
dryRunWorkbench.assertDone();
expect(
await publishScanToCustomInternal(scanDir, options, {
@@ -207,7 +228,13 @@ test("failed publication records its error, dry-run does not advance it, and ret
runWorkbench: workbench.run,
fetch: async () => Response.json(result.findingIds),
}),
- ).toEqual(result);
+ ).toEqual({
+ ...result,
+ telemetry: expect.objectContaining({
+ outcome: "completed",
+ attempted: true,
+ }),
+ });
workbench.assertDone();
});
diff --git a/sdk/typescript/tests-ts/fixtures/skill-native-config.mjs b/sdk/typescript/tests-ts/fixtures/skill-native-config.mjs
index c22736c97..9bd986c85 100644
--- a/sdk/typescript/tests-ts/fixtures/skill-native-config.mjs
+++ b/sdk/typescript/tests-ts/fixtures/skill-native-config.mjs
@@ -1,5 +1,6 @@
import { send, completeTurn } from "./app-server-messages.mjs";
import { spawn } from "node:child_process";
+import { appendFileSync } from "node:fs";
import { createInterface } from "node:readline";
const methods = new Map();
@@ -62,6 +63,23 @@ await Promise.all([
let preflightResponse;
for await (const line of createInterface({ input: child.stdout })) {
const response = JSON.parse(line);
+ if (methods.get(response.id) === "thread/start")
+ modelProvider = response.result?.modelProvider;
+ if (methods.get(response.id) === "config/read") {
+ initialConfig = response.result?.config;
+ if (process.env.SYNTHETIC_CONFIG_OBSERVATIONS && initialConfig) {
+ appendFileSync(
+ process.env.SYNTHETIC_CONFIG_OBSERVATIONS,
+ JSON.stringify({
+ args: process.argv.slice(2),
+ home: process.env.CODEX_HOME,
+ analytics: initialConfig.analytics,
+ otel: initialConfig.otel,
+ metadata: initialConfig.responses_api_metadata,
+ }) + "\n",
+ );
+ }
+ }
if (
preflightConfigId !== undefined &&
response.id === preflightConfigId
@@ -72,10 +90,6 @@ await Promise.all([
child.stdin.end();
continue;
}
- if (methods.get(response.id) === "thread/start")
- modelProvider = response.result?.modelProvider;
- if (methods.get(response.id) === "config/read")
- initialConfig = response.result?.config;
if (response.id !== "inspect-config") {
process.stdout.write(line + "\n");
continue;
@@ -91,6 +105,9 @@ await Promise.all([
config.mcp_servers?.synthetic !== undefined,
daybreak: initialConfig?.daybreak ?? null,
daybreakEnabled,
+ analytics: initialConfig?.analytics ?? null,
+ otel: initialConfig?.otel ?? null,
+ requestMetadata: initialConfig?.responses_api_metadata ?? null,
daybreakFeatures: Object.fromEntries(
[
"cli_daybreak",
diff --git a/sdk/typescript/tests-ts/fixtures/stored-daybreak-workers.mjs b/sdk/typescript/tests-ts/fixtures/stored-daybreak-workers.mjs
index f8b88008f..eef9f4e1e 100644
--- a/sdk/typescript/tests-ts/fixtures/stored-daybreak-workers.mjs
+++ b/sdk/typescript/tests-ts/fixtures/stored-daybreak-workers.mjs
@@ -102,6 +102,11 @@ try {
}),
program: requests.at(-1)?.access_programs?.cyber,
daybreak: config.daybreak ?? null,
+ telemetry: {
+ analyticsEnabled: config.analytics?.enabled ?? null,
+ environment: config.otel?.environment ?? null,
+ metadataTag: config.responses_api_metadata?.["synthetic.tag"] ?? null,
+ },
daybreakFeatures: Object.fromEntries(
[
"cli_daybreak",
diff --git a/sdk/typescript/tests-ts/fixtures/verify-fix-stderr-isolation.ts b/sdk/typescript/tests-ts/fixtures/verify-fix-stderr-isolation.ts
index 6750cad99..62e44b24c 100644
--- a/sdk/typescript/tests-ts/fixtures/verify-fix-stderr-isolation.ts
+++ b/sdk/typescript/tests-ts/fixtures/verify-fix-stderr-isolation.ts
@@ -235,10 +235,13 @@ ${publishWorkerPid}
setInterval(() => {}, 1_000);
`;
return runCodexSkillCommand(
- ["-e", source],
+ ["-e", source, "--"],
{ ...output!, auth: undefined },
{ command: process.execPath },
- { VERIFY_FIX_WORKER_STATE: state },
+ {
+ VERIFY_FIX_WORKER_STATE: state,
+ CODEX_SECURITY_STATE_DIR: `${state}.state`,
+ },
);
}
}
diff --git a/sdk/typescript/tests-ts/hosted-scan.test.ts b/sdk/typescript/tests-ts/hosted-scan.test.ts
index 504b511c6..97e0495a0 100644
--- a/sdk/typescript/tests-ts/hosted-scan.test.ts
+++ b/sdk/typescript/tests-ts/hosted-scan.test.ts
@@ -25,6 +25,7 @@ import { runHostedScanProtocol } from "../src/hosted-scan-protocol.js";
import { runHostProtocol } from "../src/host-protocol.js";
import { CodexSecurity, runHostedScan } from "../src/index.js";
import * as config from "../src/config.js";
+import { readOperationTelemetry } from "../src/operation-telemetry.js";
import * as hostedScan from "../src/hosted-scan.js";
import * as ownerSuggestions from "../src/suggest-owners.js";
import {
@@ -1111,6 +1112,47 @@ test.each([
},
);
+test.each(
+ [undefined, "measured-host-session"].flatMap((sessionId) =>
+ (["failed", "acceptance_unknown"] as const).map((status) => ({
+ sessionId,
+ status,
+ })),
+ ),
+)(
+ "$status hosted scans report measured usage with session $sessionId",
+ async ({ sessionId, status }) => {
+ const input = await fixture();
+ const terminal = await runHostedScan(input, {
+ executor: {
+ async run(request) {
+ return receipt(request, {
+ status,
+ sessionId,
+ usage: {
+ input_tokens: 123,
+ cached_input_tokens: 0,
+ output_tokens: 7,
+ },
+ message: "Synthetic measured failure",
+ });
+ },
+ },
+ });
+ expect(terminal.status).toBe(status);
+ const journal = await readOperationTelemetry(input.stateDirectory);
+ expect(
+ journal.events.find((event) => event.type === "attempt_finished"),
+ ).toMatchObject({
+ outcome: status === "acceptance_unknown" ? "unresolved" : "failed",
+ measurement: {
+ coverage: "complete",
+ usage: { input_tokens: 123, output_tokens: 7, total_tokens: 130 },
+ },
+ });
+ },
+);
+
test("failed hosted config preparation removes its temporary runtime home", async () => {
const input = await fixture();
const executor = noExecution();
@@ -1366,6 +1408,13 @@ test.each([
input.severityRubric.markdown = "Edited by caller.";
const result = await pending;
expect(result.status).toBe(scanStatus);
+ const journal = await readOperationTelemetry(input.stateDirectory);
+ expect(
+ journal.events.find((entry) => entry.type === "attempt_finished"),
+ ).toMatchObject({
+ outcome: scanStatus === "acceptance_unknown" ? "unresolved" : scanStatus,
+ failureCategory: scanStatus === "canceled" ? "canceled" : "execution",
+ });
expect(
readSavedScanLifecycle(
{ CODEX_SECURITY_STATE_DIR: input.stateDirectory },
@@ -1411,25 +1460,55 @@ test("a late cancel preserves a previously committed hosted failure", async () =
});
});
-test("mismatched execution receipts are never accepted or retried", async () => {
- const input = await fixture();
- const executor = {
- run: mock(async () =>
- receipt(
- { requestId: "other-request" },
- {
- sessionId: "known-session",
- usage: { input_tokens: 9 },
- },
+test.each([
+ { status: "completed" as const, sessionId: "known-session" },
+ { status: "failed" as const, sessionId: undefined },
+])(
+ "$status mismatched execution receipts are retained without accounting or retry",
+ async ({ status, sessionId }) => {
+ const input = await fixture();
+ const usage = { input_tokens: 9, output_tokens: 1 };
+ const executor = {
+ run: mock(async () =>
+ receipt({ requestId: "other-request" }, { status, sessionId, usage }),
),
- ),
- };
- const result = await runHostedScan(input, { executor });
- expect(executor.run).toHaveBeenCalledTimes(1);
- expect(result.status).toBe("acceptance_unknown");
- expect(result.execution?.sessionId).toBe("known-session");
- expect(result.artifacts).toEqual([]);
-});
+ };
+ const result = await runHostedScan(input, { executor });
+ expect(executor.run).toHaveBeenCalledTimes(1);
+ expect(result.status).toBe("acceptance_unknown");
+ expect(result.execution?.requestId).toBe("other-request");
+ expect(result.execution?.sessionId).toBe(sessionId);
+ expect(result.execution?.usage).toEqual(usage);
+ expect(result.artifacts).toEqual([]);
+ const journal = await readOperationTelemetry(input.stateDirectory);
+ const terminal = journal.events.find(
+ (event) => event.type === "attempt_finished",
+ );
+ expect(terminal).toMatchObject({ outcome: "unresolved" });
+ expect(terminal?.measurement?.usage ?? null).toBeNull();
+ expect(terminal?.measurement?.cost ?? null).toBeNull();
+ const saved = await runWorkbench(
+ {
+ python: pythonExecutable()!,
+ pluginRoot: PLUGIN_ROOT,
+ environment: {
+ PATH: process.env["PATH"],
+ SYSTEMROOT: process.env["SYSTEMROOT"],
+ CODEX_SECURITY_STATE_DIR: input.stateDirectory,
+ },
+ },
+ ["get-scan", "--scan-id", result.scanId!],
+ );
+ const scan = saved["scan"] as Record<string, unknown>;
+ expect(scan).toBeDefined();
+ expect(scan["usage"]).toMatchObject({
+ coverage: "unavailable",
+ threadCount: 0,
+ });
+ expect(scan["usage"]).not.toHaveProperty("totalTokens");
+ expect(scan["cost"] ?? null).toBeNull();
+ },
+);
test("same Cloud attempt does not create CLI cross-invocation replay decisions", async () => {
const input = await fixture();
diff --git a/sdk/typescript/tests-ts/local-dedupe.test.ts b/sdk/typescript/tests-ts/local-dedupe.test.ts
index 35b9b74d4..4a32bfdeb 100644
--- a/sdk/typescript/tests-ts/local-dedupe.test.ts
+++ b/sdk/typescript/tests-ts/local-dedupe.test.ts
@@ -19,6 +19,7 @@ import {
EMBEDDING_MODEL,
OpenAiFindingEmbedder,
type FindingEmbedder,
+ type EmbeddingUsageObservation,
} from "../src/server/embeddings.js";
import { SqliteFindingsStore } from "../src/server/sqlite-store.js";
import { resolvePluginPython, runWorkbench } from "../src/runtime.js";
@@ -249,6 +250,53 @@ test("local dedupe indexes a sealed directory, reuses vectors and never calls th
);
});
+test("saved-scan dedupe observes built-in embedding batches and skips cached embeddings", async () => {
+ const f = await fixture();
+ const observations: EmbeddingUsageObservation[] = [];
+ const request = spyOn(globalThis, "fetch").mockResolvedValue(
+ Response.json({
+ model: EMBEDDING_MODEL,
+ data: f.document.findings.map((_, index) => ({
+ index,
+ embedding: vector,
+ })),
+ usage: { prompt_tokens: 41 },
+ }),
+ );
+ const options = {
+ repository: f.repository,
+ onEmbeddingUsage: (observation: EmbeddingUsageObservation) =>
+ observations.push(observation),
+ };
+ const dependencies = {
+ environment: { ...f.environment, OPENAI_API_KEY: "synthetic-key" },
+ reviewer: emptyNeighborhoodReviewer(),
+ fetch: rejecting("Unexpected findings HTTP call"),
+ };
+ try {
+ const first = await deduplicateScanDirectoryInternal(
+ f.scanDir,
+ options,
+ dependencies,
+ );
+ expect(first.deduplicationStatus).toBe("completed");
+ expect(observations).toEqual([
+ {
+ model: EMBEDDING_MODEL,
+ inputCount: f.document.findings.length,
+ inputTokens: 41,
+ outcome: "completed",
+ durationMs: expect.any(Number),
+ },
+ ]);
+ await deduplicateScanDirectoryInternal(f.scanDir, options, dependencies);
+ expect(request).toHaveBeenCalledTimes(1);
+ expect(observations).toHaveLength(1);
+ } finally {
+ request.mockRestore();
+ }
+});
+
test("saved-scan local review persists a group with an existing repository finding", async () => {
const f = await fixture();
const anchor = f.document.findings[0]!;
diff --git a/sdk/typescript/tests-ts/multiscan-recovery.test.ts b/sdk/typescript/tests-ts/multiscan-recovery.test.ts
index ed4668d75..526bcea5d 100644
--- a/sdk/typescript/tests-ts/multiscan-recovery.test.ts
+++ b/sdk/typescript/tests-ts/multiscan-recovery.test.ts
@@ -1476,11 +1476,14 @@ describe("multiscan", () => {
const knowledgeBasePaths = [document];
let attempts = 0;
+ const operationIds: string[] = [];
const summary = await runMultiscan(
options(
paths,
client(async (_repository, scanOptions = {}) => {
expect(scanOptions.knowledgeBasePaths).toEqual(knowledgeBasePaths);
+ expect(scanOptions.telemetryContext?.operationId).toBeString();
+ operationIds.push(scanOptions.telemetryContext!.operationId);
attempts += 1;
if (attempts === 1) {
scanOptions.onWarning?.("Warning from the failed attempt.");
@@ -1493,6 +1496,7 @@ describe("multiscan", () => {
);
expect(attempts).toBe(2);
+ expect(new Set(operationIds).size).toBe(1);
expect(summary).toMatchObject({ completed: 1, failed: 0 });
expect(summary).not.toHaveProperty("warnings");
expect(await results(summary.resultsPath)).toMatchObject([
@@ -1500,10 +1504,16 @@ describe("multiscan", () => {
id: "retry",
status: "failed",
attempt: 1,
+ operationId: operationIds[0],
error: failure,
warnings: ["Warning from the failed attempt."],
},
- { id: "retry", status: "completed", attempt: 2 },
+ {
+ id: "retry",
+ status: "completed",
+ attempt: 2,
+ operationId: operationIds[0],
+ },
]);
});
diff --git a/sdk/typescript/tests-ts/multiscan.test.ts b/sdk/typescript/tests-ts/multiscan.test.ts
index 89645f8aa..2c2771e04 100644
--- a/sdk/typescript/tests-ts/multiscan.test.ts
+++ b/sdk/typescript/tests-ts/multiscan.test.ts
@@ -172,6 +172,49 @@ describe("multiscan", () => {
]);
});
+ test.each([false, true])(
+ "retains usage for failed or canceled bulk attempts: canceled=%p",
+ async (cancel) => {
+ const { paths } = await repositoryFixture("synthetic-usage");
+ const controller = new AbortController();
+ const measurement = {
+ coverage: "partial" as const,
+ cost: null,
+ observedAt: "2026-10-01T00:00:00.000Z",
+ threadCount: 1,
+ missingThreadCount: 1,
+ usage: {
+ input_tokens: 100,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 5,
+ reasoning_output_tokens: 0,
+ total_tokens: 105,
+ },
+ };
+ const run = runMultiscan(
+ options(
+ paths,
+ client(async (_repository, scanOptions = {}) => {
+ scanOptions.onMeasurement?.(measurement);
+ if (cancel) controller.abort(new Error("Synthetic cancellation"));
+ throw new Error("Synthetic execution failure");
+ }),
+ { maxAttempts: 1, signal: controller.signal },
+ ),
+ );
+ if (cancel) await expect(run).rejects.toThrow("Synthetic cancellation");
+ else expect(await run).toMatchObject({ completed: 0, failed: 1 });
+ expect(await results(join(paths.output, "results.jsonl"))).toMatchObject([
+ {
+ status: "failed",
+ outcome: cancel ? "canceled" : "failed",
+ measurement,
+ },
+ ]);
+ },
+ );
+
test("records an exhausted repository budget without retrying the scan", async () => {
const { paths } = await repositoryFixture("over-budget");
const cost = {
diff --git a/sdk/typescript/tests-ts/operation-telemetry.test.ts b/sdk/typescript/tests-ts/operation-telemetry.test.ts
new file mode 100644
index 000000000..f4945c43e
--- /dev/null
+++ b/sdk/typescript/tests-ts/operation-telemetry.test.ts
@@ -0,0 +1,746 @@
+import { afterEach, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import {
+ access,
+ appendFile,
+ mkdir,
+ readdir,
+ rename,
+ writeFile,
+} from "node:fs/promises";
+import { join } from "node:path";
+import {
+ OperationTelemetry,
+ readOperationTelemetry,
+ summarizeOperationTelemetry,
+ type OperationTelemetryEvent,
+} from "../src/operation-telemetry.js";
+import { TestClient } from "./support/api-client.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { workflowFixture } from "./support/workflow-fixture.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures("telemetry-");
+afterEach(cleanup);
+
+test("journals early failures without copying target paths or diagnostic text", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "missing-synthetic-repository");
+ const observed: OperationTelemetryEvent[] = [];
+ const client = new TestClient(
+ {},
+ {
+ environment: { CODEX_SECURITY_STATE_DIR: root },
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ },
+ );
+ try {
+ await expect(
+ client.run(repository, {
+ onTelemetry: (event) => observed.push(event),
+ }),
+ ).rejects.toThrow();
+ } finally {
+ await client.close();
+ }
+ const saved = await readOperationTelemetry(root);
+ expect(saved.parseFailures).toBe(0);
+ expect(saved.events.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(saved.events[1]).toMatchObject({
+ outcome: "failed",
+ command: "scan",
+ surface: "sdk",
+ failureCategory: "input",
+ });
+ expect(saved.events[1]!.durationMs).toBeGreaterThanOrEqual(0);
+ expect(observed.map((event) => event.eventId)).toEqual(
+ saved.events.map((event) => event.eventId),
+ );
+ expect(JSON.stringify(saved.events)).not.toContain(repository);
+ expect(JSON.stringify(saved.events)).not.toContain(
+ "missing-synthetic-repository",
+ );
+});
+
+test.each(["scan", "validate", "policy"] as const)(
+ "explicit %s output stays empty through runtime preparation",
+ async (command) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const state = join(root, "state");
+ const outputDir = join(state, "telemetry");
+ await mkdir(repository);
+ await mkdir(outputDir, { recursive: true, mode: 0o700 });
+ const observed: OperationTelemetryEvent[] = [];
+ const failure = new Error("Synthetic runtime boundary reached");
+ let runtimeCalls = 0;
+ const client = new TestClient(
+ {},
+ {
+ environment: {
+ CODEX_SECURITY_STATE_DIR: state,
+ CODEX_HOME: join(root, "codex"),
+ },
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ prepareRuntime: async () => {
+ runtimeCalls++;
+ throw failure;
+ },
+ },
+ );
+ const options = {
+ outputDir,
+ onTelemetry: (event: Readonly<OperationTelemetryEvent>) =>
+ observed.push(event),
+ };
+ try {
+ const operation =
+ command === "scan"
+ ? client.run(repository, { ...options, mode: "standard" })
+ : command === "validate"
+ ? client.validate({
+ ...options,
+ repositoryPath: repository,
+ finding: "Synthetic candidate finding",
+ })
+ : client.generatePolicy(repository, options);
+ await expect(operation).rejects.toBe(failure);
+ } finally {
+ await client.close();
+ }
+ expect(runtimeCalls).toBe(1);
+ expect(await readdir(outputDir)).toEqual([]);
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]).toMatchObject({
+ operationId: observed[0]!.operationId,
+ attemptId: observed[0]!.attemptId,
+ outcome: "failed",
+ collection: { persisted: 0 },
+ });
+ },
+);
+
+test("rejected explicit scan output keeps its completed artifacts unchanged", async () => {
+ await using fixture = await workflowFixture();
+ const state = fixture.environment.CODEX_SECURITY_STATE_DIR;
+ await mkdir(state, { mode: 0o700 });
+ const outputDir = join(state, "telemetry");
+ await rename(fixture.scanDir, outputDir);
+ const entries = await readdir(outputDir, { recursive: true });
+ const client = new TestClient(
+ {},
+ {
+ environment: fixture.environment,
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ },
+ );
+ try {
+ await expect(
+ client.run(fixture.repository, { mode: "standard", outputDir }),
+ ).rejects.toThrow("Scan output directory is not empty");
+ } finally {
+ await client.close();
+ }
+ expect((await readdir(outputDir, { recursive: true })).sort()).toEqual(
+ entries.sort(),
+ );
+});
+
+test("rejected workflow state paths leave sealed artifacts unchanged", async () => {
+ await using fixture = await workflowFixture();
+ const state = join(fixture.scanDir, "state");
+ const entries = await readdir(fixture.scanDir, { recursive: true });
+ const observed: OperationTelemetryEvent[] = [];
+ const client = new TestClient(
+ {},
+ {
+ environment: {
+ ...fixture.environment,
+ CODEX_SECURITY_STATE_DIR: state,
+ },
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ },
+ );
+ try {
+ await expect(
+ client.run(fixture.repository, {
+ mode: "standard",
+ workflowId: "synthetic-workflow",
+ outputDir: fixture.scanDir,
+ onTelemetry: (event) => observed.push(event),
+ }),
+ ).rejects.toThrow(
+ "Workflow state must be outside the sealed scan artifacts.",
+ );
+ } finally {
+ await client.close();
+ }
+ expect((await readdir(fixture.scanDir, { recursive: true })).sort()).toEqual(
+ entries.sort(),
+ );
+ await expect(access(state)).rejects.toThrow();
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]).toMatchObject({
+ outcome: "failed",
+ collection: { persisted: 0, writeFailures: 0 },
+ });
+});
+
+test.each(["explicit", "saved"] as const)(
+ "%s workflow artifacts cannot become the journal directory",
+ async (source) => {
+ await using fixture = await workflowFixture();
+ const state = fixture.environment.CODEX_SECURITY_STATE_DIR;
+ await mkdir(state, { mode: 0o700 });
+ const scanDir = join(state, "telemetry");
+ await rename(fixture.scanDir, scanDir);
+ const entries = await readdir(scanDir, { recursive: true });
+ const observed: OperationTelemetryEvent[] = [];
+ const warnings: string[] = [];
+ const client = new TestClient(
+ {},
+ {
+ environment: {
+ ...fixture.environment,
+ CODEX_SECURITY_STATE_DIR: state,
+ },
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ runWorkbench: async () => ({
+ workflow: {
+ id: "synthetic-workflow",
+ scanId: fixture.document.scanId,
+ scanDir,
+ stages: {
+ scan: {
+ status: "completed",
+ result: {
+ threadId: "synthetic-thread",
+ turnResult: { status: "completed" },
+ },
+ },
+ publish: { status: "pending" },
+ dedupe: { status: "pending" },
+ },
+ },
+ }),
+ },
+ );
+ try {
+ const result = await client.run(fixture.repository, {
+ mode: "standard",
+ workflowId: "synthetic-workflow",
+ ...(source === "explicit" ? { outputDir: scanDir } : {}),
+ onTelemetry: (event) => observed.push(event),
+ onWarning: (message) => warnings.push(message),
+ });
+ expect(result.manifest.scan.id).toBe(fixture.document.scanId);
+ } finally {
+ await client.close();
+ }
+ expect((await readdir(scanDir, { recursive: true })).sort()).toEqual(
+ entries.sort(),
+ );
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]).toMatchObject({
+ outcome: "completed",
+ reusedResult: true,
+ collection: { persisted: 0, writeFailures: 1 },
+ });
+ expect(warnings).toHaveLength(1);
+ },
+);
+
+test.each(["immediate", "deferred"] as const)(
+ "resume keeps one operation identity and deduplicates receipts, %s",
+ async (persistence) => {
+ const deferPersistence = persistence === "deferred";
+ const directory = await temporaryDirectory();
+ const first = new OperationTelemetry({
+ directory,
+ protectedOutput: join(directory, "scan-artifacts"),
+ command: "scan",
+ surface: "sdk",
+ });
+ await first.start();
+ await first.bindScan("synthetic-scan");
+ await first.finish("failed");
+ await first.finish("completed");
+ const observed: OperationTelemetryEvent[] = [];
+ const resumed = new OperationTelemetry({
+ directory,
+ deferPersistence,
+ onEvent: (event) => observed.push(structuredClone(event)),
+ protectedOutput: join(directory, "scan-artifacts"),
+ command: "scan",
+ surface: "sdk",
+ resumeScanId: "synthetic-scan",
+ });
+ await resumed.start();
+ if (deferPersistence) {
+ expect(observed).toHaveLength(0);
+ await resumed.activatePersistence([]);
+ }
+ expect(resumed.operationId).toBe(first.operationId);
+ expect(resumed.attemptId).not.toBe(first.attemptId);
+ await resumed.finish("completed");
+ expect(observed.map((event) => event.operationId)).toEqual([
+ first.operationId,
+ first.operationId,
+ ]);
+ expect(new Set(observed.map((event) => event.usageScopeId))).toEqual(
+ new Set([first.attemptId]),
+ );
+ const interrupted = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ });
+ await interrupted.start();
+ const { events } = await readOperationTelemetry(directory);
+ expect(events).toHaveLength(5);
+ expect(
+ events
+ .filter((event) => event.attemptId === resumed.attemptId)
+ .map((event) => event.operationId),
+ ).toEqual([first.operationId, first.operationId]);
+ const summary = summarizeOperationTelemetry(
+ [...events].reverse().concat(events),
+ );
+ expect(summary).toMatchObject({
+ attempts: 3,
+ outcomes: { completed: 1, failed: 1, canceled: 0, unresolved: 1 },
+ usageCoverage: { complete: 0, partial: 0, unavailable: 3 },
+ duplicates: 5,
+ pricedAttempts: 0,
+ });
+ },
+);
+
+test("reports corrupt trailing records and keeps usable receipts", async () => {
+ const directory = await temporaryDirectory();
+ const journal = new OperationTelemetry({
+ directory,
+ command: "patch",
+ surface: "cli",
+ });
+ await journal.start();
+ await appendFile(
+ join(directory, "telemetry", `${journal.attemptId}.jsonl`),
+ '{"partial":',
+ );
+ const result = await readOperationTelemetry(directory);
+ expect(result.events).toHaveLength(1);
+ expect(result.parseFailures).toBe(1);
+ expect(summarizeOperationTelemetry(result.events).outcomes.unresolved).toBe(
+ 1,
+ );
+});
+
+test("counts reused results once while preserving completed call outcomes", async () => {
+ const directory = await temporaryDirectory();
+ const execution = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ });
+ await execution.start();
+ await execution.finish("completed", { findingCount: 2 });
+ const retrieval = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ context: { operationId: execution.operationId },
+ });
+ await retrieval.start();
+ retrieval.reusedResult = true;
+ await retrieval.finish("completed", { findingCount: 2 });
+ const { events } = await readOperationTelemetry(directory);
+ expect(
+ events.find(
+ (event) =>
+ event.attemptId === execution.attemptId &&
+ event.type === "attempt_finished",
+ )?.reusedResult,
+ ).toBe(false);
+ const reused = events.find((event) => event.reusedResult === true);
+ expect(reused).toMatchObject({
+ type: "attempt_finished",
+ outcome: "completed",
+ findingCount: 2,
+ });
+ expect(reused?.measurement).toBeUndefined();
+ expect(
+ summarizeOperationTelemetry([...events].reverse().concat(events)),
+ ).toMatchObject({
+ operations: 1,
+ successfulOperations: 1,
+ attempts: 2,
+ reusedAttempts: 1,
+ usageCoverage: { complete: 0, partial: 0, unavailable: 1 },
+ outcomes: { completed: 2, failed: 0, canceled: 0, unresolved: 0 },
+ duplicates: 4,
+ });
+});
+
+test.each([
+ ["operation ID", { operationId: undefined }],
+ ["usage scope ID", { usageScopeId: undefined }],
+ ["outcome", { outcome: "unknown" }],
+ ["terminal outcome", { outcome: undefined }],
+ ["measurement coverage", { measurement: { coverage: "unknown" } }],
+] as const)(
+ "reports incomplete journal %s without changing valid summaries",
+ async (_field, invalid) => {
+ const directory = await temporaryDirectory();
+ const journal = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ });
+ await journal.start();
+ await journal.finish("completed");
+ const original = await readOperationTelemetry(directory);
+ const terminal = original.events.find(
+ (event) => event.type === "attempt_finished",
+ )!;
+ await appendFile(
+ join(directory, "telemetry", `${journal.attemptId}.jsonl`),
+ `${JSON.stringify({ ...terminal, eventId: "invalid-event", attemptId: "invalid-attempt", ...invalid })}\n`,
+ );
+ const result = await readOperationTelemetry(directory);
+ expect(result.parseFailures).toBe(1);
+ expect(result.events).toEqual(original.events);
+ expect(summarizeOperationTelemetry(result.events)).toEqual(
+ summarizeOperationTelemetry(original.events),
+ );
+ },
+);
+
+test("deferred resume failures emit matching in-memory start and terminal events", async () => {
+ const directory = join(await temporaryDirectory(), "not-created");
+ const observed: OperationTelemetryEvent[] = [];
+ const journal = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ deferPersistence: true,
+ resumeScanId: "synthetic-scan",
+ onEvent: (event) => observed.push(structuredClone(event)),
+ });
+ await journal.start();
+ await journal.finish("failed", { failureCategory: "input" });
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]).toMatchObject({
+ operationId: observed[0]!.operationId,
+ usageScopeId: observed[0]!.usageScopeId,
+ attemptId: observed[0]!.attemptId,
+ collection: { persisted: 0, writeFailures: 0 },
+ });
+ await expect(access(directory)).rejects.toThrow();
+});
+
+test("journal and observer failures cannot stop an operation", async () => {
+ const directory = await temporaryDirectory();
+ await writeFile(join(directory, "telemetry"), "occupied");
+ const observed: OperationTelemetryEvent[] = [];
+ const errors: unknown[] = [];
+ const journal = new OperationTelemetry({
+ directory,
+ command: "validate",
+ surface: "sdk",
+ onEvent(event) {
+ observed.push(event);
+ throw new Error("observer failed");
+ },
+ onError(error) {
+ errors.push(error);
+ },
+ });
+ await journal.start();
+ await journal.finish("canceled");
+ await Promise.resolve();
+ expect(errors.length).toBeGreaterThan(0);
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]!.collection.writeFailures).toBeGreaterThan(0);
+});
+
+test("journal refuses to write inside the protected repository", async () => {
+ const repository = await temporaryDirectory();
+ const state = join(repository, "state");
+ const errors: unknown[] = [];
+ const journal = new OperationTelemetry({
+ directory: state,
+ protectedRepository: repository,
+ command: "scan",
+ surface: "sdk",
+ onError: (error) => errors.push(error),
+ });
+ await journal.start();
+ await journal.finish("failed");
+ expect(errors).toHaveLength(1);
+ await expect(access(state)).rejects.toThrow();
+});
+
+test("journal protects the enclosing checkout before a missing target is validated", async () => {
+ const repository = await temporaryDirectory();
+ await mkdir(join(repository, ".git"), { mode: 0o700 });
+ const state = join(repository, "state");
+ const errors: unknown[] = [];
+ const observed: OperationTelemetryEvent[] = [];
+ const journal = new OperationTelemetry({
+ directory: state,
+ protectedRepository: join(repository, "missing-target"),
+ command: "scan",
+ surface: "sdk",
+ onError: (error) => errors.push(error),
+ onEvent: (event) => observed.push(event),
+ });
+ await journal.start();
+ await journal.finish("failed");
+ expect(errors).toHaveLength(1);
+ await expect(access(state)).rejects.toThrow();
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]!.collection).toEqual({
+ persisted: 0,
+ writeFailures: 1,
+ });
+});
+
+test.each([
+ "separate",
+ "linked",
+ "nested",
+ "objects",
+ "nested-objects",
+] as const)(
+ "policy journals leave external %s Git metadata untouched",
+ async (kind) => {
+ const root = await temporaryDirectory();
+ let repository = join(root, "repository");
+ await mkdir(repository, { mode: 0o700 });
+ let metadata = join(root, "metadata");
+ if (kind === "linked") {
+ execFileSync("git", ["init", "--quiet", repository]);
+ execFileSync("git", [
+ "-C",
+ repository,
+ "-c",
+ "user.name=Synthetic",
+ "-c",
+ "commit",
+ "--allow-empty",
+ "--quiet",
+ "-m",
+ "initial",
+ ]);
+ const linked = join(root, "linked");
+ execFileSync("git", [
+ "-C",
+ repository,
+ "worktree",
+ "add",
+ "--quiet",
+ "--detach",
+ linked,
+ ]);
+ metadata = join(repository, ".git", "worktrees", "linked");
+ repository = linked;
+ } else {
+ const checkout = kind.startsWith("nested")
+ ? join(repository, "component")
+ : repository;
+ execFileSync("git", [
+ "init",
+ "--quiet",
+ "--separate-git-dir",
+ metadata,
+ checkout,
+ ]);
+ execFileSync("git", [
+ "-C",
+ checkout,
+ "config",
+ "core.worktree",
+ checkout,
+ ]);
+ if (kind.endsWith("objects")) {
+ const objects = join(root, "external-objects");
+ await mkdir(join(objects, "info"), { recursive: true, mode: 0o700 });
+ await writeFile(
+ join(metadata, "objects", "info", "alternates"),
+ `${objects}\n`,
+ );
+ metadata = objects;
+ }
+ }
+ const state = join(metadata, "state");
+ const observed: OperationTelemetryEvent[] = [];
+ const client = new TestClient(
+ {},
+ {
+ environment: { CODEX_SECURITY_STATE_DIR: state },
+ createOperationTelemetry: (options) => new OperationTelemetry(options),
+ },
+ );
+ try {
+ await expect(
+ client.generatePolicy(repository, {
+ onTelemetry: (event) => observed.push(event),
+ }),
+ ).rejects.toThrow("outside the protected scan root");
+ } finally {
+ await client.close();
+ }
+ await expect(access(state)).rejects.toThrow();
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]!.outcome).toBe("failed");
+ },
+);
+
+test("deferred journals persist the original start once after path validation", async () => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ await mkdir(repository, { mode: 0o700 });
+ const state = join(root, "state");
+ const observed: OperationTelemetryEvent[] = [];
+ const journal = new OperationTelemetry({
+ directory: state,
+ protectedRepository: repository,
+ command: "policy",
+ surface: "sdk",
+ deferPersistence: true,
+ onEvent: (event) => observed.push(event),
+ });
+ await journal.start();
+ expect(observed).toHaveLength(1);
+ await expect(access(state)).rejects.toThrow();
+ await journal.activatePersistence([repository]);
+ await journal.activatePersistence([repository]);
+ await journal.finish("completed");
+ const saved = await readOperationTelemetry(state);
+ expect(saved.events).toHaveLength(2);
+ expect(observed).toHaveLength(2);
+ expect(saved.events[0]).toMatchObject({
+ eventId: observed[0]!.eventId,
+ occurredAt: observed[0]!.occurredAt,
+ observedAt: observed[0]!.observedAt,
+ collection: { persisted: 1, writeFailures: 0 },
+ });
+ expect(saved.events[1]!.collection.persisted).toBe(2);
+});
+
+test("deferred journal activation failures leave the operation observable", async () => {
+ const directory = await temporaryDirectory();
+ await writeFile(join(directory, "telemetry"), "occupied");
+ const observed: OperationTelemetryEvent[] = [];
+ const journal = new OperationTelemetry({
+ directory,
+ command: "policy",
+ surface: "sdk",
+ deferPersistence: true,
+ onEvent: (event) => observed.push(event),
+ onError: () => {
+ throw new Error("Synthetic warning observer failure");
+ },
+ });
+ await journal.start();
+ await journal.activatePersistence([]);
+ await journal.finish("completed");
+ expect(observed.map((event) => event.type)).toEqual([
+ "attempt_started",
+ "attempt_finished",
+ ]);
+ expect(observed[1]!.collection).toEqual({
+ persisted: 0,
+ writeFailures: 1,
+ });
+});
+
+test("cumulative resume costs are counted once while independent retries are added", async () => {
+ const directory = await temporaryDirectory();
+ await mkdir(join(directory, "telemetry"));
+ const first = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ });
+ const measurement = (tokens: number) => ({
+ usage: {
+ input_tokens: tokens,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 0,
+ reasoning_output_tokens: 0,
+ total_tokens: tokens,
+ },
+ cost: {
+ model: "gpt-5.6-sol",
+ inputTokens: tokens,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: 0,
+ estimatedUsd: tokens,
+ },
+ coverage: "complete" as const,
+ observedAt: new Date().toISOString(),
+ threadCount: 1,
+ missingThreadCount: 0,
+ });
+ await first.start();
+ await first.bindScan("synthetic-scan");
+ first.measurement = measurement(10);
+ await first.finish("failed");
+ const resumed = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ resumeScanId: "synthetic-scan",
+ });
+ await resumed.start();
+ resumed.measurement = measurement(15);
+ await resumed.finish("completed");
+ const retry = new OperationTelemetry({
+ directory,
+ command: "scan",
+ surface: "sdk",
+ context: { operationId: first.operationId },
+ });
+ await retry.start();
+ retry.measurement = measurement(3);
+ await retry.finish("completed");
+ expect(
+ summarizeOperationTelemetry(
+ (await readOperationTelemetry(directory)).events,
+ ),
+ ).toMatchObject({
+ attempts: 3,
+ operations: 1,
+ successfulOperations: 1,
+ pricedAttempts: 3,
+ observedCostUsd: 18,
+ });
+});
diff --git a/sdk/typescript/tests-ts/package-tar-listing.test.ts b/sdk/typescript/tests-ts/package-tar-listing.test.ts
index f415b43a0..9c8277005 100644
--- a/sdk/typescript/tests-ts/package-tar-listing.test.ts
+++ b/sdk/typescript/tests-ts/package-tar-listing.test.ts
@@ -85,6 +85,7 @@ function packageTar({
"package/docs/hosted-scans.md",
"package/docs/validate-records.md",
"package/docs/hosted-remediation.md",
+ "package/docs/telemetry.md",
"package/schemas/hosted-scan-v2.fixture.json",
"package/schemas/project-config.schema.json",
"package/schemas/external-findings.schema.json",
diff --git a/sdk/typescript/tests-ts/provider-profile.test.ts b/sdk/typescript/tests-ts/provider-profile.test.ts
index f71dec38c..a8af182f2 100644
--- a/sdk/typescript/tests-ts/provider-profile.test.ts
+++ b/sdk/typescript/tests-ts/provider-profile.test.ts
@@ -61,6 +61,141 @@ const startupProviders = {
"synthetic.gateway": startupProvider,
};
+test("native preflight preserves consent and attribution while reading exporters from its private home", async () => {
+ const home = await temporaryDirectory();
+ const sharedConfig =
+ '[analytics]\nenabled = false\n[otel]\nexporter = "none"\nenvironment = "synthetic-shared"\n';
+ await writeFile(join(home, "config.toml"), sharedConfig);
+ const { readDeepScanRuntimeConfig } = await import(
+ pathToFileURL(
+ join(
+ await bundledPluginRoot(),
+ "mcp",
+ "permission-profile-preflight.mjs",
+ ),
+ ).href
+ );
+ const native = await providerPreflightCommand(resolveCodexCommand({}), {
+ analytics: { enabled: false },
+ otel: { exporter: "none", environment: "synthetic-root" },
+ profile: "selected",
+ profiles: {
+ selected: {
+ otel: { environment: "synthetic-selected", log_user_prompt: false },
+ responses_api_metadata: { "synthetic.tag": "selected" },
+ },
+ },
+ });
+ const read = async (args: readonly string[] | undefined) =>
+ await readDeepScanRuntimeConfig({
+ codexPath: native.command,
+ commandArgs: args,
+ cwd: home,
+ configOverrides: [],
+ env: {
+ PATH: process.env["PATH"] ?? "",
+ ...(process.env["SystemRoot"] === undefined
+ ? {}
+ : { SystemRoot: process.env["SystemRoot"] }),
+ ...(process.env["TMPDIR"] === undefined
+ ? {}
+ : { TMPDIR: process.env["TMPDIR"] }),
+ HOME: home,
+ CODEX_HOME: home,
+ },
+ signal: new AbortController().signal,
+ context: "helper",
+ });
+ const effective = await read(native.args);
+ expect(effective.analytics).toEqual({ enabled: false });
+ expect(effective.otel).toMatchObject({
+ exporter: "none",
+ environment: "synthetic-shared",
+ });
+ expect(effective.responses_api_metadata).toEqual({
+ "synthetic.tag": "selected",
+ });
+ expect(await readFile(join(home, "config.toml"), "utf8")).toBe(sharedConfig);
+ const next = await read(
+ (await providerPreflightCommand(resolveCodexCommand({}), {})).args,
+ );
+ expect(next.otel.environment).toBe("synthetic-shared");
+ expect(next.responses_api_metadata ?? null).toBeNull();
+});
+
+test.each(["root", "selected profile"] as const)(
+ "native helper children keep %s exporter headers out of argv without moving their home",
+ async (source) => {
+ const home = await temporaryDirectory();
+ const sharedConfig =
+ '[analytics]\nenabled = false\n[otel]\nexporter = "none"\nenvironment = "synthetic-shared"\n';
+ await writeFile(join(home, "config.toml"), sharedConfig);
+ const script = join(home, "native telemetry.mjs");
+ await writeFile(
+ script,
+ `import { readFileSync } from "node:fs";
+ import { join } from "node:path";
+ console.log(JSON.stringify({
+ args: process.argv.slice(2),
+ home: process.env.CODEX_HOME,
+ config: readFileSync(join(process.env.CODEX_HOME, "config.toml"), "utf8"),
+ }));`,
+ );
+ const telemetry = {
+ analytics: { enabled: false },
+ responses_api_metadata: { "synthetic.tag": source },
+ otel: {
+ exporter: {
+ "otlp-http": {
+ endpoint: "https://telemetry.example.test/v1/logs",
+ protocol: "json",
+ headers: { Authorization: "Bearer synthetic-helper-exporter" },
+ },
+ },
+ },
+ };
+ const settings =
+ source === "root"
+ ? telemetry
+ : { profile: "selected", profiles: { selected: telemetry } };
+ const command = await providerPreflightCommand(
+ { command: process.execPath, args: [script] },
+ settings,
+ );
+ for (const args of [
+ ["login", "status"],
+ ["plugin", "marketplace", "list"],
+ ["app-server", "--stdio"],
+ ]) {
+ const result = await runCodexCommand(command, args, {
+ ...process.env,
+ CODEX_HOME: home,
+ });
+ expect(result.success, result.stderr).toBe(true);
+ const observed = JSON.parse(result.stdout);
+ expect(observed.home).toBe(home);
+ expect(observed.config).toBe(sharedConfig);
+ expect(JSON.stringify(observed.args)).not.toContain(
+ "synthetic-helper-exporter",
+ );
+ const forwarded = Object.assign(
+ {},
+ ...observed.args
+ .slice(0, -args.length)
+ .filter((_: string, index: number) => index % 2 === 1)
+ .map((value: string) => parse(value)),
+ );
+ expect(forwarded).toEqual({
+ analytics: telemetry.analytics,
+ responses_api_metadata: telemetry.responses_api_metadata,
+ });
+ }
+ expect(await readFile(join(home, "config.toml"), "utf8")).toBe(
+ sharedConfig,
+ );
+ },
+);
+
test.each([false, true])(
"saved managed provider profiles remain isolated across concurrent scans (replay: %p)",
async (replay) => {
diff --git a/sdk/typescript/tests-ts/publish.test.ts b/sdk/typescript/tests-ts/publish.test.ts
index c2b4f7574..fa3d71ca1 100644
--- a/sdk/typescript/tests-ts/publish.test.ts
+++ b/sdk/typescript/tests-ts/publish.test.ts
@@ -45,12 +45,56 @@ import type {
} from "../src/publication.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
import { rejecting, throwing } from "./support/errors.js";
+import type { PublicationTelemetry } from "../src/publication-telemetry.js";
const copyPublishedIssues: PublishScanDependencies["recordPublishedIssues"] =
async (_prepared, issues) => {
return [...issues];
};
+test.each(["failed", "canceled"] as const)(
+ "observes publication %s before preparation and preserves the original error",
+ async (outcome) => {
+ const controller = new AbortController();
+ const reason = new Error("Synthetic preparation failure");
+ if (outcome === "canceled") controller.abort(reason);
+ const observations: PublicationTelemetry[] = [];
+ await expect(
+ publishScanInternal(
+ "scan",
+ {
+ ...OPTIONS,
+ signal: controller.signal,
+ onTelemetry: (event) => {
+ observations.push(event);
+ throw new Error("Synthetic observer failure");
+ },
+ },
+ dependencies(preparedPublication(), {
+ prepare: async () => {
+ throw reason;
+ },
+ }),
+ ),
+ ).rejects.toBe(reason);
+ expect(observations).toEqual([
+ expect.objectContaining({
+ destination: "linear",
+ outcome,
+ attempted: false,
+ counts: {
+ selected: null,
+ submitted: 0,
+ created: 0,
+ reused: 0,
+ acknowledged: 0,
+ failed: 0,
+ },
+ }),
+ ]);
+ },
+);
+
for (const [fileName, partialWrite, cleanupFails] of [
["issues.jsonl", false, false],
["issues.jsonl", true, false],
@@ -574,6 +618,10 @@ describe("skip-recorded publication", () => {
counts: { findings: 2, created: 0, failed: 0 },
dryRun: true,
issues: publication.issues,
+ telemetry: expect.objectContaining({
+ outcome: "preview",
+ attempted: false,
+ }),
});
expect(ordinary).not.toHaveProperty("skipped");
const preview = await publishScanInternal(
@@ -618,6 +666,18 @@ describe("skip-recorded publication", () => {
failed: 0,
skipped: 1,
});
+ expect(result.telemetry).toMatchObject({
+ outcome: "completed",
+ attempted: false,
+ counts: {
+ selected: 1,
+ submitted: 0,
+ reused: 1,
+ created: 0,
+ acknowledged: 0,
+ failed: 0,
+ },
+ });
});
test("publishes only pending findings while validating and recording against the full scan", async () => {
@@ -684,6 +744,19 @@ describe("skip-recorded publication", () => {
failed: 0,
skipped: 1,
});
+ expect(result.telemetry).toMatchObject({
+ destination: "linear",
+ outcome: "completed",
+ attempted: true,
+ counts: {
+ selected: 2,
+ submitted: 1,
+ reused: 1,
+ created: 1,
+ acknowledged: 1,
+ failed: 0,
+ },
+ });
expect(progress[0]).toEqual({
type: "started",
scanId: publication.scanId,
@@ -1534,6 +1607,7 @@ describe("connected Linear publication", () => {
codex_security_surface: "sdk",
codex_security_command: "publish",
codex_security_package_version: VERSION,
+ codex_security_attempt_id: result.telemetry!.attemptId,
});
expect(inheritedEnvironment).toBe(environment);
expect(input).toContain("already-connected hosted Linear application");
@@ -1605,6 +1679,10 @@ describe("connected Linear publication", () => {
],
failed: [],
counts: { findings: 1, created: 1, failed: 0 },
+ telemetry: expect.objectContaining({
+ destination: "linear",
+ outcome: "completed",
+ }),
});
expect(receiptScanId).toBe("scan-example");
});
@@ -2544,6 +2622,7 @@ describe("connected Linear publication", () => {
const publication = preparedPublication(3);
const controller = new AbortController();
const updates: PublishScanProgress[] = [];
+ const observations: PublicationTelemetry[] = [];
let handoffFile: string | undefined;
let publicationFile: string | undefined;
let childStopped = false;
@@ -2557,6 +2636,7 @@ describe("connected Linear publication", () => {
...OPTIONS,
signal: controller.signal,
onProgress: (event) => updates.push(event),
+ onTelemetry: (event) => observations.push(event),
},
dependencies(publication, {
runCodex: async (
@@ -2617,7 +2697,19 @@ describe("connected Linear publication", () => {
],
failed: [{ findingId: "finding-3" }],
counts: { findings: 3, created: 2, failed: 1 },
+ telemetry: {
+ outcome: "indeterminate",
+ attempted: true,
+ counts: { created: 2, acknowledged: 2, failed: null },
+ },
});
+ expect(observations).toMatchObject([
+ {
+ outcome: "indeterminate",
+ attempted: true,
+ counts: { created: 2, acknowledged: 2, failed: null },
+ },
+ ]);
expect(JSON.stringify(receipt)).not.toContain("SEC-UNVERIFIED");
expect(updates.some((event) => event.type === "completed")).toBe(false);
diff --git a/sdk/typescript/tests-ts/scan-dashboard.test.ts b/sdk/typescript/tests-ts/scan-dashboard.test.ts
index 039ffb313..83f16b329 100644
--- a/sdk/typescript/tests-ts/scan-dashboard.test.ts
+++ b/sdk/typescript/tests-ts/scan-dashboard.test.ts
@@ -80,6 +80,57 @@ class DashboardTestInput extends EventEmitter {
}
describe("live scan dashboard", () => {
+ test("invalidates complete totals when usage becomes partial or unavailable", () => {
+ const stderr = capture(true);
+ const dashboard = createDashboard(stderr.stream, { showCost: true });
+ dashboard.start();
+ const usage = {
+ input_tokens: 100,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 5,
+ reasoning_output_tokens: 0,
+ total_tokens: 105,
+ };
+ const cost = {
+ model: "gpt-5.6-sol",
+ inputTokens: 100,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: 5,
+ estimatedUsd: 0.001,
+ };
+ dashboard.setMeasurement({
+ usage,
+ cost,
+ coverage: "complete",
+ observedAt: new Date().toISOString(),
+ threadCount: 1,
+ missingThreadCount: 0,
+ });
+ expect(lastFrame(stderr)).not.toContain("(partial)");
+ dashboard.setMeasurement({
+ usage,
+ cost,
+ coverage: "partial",
+ observedAt: new Date().toISOString(),
+ threadCount: 1,
+ missingThreadCount: 1,
+ });
+ expect(lastFrame(stderr)).toContain("(partial)");
+ dashboard.setMeasurement({
+ usage: null,
+ cost: null,
+ coverage: "unavailable",
+ observedAt: new Date().toISOString(),
+ threadCount: 0,
+ missingThreadCount: 2,
+ });
+ expect(lastFrame(stderr)).toContain("usage unavailable");
+ expect(lastFrame(stderr)).not.toContain("105");
+ dashboard.stop();
+ });
+
test("keeps activity while a terminal is backpressured and restores the screen", async () => {
const stderr = capture(true);
const stream = { ...stderr.stream, writableNeedDrain: true };
diff --git a/sdk/typescript/tests-ts/scan-logs-node.test.ts b/sdk/typescript/tests-ts/scan-logs-node.test.ts
index 7b2deca11..d99d45be9 100644
--- a/sdk/typescript/tests-ts/scan-logs-node.test.ts
+++ b/sdk/typescript/tests-ts/scan-logs-node.test.ts
@@ -1,11 +1,12 @@
import { execFile } from "node:child_process";
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { promisify } from "node:util";
import { zstdCompressSync } from "node:zlib";
import { afterEach, beforeAll, expect, test } from "bun:test";
import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { PLUGIN_ROOT } from "./plugin-root.js";
const { temporaryDirectory, cleanup } = createApiTestFixtures(
"codex-security-scan-logs-node-",
@@ -52,7 +53,16 @@ test.each(["native", "without zstd"])(
zstdCompressSync(`${JSON.stringify(worker)}\n`),
);
- const module = join(root, "scan-logs.mjs");
+ for (const relativePath of [
+ ".codex-plugin/plugin.json",
+ "mcp/session-decompression.mjs",
+ ]) {
+ const destination = join(root, "_bundled_plugin", relativePath);
+ await mkdir(dirname(destination), { recursive: true });
+ await copyFile(join(PLUGIN_ROOT, relativePath), destination);
+ }
+ const module = join(root, "dist", "scan-logs.mjs");
+ await mkdir(dirname(module), { recursive: true });
await writeFile(module, moduleSource);
const { stdout } = await promisify(execFile)(
"node",
@@ -86,17 +96,13 @@ test.each(["native", "without zstd"])(
threadId: "parent",
workingDirectory: root,
});
- expect(result.worker).toEqual(
- result.compressed
- ? expect.objectContaining({
- threadId: "worker",
- workingDirectory: root,
- })
- : null,
- );
+ expect(result.worker).toMatchObject({
+ threadId: "worker",
+ workingDirectory: root,
+ });
expect(result.logs.events).toEqual([
{ threadId: "parent", event: parent },
- ...(result.compressed ? [{ threadId: "worker", event: worker }] : []),
+ { threadId: "worker", event: worker },
]);
},
);
diff --git a/sdk/typescript/tests-ts/scan-measurement.test.ts b/sdk/typescript/tests-ts/scan-measurement.test.ts
new file mode 100644
index 000000000..7a2209a52
--- /dev/null
+++ b/sdk/typescript/tests-ts/scan-measurement.test.ts
@@ -0,0 +1,73 @@
+import { expect, test } from "bun:test";
+import {
+ combineMeasurements,
+ measuredScanCost,
+ measurementFromUsage,
+} from "../src/scan-measurement.js";
+
+const usage = {
+ input_tokens: 10,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: 2,
+ reasoning_output_tokens: 0,
+ total_tokens: 12,
+};
+
+test("workbench usage retains coverage identities for a large scan", () => {
+ const coverageScope = Array.from(
+ { length: 400 },
+ (_, index) => `thread:synthetic-worker-${index}`,
+ );
+ const measurement = {
+ ...measurementFromUsage(usage, "synthetic-unpriced-model"),
+ coverage: "partial" as const,
+ threadCount: 399,
+ missingThreadCount: 1,
+ coverageScope,
+ };
+ const envelope = measuredScanCost(measurement);
+ expect(envelope?.usage.coverageScope).toEqual(coverageScope);
+ expect(envelope?.usage.coverage).toBe("partial");
+ expect(envelope?.usage.totalTokens).toBe(12);
+ expect(envelope).not.toHaveProperty("cost");
+ expect(JSON.stringify(envelope).length).toBeGreaterThan(8192);
+});
+
+test("disjoint stage measurements retain the union of known coverage scopes", () => {
+ const first = {
+ ...measurementFromUsage(usage, "synthetic-unpriced-model"),
+ coverageScope: ["thread:first", "worker-attempt:first"],
+ warnings: ["cost_estimate_covers_earlier_usage"],
+ };
+ const second = {
+ ...measurementFromUsage(usage, "synthetic-unpriced-model"),
+ coverage: "partial" as const,
+ missingThreadCount: 1,
+ coverageScope: ["thread:second", "thread:missing", "worker-attempt:second"],
+ warnings: ["turn_in_progress", "cost_estimate_covers_earlier_usage"],
+ };
+ const combined = combineMeasurements(
+ [first, second],
+ "synthetic-unpriced-model",
+ );
+ expect(combined.coverageScope).toEqual([
+ "thread:first",
+ "thread:missing",
+ "thread:second",
+ "worker-attempt:first",
+ "worker-attempt:second",
+ ]);
+ expect(measuredScanCost(combined)?.usage.warnings).toEqual([
+ "cost_estimate_covers_earlier_usage",
+ "turn_in_progress",
+ ]);
+ expect(combined.coverage).toBe("partial");
+ expect(combined.usage?.total_tokens).toBe(24);
+ expect(
+ combineMeasurements(
+ [first, measurementFromUsage(usage, "synthetic-unpriced-model")],
+ "synthetic-unpriced-model",
+ ),
+ ).not.toHaveProperty("coverageScope");
+});
diff --git a/sdk/typescript/tests-ts/scan-resume.test.ts b/sdk/typescript/tests-ts/scan-resume.test.ts
index fbe6a2710..bc1b0b85c 100644
--- a/sdk/typescript/tests-ts/scan-resume.test.ts
+++ b/sdk/typescript/tests-ts/scan-resume.test.ts
@@ -27,6 +27,10 @@ import { runWorkbench } from "../src/runtime.js";
import { readKnowledgeBaseSnapshot } from "../src/knowledge-base.js";
import { saveScanKnowledge, scanInputIdentity } from "../src/scan-inputs.js";
import { workflowDigest } from "../src/finding-workflow.js";
+import {
+ OperationTelemetry,
+ readOperationTelemetry,
+} from "../src/operation-telemetry.js";
import { capture, dependencies } from "./cli-fixtures.js";
import { runPython } from "./support/python-probe.js";
import { copyCompletedScanFixture, PLUGIN_ROOT } from "./plugin-root.js";
@@ -734,6 +738,9 @@ function resumeDependencies(
ConstructorParameters<typeof TestClient>[1]["createCodex"]
>,
runtimeOverrides: Partial<ReturnType<typeof preparedRuntime>> = {},
+ createOperationTelemetry?: ConstructorParameters<
+ typeof TestClient
+ >[1]["createOperationTelemetry"],
) {
return {
...dependencies({ environment: f.environment, currentDirectory: f.root }),
@@ -763,6 +770,9 @@ function resumeDependencies(
resolvePluginPython: async () => f.python,
runWorkbench,
createCodex,
+ ...(createOperationTelemetry === undefined
+ ? {}
+ : { createOperationTelemetry }),
}),
};
}
@@ -811,6 +821,137 @@ async function finishDiscovery(f: Awaited<ReturnType<typeof interruptedScan>>) {
]);
}
+test.each(["completed", "failed"] as const)(
+ "bulk recovery retains original correlation and unpriced usage after %s without a ledger",
+ async (outcome) => {
+ const f = await interruptedScan("deep", true, {
+ config: { model: "synthetic-unpriced-model", approval_policy: "never" },
+ });
+ await rm(join(f.root, "results.jsonl"));
+ const original = new OperationTelemetry({
+ directory: f.environment.CODEX_SECURITY_STATE_DIR,
+ protectedRepository: f.repository,
+ protectedOutput: f.scanDir,
+ command: "scan",
+ surface: "cli",
+ mode: "deep",
+ });
+ await original.start();
+ await original.bindScan(f.scanId);
+ const { stdout, stderr, runCli } = createCliTest(main);
+ let resumed = 0;
+ const code = await runCli(
+ ["bulk-scan", f.input, "--output-dir", f.root, "--recover", "--json"],
+ resumeDependencies(
+ f,
+ () => ({
+ startThread: () => fail("Unexpected new session"),
+ resumeThread(threadId) {
+ expect(threadId).toBe(f.threadId);
+ resumed++;
+ return {
+ id: threadId,
+ async runStreamed() {
+ await appendFile(
+ f.sessionPath,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: {
+ input_tokens: 10000,
+ output_tokens: 2000,
+ },
+ },
+ },
+ }) + "\n",
+ );
+ if (outcome === "failed")
+ throw new Error("Synthetic resumed failure");
+ await finishDiscovery(f);
+ return { events: completedEvents(threadId) };
+ },
+ };
+ },
+ }),
+ {},
+ (options) => new OperationTelemetry(options),
+ ),
+ );
+ expect(code, stderr.text()).toBe(outcome === "completed" ? 0 : 2);
+ expect(resumed).toBe(1);
+ const result = JSON.parse(stdout.text());
+ const receipts = await readJsonLines(result.resultsPath);
+ expect(receipts).toHaveLength(1);
+ const { events } = await readOperationTelemetry(
+ f.environment.CODEX_SECURITY_STATE_DIR,
+ );
+ const starts = events.filter((event) => event.type === "attempt_started");
+ expect(starts).toHaveLength(2);
+ expect(new Set(starts.map((event) => event.attemptId)).size).toBe(2);
+ expect(
+ starts.every((event) => event.operationId === original.operationId),
+ ).toBe(true);
+ const terminal = events.find((event) => event.type === "attempt_finished");
+ expect(terminal).toMatchObject({
+ operationId: original.operationId,
+ outcome,
+ resumed: true,
+ measurement: {
+ cost: null,
+ usage: {
+ input_tokens: 10000,
+ output_tokens: 2000,
+ total_tokens: 12000,
+ },
+ },
+ });
+ expect(receipts[0]).toMatchObject({
+ attempt: 1,
+ status: outcome,
+ operationId: original.operationId,
+ measurement: terminal!.measurement,
+ });
+ expect(receipts[0]).not.toHaveProperty("cost");
+ if (outcome === "completed") {
+ const saved = (await f.command(["get-scan", "--scan-id", f.scanId]))[
+ "scan"
+ ] as JsonObject;
+ expect(saved["usage"]).toMatchObject({
+ coverage: "complete",
+ totalTokens: 12000,
+ });
+ expect(saved).not.toHaveProperty("cost");
+ await rm(result.resultsPath);
+ const recovered = createCliTest(main);
+ expect(
+ await recovered.runCli(
+ ["bulk-scan", f.input, "--output-dir", f.root, "--recover", "--json"],
+ {
+ ...dependencies({
+ environment: f.environment,
+ currentDirectory: f.root,
+ onRun: () => fail("A sealed scan needs no Codex invocation"),
+ }),
+ runWorkbench: f.command,
+ },
+ ),
+ recovered.stderr.text(),
+ ).toBe(0);
+ const restored = await readJsonLines(result.resultsPath);
+ expect(restored).toHaveLength(1);
+ expect(restored[0]!["usage"]).toEqual(saved["usage"]);
+ for (const key of ["cost", "measurement", "operationId"])
+ expect(restored[0]).not.toHaveProperty(key);
+ expect(
+ (await readOperationTelemetry(f.environment.CODEX_SECURITY_STATE_DIR))
+ .events,
+ ).toEqual(events);
+ }
+ },
+);
+
test.each([false, true])(
"resumed CLI starts with terminal Deep progress (interactive=%p)",
async (interactive) => {
@@ -956,6 +1097,7 @@ test.each([
attempt: 1,
cost: { inputTokens: 10000, outputTokens: 2000 },
});
+ expect(reconciled[1]).not.toHaveProperty("operationId");
// A subsequent bulk recovery must skip the reconciled completion.
const nextOutput = capture();
expect(
diff --git a/sdk/typescript/tests-ts/session-lines.test.ts b/sdk/typescript/tests-ts/session-lines.test.ts
new file mode 100644
index 000000000..8e5f1572f
--- /dev/null
+++ b/sdk/typescript/tests-ts/session-lines.test.ts
@@ -0,0 +1,89 @@
+import { afterEach, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import zlib from "node:zlib";
+import { sessionLines } from "../src/session-lines.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import { PLUGIN_ROOT } from "./plugin-root.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures("session-lines-");
+afterEach(cleanup);
+
+// Native level-3 frame, also usable on Node versions without a compressor.
+const frame = Buffer.from(
+ "KLUv/SA2sQEAeyJ0eXBlIjoic2Vzc2lvbl9tZXRhIiwicGF5bG9hZCI6eyJpZCI6ImNvbXByZXNzZWQifX0K",
+ "base64",
+);
+const line = '{"type":"session_meta","payload":{"id":"compressed"}}';
+
+async function withoutNativeZstd(run: () => Promise<void>): Promise<void> {
+ const original = Object.getOwnPropertyDescriptor(
+ zlib,
+ "createZstdDecompress",
+ );
+ Object.defineProperty(zlib, "createZstdDecompress", {
+ value: undefined,
+ configurable: true,
+ });
+ try {
+ await run();
+ } finally {
+ if (original) Object.defineProperty(zlib, "createZstdDecompress", original);
+ else Reflect.deleteProperty(zlib, "createZstdDecompress");
+ }
+}
+
+test("portable decoder reads concatenated native frames and rejects truncated input", async () => {
+ const path = join(await temporaryDirectory(), "rollout.jsonl.zst");
+ await withoutNativeZstd(async () => {
+ await writeFile(path, Buffer.concat([frame, frame]));
+ expect(await Array.fromAsync(sessionLines(path))).toEqual([line, line]);
+ await writeFile(path, frame.subarray(0, frame.length - 3));
+ await expect(Array.fromAsync(sessionLines(path))).rejects.toThrow();
+ });
+});
+
+test("bundled Python reader helper works without native Zstandard", async () => {
+ const path = join(await temporaryDirectory(), "rollout.jsonl.zst");
+ await writeFile(path, frame);
+ const output = execFileSync(
+ "node",
+ [
+ "--input-type=module",
+ "--eval",
+ `import zlib from "node:zlib";
+import { pathToFileURL } from "node:url";
+Object.defineProperty(zlib, "createZstdDecompress", { value: undefined });
+const [helper, rollout] = process.argv.slice(1);
+process.argv = [process.execPath, helper, rollout];
+await import(pathToFileURL(helper).href);`,
+ join(PLUGIN_ROOT, "scripts", "read_codex_session.mjs"),
+ path,
+ ],
+ { encoding: "utf8" },
+ );
+ expect(output).toBe(`${line}\n`);
+});
+
+test.skipIf(typeof zlib.zstdCompressSync !== "function")(
+ "portable decoder streams native level-3 rollouts larger than 32 MiB",
+ async () => {
+ const path = join(await temporaryDirectory(), "large.jsonl.zst");
+ const repetitions = Math.ceil((33 * 1024 * 1024) / (line.length + 1));
+ await writeFile(
+ path,
+ zlib.zstdCompressSync(Buffer.from(`${line}\n`.repeat(repetitions))),
+ );
+ await withoutNativeZstd(async () => {
+ let count = 0;
+ let bytes = 0;
+ for await (const value of sessionLines(path)) {
+ count += 1;
+ bytes += value.length + 1;
+ }
+ expect(count).toBe(repetitions);
+ expect(bytes).toBe(repetitions * (line.length + 1));
+ });
+ },
+);
diff --git a/sdk/typescript/tests-ts/support/api-client.ts b/sdk/typescript/tests-ts/support/api-client.ts
index d67c080f4..a08fa252d 100644
--- a/sdk/typescript/tests-ts/support/api-client.ts
+++ b/sdk/typescript/tests-ts/support/api-client.ts
@@ -177,6 +177,7 @@ export class TestClient extends CodexSecurity {
withSyntheticScanEvents({
createCodex: throwing("Unexpected Codex invocation in test"),
environment: {},
+ createOperationTelemetry: () => null,
probeCodexSandbox: async () => {},
prepareScanArtifactRestorer: async () => ({
restore: async () => {},
diff --git a/sdk/typescript/tests-ts/support/validation.ts b/sdk/typescript/tests-ts/support/validation.ts
index 57855354a..dab241ef4 100644
--- a/sdk/typescript/tests-ts/support/validation.ts
+++ b/sdk/typescript/tests-ts/support/validation.ts
@@ -1,3 +1,4 @@
+import { OperationTelemetry } from "../../src/operation-telemetry.js";
import { mkdir } from "node:fs/promises";
import * as fsPromises from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -122,6 +123,7 @@ export function createValidationFixtures() {
const root = fixtureRoot ?? (await temporaryDirectory());
const repository = join(root, "repository");
const codexHome = await temporaryDirectory();
+ let telemetryEnabled = false;
const stateDirectory =
environmentOverrides["CODEX_SECURITY_STATE_DIR"] ?? join(root, "state");
await mkdir(repository, { recursive: true });
@@ -163,6 +165,8 @@ export function createValidationFixtures() {
},
{
environment,
+ createOperationTelemetry: (options) =>
+ telemetryEnabled ? new OperationTelemetry(options) : null,
prepareRuntime: runtimePreparer(codexHome, () => ({
plugin: { ...preparedRuntime(codexHome).plugin, pluginRoot },
environment,
@@ -200,6 +204,9 @@ export function createValidationFixtures() {
workbench,
root,
codexHome,
+ enableTelemetry() {
+ telemetryEnabled = true;
+ },
};
}
diff --git a/sdk/typescript/tests-ts/workbench-arguments.test.ts b/sdk/typescript/tests-ts/workbench-arguments.test.ts
index 77fc64fcc..c61e8c12d 100644
--- a/sdk/typescript/tests-ts/workbench-arguments.test.ts
+++ b/sdk/typescript/tests-ts/workbench-arguments.test.ts
@@ -1,5 +1,18 @@
-import { expect, test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, expect, test } from "bun:test";
+import { resolvePluginPython } from "../src/runtime.js";
import { workbenchArgs } from "../src/workbench-arguments.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+import {
+ scanRegistrationArguments,
+ workbenchCommand,
+} from "./support/workbench-command.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "workbench-arguments-",
+);
+afterEach(cleanup);
test("workbench arguments preserve field order, values, and repeated flags", () => {
expect(
@@ -34,3 +47,62 @@ test("workbench arguments preserve field order, values, and repeated flags", ()
"worker-2",
]);
});
+
+test.each(["fail-scan", "cancel-scan"])(
+ "persists large worker coverage through %s at the process boundary",
+ async (command) => {
+ const root = await temporaryDirectory();
+ const repository = join(root, "repository");
+ const scanDirectory = join(root, "scan");
+ await mkdir(repository);
+ await mkdir(scanDirectory, { mode: 0o700 });
+ const workbench = workbenchCommand(await resolvePluginPython(), () => ({
+ PATH: process.env["PATH"],
+ CODEX_SECURITY_STATE_DIR: join(root, "state"),
+ CODEX_HOME: join(root, "codex-home"),
+ CODEX_SQLITE_HOME: join(root, "codex-sqlite"),
+ CODEX_STATE_DB: "",
+ }));
+ const registration = await workbench(
+ scanRegistrationArguments(repository, scanDirectory),
+ );
+ const coverageScope = Array.from({ length: 1600 }, (_, index) => {
+ const suffix = String(index).padStart(12, "0");
+ return [
+ `thread:00000000-0000-4000-8000-${suffix}`,
+ `worker-attempt:10000000-0000-4000-8000-${suffix}`,
+ ];
+ }).flat();
+ const usage = {
+ source: "codex_runtime",
+ coverage: "partial",
+ coverageScope,
+ threadCount: 1600,
+ missingThreadCount: 1,
+ cacheWriteInputTokensReported: false,
+ inputTokens: 40,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: 5,
+ reasoningOutputTokens: 0,
+ totalTokens: 45,
+ };
+ const payload = JSON.stringify({ usage });
+ // A realistic Deep Scan scope can exceed Linux's per-argument byte limit.
+ expect(Buffer.byteLength(payload)).toBeGreaterThan(128 * 1024);
+ const scanId = String(registration["scanId"]);
+ await workbench([
+ command,
+ "--scan-id",
+ scanId,
+ ...(command === "fail-scan" ? ["--message=Synthetic failure."] : []),
+ "--cost-json",
+ payload,
+ ]);
+ const stored = await workbench(["get-scan", "--scan-id", scanId]);
+ expect(stored["scan"]).toMatchObject({
+ progress: { status: command === "fail-scan" ? "failed" : "canceled" },
+ usage,
+ });
+ },
+);
diff --git a/sdk/typescript/tests-ts/workbench-compressed-usage.test.ts b/sdk/typescript/tests-ts/workbench-compressed-usage.test.ts
new file mode 100644
index 000000000..a263dfcf8
--- /dev/null
+++ b/sdk/typescript/tests-ts/workbench-compressed-usage.test.ts
@@ -0,0 +1,259 @@
+import { afterEach, expect, test } from "bun:test";
+import { build } from "esbuild";
+import { execFileSync } from "node:child_process";
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pythonExecutable } from "./support/python.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+
+const { temporaryDirectory, cleanup } = createApiTestFixtures(
+ "workbench-compressed-usage-",
+);
+afterEach(cleanup);
+
+const sourcePlugin = fileURLToPath(
+ new URL("../../../plugins/codex-security/", import.meta.url),
+);
+
+// Native level-3 frames keep these integration cases available on Node 22.13,
+// which has no compressor. The first two frames report cumulative 12 then 34.
+const firstFrame = Buffer.from(
+ "KLUv/WBoAP0FAOLLIx1wp9UB1jFCE/GD0iiS1GouFgZXn8F8ajAPQAM9JkSMMZ5i0uGYS1VHXM7C/DLEICXjA0stF1Mg68Ln2A+lMBnU5qaAYy5eB3Mld4LcQ1ta94KfhIjR6wc38hcCU10cUCBjAApDKAyhcMwx8mtq9Y2ti42rHnktl5EN5gTZUGk4qOditW/JJVO9GvnvsE4CEQB4BKBhOOxn96XiBlC+dhIAT6kAapxW/0yReiGCZpZh8h7GAax3Vt2PgTMD",
+ "base64",
+);
+const laterFrame = Buffer.from(
+ "KLUv/SD/zQQA8kgdHmA1bgPwywwJHq2g6RyLxSJlTFGwGID4zQMiAIZcDoL33jsQKmXXckttjo52rL2aAaUSBUASOcJBemvHdv1JVyWbU0s282HX0XsdI2o1gPtJT5IXJ9nRlcaoXhXQpytz+ugGIyEWCiQKJAgGGk9nTHZTZvWfDAB4BKBhOOxn96XiBlC+dhIAT6ngxOrnaEDdoKCIYODy",
+ "base64",
+);
+const workerFrames = {
+ first:
+ "KLUv/WBuADUGADJMJR5gZ9sGBqGhvdpM+qNbLXaX7jcEObew2na8jABwIXjFe+8hB5PCFltObT9Iu9VeDZFSogMq1Q8e6NyOYUuVZJcO2dtbYOvnzdyqxNSwrfCSmimBHk3x3pUW6NFVNbf8cwFEZIAQAwhoENAAOPA4OrNksy6rf97U0BZhNLdVOHqy3qAnuYdEMj/P1iWxXczKR1cm0W8CEQB4BKBhOOxn96XiBlC+dhIAT6kAapxW/0zxeiGCZlZi8irGIav12lWPyMtFAQ==",
+ child:
+ "KLUv/WBvAQUIAOKOKx5gR9wGQQuHRBuJ4LvoY7FlzhiCXM3Jv4oDEQAeCRiEw+HZuTRmlyGQzgcpRJkuY7ofo99mM9copI5MFq6fgHTu15QhyE8t2NtbUPbz1rdLaSprnFD3sh02K4WxEWYM0kA4nGh2rKBa02HTBhurA9Ml3ZoIFjzO5d7yzwmKhNBAgYgCEQAGMp7eGGxOhvXPj4Uli3CpuG2efrAb0g/c5QDbz7GTUbqMOfnp2Q76hh8AgynE7UMYhsN+dl8qbgDlC2TXTvlxUK/QRn6w1D9rA3ToQGxmSfcFyGPG0lwPmoWkyaCCIdPckA6E8YXpwHJDAzrdzNz0Wk6E9cjVnQE=",
+ boundary:
+ "KLUv/WB0AFUGAJJMJh9gSdsGCHYYtH22+2PTLPZb5n+KgmUM2I0hUBHkEjgBhffew2MwIbuWWyq7wdOOtRdDpHTogUp1g3jQWztllyLZXDpkc7PBrpv3OlZp1cCNtCT1KoIaicJ7V5qgR1fFHLebEyAGACDEgYPFwULAQOPoSpLdNFl9c6YGxohiYXms44KjH+sJ9CP5sKRy82xN0vJqTdvRVVn6iREAegTgYTgMqE5JxQ2gfO0kgJ6yAnw47fsZSPaCBc1WxaRgjK+sVmFXPSgvFwU=",
+};
+
+async function fixture() {
+ const root = await temporaryDirectory();
+ const plugin = join(root, "plugin");
+ const paths = [
+ "scripts/workbench_scan_usage.py",
+ "scripts/windows_scan_local_files.py",
+ "scripts/read_codex_session.mjs",
+ "scripts/workbench/__init__.py",
+ "scripts/workbench/storage.py",
+ ];
+ for (const path of paths) {
+ await mkdir(dirname(join(plugin, path)), { recursive: true });
+ await copyFile(join(sourcePlugin, path), join(plugin, path));
+ }
+ await build({
+ entryPoints: [join(sourcePlugin, "mcp-app/src/session-decompression.ts")],
+ outfile: join(plugin, "mcp/session-decompression.mjs"),
+ bundle: true,
+ platform: "node",
+ format: "esm",
+ });
+ return { root, plugin };
+}
+
+function collect(
+ root: string,
+ plugin: string,
+ options: {
+ owner: string;
+ workerKind?: "discovery" | "dedup";
+ threads: Array<{
+ id: string;
+ path: string;
+ cwd?: string;
+ createdAt?: number;
+ }>;
+ edges?: string[][];
+ },
+) {
+ const python = pythonExecutable();
+ const node = Bun.which("node");
+ expect(python).not.toBeNull();
+ expect(node).not.toBeNull();
+ const script = `
+import json, os, sqlite3, sys
+from pathlib import Path
+sys.path.insert(0, str(Path(sys.argv[1]) / "scripts"))
+from workbench_scan_usage import collect_scan_usage
+root = Path(sys.argv[2])
+options = json.loads(sys.argv[3])
+with sqlite3.connect(os.environ["CODEX_STATE_DB"]) as native:
+ native.execute("CREATE TABLE threads (id TEXT PRIMARY KEY, rollout_path TEXT, cwd TEXT, created_at INTEGER)")
+ native.execute("CREATE TABLE thread_spawn_edges (parent_thread_id TEXT, child_thread_id TEXT)")
+ native.executemany("INSERT INTO threads VALUES (?, ?, ?, ?)", [(t["id"], t["path"], t.get("cwd"), t.get("createdAt")) for t in options["threads"]])
+ native.executemany("INSERT INTO thread_spawn_edges VALUES (?, ?)", options.get("edges", []))
+with sqlite3.connect(":memory:") as db:
+ db.row_factory = sqlite3.Row
+ db.execute("CREATE TABLE workspaces (id TEXT, thread_id TEXT)")
+ db.execute("INSERT INTO workspaces VALUES ('workspace', ?)", (options["owner"],))
+ db.execute("CREATE TABLE deep_scan_worker_threads (scan_id TEXT, sdk_thread_id TEXT)")
+ db.execute("CREATE TABLE deep_scan_runs (scan_id TEXT, worker_usage_gap INTEGER)")
+ db.execute("CREATE TABLE deep_scan_workers (scan_id TEXT, kind TEXT, artifact_dir TEXT, started_at TEXT, sdk_thread_id TEXT, attempt INTEGER)")
+ mode = "deep" if options.get("workerKind") else "standard"
+ if mode == "deep":
+ db.execute("INSERT INTO deep_scan_runs VALUES ('scan', 0)")
+ db.execute("INSERT INTO deep_scan_workers VALUES ('scan', ?, ?, '2026-01-01T00:00:01Z', 'current-worker', 2)", (options["workerKind"], str(root / "artifacts" / "worker")))
+ db.execute("INSERT INTO deep_scan_worker_threads VALUES ('scan', 'current-worker')")
+ scan = db.execute("SELECT 'scan' AS id, 'workspace' AS workspace_id, ? AS mode, ? AS scan_dir, '2026-01-01T00:00:00.500123Z' AS started_at, '2026-01-01T00:00:05Z' AS completed_at, NULL AS deep_scan_owner_thread_id", (mode, str(root))).fetchone()
+ print(json.dumps(collect_scan_usage(db, scan)))
+`;
+ return JSON.parse(
+ execFileSync(
+ python!,
+ ["-I", "-B", "-c", script, plugin, root, JSON.stringify(options)],
+ {
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ CODEX_STATE_DB: join(root, "native.sqlite"),
+ CODEX_HOME: join(root, "home"),
+ CODEX_SECURITY_STATE_DIR: join(root, "state"),
+ CODEX_MCP_NODE_PATH: node!,
+ },
+ },
+ ),
+ );
+}
+
+test.each([
+ ["single", firstFrame, 12],
+ ["concatenated", Buffer.concat([firstFrame, laterFrame]), 34],
+ ["truncated first", firstFrame.subarray(0, -3), null],
+ [
+ "truncated later",
+ Buffer.concat([firstFrame, laterFrame.subarray(0, -3)]),
+ null,
+ ],
+] as const)(
+ "Python collector reads %s Zstandard frames",
+ async (_kind, contents, total) => {
+ const { root, plugin } = await fixture();
+ const path = join(root, "compressed.jsonl.zst");
+ await writeFile(path, contents);
+ const usage = collect(root, plugin, {
+ owner: "compressed",
+ threads: [{ id: "compressed", path }],
+ });
+ if (total === null) {
+ expect(usage.coverage).toBe("unavailable");
+ expect(usage.warnings).toContain("rollout_unavailable");
+ expect(usage).not.toHaveProperty("totalTokens");
+ } else {
+ expect(usage).toMatchObject({
+ coverage: "complete",
+ inputTokens: total === 12 ? 10 : 30,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: total === 12 ? 2 : 4,
+ reasoningOutputTokens: 0,
+ totalTokens: total,
+ threadCount: 1,
+ });
+ }
+ },
+);
+
+test.each(["discovery", "dedup"] as const)(
+ "Python collector discovers compressed replaced %s workers by cwd",
+ async (workerKind) => {
+ const { root, plugin } = await fixture();
+ const cwd =
+ workerKind === "discovery"
+ ? join(root, "artifacts", "worker")
+ : join(root, "artifacts");
+ const threads: Parameters<typeof collect>[2]["threads"] = [];
+ for (const [id, frame] of [
+ ["first-worker", workerFrames.first],
+ ["worker-child", workerFrames.child],
+ ["boundary-worker", workerFrames.boundary],
+ ] as const) {
+ const path = join(root, `${id}.jsonl.zst`);
+ await writeFile(path, Buffer.from(frame, "base64"));
+ threads.push({ id, path, cwd, createdAt: 1767225600 });
+ }
+ for (const [id, input, output, counts, createdAt] of [
+ ["scan-parent", 10, 3, 1, 1767225600],
+ ["current-worker", 30, 8, 2, 1767139200],
+ ["other-worker", 80000, 20000, 1, 1767225600],
+ ["archived-worker", 100, 10, 1, 1767139200],
+ ["later-worker", 100, 10, 1, 1767312000],
+ ] as const) {
+ const path = join(root, `${id}.jsonl`);
+ const token = (input: number, output: number) => ({
+ timestamp: "2026-01-01T00:00:02Z",
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: {
+ input_tokens: input,
+ cached_input_tokens: 0,
+ cache_write_input_tokens: 0,
+ output_tokens: output,
+ reasoning_output_tokens: 0,
+ total_tokens: input + output,
+ },
+ },
+ },
+ });
+ await writeFile(
+ path,
+ [
+ {
+ type: "session_meta",
+ payload: { id, timestamp: "2025-12-31T00:00:00Z", source: "exec" },
+ },
+ ...(counts === 2 ? [token(20, 5)] : []),
+ token(input, output),
+ ]
+ .map((record) => `${JSON.stringify(record)}\n`)
+ .join(""),
+ );
+ threads.push({
+ id,
+ path,
+ cwd: id === "other-worker" ? join(root, "other-scan") : cwd,
+ createdAt,
+ });
+ }
+ for (const [id, createdAt] of [
+ ["boundary-child", 1767225600],
+ ["archived-missing", 1767139200],
+ ["later-missing", 1767312000],
+ ] as const)
+ threads.push({
+ id,
+ path: join(root, `${id}.jsonl`),
+ cwd: id === "boundary-child" ? undefined : cwd,
+ createdAt,
+ });
+ const usage = collect(root, plugin, {
+ owner: "scan-parent",
+ workerKind,
+ threads,
+ edges: [
+ ["first-worker", "worker-child"],
+ ["boundary-worker", "boundary-child"],
+ ],
+ });
+ expect(usage).toMatchObject({
+ coverage: "complete",
+ source: "codex_rollout",
+ inputTokens: 67,
+ cachedInputTokens: 0,
+ cacheWriteInputTokens: 0,
+ outputTokens: 18,
+ reasoningOutputTokens: 0,
+ totalTokens: 85,
+ threadCount: 4,
+ });
+ },
+);
diff --git a/sdk/typescript/tests-ts/workbench-node-runtime.test.ts b/sdk/typescript/tests-ts/workbench-node-runtime.test.ts
new file mode 100644
index 000000000..7859bb9dd
--- /dev/null
+++ b/sdk/typescript/tests-ts/workbench-node-runtime.test.ts
@@ -0,0 +1,80 @@
+import { afterEach, expect, test } from "bun:test";
+import { build } from "esbuild";
+import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { PLUGIN_ROOT } from "./plugin-root.js";
+import { pythonExecutable } from "./support/python.js";
+import { createApiTestFixtures } from "./support/temporary-directories.js";
+
+const { temporaryDirectory, cleanup } =
+ createApiTestFixtures("workbench-node-");
+afterEach(cleanup);
+
+test("SDK workbench forwards Node to compressed reads without PATH and preserves an explicit runtime", async () => {
+ const root = await temporaryDirectory();
+ const scripts = join(root, "scripts");
+ await mkdir(scripts);
+ const rollout = join(root, "rollout.jsonl.zst");
+ await writeFile(
+ rollout,
+ Buffer.from(
+ "KLUv/SA2sQEAeyJ0eXBlIjoic2Vzc2lvbl9tZXRhIiwicGF5bG9hZCI6eyJpZCI6ImNvbXByZXNzZWQifX0K",
+ "base64",
+ ),
+ );
+ await writeFile(
+ join(scripts, "workbench_db.py"),
+ `import json, os, sys
+from pathlib import Path
+sys.path.insert(0, ${JSON.stringify(join(PLUGIN_ROOT, "scripts"))})
+from workbench_scan_usage import _rollout_lines
+with _rollout_lines(Path(sys.argv[1])) as source:
+ contents = b"".join(source).decode("utf-8")
+print(json.dumps({"contents": contents, "node": os.environ["CODEX_MCP_NODE_PATH"]}))
+`,
+ );
+ const runtimeSource = new URL("../src/runtime.ts", import.meta.url);
+ const runtimeModule = join(root, "runtime.cjs");
+ await build({
+ entryPoints: [fileURLToPath(runtimeSource)],
+ outfile: runtimeModule,
+ bundle: true,
+ platform: "node",
+ format: "cjs",
+ define: { "import.meta.url": JSON.stringify(runtimeSource.href) },
+ });
+ const node = Bun.which("node");
+ const python = pythonExecutable();
+ expect(node).not.toBeNull();
+ expect(python).not.toBeNull();
+ const script = `
+const { runWorkbench } = require(process.argv[1]);
+const [python, pluginRoot, rollout, selected] = process.argv.slice(2);
+const environment = { ...process.env, PATH: "" };
+for (const name of Object.keys(environment))
+ if (name.toUpperCase() === "CODEX_MCP_NODE_PATH") delete environment[name];
+if (selected) environment.CODEX_MCP_NODE_PATH = selected;
+runWorkbench({ python, pluginRoot, environment }, [rollout])
+ .then((result) => process.stdout.write(JSON.stringify({ result, selected: environment.CODEX_MCP_NODE_PATH, node: process.execPath })),
+ (error) => { console.error(error); process.exitCode = 1; });
+`;
+ for (const selected of [
+ "",
+ `${dirname(node!)}${sep}.${sep}${basename(node!)}`,
+ ]) {
+ const { stdout } = await promisify(execFile)(
+ node!,
+ ["--eval", script, runtimeModule, python!, root, rollout, selected],
+ { encoding: "utf8", windowsHide: true },
+ );
+ const observed = JSON.parse(stdout);
+ expect(observed.result).toEqual({
+ contents: '{"type":"session_meta","payload":{"id":"compressed"}}\n',
+ node: selected || observed.node,
+ });
+ expect(observed.selected).toBe(selected || undefined);
+ }
+});