Expose Goal APIs in the TypeScript SDK #29283

Summary

Please expose first-class Goal mode APIs in @openai/codex-sdk for TypeScript.

The app-server protocol already has thread goal RPCs:

• thread/goal/set
• thread/goal/get
• thread/goal/clear

But the current TypeScript SDK primarily exposes Thread.run() / Thread.runStreamed() and wraps codex exec --experimental-json. That makes it difficult for SDK users to set, read, pause, resume, or clear goals programmatically without relying on prompt text such as "create a goal".

Proposed API shape

A possible high-level TypeScript API could be:

await thread.setGoal("Finish the migration and add tests", {
  tokenBudget: 200_000,
});

const goal = await thread.getGoal();

await thread.pauseGoal();
await thread.resumeGoal();
await thread.clearGoal();

Possible lower-level status support:

await thread.setGoalStatus("paused");
await thread.setGoalStatus("active");

Why this matters

Goal mode is useful for long-running Codex work, but SDK users need a stable typed surface rather than prompt-level workarounds. A typed API would let integrations:

• create goals deterministically
• inspect current goal state and usage accounting
• pause/resume/clear active goals from external controllers
• avoid sending /goal ... or natural-language instructions through Thread.run() and hoping they are interpreted as control commands
• build long-running automation around Goal mode using the same primitives as the app-server protocol

Current workaround

Today, an SDK user can only approximate this by doing something like:

await thread.run(`Create a Codex goal with this exact objective: ${objective}`);

That depends on model/tool behavior rather than a typed SDK contract, and it does not provide direct getGoal, pauseGoal, resumeGoal, or clearGoal operations.

Related issues

• Feature request: clarify and support scalable remote execution patterns #23854 discusses that the TypeScript SDK currently wraps local codex exec --experimental-json and does not expose a remote app-server / worker protocol client.
• Python SDK generated protocol types omit thread goal RPCs #25565 mentions the app-server thread goal RPCs and generated protocol/schema gap for Python SDK types.
• Add wait/wake support for goals without spending tokens #28144 discusses long-running goals and SDK/app-server integrations that drive them.

Expected behavior

The TypeScript SDK should expose stable Goal APIs backed by the existing app-server goal RPCs, or otherwise document the intended TypeScript integration path for programmatic Goal mode control.