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

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Codex agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Codex CLI, and ask or tell the installer that owns it (npm or Homebrew) about a newer versionPrograms: codexnpmbrew
  • Environment variables envMediumReads the listed environment variables.Find each account's Codex home, and pass extra app-server arguments set in CODEX_ARGSVariables: HOMECODEX_HOMECODEX_ARGS
  • Read files fs.readMediumReads files in the listed places.Notice a conversation started in the Codex app or CLI, so it shows up at once, and read, once, the accounts the previous Codex provider keptPlaces: its own data folder~/.codex/sessions~/.codex/sessions/**~/.codex*/sessions~/.codex*/sessions/**

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" });
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6121.1 KB4 permissionsListed
0.2.4Nov 16, 2026>=5 <6120.2 KB4 permissionsListed
0.2.3Nov 11, 2026>=5 <695.2 KB4 permissionsListed
0.2.2Nov 9, 2026>=5 <688.9 KB4 permissionsListed
0.2.1Oct 27, 2026>=2 <484.1 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.