nanocoai/nanoclaw / .claude/skills/add-codex
add-codex
FlaggedUse Codex (OpenAI's codex app-server) as a full agent provider — planning, tool orchestration, MCP tools, server-side history, session resume — alongside or instead of Claude. ChatGPT subscription or OpenAI API key, vault-only via the selected gateway. Per-group via `ncl groups config update --provider codex`. Distinct from using OpenAI as an MCP tool (where Claude remains the planner).
payload/container/agent-runner/src/providers/codex.ts
View on GitHub// This module never imports the runtime contract (provider-contracts/codex.ts):
// registration is two-step, so it compiles and runs on a core that predates the
// contract seam. The contract attaches itself through registerProviderContract.
import { registerProvider } from './provider-registry.js';
import type {
AgentProvider,
AgentQuery,
McpServerConfig,
ProviderEvent,
ProviderOptions,
QueryInput,
} from './types.js';
import {
type AppServer,
type CodexConfigPlan,
type CodexMemorySessionHook,
type JsonRpcNotification,
STALE_THREAD_RE,
attachCodexAutoApproval,
codexInferenceSection,
codexRuntimeOwnership,
codexTone,
initializeCodexAppServer,
interruptCodexTurn,
killCodexAppServer,
spawnCodexAppServer,
startCodexTurn,
startOrResumeCodexThread,
steerCodexTurn,
writeCodexConfigToml,
} from './codex-app-server.js';
const TURN_TIMEOUT_MS = 10 * 60 * 1000;
export interface CodexRuntimeDeps {
writeCodexConfigToml: typeof writeCodexConfigToml;
spawnCodexAppServer: typeof spawnCodexAppServer;
attachCodexAutoApproval: typeof attachCodexAutoApproval;
initializeCodexAppServer: typeof initializeCodexAppServer;
startOrResumeCodexThread: typeof startOrResumeCodexThread;
startCodexTurn: typeof startCodexTurn;
steerCodexTurn: typeof steerCodexTurn;
interruptCodexTurn: typeof interruptCodexTurn;
killCodexAppServer: typeof killCodexAppServer;
}
/**
* Structural mirror of the contract core's `ResolvedRuntimeConfiguration` —
* what `createProvider` hands the factory after running the contract's
* configuration resolves. Mirrored, not imported: the type lives in
* `provider-contracts/registry.ts`, which a pre-contract core does not have.
*/
export interface CodexResolvedConfiguration {
executionPolicy?: unknown;
inference?: unknown;
mcpServers?: unknown;
tone?: unknown;
}
/**
* The production runtime deps. Exported as one mutable object so a test can
* swap in fakes for a provider that core constructs (createProvider gives the
* test no constructor access); every instance built without explicit deps
* reads through this object.
*/
export const defaultCodexRuntimeDeps: CodexRuntimeDeps = {
writeCodexConfigToml,
spawnCodexAppServer,
attachCodexAutoApproval,
initializeCodexAppServer,
startOrResumeCodexThread,
startCodexTurn,
steerCodexTurn,
interruptCodexTurn,
killCodexAppServer,
};
function classifyError(message: string): string | undefined {
if (/auth|api key|unauthorized|login|credential/i.test(message)) return 'auth';
if (/quota|rate limit|insufficient|billing|credit/i.test(message)) return 'quota';
if (/sandbox|permission|denied/i.test(message)) return 'sandbox';
if (/thread|conversation|session/i.test(message)) return 'stale-session';
return undefined;
}
export class CodexProvider implements AgentProvider {
readonly supportsNativeSlashCommands = false;
private readonly mcpServers: Record<string, McpServerConfig>;
private readonly inference: CodexConfigPlan['inference'];
private readonly tone: ReturnType<typeof codexTone.toSettings>;
private readonly runtime: CodexRuntimeDeps;
private memorySessionHook?: CodexMemorySessionHook;
/**
* `configuration` is present on a contract core: core has already run the
* contract's inference and MCP resolves and hands the results over, so
* they are consumed as-is. Without it (a pre-contract core) the provider
* derives the same values itself, exactly as it always did.
*/
constructor(
options: ProviderOptions = {},
runtime: CodexRuntimeDeps = defaultCodexRuntimeDeps,
configuration?: CodexResolvedConfiguration,
) {
this.runtime = runtime;
this.tone = (configuration?.tone as typeof this.tone | undefined) ?? codexTone.toSettings(codexTone.default);
if (configuration) {
this.inference = configuration.inference as CodexConfigPlan['inference'];
this.mcpServers = configuration.mcpServers as Record<string, McpServerConfig>;
} else {
this.mcpServers = options.mcpServers ?? {};
// `speed` exists on ProviderOptions only from the contract core on; read
// it structurally so this compiles against the older options type too.
const { speed } = options as ProviderOptions & { speed?: string };
this.inference = codexInferenceSection({ model: options.model, effort: options.effort, speed });
}
}
registerMemorySessionHook(hook: CodexMemorySessionHook): void {
this.memorySessionHook = hook;
}
isSessionInvalid(err: unknown): boolean {
const msg = err instanceof Error ? err.message : String(err);
return STALE_THREAD_RE.test(msg);
}
query(input: QueryInput): AgentQuery {
if (!this.memorySessionHook) throw new Error('Codex memory session hook was not registered');
const memorySessionHook = this.memorySessionHook;
const pending: string[] = [input.prompt];
let waiting: (() => void) | null = null;
let ended = false;
let aborted = false;
let activeServer: AppServer | null = null;
let activeThreadId: string | null = null;
let activeTurnId: string | null = null;
let wakeActiveTurn: (() => void) | null = null;
const wake = (): void => {
waiting?.();
waiting = null;
};
const pushOrSteer = (message: string): void => {
if (activeServer && activeThreadId && activeTurnId) {
void this.runtime.steerCodexTurn(activeServer, activeThreadId, activeTurnId, message).catch(() => {
pending.push(message);
wake();
});
return;
}
pending.push(message);
wake();
};
// An image note belongs to the turn that made the image, which the event
// names (a sub-agent's turn/started can move activeTurnId); a sub-agent's
// image is noted in its own turn, so only a sub-agent that can send_file
// delivers it. Never queued as a new turn: the runner never asked for one.
const steerImageNote = (savedPath: string, threadId: string, turnId: string): void => {
if (!activeServer) {
console.error(`[codex] image note dropped, query ended: ${savedPath}`);
return;
}
const note = codexImageSavedNote(savedPath);
void this.runtime.steerCodexTurn(activeServer, threadId, turnId, note).then(
() => console.error(`[codex] image note steered: ${savedPath}`),
(err) =>
console.error(
`[codex] image note dropped: ${savedPath}: ${err instanceof Error ? err.message : String(err)}`,
),
);
};
const self = this;
async function* gen(): AsyncGenerator<ProviderEvent> {
// On a contract core the contract's beforeQuery has already written
// config.toml and hooks.json for this query (see codexRuntimeOwnership);
// this direct write is the pre-contract core's path only.
if (!codexRuntimeOwnership.contractOwnsRuntimeFiles) {
self.runtime.writeCodexConfigToml(self.mcpServers, memorySessionHook, self.inference);
}
const server = self.runtime.spawnCodexAppServer();
activeServer = server;
self.runtime.attachCodexAutoApproval(server);
let threadId: string | undefined = input.continuation;
let initYielded = false;
try {
await self.runtime.initializeCodexAppServer(server);
threadId = await self.runtime.startOrResumeCodexThread(server, threadId, {
model: self.inference.model,
...self.tone,
cwd: input.cwd,
baseInstructions: input.systemContext?.instructions,
});
activeThreadId = threadId;
while (!aborted) {
while (pending.length === 0 && !ended && !aborted) {
await new Promise<void>((resolve) => {
waiting = resolve;
});
}
if (aborted) return;
if (pending.length === 0 && ended) return;
const text = pending.shift()!;
yield* runOneTurn(
server,
threadId,
text,
self.inference.model,
self.inference.effort,
input.cwd,
(turnId) => {
activeTurnId = turnId;
},
() => {
activeTurnId = null;
},
() => initYielded,
() => {
initYielded = true;
},
() => aborted,
(waker) => {
wakeActiveTurn = waker;
},
self.runtime.startCodexTurn,
steerImageNote,
);
}
} finally {
activeTurnId = null;
activeThreadId = null;
activeServer = null;
wakeActiveTurn = null;
self.runtime.killCodexAppServer(server);
}
}
return {
push: pushOrSteer,
end: () => {
ended = true;
wake();
},
abort: () => {
aborted = true;
if (activeServer && activeThreadId && activeTurnId) {
void this.runtime.interruptCodexTurn(activeServer, activeThreadId, activeTurnId).catch(() => {});
}
wakeActiveTurn?.();
wake();
},
events: gen(),
};
}
}
async function* runOneTurn(
server: AppServer,
threadId: string,
inputText: string,
model: string | undefined,
effort: string | undefined,
cwd: string,
setActiveTurn: (turnId: string) => void,
clearActiveTurn: () => void,
hasInit: () => boolean,
markInit: () => void,
isAborted: () => boolean,
setAbortWaker: (waker: (() => void) | null) => void,
startTurn: typeof startCodexTurn,
onImageSaved: (savedPath: string, threadId: string, turnId: string) => void,
): AsyncGenerator<ProviderEvent> {
const state: { error: Error | null } = { error: null };
let resultText = '';
let turnDone = false;
let turnId: string | null = null;
// A finished turn can no longer absorb steered input: codex's turn/steer
// against a completed turn resolves as a no-op, so a follow-up routed there
// is lost silently. Clear the active-turn marker the moment the turn ends —
// before the generator drains and tears down in its `finally` — so
// pushOrSteer queues any racing follow-up into a fresh turn instead.
const finishTurn = (): void => {
turnDone = true;
clearActiveTurn();
};
const buffer: ProviderEvent[] = [];
let waker: (() => void) | null = null;
const kick = (): void => {
waker?.();
waker = null;
};
setAbortWaker(kick);
const handler = (n: JsonRpcNotification): void => {
const method = n.method;
const params = n.params ?? {};
buffer.push({ type: 'activity' });
switch (method) {
case 'thread/started': {
const thread = params.thread as { id?: string } | undefined;
if (thread?.id && !hasInit()) {
markInit();
buffer.push({ type: 'init', continuation: thread.id });
}
break;
}
case 'turn/started': {
const turn = params.turn as { id?: string } | undefined;
if (turn?.id) {
turnId = turn.id;
setActiveTurn(turn.id);
}
break;
}
case 'item/agentMessage/delta': {
const delta = params.delta as string | undefined;
if (delta) resultText += delta;
break;
}
case 'item/completed': {
const item = params.item as { type?: string; text?: string; savedPath?: string } | undefined;
if (item?.type === 'agentMessage' && item.text) resultText = item.text;
const { threadId: itemThread, turnId: itemTurn } = params as { threadId?: string; turnId?: string };
if (item?.type === 'imageGeneration' && item.savedPath && itemThread && itemTurn) {
onImageSaved(item.savedPath, itemThread, itemTurn);
}
break;
}
case 'thread/status/changed': {
const status = params.status as string | undefined;
if (status) buffer.push({ type: 'progress', message: `status: ${status}` });
break;
}
case 'error': {
const err = params.error as { message?: string; additionalDetails?: string | null } | undefined;
const msg = [err?.message, err?.additionalDetails].filter(Boolean).join(': ') || 'Codex turn failed';
state.error = new Error(msg);
finishTurn();
break;
}
case 'turn/completed': {
const turn = params.turn as
| { error?: { message?: string; additionalDetails?: string | null } | null; items?: unknown[] }
| undefined;
const agentMessage = turn?.items
?.filter((item): item is { type: string; text?: string } => typeof item === 'object' && item !== null)
.find((item) => item.type === 'agentMessage' && item.text);
if (agentMessage?.text) resultText = agentMessage.text;
if (turn?.error) {
const msg =
[turn.error.message, turn.error.additionalDetails].filter(Boolean).join(': ') || 'Codex turn failed';
state.error = new Error(msg);
}
finishTurn();
break;
}
default:
break;
}
kick();
};
server.notificationHandlers.push(handler);
// A dead app-server can't send the notification this turn is parked on —
// end the turn immediately with the real cause instead of the 10-min timeout.
const onServerExit = (err: Error): void => {
if (turnDone) return;
state.error = err;
finishTurn();
kick();
};
server.exitHandlers.push(onServerExit);
const timer = setTimeout(() => {
state.error = new Error(`Turn timed out after ${TURN_TIMEOUT_MS}ms`);
finishTurn();
kick();
}, TURN_TIMEOUT_MS);
try {
if (!hasInit()) {
markInit();
buffer.push({ type: 'init', continuation: threadId });
}
turnId = await startTurn(server, {
threadId,
inputText,
model,
effort,
cwd,
});
setActiveTurn(turnId);
if (isAborted()) return;
while (true) {
while (buffer.length > 0) {
yield buffer.shift()!;
}
if (turnDone || isAborted()) break;
await new Promise<void>((resolve) => {
waker = resolve;
});
waker = null;
}
while (buffer.length > 0) yield buffer.shift()!;
if (isAborted()) return;
if (state.error) {
yield {
type: 'error',
message: state.error.message,
retryable: false,
classification: classifyError(state.error.message),
};
throw state.error;
}
yield { type: 'result', text: resultText || null };
} finally {
clearTimeout(timer);
clearActiveTurn();
setAbortWaker(null);
const idx = server.notificationHandlers.indexOf(handler);
if (idx >= 0) server.notificationHandlers.splice(idx, 1);
const exitIdx = server.exitHandlers.indexOf(onServerExit);
if (exitIdx >= 0) server.exitHandlers.splice(exitIdx, 1);
}
}
/**
* Codex tells the model a generated image is already on screen, so it never
* sends it. Steered into the same turn, this note corrects that and leaves
* delivery to the original request: a chat ask gets the file, while a
* save-only ask or a task that did not ask to notify anyone does not.
*/
export function codexImageSavedNote(savedPath: string): string {
return (
`<system>Your image generation tool saved ${savedPath}. Nobody has seen it: it is not shown automatically. ` +
"Follow the original request's delivery instructions. If whoever asked expects to see the image, send it with send_file. " +
'If the request only asked to save it, said not to send it, or is a task that did not ask you to notify anyone, do not send it.</system>'
);
}
// Function-form registration only — the one shape both core generations
// accept. A contract core passes the resolved configuration as the second
// argument; a pre-contract core passes nothing there.
registerProvider(
'codex',
(opts, configuration?: CodexResolvedConfiguration) => new CodexProvider(opts, defaultCodexRuntimeDeps, configuration),
);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |