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.3

Permissions in 0.2.3

  • 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.Read, once, the accounts the previous Codex provider keptPlaces: its own data folder

Files

requests.ts5.3 KB
// What the app-server's requests become (approval cards and questions),
// and the replies Codex expects for the user's answers. Pure functions of
// the request and the answer; the agent keeps the pending requests.
import type { ApprovalOption } from "divergence/protocol";
import type { Notification } from "./wire.ts";
import type { QuestionAnswer, QuestionField, QuestionOption, ToolContent } from "./types.ts";
import * as map from "./map.ts";

/// A command or file change approval's options. Both decision enums share
/// these four values, so the option ids are the Codex decisions.
export const APPROVAL_OPTIONS: ApprovalOption[] = [
  { id: "accept", name: "Allow once", kind: "allow_once" },
  { id: "acceptForSession", name: "Allow for this session", kind: "allow_always" },
  { id: "decline", name: "Reject", kind: "reject_once" },
  { id: "cancel", name: "Reject and stop", kind: "reject_always" },
];

/// A command approval's headline and the tool call its card shows.
export function commandApproval(p: Notification & { itemId: string }) {
  const command = typeof p.command === "string" ? p.command : "";
  const cwd = typeof p.cwd === "string" ? p.cwd : null;
  const terminal: ToolContent = { type: "terminal", command, output: "" };
  if (cwd !== null) terminal.cwd = cwd;
  const call = map.toolCall({
    id: p.itemId,
    name: "shell",
    kind: map.commandToolKind(p.commandActions),
    title: command,
    status: "pending",
    input: { command, cwd },
    content: [terminal],
  });
  // The card draws the command under its headline; saying it in the
  // headline too would show it twice.
  return { title: typeof p.reason === "string" ? p.reason : "Run a command", call };
}

/// A file change approval's headline and the tool call its card shows,
/// with the diffs the item streamed so far.
export function fileChangeApproval(p: Notification & { itemId: string }, content: ToolContent[]) {
  const title =
    typeof p.reason === "string"
      ? p.reason
      : typeof p.grantRoot === "string"
        ? `Allow writes under ${p.grantRoot}`
        : "Apply file changes";
  return { title, call: map.toolCall({ id: p.itemId, name: "apply_patch", kind: "edit", title, status: "pending", content }) };
}

/// An MCP elicitation's refusal.
export const REFUSE = { action: "cancel", content: null, _meta: null };

/// An MCP tool approval's options: the persistence scopes the request
/// advertises become choices.
export function mcpApprovalOptions(persist: string | string[] | null | undefined) {
  const supports = (scope: string) => (Array.isArray(persist) ? persist.includes(scope) : persist === scope);
  const options: ApprovalOption[] = [{ id: "accept", name: "Allow once", kind: "allow_once" }];
  if (supports("session")) options.push({ id: "acceptForSession", name: "Allow for this session", kind: "allow_always" });
  if (supports("always")) options.push({ id: "acceptAlways", name: "Always allow", kind: "allow_always" });
  options.push({ id: "cancel", name: "Cancel", kind: "reject_always" });
  return options;
}

/// The reply to an MCP tool approval. The scope goes back in the
/// response metadata, never in the form content.
export function mcpApprovalReply(decision: string) {
  if (decision === "accept") return { action: "accept", content: {}, _meta: null };
  if (decision === "acceptForSession") return { action: "accept", content: {}, _meta: { persist: "session" } };
  if (decision === "acceptAlways") return { action: "accept", content: {}, _meta: { persist: "always" } };
  if (decision === "decline") return { action: "decline", content: null, _meta: null };
  return REFUSE;
}

type Questions = NonNullable<Notification["questions"]>;

/// `item/tool/requestUserInput`'s questions as one field each: a select
/// when it carries options, text otherwise.
export function userInputFields(questions: Questions) {
  return questions.map((question) => {
    const header = typeof question?.header === "string" ? question.header : "";
    const text = typeof question?.question === "string" ? question.question : "";
    const options = (Array.isArray(question?.options) ? question.options : []).map((option) => {
      const out: QuestionOption = { value: String(option?.label ?? ""), label: String(option?.label ?? "") };
      if (typeof option?.description === "string" && option.description) out.description = option.description;
      return out;
    });
    const field: QuestionField = {
      id: String(question?.id ?? ""),
      label: header || text,
      kind: options.length ? "select" : "text",
      allowOther: question?.isOther === true,
      required: true,
    };
    if (text) field.description = text;
    if (options.length) field.options = options;
    return field;
  });
}

/// The user's answer as Codex expects it: `{ answers: { <questionId>: { answers: [...] } } }`.
export function userInputReply(questions: Questions, answer: QuestionAnswer) {
  const values = answer.values ?? {};
  const answers: Record<string, { answers: string[] }> = {};
  for (const question of questions) {
    const id = String(question?.id ?? "");
    const value = values[id];
    let list: string[] = [];
    if (typeof value === "string") list = [value];
    else if (Array.isArray(value)) list = value.filter((item) => typeof item === "string");
    else if (typeof value === "boolean") list = [String(value)];
    answers[id] = { answers: list };
  }
  return { answers };
}

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.