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(cli): refresh scan progress from saved state (#1757)

Michael D'Angelo0534445ac4ec
diff --git a/sdk/typescript/docs/hosted-scans.md b/sdk/typescript/docs/hosted-scans.md
index 88d02b382..f675f6c35 100644
--- a/sdk/typescript/docs/hosted-scans.md
+++ b/sdk/typescript/docs/hosted-scans.md
@@ -73,9 +73,11 @@ local profiles and other local scan options are not accepted.
`ScanExecutor.run` receives an AbortSignal and an optional `onEvent` observer for
`{type: "progress", progress}` or `{type: "activity", activity}` events. Progress
-uses the existing `ScanProgress` type; activity uses `ScanActivity`. Observer
-failures cannot stop execution. Aborting waits for the executor to settle; the
-host must cancel remote work and return its recorded outcome.
+uses the existing `ScanProgress` type; activity uses `ScanActivity`. Progress may
+include `reviewItems: { completed, total }` for saved reviews, counted separately
+from files. Observer failures cannot stop execution. Aborting waits for the
+executor to settle; the host must cancel remote work and return its recorded
+outcome.
Preparation errors throw before execution. Execution and finalization return a
`HostedScanResult` receipt with status `completed`, `failed`,
diff --git a/sdk/typescript/scripts/package-dist-files.mjs b/sdk/typescript/scripts/package-dist-files.mjs
index 13e0346a4..93d72a878 100644
--- a/sdk/typescript/scripts/package-dist-files.mjs
+++ b/sdk/typescript/scripts/package-dist-files.mjs
@@ -31,7 +31,7 @@ const distModules = [
"custom-validation",
"custom-validation-prompt",
"custom-publish",
- "deep-progress",
+ "scan-progress",
"deep-scan",
"deep-config",
"deep-scan-defaults",
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 28ced1b2b..7f2e8029d 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -95,10 +95,7 @@ import {
type ScanWorkerEvent,
} from "./cost.js";
import type { ScanTokenUsage } from "./cost-model.js";
-import {
- DeepScanProgressTracker,
- type DeepScanProgress,
-} from "./deep-progress.js";
+import { ScanProgressTracker, type DeepScanProgress } from "./scan-progress.js";
import { findScanSession } from "./scan-logs.js";
import { runDeepScan } from "./deep-scan.js";
import {
@@ -195,6 +192,7 @@ import {
} from "./scan-comparison.js";
import {
scanProgressUpdatesFromEvent,
+ scanPhaseSchema,
workerStatusFromEvent,
type ScanProgress,
type ScanWorkerStatus,
@@ -1606,7 +1604,7 @@ export class CodexSecurity {
let targetPathsFile: string | null = null;
let knowledgeBase: PreparedKnowledgeBase | null = null;
let costTracker: ScanCostTracker | null = null;
- let deepProgressTracker: DeepScanProgressTracker | null = null;
+ let scanProgressTracker: ScanProgressTracker | null = null;
let artifactRestorationFailure: OutputDirectoryError | null = null;
let customValidationComplete = false;
let completionCost: ScanCost | null = null;
@@ -1946,6 +1944,8 @@ export class CodexSecurity {
}
let scopeFileCount: number | null = null;
let reviewedFileCount = 0;
+ let latestPhase: ScanProgress["phase"] = "preflight";
+ let reviewItems: ScanProgress["reviewItems"];
const reportProgress = (progress: ScanProgress): void => {
if (
scopeFileCount === null ||
@@ -1955,10 +1955,37 @@ export class CodexSecurity {
return;
}
reviewedFileCount = progress.filesCompleted;
+ if (
+ mode === "deep" ||
+ scanPhaseSchema.options.indexOf(progress.phase) >
+ scanPhaseSchema.options.indexOf(latestPhase)
+ ) {
+ latestPhase = progress.phase;
+ }
notifyObserver(
options,
"onProgress",
- )({ ...progress, filesTotal: scopeFileCount });
+ )({
+ ...progress,
+ phase: latestPhase,
+ filesTotal: scopeFileCount,
+ ...(reviewItems === undefined ? {} : { reviewItems }),
+ });
+ };
+ const reportWorkerStatus = (status: ScanWorkerStatus): void => {
+ if (mode !== "deep") {
+ const phase =
+ status.phase === "ranking" || status.phase === "file_review"
+ ? "discovery"
+ : status.phase;
+ if (
+ scanPhaseSchema.options.indexOf(phase) <
+ scanPhaseSchema.options.indexOf(latestPhase)
+ )
+ return;
+ latestPhase = phase;
+ }
+ notifyObserver(options, "onWorkerStatus")(status);
};
const reportedInaccessibleSessionLogs = new Set<string>();
const reportTrackingError = (error: unknown): void => {
@@ -2004,7 +2031,14 @@ export class CodexSecurity {
? undefined
: (event) => notifyObserver(options, "onSessionEvent")(event),
onProgress:
- options.onProgress === undefined ? undefined : reportProgress,
+ options.onProgress === undefined
+ ? undefined
+ : (progress) =>
+ reportProgress({
+ ...progress,
+ // Worker counts belong to the parent scan's current phase.
+ phase: mode === "deep" ? progress.phase : latestPhase,
+ }),
onCost:
options.onCost === undefined && options.maxCostUsd === undefined
? undefined
@@ -2275,9 +2309,13 @@ export class CodexSecurity {
notifyObserver(options, "onOutputDirReady")(scanDir);
}
throwIfAborted(signal, scanDir);
- if (mode === "deep" && options.onDeepProgress !== undefined) {
+ if (
+ this.#dependencies.hostedScan === undefined &&
+ ((mode !== "deep" && options.onProgress !== undefined) ||
+ (mode === "deep" && options.onDeepProgress !== undefined))
+ ) {
let progressWarningReported = false;
- deepProgressTracker = new DeepScanProgressTracker({
+ scanProgressTracker = new ScanProgressTracker({
read: (progressSignal) =>
workbench(
{
@@ -2286,18 +2324,39 @@ export class CodexSecurity {
},
workbenchArgs("get-scan", { scanId }),
),
- onProgress: (progress) =>
- notifyObserver(options, "onDeepProgress")(progress),
+ onProgress:
+ mode === "deep"
+ ? undefined
+ : (progress) => {
+ reviewItems = progress.reviewItems;
+ if (scopeFileCount === null && progress.filesTotal !== null) {
+ scopeFileCount = progress.filesTotal;
+ tracker.setExpectedFilesTotal(scopeFileCount);
+ }
+ if (scopeFileCount === null) return;
+ reportProgress({
+ phase: progress.phase,
+ filesCompleted: reviewedFileCount,
+ filesTotal: scopeFileCount,
+ });
+ },
+ onDeepProgress:
+ mode === "deep"
+ ? (progress) =>
+ notifyObserver(options, "onDeepProgress")(progress)
+ : undefined,
onError: (error) => {
if (progressWarningReported) return;
progressWarningReported = true;
notifyObserver(
options,
"onWarning",
- )(`Could not track Deep Scan progress: ${errorMessage(error)}`);
+ )(
+ `Could not track ${mode === "deep" ? "Deep Scan" : "scan"} progress: ${errorMessage(error)}`,
+ );
},
});
- deepProgressTracker.start();
+ scanProgressTracker.start();
}
if (options.validationPrompt !== undefined) {
await writeCustomValidationStatus(
@@ -2568,6 +2627,9 @@ export class CodexSecurity {
falsePositives: falsePositiveExamples,
signal,
run: async (validationPrompt, outputSchema) => {
+ // This turn follows the primary scan's reporting phase.
+ scanProgressTracker?.stop();
+ latestPhase = "validation";
if (scopeFileCount !== null)
reportProgress({
phase: "validation",
@@ -2676,7 +2738,7 @@ export class CodexSecurity {
}
reportProgress(progress);
},
- onWorkerStatus: options.onWorkerStatus,
+ onWorkerStatus: reportWorkerStatus,
onWarning: options.onWarning,
onObserverError: options.onObserverError,
});
@@ -2728,6 +2790,7 @@ export class CodexSecurity {
}
}
}
+ scanProgressTracker?.stop();
if (runPostScan !== null) {
const followUp = runPostScan;
runPostScan = null;
@@ -3029,6 +3092,7 @@ export class CodexSecurity {
} catch {}
}
if (runPostScan !== null && !signal.aborted) {
+ scanProgressTracker?.stop();
try {
for await (const event of (await runPostScan()).events) {
if (event.type === "turn.failed") {
@@ -3055,7 +3119,7 @@ export class CodexSecurity {
throw failure;
} finally {
budgetAbortController.abort();
- deepProgressTracker?.stop();
+ scanProgressTracker?.stop();
// Temporary-input cleanup must not replace the scan's outcome.
try {
for (const cleanup of await Promise.allSettled([
diff --git a/sdk/typescript/src/cli.ts b/sdk/typescript/src/cli.ts
index a6894a1b4..c9bc7a736 100644
--- a/sdk/typescript/src/cli.ts
+++ b/sdk/typescript/src/cli.ts
@@ -96,7 +96,7 @@ import {
readCodexHomeConfig,
} from "./auth.js";
import { loadContract, sha256Text } from "./contract.js";
-import type { DeepScanProgress } from "./deep-progress.js";
+import type { DeepScanProgress } from "./scan-progress.js";
import { isRecord as isJsonObject } from "./record.js";
import { suggestOwnersInternal } from "./suggest-owners.js";
import { parseImportedFindings } from "./findings-import.js";
@@ -274,6 +274,7 @@ import {
import type { PatchSelection } from "./patch-tui.js";
import {
scanPhaseLabel as scanPhase,
+ scanProgressCount,
type ScanProgress,
type ScanWorkerStatus,
} from "./worker-progress.js";
@@ -8772,10 +8773,12 @@ async function executeScan(
details.push(
`Reviews: ${deepProgress.completed} completed, ${deepProgress.active} active, cap ${deepProgress.maximum}`,
);
- } else if (fileProgress !== null && fileProgress.filesTotal > 0) {
- details.push(
- `Files: ${fileProgress.filesCompleted.toLocaleString("en-US")}/${fileProgress.filesTotal.toLocaleString("en-US")}`,
- );
+ } else if (fileProgress !== null) {
+ const count = scanProgressCount(fileProgress);
+ if (count.total > 0)
+ details.push(
+ `${count.label === "reviews" ? "Reviews" : "Files"}: ${count.completed.toLocaleString("en-US")}/${count.total.toLocaleString("en-US")}`,
+ );
}
const tokens =
runningCost !== null
@@ -9008,7 +9011,7 @@ async function executeScan(
? dashboard?.recordDetails.bind(dashboard)
: undefined,
onProgress: (update) => {
- const key = `${update.phase}:${update.filesCompleted}:${update.filesTotal}`;
+ const key = `${update.phase}:${update.filesCompleted}:${update.filesTotal}:${update.reviewItems?.completed}:${update.reviewItems?.total}`;
if (key === lastProgressUpdate) return;
lastProgressUpdate = key;
fileProgress = update;
@@ -9022,8 +9025,9 @@ async function executeScan(
}
if (progress === null) return;
progress.stopTimer();
+ const count = scanProgressCount(update);
progress.stage(
- `Scan phase: ${phase}${update.filesTotal === 0 ? "" : ` (${update.filesCompleted.toLocaleString("en-US")}/${update.filesTotal.toLocaleString("en-US")} files)`}.`,
+ `Scan phase: ${phase}${count.total === 0 ? "" : ` (${count.completed.toLocaleString("en-US")}/${count.total.toLocaleString("en-US")} ${count.label})`}.`,
);
progress.startTimer(runningMessage());
},
@@ -9895,7 +9899,8 @@ function componentScanEventLine(
): string | null {
if (event.type === "progress") {
const progress = event.value;
- return `codex-security: ${componentName} ${scanPhase(progress.phase)} | Files: ${progress.filesCompleted.toLocaleString("en-US")}/${progress.filesTotal.toLocaleString("en-US")}\n`;
+ const count = scanProgressCount(progress);
+ return `codex-security: ${componentName} ${scanPhase(progress.phase)} | ${count.label === "reviews" ? "Reviews" : "Files"}: ${count.completed.toLocaleString("en-US")}/${count.total.toLocaleString("en-US")}\n`;
}
if (event.type === "usage") {
const tokens = formatTokenUsage(event.value);
diff --git a/sdk/typescript/src/deep-progress.ts b/sdk/typescript/src/deep-progress.ts
deleted file mode 100644
index 81c79372c..000000000
--- a/sdk/typescript/src/deep-progress.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-import { isRecord } from "./record.js";
-import { z } from "zod";
-
-const progressSchema = z
- .object({
- completed: z.int().nonnegative(),
- active: z.int().nonnegative(),
- maximum: z.int().positive(),
- consolidating: z.boolean().optional(),
- })
- .transform(({ consolidating, ...counts }) => ({
- ...counts,
- ...(consolidating === undefined ? {} : { consolidating }),
- }));
-
-export interface DeepScanProgress extends z.output<typeof progressSchema> {
- /** Whether the coordinator is reducing results or has finished. */
- consolidating?: boolean;
-}
-
-interface DeepScanProgressTrackerOptions {
- read: (signal: AbortSignal) => Promise<unknown>;
- onProgress: (progress: DeepScanProgress) => void;
- onError?: (error: unknown) => void;
-}
-
-const DEEP_PROGRESS_POLL_INTERVAL_MS = 5_000;
-
-export class DeepScanProgressTracker {
- readonly #options: DeepScanProgressTrackerOptions;
- #timer: NodeJS.Timeout | null = null;
- #pending: Promise<void> | null = null;
- readonly #abortController = new AbortController();
- #lastProgress: DeepScanProgress | null = null;
-
- public constructor(options: DeepScanProgressTrackerOptions) {
- this.#options = options;
- }
-
- public start(): void {
- if (this.#timer !== null || this.#abortController.signal.aborted) return;
- const poll = () => {
- void this.refresh().catch((error: unknown) => {
- this.#options.onError?.(error);
- });
- };
- this.#timer = setInterval(poll, DEEP_PROGRESS_POLL_INTERVAL_MS);
- this.#timer.unref();
- poll();
- }
-
- public async refresh(): Promise<void> {
- if (this.#abortController.signal.aborted) return;
- if (this.#pending !== null) return await this.#pending;
- const abortController = this.#abortController;
- let update: Promise<void> | null = null;
- update = (async () => {
- try {
- const progress = deepScanProgressFromWorkbench(
- await this.#options.read(abortController.signal),
- );
- if (
- abortController.signal.aborted ||
- progress === null ||
- (progress.completed === this.#lastProgress?.completed &&
- progress.active === this.#lastProgress?.active &&
- progress.maximum === this.#lastProgress?.maximum &&
- progress.consolidating === this.#lastProgress?.consolidating)
- ) {
- return;
- }
- this.#lastProgress = progress;
- this.#options.onProgress(progress);
- } catch (error) {
- if (abortController.signal.aborted) return;
- throw error;
- } finally {
- if (this.#pending === update) this.#pending = null;
- }
- })();
- this.#pending = update;
- await update;
- }
-
- public stop(): void {
- if (this.#abortController.signal.aborted) return;
- clearInterval(this.#timer ?? undefined);
- this.#timer = null;
- this.#abortController.abort();
- }
-}
-
-export function deepScanProgressFromWorkbench(
- result: unknown,
-): DeepScanProgress | null {
- if (!isRecord(result) || !isRecord(result["scan"])) return null;
- const progress = result["scan"]["progress"];
- if (!isRecord(progress)) return null;
- const independentReviews = progress["independentReviews"];
- if (independentReviews === undefined) return null;
- const parsed = progressSchema.safeParse(independentReviews);
- if (parsed.success) return parsed.data;
- throw new Error(
- "Codex Security workbench returned invalid Deep Scan progress.",
- );
-}
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index 544385d1f..89f5dde61 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -70,7 +70,7 @@ export type {
export { estimateScanCost } from "./cost.js";
export type { ScanCost, ScanSessionEvent, ScanWorkerEvent } from "./cost.js";
export type { ScanTokenUsage } from "./cost-model.js";
-export type { DeepScanProgress } from "./deep-progress.js";
+export type { DeepScanProgress } from "./scan-progress.js";
export type { CustomValidationResult } from "./custom-validation.js";
export type { ScanActivity, ScanActivityStatus } from "./scan-activity.js";
export { matchScanFindings } from "./scan-comparison.js";
diff --git a/sdk/typescript/src/scan-dashboard.ts b/sdk/typescript/src/scan-dashboard.ts
index e341b6f06..ef6b6aff4 100644
--- a/sdk/typescript/src/scan-dashboard.ts
+++ b/sdk/typescript/src/scan-dashboard.ts
@@ -23,7 +23,11 @@ import {
} from "./cost-model.js";
import type { ScanActivity } from "./scan-activity.js";
import type { ScanMode } from "./targets.js";
-import { scanPhaseLabel, type ScanProgress } from "./worker-progress.js";
+import {
+ scanPhaseLabel,
+ scanProgressCount,
+ type ScanProgress,
+} from "./worker-progress.js";
const HIDE_CURSOR = "\u001B[?25l";
const SHOW_CURSOR = "\u001B[?25h";
@@ -709,12 +713,15 @@ export class ScanDashboard {
),
);
const time = formatElapsed(elapsed);
+ const count = this.#files === null ? null : scanProgressCount(this.#files);
const files =
- this.#files === null
+ count === null
? "waiting for inventory"
- : this.#files.filesCompleted > 0
- ? `${formatCount(this.#files.filesCompleted)} / ${formatCount(this.#files.filesTotal)} reviewed`
- : `${formatCount(this.#files.filesTotal)} in scope`;
+ : count.label === "reviews"
+ ? `${formatCount(count.completed)} / ${formatCount(count.total)} completed`
+ : count.completed > 0
+ ? `${formatCount(count.completed)} / ${formatCount(count.total)} reviewed`
+ : `${formatCount(count.total)} in scope`;
const history = this.#activityLines(width);
const maximumOffset = Math.max(0, history.length - activityRows);
this.#scrollOffset = Math.min(this.#scrollOffset, maximumOffset);
@@ -759,7 +766,10 @@ export class ScanDashboard {
: [
...(this.#options.mode === "deep"
? []
- : [` STAGE ${this.#stage}`, ` FILES ${files}`]),
+ : [
+ ` STAGE ${this.#stage}`,
+ ` ${count?.label === "reviews" ? "REVIEWS" : "FILES "} ${files}`,
+ ]),
...this.#tokenLines(),
...this.#costLines(),
...(this.#budget === null
diff --git a/sdk/typescript/src/scan-executor.ts b/sdk/typescript/src/scan-executor.ts
index e9b25aa36..8761e2fb4 100644
--- a/sdk/typescript/src/scan-executor.ts
+++ b/sdk/typescript/src/scan-executor.ts
@@ -1,7 +1,7 @@
import { z } from "zod";
import { CodexSecurityError } from "./errors.js";
import type { ScanActivity } from "./scan-activity.js";
-import type { ScanProgress } from "./worker-progress.js";
+import { scanPhaseSchema, type ScanProgress } from "./worker-progress.js";
/** One Standard scan. The host owns execution, persistence and reconciliation. */
export interface ScanExecutionRequest {
@@ -57,16 +57,16 @@ export const ScanExecutionEventSchema = z.discriminatedUnion("type", [
z.strictObject({
type: z.literal("progress"),
progress: z.strictObject({
- phase: z.enum([
- "preflight",
- "threat_model",
- "discovery",
- "validation",
- "attack_path",
- "reporting",
- ]),
+ phase: scanPhaseSchema,
filesCompleted: z.number().int().nonnegative(),
filesTotal: z.number().int().nonnegative(),
+ reviewItems: z
+ .strictObject({
+ completed: z.number().int().nonnegative(),
+ total: z.number().int().nonnegative(),
+ })
+ .refine(({ completed, total }) => completed <= total)
+ .optional(),
}),
}),
z.strictObject({
diff --git a/sdk/typescript/src/scan-progress.ts b/sdk/typescript/src/scan-progress.ts
new file mode 100644
index 000000000..0e3438220
--- /dev/null
+++ b/sdk/typescript/src/scan-progress.ts
@@ -0,0 +1,157 @@
+import { isRecord } from "./record.js";
+import { z } from "zod";
+import { scanPhaseSchema, type ScanProgress } from "./worker-progress.js";
+
+const deepProgressSchema = z
+ .object({
+ completed: z.int().nonnegative(),
+ active: z.int().nonnegative(),
+ maximum: z.int().positive(),
+ consolidating: z.boolean().optional(),
+ })
+ .transform(({ consolidating, ...counts }) => ({
+ ...counts,
+ ...(consolidating === undefined ? {} : { consolidating }),
+ }));
+
+export interface DeepScanProgress extends z.output<typeof deepProgressSchema> {
+ /** Whether the coordinator is reducing results or has finished. */
+ consolidating?: boolean;
+}
+
+interface ScanProgressTrackerOptions {
+ read: (signal: AbortSignal) => Promise<unknown>;
+ onProgress?: (progress: SavedScanProgress) => void;
+ onDeepProgress?: (progress: DeepScanProgress) => void;
+ onError?: (error: unknown) => void;
+}
+
+const PROGRESS_POLL_INTERVAL_MS = 5_000;
+
+export class ScanProgressTracker {
+ readonly #options: ScanProgressTrackerOptions;
+ #timer: NodeJS.Timeout | null = null;
+ #pending: Promise<void> | null = null;
+ readonly #abortController = new AbortController();
+ #lastDeepProgress: DeepScanProgress | null = null;
+ #lastScanProgress: string | null = null;
+
+ public constructor(options: ScanProgressTrackerOptions) {
+ this.#options = options;
+ }
+
+ public start(): void {
+ if (this.#timer !== null || this.#abortController.signal.aborted) return;
+ const poll = () => {
+ void this.refresh().catch((error: unknown) => {
+ this.#options.onError?.(error);
+ });
+ };
+ this.#timer = setInterval(poll, PROGRESS_POLL_INTERVAL_MS);
+ this.#timer.unref();
+ poll();
+ }
+
+ public async refresh(): Promise<void> {
+ if (this.#abortController.signal.aborted) return;
+ if (this.#pending !== null) return await this.#pending;
+ const abortController = this.#abortController;
+ let update: Promise<void> | null = null;
+ update = (async () => {
+ try {
+ const result = await this.#options.read(abortController.signal);
+ if (abortController.signal.aborted) return;
+ if (this.#options.onProgress !== undefined) {
+ const progress = scanProgressFromWorkbench(result);
+ if (progress !== null) {
+ const key = JSON.stringify(progress);
+ if (key !== this.#lastScanProgress) {
+ this.#lastScanProgress = key;
+ this.#options.onProgress(progress);
+ }
+ }
+ }
+ if (this.#options.onDeepProgress === undefined) return;
+ const progress = deepScanProgressFromWorkbench(result);
+ if (
+ abortController.signal.aborted ||
+ progress === null ||
+ (progress.completed === this.#lastDeepProgress?.completed &&
+ progress.active === this.#lastDeepProgress?.active &&
+ progress.maximum === this.#lastDeepProgress?.maximum &&
+ progress.consolidating === this.#lastDeepProgress?.consolidating)
+ ) {
+ return;
+ }
+ this.#lastDeepProgress = progress;
+ this.#options.onDeepProgress(progress);
+ } catch (error) {
+ if (abortController.signal.aborted) return;
+ throw error;
+ } finally {
+ if (this.#pending === update) this.#pending = null;
+ }
+ })();
+ this.#pending = update;
+ await update;
+ }
+
+ public stop(): void {
+ if (this.#abortController.signal.aborted) return;
+ clearInterval(this.#timer ?? undefined);
+ this.#timer = null;
+ this.#abortController.abort();
+ }
+}
+
+const savedProgressSchema = z.object({
+ phase: scanPhaseSchema,
+ coverage: z
+ .object({
+ filesTotal: z.int().nonnegative().nullable(),
+ closedRows: z.int().nonnegative(),
+ worklistRows: z.int().nonnegative(),
+ })
+ .refine(({ closedRows, worklistRows }) => closedRows <= worklistRows),
+});
+
+export interface SavedScanProgress {
+ phase: ScanProgress["phase"];
+ filesTotal: number | null;
+ reviewItems: NonNullable<ScanProgress["reviewItems"]>;
+}
+
+export function scanProgressFromWorkbench(
+ result: unknown,
+): SavedScanProgress | null {
+ if (!isRecord(result) || !isRecord(result["scan"])) return null;
+ const progress = result["scan"]["progress"];
+ if (!isRecord(progress) || progress["coverage"] === undefined) return null;
+ const parsed = savedProgressSchema.safeParse(progress);
+ if (!parsed.success) {
+ throw new Error("Codex Security workbench returned invalid scan progress.");
+ }
+ return {
+ phase: parsed.data.phase,
+ filesTotal: parsed.data.coverage.filesTotal,
+ reviewItems: {
+ completed: parsed.data.coverage.closedRows,
+ total: parsed.data.coverage.worklistRows,
+ },
+ };
+}
+
+export function deepScanProgressFromWorkbench(
+ result: unknown,
+): DeepScanProgress | null {
+ if (!isRecord(result) || !isRecord(result["scan"])) return null;
+ const progress = result["scan"]["progress"];
+ if (!isRecord(progress)) return null;
+ const independentReviews = progress["independentReviews"];
+ if (independentReviews === undefined) return null;
+ const parsed = deepProgressSchema.safeParse(independentReviews);
+ if (parsed.success) return parsed.data;
+ throw new Error(
+ "Codex Security workbench returned invalid Deep Scan progress.",
+ );
+}
diff --git a/sdk/typescript/src/worker-progress.ts b/sdk/typescript/src/worker-progress.ts
index fdfe50970..8ad06488b 100644
--- a/sdk/typescript/src/worker-progress.ts
+++ b/sdk/typescript/src/worker-progress.ts
@@ -13,7 +13,7 @@ const workerPhaseSchema = z.enum([
export type ScanWorkerPhase = z.infer<typeof workerPhaseSchema>;
-const scanPhaseSchema = z.enum([
+export const scanPhaseSchema = z.enum([
"preflight",
"threat_model",
"discovery",
@@ -31,7 +31,25 @@ const dispatchSchema = z
.object({ phase: workerPhaseSchema, planned: count, started: count })
.refine(({ started, planned }) => started <= planned);
-export interface ScanProgress extends z.infer<typeof scanProgressSchema> {}
+export interface ScanProgress extends z.infer<typeof scanProgressSchema> {
+ /** Saved reviews or coverage surfaces; these are not necessarily files. */
+ reviewItems?: { completed: number; total: number };
+}
+
+export function scanProgressCount(progress: ScanProgress): {
+ label: "files" | "reviews";
+ completed: number;
+ total: number;
+} {
+ if (progress.reviewItems !== undefined && progress.reviewItems.total > 0) {
+ return { label: "reviews", ...progress.reviewItems };
+ }
+ return {
+ label: "files",
+ completed: progress.filesCompleted,
+ total: progress.filesTotal,
+ };
+}
export function scanPhaseLabel(value: ScanWorkerPhase | ScanPhase): string {
return {
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 9e0f99929..49af49435 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -43,6 +43,7 @@ import {
type ScanProgress,
type ScanSessionEvent,
type ScanWorkerEvent,
+ type ScanWorkerStatus,
ScanInterruptedError,
} from "../src/index.js";
import {
@@ -3505,6 +3506,280 @@ describe("CodexSecurity orchestration", () => {
await client.close();
});
+ test("keeps hosted executor progress authoritative", async () => {
+ const { repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const savedProgress = Promise.withResolvers<JsonObject>();
+ const client = new TestClient(
+ {
+ codexOverrides: {
+ model: "gpt-5.6-sol",
+ model_reasoning_effort: "high",
+ },
+ },
+ {
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (_options, args, input) => {
+ if (args[0] === "register-cli-scan") {
+ return { ...mockScanRegistration(args, input), scopeFileCount: 8 };
+ }
+ if (args[0] === "get-scan") return await savedProgress.promise;
+ return mockWorkbench(args, input);
+ },
+ hostedScan: {
+ context: {
+ repository,
+ revision: "deadbeef",
+ scope: { paths: ["."] },
+ identity: { runId: "run", attemptId: "attempt", buildId: "build" },
+ },
+ onEvent(event) {
+ if (event.type === "progress") updates.push(event.progress);
+ },
+ executor: {
+ async run(_request, { onEvent }) {
+ onEvent?.({
+ type: "progress",
+ progress: {
+ phase: "validation",
+ filesCompleted: 8,
+ filesTotal: 8,
+ },
+ });
+ savedProgress.resolve({
+ scan: {
+ progress: {
+ phase: "discovery",
+ coverage: { filesTotal: 8, closedRows: 0, worklistRows: 8 },
+ },
+ },
+ });
+ await new Promise<void>((resolve) => setImmediate(resolve));
+ throw new Error("hosted execution failed");
+ },
+ },
+ },
+ },
+ );
+ const python = spyOn(runtime, "resolvePluginPython").mockResolvedValue(
+ "/managed/python",
+ );
+ try {
+ await expect(
+ client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ }),
+ ).rejects.toThrow("hosted execution failed");
+ expect(
+ updates.map(({ phase, filesCompleted }) => [phase, filesCompleted]),
+ ).toEqual([
+ ["preflight", 0],
+ ["validation", 8],
+ ]);
+ } finally {
+ python.mockRestore();
+ await client.close();
+ }
+ });
+
+ test.each([false, true])(
+ "stops polling before follow-up (failed=%p)",
+ async (primaryFails) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const statuses: ScanWorkerStatus[] = [];
+ const warnings: string[] = [];
+ let progressSignal: AbortSignal | undefined;
+ let turns = 0;
+ const status = {
+ kind: "dispatch",
+ phase: "validation",
+ planned: 2,
+ started: 2,
+ } as const;
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (options, args, input) => {
+ if (args[0] === "register-cli-scan") {
+ return { ...mockScanRegistration(args, input), scopeFileCount: 1 };
+ }
+ if (args[0] === "get-scan") {
+ progressSignal ??= options.signal;
+ return {
+ scan: {
+ progress: {
+ phase: "reporting",
+ coverage: { filesTotal: 1, closedRows: 1, worklistRows: 1 },
+ },
+ },
+ };
+ }
+ return mockWorkbench(args, input);
+ },
+ createCodex: codexFactory(async () => {
+ if (++turns === 1) {
+ if (primaryFails) return { events: failedEvents() };
+ await copyCompletedScan(root);
+ return { events: completedEvents() };
+ }
+ expect(progressSignal?.aborted).toBe(true);
+ return {
+ events: completedEvents(
+ "thread-1",
+ (async function* (): AsyncGenerator<ThreadEvent> {
+ yield {
+ type: "item.completed",
+ item: {
+ id: "follow-up-dispatch",
+ type: "agent_message",
+ text: `CODEX_SECURITY_WORKER_STATUS ${JSON.stringify(status)}`,
+ },
+ };
+ })(),
+ ),
+ };
+ }, "thread-1"),
+ });
+ try {
+ const result = client.run(repository, {
+ postScanPrompt: "Review the synthetic fix.",
+ onProgress() {},
+ onWorkerStatus: (update) => statuses.push(update),
+ onWarning: (warning) => warnings.push(warning),
+ });
+ if (primaryFails)
+ await expect(result).rejects.toThrow("Could not draft fixes.");
+ else await result;
+ expect(turns).toBe(2);
+ expect(warnings).toEqual([]);
+ expect(statuses).toEqual(primaryFails ? [] : [status]);
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ "marker-free",
+ "late marker",
+ "late worker",
+ "unavailable",
+ "malformed",
+ ])(
+ "routes saved scan progress without replacing scan errors (%s)",
+ async (scenario) => {
+ const { repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const warnings: string[] = [];
+ const observerErrors: string[] = [];
+ const workerStatuses: unknown[] = [];
+ let failNextProgressRead = scenario === "unavailable";
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> => {
+ if (args[0] === "register-cli-scan") {
+ return { ...mockScanRegistration(args, input), scopeFileCount: 8 };
+ }
+ if (args[0] === "get-scan") {
+ if (failNextProgressRead) {
+ failNextProgressRead = false;
+ throw new Error("progress read failed");
+ }
+ return {
+ scan: {
+ progress: {
+ phase: "validation",
+ coverage: {
+ filesTotal: 8,
+ closedRows: scenario === "malformed" ? -1 : 11,
+ worklistRows: 13,
+ },
+ },
+ },
+ };
+ }
+ return mockWorkbench(args, input);
+ },
+ createCodex: codexFactory(async () => ({
+ events: (async function* (): AsyncGenerator<ThreadEvent> {
+ if (scenario === "late marker") {
+ yield {
+ type: "item.completed",
+ item: {
+ id: "late-discovery-update",
+ type: "agent_message",
+ text: 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8}',
+ },
+ };
+ }
+ if (scenario === "late worker") {
+ yield {
+ type: "item.completed",
+ item: {
+ id: "late-worker-dispatch",
+ type: "agent_message",
+ text: 'CODEX_SECURITY_WORKER_STATUS {"kind":"dispatch","phase":"file_review","planned":2,"started":2}',
+ },
+ };
+ }
+ throw new Error("original scan failure");
+ })(),
+ })),
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ onProgress: (progress) => {
+ updates.push(progress);
+ if (progress.reviewItems !== undefined)
+ throw new Error("presenter failed");
+ },
+ onWarning: (warning) => warnings.push(warning),
+ onWorkerStatus: (status) => workerStatuses.push(status),
+ onObserverError: (observer) => observerErrors.push(observer),
+ }),
+ ).rejects.toThrow("original scan failure");
+ expect(updates[0]).toEqual({
+ phase: "preflight",
+ filesCompleted: 0,
+ filesTotal: 8,
+ });
+ expect(workerStatuses).toEqual([]);
+ if (["marker-free", "late marker", "late worker"].includes(scenario)) {
+ expect(updates[1]).toEqual({
+ phase: "validation",
+ filesCompleted: 0,
+ filesTotal: 8,
+ reviewItems: { completed: 11, total: 13 },
+ });
+ if (scenario === "late marker") {
+ expect(updates.at(-1)).toEqual({
+ ...updates[1]!,
+ filesCompleted: 3,
+ });
+ }
+ expect(warnings).toEqual([]);
+ expect(observerErrors).toEqual(
+ Array(updates.length - 1).fill("onProgress"),
+ );
+ } else {
+ expect(updates).toHaveLength(1);
+ expect(observerErrors).toEqual([]);
+ expect(warnings).toEqual([
+ scenario === "unavailable"
+ ? "Could not track scan progress: progress read failed"
+ : "Could not track scan progress: Codex Security workbench returned invalid scan progress.",
+ ]);
+ }
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
test.each([true, "false", null])(
"routes durable Deep progress without replacing scan errors (consolidating=%p)",
async (consolidating) => {
@@ -4118,116 +4393,157 @@ describe("CodexSecurity orchestration", () => {
},
);
- test("normalizes worker progress while streaming related session events", async () => {
- const { root, repository, codexHome, scanDir } = await scanDirectories();
- const updates: ScanProgress[] = [];
- const sessionEvents: ScanSessionEvent[] = [];
- const workers: ScanWorkerEvent[] = [];
- const observerErrors: ScanObserverName[] = [];
- const usage = { input_tokens: 100, output_tokens: 10 };
- const client = TestClient.withDependencies({
- ...scanRuntimeDependencies(codexHome, scanDir),
- runWorkbench: async (
- _options: unknown,
- args: readonly string[],
- input?: string,
- ): Promise<JsonObject> =>
- args[0] === "register-cli-scan"
- ? { ...mockScanRegistration(args, input), scopeFileCount: 1_258 }
- : mockWorkbench(args, input),
- createCodex: codexFactory(async () => {
- await copyCompletedScan(root);
- await Promise.all([
- writeUsageSession(codexHome, "thread-1", usage),
- writeUsageSession(codexHome, "worker-thread", usage, {
- parent: "thread-1",
- parentField: "parent_thread_id",
- }),
- writeUsageSession(codexHome, "unrelated-thread", usage),
- ]);
- const marker = (
- phase: ScanProgress["phase"],
- filesCompleted: number,
- filesTotal: number,
- ): string =>
- `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({
- phase,
- filesCompleted,
- filesTotal,
- })}`;
- for (const [threadId, text] of [
- ["worker-thread", marker("discovery", 3, 1_249)],
- ["worker-thread", marker("discovery", 2, 2)],
- ["worker-thread", marker("discovery", 7, 1_259)],
- ["unrelated-thread", marker("discovery", 7, 1_258)],
- ["worker-thread", marker("discovery", 1_250, 1_249)],
- ["worker-thread", marker("discovery", 1_249, 1_249)],
- ["worker-thread", marker("validation", 1_249, 1_249)],
- ] as const) {
- await appendFile(
- join(
- codexHome,
- "sessions",
- "2026",
- "07",
- "26",
- `rollout-${threadId}.jsonl`,
- ),
- `${JSON.stringify({
- type: "response_item",
- payload: {
- type: "custom_tool_call_output",
- status: "completed",
- output: [
- { type: "input_text", text: "Reviewed file batch." },
- { type: "input_text", text },
- ],
+ test.each([false, true])(
+ "normalizes worker counts using the parent phase (validation dispatch: %p)",
+ async (parentDispatch) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const sessionEvents: ScanSessionEvent[] = [];
+ const workers: ScanWorkerEvent[] = [];
+ const observerErrors: ScanObserverName[] = [];
+ const usage = { input_tokens: 100, output_tokens: 10 };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> => {
+ if (args[0] === "register-cli-scan")
+ return {
+ ...mockScanRegistration(args, input),
+ scopeFileCount: 1_258,
+ };
+ if (args[0] === "get-scan")
+ return {
+ scan: {
+ progress: {
+ phase: "discovery",
+ coverage: {
+ filesTotal: 1_258,
+ closedRows: 0,
+ worklistRows: 0,
+ },
+ },
},
- })}\n`,
- );
- }
- return { events: completedEvents() };
- }),
- });
+ };
+ return mockWorkbench(args, input);
+ },
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ await Promise.all([
+ writeUsageSession(codexHome, "thread-1", usage),
+ writeUsageSession(codexHome, "worker-thread", usage, {
+ parent: "thread-1",
+ parentField: "parent_thread_id",
+ }),
+ writeUsageSession(codexHome, "unrelated-thread", usage),
+ ]);
+ const marker = (
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ filesTotal: number,
+ ): string =>
+ `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({
+ phase,
+ filesCompleted,
+ filesTotal,
+ })}`;
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (parentDispatch) {
+ yield {
+ type: "item.completed",
+ item: {
+ id: "parent-validation-dispatch",
+ type: "agent_message",
+ text: 'CODEX_SECURITY_WORKER_STATUS {"kind":"dispatch","phase":"validation","planned":2,"started":2}',
+ },
+ };
+ }
+ for (const [threadId, text] of [
+ ["worker-thread", marker("discovery", 3, 1_249)],
+ ["worker-thread", marker("discovery", 2, 2)],
+ ["worker-thread", marker("discovery", 7, 1_259)],
+ ["unrelated-thread", marker("discovery", 7, 1_258)],
+ ["worker-thread", marker("discovery", 1_250, 1_249)],
+ ["worker-thread", marker("discovery", 1_249, 1_249)],
+ ["worker-thread", marker("validation", 1_249, 1_249)],
+ ] as const) {
+ await appendFile(
+ join(
+ codexHome,
+ "sessions",
+ "2026",
+ "07",
+ "26",
+ `rollout-${threadId}.jsonl`,
+ ),
+ `${JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ status: "completed",
+ output: [
+ { type: "input_text", text: "Reviewed file batch." },
+ { type: "input_text", text },
+ ],
+ },
+ })}\n`,
+ );
+ }
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
- const result = await client.run(repository, {
- onProgress: (progress) => updates.push(progress),
- onWorkerEvent: (event) => workers.push(event),
- onSessionEvent: (event) => {
- sessionEvents.push(event);
- if (sessionEvents.length === 1) {
- throw new Error("session observer exploded");
- }
- },
- onObserverError: (observer) => observerErrors.push(observer),
- });
+ const result = await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onWorkerEvent: (event) => workers.push(event),
+ onSessionEvent: (event) => {
+ sessionEvents.push(event);
+ if (sessionEvents.length === 1) {
+ throw new Error("session observer exploded");
+ }
+ },
+ onObserverError: (observer) => observerErrors.push(observer),
+ });
- expect(result.threadId).toBe("thread-1");
- expect(updates).toEqual([
- { phase: "preflight", filesCompleted: 0, filesTotal: 1_258 },
- { phase: "discovery", filesCompleted: 3, filesTotal: 1_258 },
- { phase: "discovery", filesCompleted: 1_249, filesTotal: 1_258 },
- { phase: "validation", filesCompleted: 1_249, filesTotal: 1_258 },
- ]);
- expect(sessionEvents).toHaveLength(10);
- expect(
- new Set(
- sessionEvents.map(
- ({ threadId, parentThreadId }) => `${threadId}:${parentThreadId}`,
+ expect(result.threadId).toBe("thread-1");
+ expect(updates).toEqual([
+ { phase: "preflight", filesCompleted: 0, filesTotal: 1_258 },
+ {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 1_258,
+ reviewItems: { completed: 0, total: 0 },
+ },
+ ...[3, 1_249, 1_249].map<ScanProgress>((filesCompleted) => ({
+ phase: parentDispatch ? "validation" : "discovery",
+ filesCompleted,
+ filesTotal: 1_258,
+ reviewItems: { completed: 0, total: 0 },
+ })),
+ ]);
+ expect(sessionEvents).toHaveLength(10);
+ expect(
+ new Set(
+ sessionEvents.map(
+ ({ threadId, parentThreadId }) => `${threadId}:${parentThreadId}`,
+ ),
),
- ),
- ).toEqual(new Set(["thread-1:null", "worker-thread:thread-1"]));
- expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
- expect(
- new Set(
- sessionEvents
- .filter((event) => event.threadId === "worker-thread")
- .map((event) => event.worker),
- ),
- ).toEqual(new Set([1]));
- expect(observerErrors).toEqual(["onSessionEvent"]);
- await client.close();
- });
+ ).toEqual(new Set(["thread-1:null", "worker-thread:thread-1"]));
+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
+ expect(
+ new Set(
+ sessionEvents
+ .filter((event) => event.threadId === "worker-thread")
+ .map((event) => event.worker),
+ ),
+ ).toEqual(new Set([1]));
+ expect(observerErrors).toEqual(["onSessionEvent"]);
+ await client.close();
+ },
+ );
test.each(["none", "sync", "async"] as const)(
"observes workers before scan completion with %s observer errors",
@@ -4544,6 +4860,7 @@ describe("CodexSecurity orchestration", () => {
let modelCalled = false;
let matchingTurns = 0;
let observedSingleTurn: boolean | undefined;
+ let progressSignal: AbortSignal | undefined;
let matched = false;
let savedComparisonInput: string | undefined;
const managedProvider = {
@@ -4676,12 +4993,11 @@ describe("CodexSecurity orchestration", () => {
: {}),
},
})),
- runWorkbench: async (
- _options: unknown,
- args: readonly string[],
- input?: string,
- ): Promise<JsonObject> => {
+ runWorkbench: async (options, args, input): Promise<JsonObject> => {
commands.push(args);
+ if (args[0] === "get-scan") {
+ progressSignal ??= options.signal;
+ }
if (args[0] === "get-scan-feedback") {
return {
scanId: "scan_example_001",
@@ -4701,6 +5017,7 @@ describe("CodexSecurity orchestration", () => {
};
}
if (args[0] === "list-global-findings") {
+ expect(progressSignal?.aborted).toBe(true);
if (failure === "index") throw new Error("index unavailable");
if (failure === "dismissed" || failure === "managed") {
return {
@@ -4843,6 +5160,7 @@ describe("CodexSecurity orchestration", () => {
const result = await client.run(repository, {
...(limited ? { maxCostUsd: 1 } : {}),
cyberAccessProgram: "daybreak_blue",
+ onProgress() {},
onWarning: (message) => warnings.push(message),
});
expect(result.threadId).toBe("thread-1");
diff --git a/sdk/typescript/tests-ts/cli.test.ts b/sdk/typescript/tests-ts/cli.test.ts
index 6a98884a0..af7d7c8a6 100644
--- a/sdk/typescript/tests-ts/cli.test.ts
+++ b/sdk/typescript/tests-ts/cli.test.ts
@@ -2000,6 +2000,39 @@ describe("CLI", () => {
},
);
+ test("shows saved review counts even when the phase and file counts do not change", async () => {
+ const { stderr, runCli } = createCliTest(main);
+ const deps = dependencies({
+ scanProgress: [
+ { phase: "preflight", filesCompleted: 0, filesTotal: 8 },
+ {
+ phase: "validation",
+ filesCompleted: 0,
+ filesTotal: 8,
+ reviewItems: { completed: 11, total: 13 },
+ },
+ {
+ phase: "validation",
+ filesCompleted: 0,
+ filesTotal: 8,
+ reviewItems: { completed: 13, total: 13 },
+ },
+ ],
+ });
+ deps.setInterval = mock(fakeInterval);
+ expect(await runCli(["scan", ".", "--headless"], deps)).toBe(0);
+ expect(stderr.text()).toContain(
+ "Scan phase: validating findings (11/13 reviews).",
+ );
+ expect(stderr.text()).toContain(
+ "Scan phase: validating findings (13/13 reviews).",
+ );
+ expect(stderr.text()).toContain(
+ "Running scan: validating findings | Reviews: 13/13",
+ );
+ expect(stderr.text()).not.toContain("Files: 13/13");
+ });
+
test("uses plain scan progress in headless, CI, and noninteractive terminals", async () => {
for (const { options, environment, isTTY } of [
{ options: ["--headless"], environment: {}, isTTY: true },
diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.ts
index a72d3a50e..b7ba8157c 100644
--- a/sdk/typescript/tests-ts/custom-validation.test.ts
+++ b/sdk/typescript/tests-ts/custom-validation.test.ts
@@ -19,6 +19,7 @@ import {
type CoverageDocument,
type FindingsDocument,
type ScanManifest,
+ type ScanProgress,
} from "../src/index.js";
import { createMarketplace, resolveCodexCommand } from "../src/runtime.js";
import { copyCompletedScanFixture, PLUGIN_ROOT } from "./plugin-root.js";
@@ -417,6 +418,7 @@ describe("custom validation", () => {
const completionScenarios = [
"standard",
+ "progress",
"diff",
"empty",
"incomplete",
@@ -470,6 +472,7 @@ describe("custom validation", () => {
const workingDirectories: Array<string | undefined> = [];
const commands: string[] = [];
const activities: ScanActivity[] = [];
+ const progress: ScanProgress[] = [];
const validationActivity = "Synthetic validation activity.";
const profileDisabledTools =
scenario === "standard"
@@ -586,8 +589,31 @@ describe("custom validation", () => {
);
expect(commands).not.toContain("prepare-scan-completion");
expect(commands).not.toContain("complete-scan");
+ if (scenario === "progress") {
+ return {
+ events:
+ (async function* (): AsyncGenerator<ThreadEvent> {
+ yield {
+ type: "item.completed",
+ item: {
+ id: "primary-reporting",
+ type: "agent_message",
+ text: 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"reporting","filesCompleted":1,"filesTotal":1}',
+ },
+ };
+ yield* completedEvents();
+ })(),
+ };
+ }
return { events: completedEvents() };
}
+ if (scenario === "progress") {
+ await Promise.resolve();
+ expect(
+ progress.some(({ phase }) => phase === "reporting"),
+ ).toBe(true);
+ expect(progress.at(-1)?.phase).toBe("validation");
+ }
expect(prompt).toContain(workflow);
expect(prompt).not.toContain("2026-01-01T00:05:00.000Z");
const pendingManifest = await json<ScanManifest>(
@@ -705,6 +731,9 @@ describe("custom validation", () => {
? { validationPromptFile: workflowFile }
: { validationPrompt: workflow }),
onActivity: (activity) => activities.push(activity),
+ ...(scenario === "progress"
+ ? { onProgress: (update: ScanProgress) => progress.push(update) }
+ : {}),
...(diff ? { target: DiffTarget.workingTree({}) } : {}),
});
if (scenario === "unfinished-source") {
diff --git a/sdk/typescript/tests-ts/deep-progress.test.ts b/sdk/typescript/tests-ts/deep-progress.test.ts
index e0a5a7026..a769376bb 100644
--- a/sdk/typescript/tests-ts/deep-progress.test.ts
+++ b/sdk/typescript/tests-ts/deep-progress.test.ts
@@ -1,10 +1,10 @@
import { once } from "node:events";
import { describe, expect, test, mock } from "bun:test";
import {
- DeepScanProgressTracker,
+ ScanProgressTracker,
deepScanProgressFromWorkbench,
type DeepScanProgress,
-} from "../src/deep-progress.js";
+} from "../src/scan-progress.js";
function workbenchResult(
independentReviews?: Record<string, unknown>,
@@ -59,9 +59,9 @@ describe("Deep Scan progress", () => {
const read = mock(async () => {
return reads.shift() ?? workbenchResult();
});
- const tracker = new DeepScanProgressTracker({
+ const tracker = new ScanProgressTracker({
read,
- onProgress: (update) => progress.push(update),
+ onDeepProgress: (update) => progress.push(update),
});
await tracker.refresh();
@@ -86,9 +86,9 @@ describe("Deep Scan progress", () => {
return workbenchResult({ completed: 1, active: 0, maximum: 40 });
});
let aborted = false;
- const tracker = new DeepScanProgressTracker({
+ const tracker = new ScanProgressTracker({
read,
- onProgress: (update) => progress.push(update),
+ onDeepProgress: (update) => progress.push(update),
});
const first = tracker.refresh();
@@ -107,9 +107,9 @@ describe("Deep Scan progress", () => {
workbenchResult({ completed: 2, active: 2, maximum: 40, consolidating }),
);
const progress: DeepScanProgress[] = [];
- const tracker = new DeepScanProgressTracker({
+ const tracker = new ScanProgressTracker({
read: async () => reads.shift(),
- onProgress: (update) => progress.push(update),
+ onDeepProgress: (update) => progress.push(update),
});
for (let index = 0; index < 4; index++) await tracker.refresh();
tracker.stop();
diff --git a/sdk/typescript/tests-ts/hosted-scan.test.ts b/sdk/typescript/tests-ts/hosted-scan.test.ts
index f13f7fede..4310b50fe 100644
--- a/sdk/typescript/tests-ts/hosted-scan.test.ts
+++ b/sdk/typescript/tests-ts/hosted-scan.test.ts
@@ -19,6 +19,7 @@ import { CodexSecurity, runHostedScan } from "../src/index.js";
import * as config from "../src/config.js";
import * as hostedScan from "../src/hosted-scan.js";
import {
+ ScanExecutionEventSchema,
ScanExecutionResultSchema,
type ScanExecutionEvent,
type ScanExecutionResult,
@@ -617,7 +618,11 @@ test.each([false, true])(
if (message.method === "execution.run") {
expect(message.params.reasoningEffort).toBe(input.reasoningEffort);
requestId = message.params.requestId;
- for (const event of [progressEvent, { invalid: true }])
+ for (const event of [
+ progressEvent,
+ reviewProgressEvent,
+ { invalid: true },
+ ])
send(child.stdin, {
method: "execution.progress",
params: { requestId, event },
@@ -650,11 +655,12 @@ test.each([false, true])(
expect(
messages.filter((message) => message.method === "execution.run"),
).toHaveLength(1);
- expect(messages).toContainEqual({
- jsonrpc: "2.0",
- method: "scan.progress",
- params: { id: "run", event: progressEvent },
- });
+ for (const event of [progressEvent, reviewProgressEvent])
+ expect(messages).toContainEqual({
+ jsonrpc: "2.0",
+ method: "scan.progress",
+ params: { id: "run", event },
+ });
expect(messages.at(-1)).toMatchObject({
id: "run",
result: {
@@ -672,6 +678,28 @@ const progressEvent: ScanExecutionEvent = {
type: "progress",
progress: { phase: "discovery", filesCompleted: 1, filesTotal: 2 },
};
+const reviewProgressEvent: ScanExecutionEvent = {
+ type: "progress",
+ progress: {
+ ...progressEvent.progress,
+ phase: "validation",
+ reviewItems: { completed: 3, total: 4 },
+ },
+};
+
+test.each([
+ { completed: -1, total: 4 },
+ { completed: 5, total: 4 },
+ { completed: 1.5, total: 4 },
+])("rejects invalid hosted review counts %j", (reviewItems) => {
+ expect(
+ ScanExecutionEventSchema.safeParse({
+ ...progressEvent,
+ progress: { ...progressEvent.progress, reviewItems },
+ }).success,
+ ).toBe(false);
+});
+
const activityEvent: ScanExecutionEvent = {
type: "activity",
activity: {
diff --git a/sdk/typescript/tests-ts/scan-dashboard.test.ts b/sdk/typescript/tests-ts/scan-dashboard.test.ts
index ea41aa7e1..da263e1f0 100644
--- a/sdk/typescript/tests-ts/scan-dashboard.test.ts
+++ b/sdk/typescript/tests-ts/scan-dashboard.test.ts
@@ -2657,3 +2657,30 @@ test.each([16, 25, 120])(
}
},
);
+
+test("shows saved review counts separately from file coverage", () => {
+ const stderr = capture(true);
+ const dashboard = createDashboard(stderr.stream);
+ dashboard.start();
+ try {
+ dashboard.setStage("validating findings");
+ dashboard.setFiles({
+ phase: "validation",
+ filesCompleted: 0,
+ filesTotal: 8,
+ reviewItems: { completed: 11, total: 13 },
+ });
+ expect(lastFrame(stderr)).toContain("validating findings");
+ expect(lastFrame(stderr)).toContain("REVIEWS 11 / 13 completed");
+ expect(lastFrame(stderr)).not.toContain("FILES");
+ dashboard.setFiles({
+ phase: "validation",
+ filesCompleted: 0,
+ filesTotal: 8,
+ reviewItems: { completed: 13, total: 13 },
+ });
+ expect(lastFrame(stderr)).toContain("REVIEWS 13 / 13 completed");
+ } finally {
+ dashboard.stop();
+ }
+});
diff --git a/sdk/typescript/tests-ts/scan-progress.test.ts b/sdk/typescript/tests-ts/scan-progress.test.ts
new file mode 100644
index 000000000..71dd38cf7
--- /dev/null
+++ b/sdk/typescript/tests-ts/scan-progress.test.ts
@@ -0,0 +1,106 @@
+import { expect, mock, test } from "bun:test";
+import {
+ ScanProgressTracker,
+ scanProgressFromWorkbench,
+ type SavedScanProgress,
+} from "../src/scan-progress.js";
+
+function savedProgress(phase: string, completed: number, total: number) {
+ return {
+ scan: {
+ progress: {
+ phase,
+ coverage: { filesTotal: 8, closedRows: completed, worklistRows: total },
+ },
+ },
+ };
+}
+
+test("saved progress keeps review items distinct from files", () => {
+ expect(
+ scanProgressFromWorkbench(savedProgress("validation", 11, 13)),
+ ).toEqual({
+ phase: "validation",
+ filesTotal: 8,
+ reviewItems: { completed: 11, total: 13 },
+ });
+ const snapshot = savedProgress("preflight", 0, 0);
+ expect(
+ scanProgressFromWorkbench({
+ scan: {
+ progress: {
+ ...snapshot.scan.progress,
+ coverage: { ...snapshot.scan.progress.coverage, filesTotal: null },
+ },
+ },
+ }),
+ ).toEqual({
+ phase: "preflight",
+ filesTotal: null,
+ reviewItems: { completed: 0, total: 0 },
+ });
+ expect(scanProgressFromWorkbench({})).toBeNull();
+});
+
+test.each([
+ ["unknown", 0, 13],
+ ["discovery", -1, 13],
+ ["discovery", 14, 13],
+] as const)(
+ "rejects invalid saved progress (%s, %s/%s)",
+ (phase, completed, total) => {
+ expect(() =>
+ scanProgressFromWorkbench(savedProgress(phase, completed, total)),
+ ).toThrow("invalid scan progress");
+ },
+);
+
+test("publishes saved phase and count changes without model progress markers", async () => {
+ const snapshots = [
+ {},
+ savedProgress("discovery", 1, 13),
+ savedProgress("discovery", 1, 13),
+ savedProgress("discovery", 2, 13),
+ savedProgress("validation", 2, 13),
+ ];
+ const updates: SavedScanProgress[] = [];
+ const read = mock(async () => snapshots.shift());
+ const tracker = new ScanProgressTracker({
+ read,
+ onProgress: (update) => updates.push(update),
+ });
+ try {
+ for (let index = 0; index < 5; index++) await tracker.refresh();
+ expect(
+ updates.map(({ phase, reviewItems }) => [phase, reviewItems.completed]),
+ ).toEqual([
+ ["discovery", 1],
+ ["discovery", 2],
+ ["validation", 2],
+ ]);
+ } finally {
+ tracker.stop();
+ }
+ await tracker.refresh();
+ expect(read).toHaveBeenCalledTimes(5);
+});
+
+test("recovers on the next refresh after a progress read fails", async () => {
+ const updates: SavedScanProgress[] = [];
+ let reads = 0;
+ const tracker = new ScanProgressTracker({
+ read: async () => {
+ if (reads++ === 0) throw new Error("workbench unavailable");
+ return savedProgress("validation", 13, 13);
+ },
+ onProgress: (update) => updates.push(update),
+ });
+ try {
+ await expect(tracker.refresh()).rejects.toThrow("workbench unavailable");
+ await tracker.refresh();
+ expect(updates).toHaveLength(1);
+ expect(updates[0]?.phase).toBe("validation");
+ } finally {
+ tracker.stop();
+ }
+});