Official
codex
Codex agent provider: runs the Codex CLI's app-server for each account.
The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/codex@0.2.4
Permissions in 0.2.4
Files
audit.test.ts19.1 KB
// These cases use the Codex 0.169.0 schema shapes from the provider audit.
import { test } from "node:test";
import assert from "node:assert/strict";
import { fakeApi, settle } from "../sdk/testing.ts";
import type { PeerScript } from "../sdk/testing.ts";
import type { Event } from "./types.ts";
import { testAgent } from "./testing.test.ts";
import { newSession } from "./agent.ts";
import * as map from "./map.ts";
import * as wire from "./wire.ts";
import * as requests from "./requests.ts";
import { buildOptions, startParams, resumeParams, forkParams } from "./params.ts";
import { mergeLimits } from "./quota.ts";
function setup(script: PeerScript = () => {}) {
const api = fakeApi({ onSpawn: () => (message, peer) => {
if (message.method === "initialize") peer.reply(message, { userAgent: "divergence/0.169.0" });
else script(message, peer);
} });
const agent = testAgent(api);
const events: Event[] = [];
agent.emit = (event) => events.push(event);
agent.sessions.set("chat", newSession("/work"));
return { agent, api, events };
}
const items: wire.Item[] = [
{ type: "sleep", id: "sleep", durationMs: 1500 },
{ type: "hookPrompt", id: "hook", fragments: [{ text: "First hook.", hookRunId: "h1" }, { text: "Second hook.", hookRunId: "h2" }] },
{ type: "enteredReviewMode", id: "enter", review: "Review the current changes." },
{ type: "exitedReviewMode", id: "exit", review: "The review found no issues." },
{ type: "functionCallOutput", id: "output", name: "inspect", namespace: "tools", output: [{ type: "input_text", text: "Done." }, { type: "input_image", image_url: "data:image/webp;base64,AAAA" }] },
];
test("new native display items retain their content in live events and history", () => {
const { agent, events } = setup();
for (const item of items) {
agent.onNotification("item/started", { threadId: "chat", item });
agent.onNotification("item/completed", { threadId: "chat", item });
assert.ok(map.transcriptItem(wire.item.parse(item)));
}
const sleep = events.filter((event) => event.event === "tool_call_started").filter((event) => event.id === "sleep");
assert.equal(sleep.length, 1);
assert.equal(sleep[0].status, "running");
assert.ok(events.some((event) => event.event === "tool_call_updated" && event.id === "sleep" && event.status === "completed"));
assert.deepEqual(events.filter((event) => event.event === "notice").map((event) => event.message), ["First hook.\n\nSecond hook.", "Entered review mode: Review the current changes.", "The review found no issues."]);
const output = map.toolCallFromItem(items[4]);
assert.equal(output?.name, "tools.inspect");
assert.deepEqual(output?.content, [{ type: "text", text: "Done." }, { type: "image", mimeType: "image/webp", data: "AAAA" }]);
assert.ok(events.some((event) => event.event === "tool_call_updated" && event.id === "output" && event.content?.length === 2));
assert.equal(map.toolCallFromItem({ type: "functionCallOutput", id: "text", name: "read", output: "Raw output." })?.content?.[0].type, "text");
assert.equal(map.itemType({ type: "mcpAppUi" }), null);
});
test("file-backed images retain their identity without inventing bytes or paths", () => {
const generated = map.toolCallFromItem({ type: "imageGeneration", id: "g", status: "completed", result: "", fileId: "file-generated" });
assert.match(JSON.stringify(generated?.content), /file-generated/);
assert.match(JSON.stringify(map.userBlocks([{ type: "image", fileId: "file-user" }])), /file-user/);
const output = map.toolCallFromItem({ type: "functionCallOutput", id: "f", name: "image", output: [{ type: "input_image", file_id: "file-output" }, { type: "input_audio", audio_url: "data:audio/wav;base64,AAAA" }] });
assert.match(JSON.stringify(output?.content), /file-output/);
assert.match(JSON.stringify(output?.content), /audio/);
const saved = map.toolCallFromItem({ type: "imageGeneration", id: "g", fileId: "file-generated", savedPath: "/work/image.webp" });
assert.deepEqual(saved?.content, [{ type: "image", mimeType: "image/webp", path: "/work/image.webp" }]);
});
test("native human, stdin and network approvals show the operation and constrain decisions", async () => {
const { agent, api, events } = setup();
await agent.client();
for (const [index, kind] of ["humanCommand", "writeStdin", "command"].entries()) {
const params = { kind, threadId: "chat", itemId: `item-${index}`, command: kind === "humanCommand" ? "deploy" : null, networkApprovalContext: { host: "example.com", protocol: "https" }, proposedExecpolicyAmendment: ["deploy"], proposedNetworkPolicyAmendments: [{ host: "example.com", action: "allow" }, { host: "example.com", action: "deny" }] };
api.peers[0].send({ jsonrpc: "2.0", id: 100 + index, method: "item/commandExecution/requestApproval", params });
await settle();
const card = events.filter((event) => event.event === "approval").at(-1)!;
assert.match(JSON.stringify(card.toolCall), /example.com/);
if (kind === "humanCommand") {
assert.deepEqual(card.options!.map((option) => option.id), ["accept", "decline", "cancel"]);
await agent.respondToApproval({ approvalId: card.id, optionId: "acceptForSession" });
assert.deepEqual((await api.peers[0].waitFor((message) => message.id === 100 + index)).result, { decision: "decline" });
} else {
if (kind === "writeStdin") assert.equal(card.toolCall?.name, "write_stdin");
const decision = kind === "command" ? "acceptWithExecpolicyAmendment" : "network:1";
await agent.respondToApproval({ approvalId: card.id, optionId: decision });
assert.deepEqual((await api.peers[0].waitFor((message) => message.id === 100 + index)).result, { decision: kind === "command" ? { acceptWithExecpolicyAmendment: { execpolicy_amendment: ["deploy"] } } : { applyNetworkPolicyAmendment: { network_policy_amendment: { host: "example.com", action: "deny" } } } });
}
}
assert.deepEqual(requests.commandDecisions({}).options, requests.APPROVAL_OPTIONS);
assert.deepEqual(requests.commandDecisions({ proposedNetworkPolicyAmendments: [{ host: "example.com", action: "allow" }] }).decisions.get("network:0"), { applyNetworkPolicyAmendment: { network_policy_amendment: { host: "example.com", action: "allow" } } });
});
test("sparse quota pushes keep reset credits and separate buckets without authorizing recovery", async () => {
const full = { accountId: "account", ordinaryUsageAllowed: false, rateLimitResetCredits: { availableCount: 2 }, rateLimits: { limitId: "codex", limitName: "Codex", primary: { usedPercent: 80, windowDurationMins: 300, resetsAt: 1000 }, secondary: { usedPercent: 10, windowDurationMins: 10080 } } };
const { agent, events } = setup((message, peer) => {
if (message.method === "account/read") peer.reply(message, { account: {}, requiresOpenaiAuth: true, workspaceRouting: { chatgptAccountId: "account" } });
if (message.method === "account/rateLimits/read") peer.reply(message, full);
});
await agent.usageLimits();
agent.onNotification("account/rateLimits/updated", { rateLimits: { limitId: "codex", limitName: null, primary: { usedPercent: 90, resetsAt: null }, secondary: null } });
let limits = events.filter((event) => event.event === "usage_limits").at(-1)!;
assert.equal(limits.resetCredits, 2);
assert.deepEqual(limits.windows!.map((window) => window.usedPercent), [90, 10]);
assert.equal(limits.windows![0].windowMinutes, 300);
assert.equal(limits.windows![0].resetsAt, new Date(1000 * 1000).toISOString());
assert.equal(limits.recovery?.availability, "unknown");
agent.onNotification("account/rateLimits/updated", { rateLimits: { limitId: "images", primary: { usedPercent: 40, windowDurationMins: 60 } } });
limits = events.filter((event) => event.event === "usage_limits").at(-1)!;
assert.deepEqual(limits.windows!.map((window) => [window.id, window.usedPercent]), [["codex:primary", 90], ["codex:secondary", 10], ["images:primary", 40]]);
assert.equal(limits.resetCredits, 2);
agent.onNotification("account/updated", {});
agent.onNotification("account/rateLimits/updated", { rateLimits: { limitId: "images", primary: { usedPercent: 5 } } });
assert.equal(events.filter((event) => event.event === "usage_limits").at(-1)?.resetCredits, undefined);
const merged = mergeLimits(full, { rateLimitsByLimitId: { codex: { primary: { usedPercent: 15 } } } });
assert.equal(merged.rateLimitsByLimitId?.codex.primary?.usedPercent, 15);
});
test("speed defaults prefer valid config tiers after chat overrides", () => {
const models = [{ id: "model", serviceTiers: [{ id: "fast" }], defaultServiceTier: "default" }];
const speed = (config: wire.Config, options = {}) => buildOptions(models, config, options).find((option) => option.id === "service_tier")?.value;
assert.equal(speed(wire.config.parse({ service_tier: "fast" })), "fast");
assert.equal(speed({ service_tier: "fast" }, { service_tier: "default" }), "default");
assert.equal(speed({ service_tier: "invalid" }), "default");
});
test("skills prefer interface descriptions while preserving legacy fallbacks", async () => {
const { agent } = setup((message, peer) => {
if (message.method === "skills/list") peer.reply(message, { data: [{ skills: [
{ name: "new", path: "/new", interface: { shortDescription: "Current." }, shortDescription: "Legacy.", description: "Full." },
{ name: "old", path: "/old", shortDescription: "Legacy." },
{ name: "full", path: "/full", description: "Full." },
] }] });
});
assert.deepEqual((await agent.listSkills({ workspace: "/work" })).skills.map((skill) => skill.description), ["Current.", "Legacy.", "Full."]);
});
const providerCatalog = { data: [{ id: "openai", name: "OpenAI" }, { id: "gateway", name: "My gateway" }], defaultProviderId: "openai", canChangeDefault: true };
test("provider catalogs stay separate and selecting one clears incompatible model settings", async () => {
const listed: unknown[] = [];
let savedProvider = "openai";
const { agent, api } = setup((message, peer) => {
if (message.method === "config/read") peer.reply(message, { config: { model_provider: "openai", model: "openai-model", service_tier: "fast" } });
if (message.method === "modelProvider/list") peer.reply(message, providerCatalog);
if (message.method === "model/list") {
listed.push(message.params);
peer.reply(message, { data: [{ id: `${message.params.modelProvider}-model` }], nextCursor: null });
}
if (message.method === "thread/resume") {
savedProvider = String(message.params.modelProvider ?? savedProvider);
peer.reply(message, { modelProvider: savedProvider });
}
if (message.method === "thread/start") peer.reply(message, { thread: { id: "created" }, modelProvider: "gateway" });
if (message.method === "thread/fork") peer.reply(message, { thread: { id: "forked" }, modelProvider: "gateway" });
});
const first = await agent.listOptions({ workspace: "/work" });
assert.equal(first.options.find((option) => option.id === "model_provider")?.value, "openai");
Object.assign(agent.sessions.get("chat")!.options, { model: "openai-model", reasoning: "high", service_tier: "fast" });
const changed = await agent.setOption({ sessionId: "chat", optionId: "model_provider", value: "gateway" });
assert.equal(changed.options.find((option) => option.id === "model")?.value, "gateway-model");
assert.deepEqual(agent.sessions.get("chat")?.options, { model_provider: "gateway" });
assert.deepEqual(listed, [{ cursor: null, limit: 100, modelProvider: "openai" }, { cursor: null, limit: 100, modelProvider: "gateway" }]);
await agent.listOptions({ workspace: "/work" });
assert.equal(listed.length, 2);
await assert.rejects(agent.setOption({ sessionId: "chat", optionId: "model_provider", value: "unknown" }), /did not list/);
agent.sessions.get("chat")!.run = "running";
await assert.rejects(agent.setOption({ sessionId: "chat", optionId: "model_provider", value: "openai" }), /current turn/);
agent.sessions.get("chat")!.run = null;
await agent.createSession({ workspace: "/work", options: { model_provider: "gateway" } });
await agent.forkSession({ sessionId: "created", workspace: "/work" });
assert.equal(agent.sessions.get("created")?.options.model_provider, "gateway");
assert.equal(agent.sessions.get("forked")?.options.model_provider, "gateway");
await agent.resumeSession({ sessionId: "chat", workspace: "/work", options: {} });
assert.equal(agent.sessions.get("chat")?.options.model_provider, "gateway");
const session = { options: { model_provider: "gateway" } };
for (const params of [startParams(session), resumeParams("chat", session), forkParams("chat", session)]) assert.equal(params.modelProvider, "gateway");
assert.ok(api.peers[0].received.some((message) => message.method === "thread/resume" && message.params.modelProvider === "gateway"));
});
test("provider discovery failures surface, while older servers keep their native catalog", async () => {
let unsupported = false;
const { agent } = setup((message, peer) => {
if (message.method === "config/read") peer.reply(message, { config: {} });
if (message.method === "model/list") peer.reply(message, { data: [{ id: "native-model" }] });
if (message.method === "modelProvider/list") peer.send({ jsonrpc: "2.0", id: message.id, error: { code: unsupported ? -32601 : -32603, message: "Provider discovery failed." } });
});
await assert.rejects(agent.listOptions({ workspace: "/work" }), /Provider discovery failed/);
unsupported = true;
const { options } = await agent.listOptions({ workspace: "/work" });
assert.equal(options.some((option) => option.id === "model_provider"), false);
assert.equal(options.find((option) => option.id === "model")?.value, "native-model");
});
test("gateway authentication advertises targeted providers and completes only after native confirmation", async () => {
let succeeded = false;
const { agent, api, events } = setup((message, peer) => {
if (message.method === "account/read") peer.reply(message, { account: {}, requiresOpenaiAuth: true });
if (message.method === "modelProvider/list") peer.reply(message, providerCatalog);
if (message.method === "account/gatewayOAuth/read") peer.reply(message, { providerId: message.params.modelProvider, providerName: "My gateway", required: message.params.modelProvider === "gateway", supportsDeviceAuth: true, status: succeeded ? "succeeded" : "notReady", error: null });
if (message.method === "account/gatewayOAuth/login") peer.reply(message, { prompt: { loginId: "device", verificationUrl: "https://gateway.example/device", userCode: "ABCD" } });
if (message.method === "account/gatewayOAuth/cancel") peer.reply(message, {});
});
const info = await agent.initialize();
assert.deepEqual(info.authMethods?.map((method) => method.id), ["gateway:gateway", "chatgpt"]);
let finished = false;
const login = agent.authenticate({ method: "gateway:gateway" }).then(() => { finished = true; });
await settle();
assert.equal(finished, false);
assert.deepEqual(api.opened, ["https://gateway.example/device"]);
assert.ok(events.some((event) => event.event === "notice" && event.message.includes("ABCD")));
const request = api.peers[0].received.find((message) => message.method === "account/gatewayOAuth/login");
assert.deepEqual(request?.params, { modelProvider: "gateway", deviceAuth: true });
agent.onNotification("account/gatewayOAuth/changed", { providerId: "other", loginId: "device", authUrl: null, status: "succeeded", error: null });
await settle();
assert.equal(finished, false);
agent.onNotification("account/gatewayOAuth/changed", { providerId: "gateway", loginId: "old-device", authUrl: null, status: "succeeded", error: null });
await settle();
assert.equal(finished, false);
succeeded = true;
agent.onNotification("account/gatewayOAuth/changed", { providerId: "gateway", loginId: "device", authUrl: null, status: "succeeded", error: null });
await login;
assert.equal(finished, true);
assert.equal(agent.gatewayLogins.size, 0);
assert.equal(agent.accountDirty, true);
});
test("gateway failures cancel their attempt and never fall back to ChatGPT", async () => {
const { agent, api } = setup((message, peer) => {
if (message.method === "account/gatewayOAuth/read") peer.reply(message, { providerId: "gateway", providerName: "Gateway", required: true, supportsDeviceAuth: false, status: "started", error: null });
if (message.method === "account/gatewayOAuth/login") {
peer.send({ jsonrpc: "2.0", method: "account/gatewayOAuth/changed", params: { providerId: "gateway", loginId: null, authUrl: "https://gateway.example/login", status: "started", error: null } });
peer.reply(message, { prompt: null });
}
if (message.method === "account/gatewayOAuth/cancel") peer.reply(message, {});
});
const login = agent.authenticate({ method: "gateway:gateway" });
const rejected = assert.rejects(login, /Gateway denied access/);
await settle();
assert.deepEqual(api.opened, ["https://gateway.example/login"]);
agent.onNotification("account/gatewayOAuth/changed", { providerId: "gateway", loginId: null, authUrl: null, status: "failed", error: "Gateway denied access." });
await rejected;
assert.equal(agent.gatewayLogins.size, 0);
assert.ok(api.peers[0].received.some((message) => message.method === "account/gatewayOAuth/cancel"));
assert.equal(api.peers[0].received.some((message) => message.method === "account/login/start"), false);
api.openUrl = async () => ({ opened: false, reason: "Browser unavailable." });
await assert.rejects(agent.authenticate({ method: "gateway:gateway" }), /Browser unavailable/);
assert.equal(agent.gatewayLogins.size, 0);
});
test("already authorized gateways complete without a browser and process exit fails pending sign-in", async () => {
let ready = true;
const { agent, api } = setup((message, peer) => {
if (message.method === "account/gatewayOAuth/read") peer.reply(message, { providerId: "gateway", providerName: "Gateway", required: true, status: ready ? "succeeded" : "started", error: null });
if (message.method === "account/gatewayOAuth/login") peer.reply(message, { prompt: null });
if (message.method === "account/gatewayOAuth/cancel") peer.reply(message, {});
});
await agent.authenticate({ method: "gateway:gateway" });
assert.deepEqual(api.opened, []);
ready = false;
const rejected = assert.rejects(agent.authenticate({ method: "gateway:gateway" }), /app-server exited/);
await settle();
api.peers[0].exit(1);
await rejected;
});
test("the configured default gateway exposes missing authorization through agent status", async () => {
let signedIn = false;
const { agent } = setup((message, peer) => {
if (message.method === "account/read") peer.reply(message, { account: {}, requiresOpenaiAuth: false });
if (message.method === "modelProvider/list") peer.reply(message, { ...providerCatalog, defaultProviderId: "gateway" });
if (message.method === "account/gatewayOAuth/read") peer.reply(message, { providerId: message.params.modelProvider, providerName: "My gateway", required: message.params.modelProvider === "gateway", status: signedIn ? "succeeded" : "notReady", error: null });
});
assert.deepEqual((await agent.initialize()).status, { state: "auth_required", message: "Sign in to My gateway." });
signedIn = true;
assert.deepEqual((await agent.initialize()).status, { state: "ready" });
});
No comments yet.