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(sdk): report worker sessions without model progress markers (#962)

mldangelo-oaiff95e6799143
diff --git a/sdk/typescript/README.md b/sdk/typescript/README.md
index 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 subscription
allowance. Use `cost.estimatedUsdRange` for reporting. `maxCostUsd` uses the
diff --git a/sdk/typescript/scripts/fixtures/package-consumer.ts b/sdk/typescript/scripts/fixtures/package-consumer.ts
index 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.ts
index 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
? undefined
diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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",