OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
fix(sdk): report worker sessions without model progress markers (#962)
mldangelo-oaiff95e6799143
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex 7d3b8a31b..7790cbdd7 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -259,9 +259,42 @@ stops, the scan combines and returns completed findings. See### Progress and cost-Use `onProgress` for scan progress, `onWorkerStatus` for individual workers, and-`onCost` for cost updates. `onDeepProgress` reports completed, active, and maximum-independent reviews; the maximum is a cap, not a percentage denominator.+Use `onProgress` for scan progress and `onCost` for cost updates.++Follow scans with `onWorkerEvent` and `onReconnect`. `onWorkerEvent` reports+persisted worker sessions discovered by the SDK's existing session tracker,+independently of model-emitted status markers:++```ts+await security.run(repository, {+ onWorkerEvent(event) {+ console.log(`Worker ${event.worker} observed`);+ },+});+```++The callback contains only `{ kind: "observed", worker: number }`. The scan-local+worker number matches `onActivity` and `onSessionEvent`; no prompts, raw thread+IDs, or session contents are exposed. Each session is reported once per run,+including nested workers and scan-associated validation or Deep Scan sessions.+On resume, already persisted workers can be reported again. Observation ends+with scan cost tracking, before `postScanPrompt`.++This works with the bundled Codex version. Persistence and polling can delay+notification, and missing notifications do not prove that delegation was skipped.+An observed session does not establish that a worker just started or that file+review has begun. The callback does not report failed spawn attempts, phase names,+or planned counts, and cannot act as a pre-dispatch gate. Use `maxCostUsd` or+`signal` for cancellation. Observer failures go to `onObserverError` without+stopping the scan.++`onWorkerStatus` remains available for tool-derived preflight status and+**best-effort** phase dispatch counts from model-emitted text markers. A missing+dispatch status does not mean delegation was skipped. `onSessionEvent` receives+saved events with thread IDs and worker numbers and can contain source code or+credentials. Deep scans additionally expose durable independent-review counts+through `onDeepProgress`: `completed`, `active`, and `maximum`. The maximum is a+configured cap, not a percentage denominator. `ScanOptions` lists all callbacks.Costs estimate API-equivalent model usage, not your bill or ChatGPT subscriptionallowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses thediff --git a/sdk/typescript/scripts/fixtures/package-consumer.ts b/sdk/typescript/scripts/fixtures/package-consumer.tsindex 0dbac682e..63425f7da 100644--- a/sdk/typescript/scripts/fixtures/package-consumer.ts+++ b/sdk/typescript/scripts/fixtures/package-consumer.ts@@ -31,6 +31,7 @@ import {type ScanComparisonResult,type ScanOptions,type ScanProgress,+ type ScanWorkerEvent,type ScanResult,type ScanSettings,type ValidationOptions,@@ -116,6 +117,10 @@ const options: ScanOptions = {onProgress(progress: ScanProgress) {progress.filesCompleted satisfies number;},+ onWorkerEvent(event: ScanWorkerEvent) {+ event.kind satisfies "observed";+ event.worker satisfies number;+ },};export async function scan(repository: string): Promise<ScanResult> {diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.tsindex 0e230e952..7fa812e1c 100644--- a/sdk/typescript/src/api.ts+++ b/sdk/typescript/src/api.ts@@ -73,6 +73,7 @@ import {ScanCostTracker,type ScanCost,type ScanSessionEvent,+ type ScanWorkerEvent,} from "./cost.js";import {DeepScanProgressTracker,@@ -310,7 +311,16 @@ export interface ScanOptions extends ScanSettings {onSessionEvent?: (event: ScanSessionEvent) => void;onProgress?: (progress: ScanProgress) => void;onDeepProgress?: (progress: DeepScanProgress) => void;+ /** Preflight status and best-effort, model-reported phase dispatch counts. */onWorkerStatus?: (status: ScanWorkerStatus) => void;+ /**+ * Reports each persisted worker session once when discovered during this run.+ * Worker numbers match onActivity/onSessionEvent. Includes saved workers on+ * resume; observation ends before postScanPrompt. Persistence and polling can+ * delay delivery. Does not report failed spawns, phase, or planned counts and+ * cannot gate dispatch; use maxCostUsd or signal for cancellation.+ */+ onWorkerEvent?: (event: ScanWorkerEvent) => void;onWarning?: (warning: string, details?: ScanWarningDetails) => void;onObserverError?: (observer: ScanObserverName, error: unknown) => void;signal?: AbortSignal;@@ -401,6 +411,7 @@ type ScanObserverName =| "onProgress"| "onDeepProgress"| "onWorkerStatus"+ | "onWorkerEvent"| "onStage"| "onWarning";@@ -1466,6 +1477,16 @@ export class CodexSecurity {options.onObserverError,activity,),+ onWorkerEvent:+ options.onWorkerEvent === undefined+ ? undefined+ : (event) =>+ notifyObserver(+ "onWorkerEvent",+ options.onWorkerEvent,+ options.onObserverError,+ event,+ ),onSessionEvent:options.onSessionEvent === undefined? undefineddiff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.tsindex c5a207999..68a914bf8 100644--- a/sdk/typescript/src/cost.ts+++ b/sdk/typescript/src/cost.ts@@ -23,6 +23,13 @@ import {export { estimateScanCost, formatUsd, type ScanCost } from "./cost-model.js";+/** A persisted worker session discovered during this run. Contains no model text. */+export interface ScanWorkerEvent {+ kind: "observed";+ /** Scan-local number shared with activity and session observers. */+ worker: number;+}+export interface ScanSessionEvent {threadId: string;parentThreadId: string | null;@@ -71,6 +78,7 @@ interface ScanCostTrackerOptions {onActivity?: (activity: ScanActivity) => void;onProgress?: (progress: ScanProgress) => void;onSessionEvent?: (event: ScanSessionEvent) => void;+ onWorkerEvent?: (event: ScanWorkerEvent) => void;onError?: (error: unknown) => void;}@@ -114,6 +122,7 @@ export class ScanCostTracker {readonly #workerProgress = new Map<string, number>();readonly #reportedProgress = new Set<string>();#threadId: string | null = null;+ #observingWorkers = true;#timer: NodeJS.Timeout | null = null;#pending: Promise<void> = Promise.resolve();#snapshot: ScanCostSnapshot = { usage: null, cost: null };@@ -145,7 +154,8 @@ export class ScanCostTracker {this.#options.onCost === undefined &&this.#options.onActivity === undefined &&this.#options.onProgress === undefined &&- this.#options.onSessionEvent === undefined+ this.#options.onSessionEvent === undefined &&+ this.#options.onWorkerEvent === undefined) {return;}@@ -187,7 +197,11 @@ export class ScanCostTracker {clearInterval(this.#timer ?? undefined);this.#timer = null;if (fallbackUsage !== undefined) this.recordUsage(fallbackUsage);- await this.refresh();+ try {+ await this.refresh();+ } finally {+ this.#observingWorkers = false;+ }if (this.#receipts.size > 0 || this.#snapshot.usage !== null)return this.#snapshot;const cost = estimateScanCost(this.#options.model, fallbackUsage);@@ -276,8 +290,13 @@ export class ScanCostTracker {}let worker: number | undefined;if (threadId !== this.#threadId) {- worker = this.#workers.get(threadId) ?? this.#workers.size + 1;- this.#workers.set(threadId, worker);+ worker = this.#workers.get(threadId);+ if (worker === undefined) {+ worker = this.#workers.size + 1;+ this.#workers.set(threadId, worker);+ if (this.#observingWorkers)+ this.#options.onWorkerEvent?.({ kind: "observed", worker });+ }}for (const event of session.events?.splice(0) ?? []) {this.#options.onSessionEvent?.({diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex e75a9cb76..b14ed5152 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -51,7 +51,7 @@ export type {ComponentPlanningOptions,} from "./component-plan.js";export { estimateScanCost } from "./cost.js";-export type { ScanCost, ScanSessionEvent } from "./cost.js";+export type { ScanCost, ScanSessionEvent, ScanWorkerEvent } from "./cost.js";export type { DeepScanProgress } from "./deep-progress.js";export type { CustomValidationResult } from "./custom-validation.js";export type { ScanActivity, ScanActivityStatus } from "./scan-activity.js";diff --git a/sdk/typescript/src/worker-progress.ts b/sdk/typescript/src/worker-progress.tsindex f788078c2..eb61c8e04 100644--- a/sdk/typescript/src/worker-progress.ts+++ b/sdk/typescript/src/worker-progress.ts@@ -41,6 +41,7 @@ export function scanPhaseLabel(value: ScanWorkerPhase | ScanPhase): string {}[value];}+/** Preflight is tool-derived; dispatch counts depend on model-emitted markers. */export type ScanWorkerStatus =| {kind: "preflight";diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.tsindex 59ea106da..48f567a35 100644--- a/sdk/typescript/tests-ts/api.test.ts+++ b/sdk/typescript/tests-ts/api.test.ts@@ -40,6 +40,7 @@ import {type ScanOptions,type ScanProgress,type ScanSessionEvent,+ type ScanWorkerEvent,ScanInterruptedError,} from "../src/index.js";import {@@ -3301,6 +3302,7 @@ describe("CodexSecurity orchestration", () => {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 = new TestClient(@@ -3378,6 +3380,7 @@ describe("CodexSecurity orchestration", () => {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) {@@ -3402,10 +3405,85 @@ describe("CodexSecurity orchestration", () => {),),).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",+ async (failure) => {+ const root = await temporaryDirectory();+ const repository = join(root, "repository");+ const codexHome = join(root, "codex-home");+ const scanDir = join(root, "scan");+ await mkdir(repository);+ await mkdir(codexHome);+ await mkdir(scanDir, { mode: 0o700 });+ const observed = Promise.withResolvers<void>();+ const workers: ScanWorkerEvent[] = [];+ const errors: ScanObserverName[] = [];+ const client = new TestClient(+ {},+ {+ environment: {},+ prepareRuntime: async () => preparedRuntime(codexHome),+ resolvePluginPython: async () => "/managed/python",+ prepareOutputDir: async () => scanDir,+ repositoryRevision: async () => "deadbeef",+ createCodex: () => ({+ startThread: () => ({+ id: "thread-1",+ async runStreamed() {+ await copyCompletedScan(root);+ await writeUsageSession(codexHome, "thread-1", {});+ async function* events(): AsyncGenerator<ThreadEvent> {+ for await (const event of completedEvents()) {+ yield event;+ if (event.type === "turn.started") {+ await writeUsageSession(+ codexHome,+ "worker-thread",+ {},+ { parent: "thread-1" },+ );+ await observed.promise;+ }+ }+ }+ return { events: events() };+ },+ }),+ }),+ },+ );+ try {+ const result = await client.run(repository, {+ onWorkerEvent: (event) => {+ workers.push(event);+ observed.resolve();+ if (failure === "sync") throw new Error("Optional observer failed");+ if (failure === "async")+ return Promise.reject(new Error("Optional observer failed"));+ },+ onObserverError: (observer) => errors.push(observer),+ });+ expect(result.threadId).toBe("thread-1");+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);+ expect(errors).toEqual(failure === "none" ? [] : ["onWorkerEvent"]);+ } finally {+ await client.close();+ }+ },+ );+test("provides only reviewed false positives to validation as a scan artifact", async () => {const { root, repository, codexHome, scanDir } = await scanDirectories();const reason =@@ -4004,17 +4082,21 @@ describe("CodexSecurity orchestration", () => {);test.each([- ["partial coverage", "partial", false],- ["unknown coverage", "unknown", false],- ["a failed scan", "failed", false],- ["a failed scan and follow-up", "failed", true],+ ["partial coverage", "partial", false, false],+ ["unknown coverage", "unknown", false, false],+ ["a failed scan", "failed", false, false],+ ["a failed scan and follow-up", "failed", true, false],+ ["an interrupted follow-up", "partial", false, true],] as const)("runs post-scan instructions after %s",- async (_scenario, outcome, followUpFails) => {+ async (_scenario, outcome, followUpFails, cancelFollowUp) => {const { root, repository, codexHome, scanDir } = await scanDirectories();const prompts: string[] = [];const warnings: string[] = [];+ const workers: ScanWorkerEvent[] = [];+ const observerErrors: string[] = [];const scanFails = outcome === "failed";+ const controller = new AbortController();const client = new TestClient({},@@ -4025,6 +4107,13 @@ describe("CodexSecurity orchestration", () => {id: "thread-1",async runStreamed(prompt: string) {prompts.push(prompt);+ await writeUsageSession(codexHome, "thread-1", {});+ await writeUsageSession(+ codexHome,+ `worker-${prompts.length}`,+ {},+ { parent: "thread-1" },+ );if (prompts.length === 1 && !scanFails) {await copyCompletedScan(root);const coveragePath = join(scanDir, "coverage.json");@@ -4044,10 +4133,12 @@ describe("CodexSecurity orchestration", () => {);return { events: completedEvents() };}+ if (prompts.length === 2 && cancelFollowUp) controller.abort();if (prompts.length === 2 && !followUpFails) {return { events: completedEvents() };}async function* failedEvents(): AsyncGenerator<ThreadEvent> {+ yield { type: "thread.started", thread_id: "thread-1" };yield {type: "turn.failed",error: {@@ -4067,15 +4158,25 @@ describe("CodexSecurity orchestration", () => {const result = client.run(repository, {postScanPrompt: "Record the scan cost.",+ signal: controller.signal,onWarning: (warning) => warnings.push(warning),+ onWorkerEvent: (event) => {+ workers.push(event);+ throw new Error("optional worker observer failed");+ },+ onObserverError: (observer) => observerErrors.push(observer),});- if (scanFails) {+ if (cancelFollowUp) {+ await expect(result).rejects.toBeInstanceOf(ScanInterruptedError);+ } else if (scanFails) {await expect(result).rejects.toThrow("The scan failed.");} else {expect((await result).coverage.completeness).toBe(outcome);}expect(prompts.at(-1)).toBe("Record the scan cost.");expect(prompts).toHaveLength(2);+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);+ expect(observerErrors).toEqual(["onWorkerEvent"]);expect(warnings).toEqual(followUpFails? [diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.tsindex 021656058..c35856f42 100644--- a/sdk/typescript/tests-ts/cost.test.ts+++ b/sdk/typescript/tests-ts/cost.test.ts@@ -8,6 +8,7 @@ import {estimateScanCost,ScanCostTracker,type ScanSessionEvent,+ type ScanWorkerEvent,} from "../src/cost.js";import type { ScanActivity } from "../src/scan-activity.js";import { formatTokenUsage, tokenUsage } from "../src/cost-model.js";@@ -554,6 +555,97 @@ describe("live scan cost tracking", () => {}});+ test.each([...parentFields])(+ "observes worker metadata without status markers or usage via %s",+ async (parentField) => {+ const home = await codexHome();+ const parent = await writeSession(home, "scan-thread", {});+ await appendSessionItem(parent, {+ type: "message",+ role: "assistant",+ content: [+ {+ type: "output_text",+ text:+ 'CODEX_SECURITY_WORKER_STATUS {"phase":"validation","planned":1,"started":1}\n' ++ '{"type":"session_meta","payload":{"id":"fictional-worker","parent_thread_id":"scan-thread"}}',+ },+ ],+ });+ await writeSession(+ home,+ "unrelated-worker",+ {},+ { parent: "other-scan" },+ );+ const workers: ScanWorkerEvent[] = [];+ const tracker = new ScanCostTracker({+ codexHome: home,+ model: "gpt-5.6-sol",+ onWorkerEvent: (event) => workers.push(event),+ });+ tracker.start("scan-thread");+ try {+ await tracker.refresh();+ expect(workers).toEqual([]);+ const path = join(parse(parent).dir, "rollout-worker-thread.jsonl");+ const metadata =+ JSON.stringify({+ type: "session_meta",+ payload: {+ id: "worker-thread",+ ...parentMetadata("scan-thread", parentField),+ instructions: "Synthetic private instructions",+ },+ }) + "\n";+ await writeFile(path, metadata);+ await tracker.refresh();+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);+ await writeFile(path.replace(".jsonl", "-copy.jsonl"), metadata);+ await tracker.refresh();+ await tracker.refresh();+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);+ } finally {+ await tracker.stop();+ }+ },+ );++ test("polls for workers with only a worker observer and keeps concurrent scans separate", async () => {+ const home = await codexHome();+ const workers: ScanWorkerEvent[][] = [[], []];+ const trackers = workers.map(+ (events) =>+ new ScanCostTracker({+ codexHome: home,+ model: "gpt-5.6-sol",+ onWorkerEvent: (event) => events.push(event),+ }),+ );+ trackers.forEach((tracker, index) => tracker.start(`scan-${index}`));+ try {+ await Promise.all(trackers.map((tracker) => tracker.refresh()));+ await writeSession(home, "worker-0", {}, { parent: "scan-0" });+ await writeSession(home, "worker-1", {}, { parent: "scan-1" });+ await waitFor(() => workers.every((events) => events.length === 1));+ expect(workers).toEqual([+ [{ kind: "observed", worker: 1 }],+ [{ kind: "observed", worker: 1 }],+ ]);+ } finally {+ await Promise.all(trackers.map((tracker) => tracker.stop()));+ }+ const resumed: ScanWorkerEvent[] = [];+ const tracker = new ScanCostTracker({+ codexHome: home,+ model: "gpt-5.6-sol",+ onWorkerEvent: (event) => resumed.push(event),+ });+ tracker.start("scan-0");+ await tracker.stop();+ expect(resumed).toEqual([{ kind: "observed", worker: 1 }]);+ });+test("counts the scan and delegated workers without including other scans", async () => {const home = await codexHome();const parent = await writeSession(home, "scan-thread", {@@ -667,11 +759,13 @@ describe("live scan cost tracking", () => {const unrelated = await writeSession(home, "unrelated-thread", usage);await appendSessionItem(unrelated, message("Unrelated output."));const events: ScanSessionEvent[] = [];+ const workers: ScanWorkerEvent[] = [];const tracker = new ScanCostTracker({codexHome: home,scanDirectory,model: "gpt-5.6-sol",onSessionEvent: (event) => events.push(event),+ onWorkerEvent: (event) => workers.push(event),});tracker.start("scan-thread");await tracker.refresh();@@ -679,6 +773,7 @@ describe("live scan cost tracking", () => {false,);+ expect(workers).toEqual([]);if (missing === "parent") {await writeSession(home, "parent-worker", usage, {parent: "scan-thread",@@ -691,6 +786,14 @@ describe("live scan cost tracking", () => {await tracker.refresh();await tracker.stop();+ expect(workers).toEqual(+ missing === "parent"+ ? [+ { kind: "observed", worker: 1 },+ { kind: "observed", worker: 2 },+ ]+ : [{ kind: "observed", worker: 1 }],+ );const workerEvents = events.filter((event) => event.threadId === "worker-thread",);@@ -803,11 +906,13 @@ describe("live scan cost tracking", () => {},);const events: ScanSessionEvent[] = [];+ const workers: ScanWorkerEvent[] = [];const tracker = new ScanCostTracker({codexHome: home,model: "gpt-5.6-sol",scanDirectory,onSessionEvent: (event) => events.push(event),+ onWorkerEvent: (event) => workers.push(event),});tracker.start("scan-thread");@@ -815,6 +920,9 @@ describe("live scan cost tracking", () => {input_tokens: 1_425,output_tokens: 14,});+ expect(workers).toEqual(+ [1, 2, 3].map((worker) => ({ kind: "observed", worker })),+ );const labels = new Map(events.map(({ threadId, worker }) => [threadId, worker]),);@@ -1125,6 +1233,7 @@ describe("live scan cost tracking", () => {const activities: ScanActivity[] = [];const progress: ScanProgress[] = [];const events: ScanSessionEvent[] = [];+ const workers: ScanWorkerEvent[] = [];const tracker = new ScanCostTracker({codexHome: home,model: "gpt-5.6-terra",@@ -1133,6 +1242,7 @@ describe("live scan cost tracking", () => {onActivity: (activity) => activities.push(activity),onProgress: (update) => progress.push(update),onSessionEvent: (event) => events.push(event),+ onWorkerEvent: (event) => workers.push(event),});tracker.start("scan-thread");@@ -1154,6 +1264,7 @@ describe("live scan cost tracking", () => {estimatedUsd: 0.003065,},});+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);expect(activities).toEqual([expect.objectContaining({kind: "message",