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
wire.ts11.8 KB
// The app-server fields this provider consumes. Optional fields preserve
// Codex's lenient defaults and unknown item types remain forward compatible.
import * as z from "zod";
const text = z.string().nullish();
const number = z.number().nullish();
export const action = z.looseObject({ type: text, path: text, command: text });
export const change = z.looseObject({ path: text, diff: text, kind: z.looseObject({ type: text }).nullish() });
export const input = z.looseObject({ type: text, text: text, path: text, url: text });
const collabState = z.object({ status: text, message: text });
export const item = z.looseObject({
type: text,
id: text,
clientId: text,
text: text,
delivery: text,
command: text,
processId: text,
cwd: text,
status: text,
aggregatedOutput: text,
exitCode: number,
commandActions: z.array(action).nullish(),
changes: z.array(change).nullish(),
server: text,
tool: text,
mcpAppUi: z.object({ resourceUri: z.string() }).nullish(),
mcpAppResourceUri: text,
appContext: z.object({ resourceUri: text }).nullish(),
error: z.unknown().optional(),
result: z.unknown().optional(),
arguments: z.unknown().optional(),
success: z.boolean().nullish(),
contentItems: z.array(z.object({ type: text, text: text, imageUrl: text })).nullish(),
query: text,
path: text,
summary: z.array(z.unknown()).nullish(),
content: z.array(z.unknown()).nullish(),
senderThreadId: text,
receiverThreadIds: z.array(z.unknown()).nullish(),
prompt: text,
model: text,
reasoningEffort: text,
agentsStates: z.record(z.string(), collabState).nullish(),
kind: text,
agentThreadId: text,
agentPath: text,
questions: z.array(z.object({ title: text, options: z.array(z.unknown()).nullish() })).nullish(),
});
export const turnError = z.object({ message: text, codexErrorInfo: z.unknown().optional(), additionalDetails: text });
export const turn = z.looseObject({
id: text,
status: text,
startedAt: number,
completedAt: number,
error: turnError.nullish(),
items: z.array(item).nullish(),
});
const spawn = z.looseObject({ parent_thread_id: text, agent_nickname: text, agent_role: text, agent_path: text });
const subagent = z.object({ thread_spawn: spawn.nullish() });
export const thread = z.looseObject({
id: text,
name: text,
preview: text,
parentThreadId: text,
agentNickname: text,
agentRole: text,
model: text,
reasoningEffort: text,
createdAt: number,
updatedAt: number,
historyMode: text,
source: z
.union([
z.string(),
z.object({
subAgent: z.union([z.string(), subagent]).nullish(),
subagent: z.union([z.string(), subagent]).nullish(),
}),
])
.nullish(),
turns: z.array(turn).nullish(),
});
export const model = z.looseObject({
id: z.string(),
hidden: z.boolean().optional(),
isDefault: z.boolean().optional(),
displayName: text,
description: text,
modelSpecialty: text,
defaultReasoningEffort: text,
defaultServiceTier: text,
supportedReasoningEfforts: z.array(z.object({ reasoningEffort: z.string(), description: text })).nullish(),
serviceTiers: z.array(z.object({ id: z.string(), name: text, description: text })).nullish(),
});
export const config = z.looseObject({
model: text,
model_reasoning_effort: text,
model_provider: text,
service_tier: text,
// A string, or `{ granular: … }` for per-category approvals.
approval_policy: z.unknown().optional(),
sandbox_mode: text,
sandbox_workspace_write: z
.object({
writable_roots: z.array(z.string()).nullish(),
network_access: z.boolean().nullish(),
exclude_tmpdir_env_var: z.boolean().nullish(),
exclude_slash_tmp: z.boolean().nullish(),
})
.nullish(),
});
const window = z.object({ windowDurationMins: number, usedPercent: number, resetsAt: number });
const limitSnapshot = z.object({
limitId: text,
rateLimitReachedType: text,
limitName: text,
primary: window.nullish(),
secondary: window.nullish(),
spendControlReached: z.boolean().nullish(),
individualLimit: z.object({ resetsAt: number }).nullish(),
});
export const limits = z.object({
ordinaryUsageAllowed: z.boolean().nullish(),
accountId: text,
rateLimits: limitSnapshot.nullish(),
rateLimitsByLimitId: z.record(z.string(), limitSnapshot).nullish(),
rateLimitResetCredits: z.object({ availableCount: number }).nullish(),
});
export const status = z.object({ type: text, activeFlags: z.array(z.unknown()).nullish() });
export const property = z.looseObject({
type: text,
title: text,
description: text,
oneOf: z.array(z.object({ const: z.unknown().optional(), title: text, description: text })).nullish(),
enum: z.array(z.unknown()).nullish(),
enumNames: z.array(z.unknown()).nullish(),
});
export const elicitation = z.object({
properties: z.record(z.string(), property.extend({ items: property.nullish() })).nullish(),
required: z.array(z.unknown()).nullish(),
});
export const requestQuestion = z.object({
id: z.unknown().optional(),
header: text,
question: text,
isOther: z.boolean().nullish(),
isSecret: z.boolean().nullish(),
options: z.array(z.object({ label: text, description: text })).nullish(),
});
/// The thread a notification names, read before its schema is checked, so
/// a notification that fails the check can still be reported to its chat.
export function threadOf(params: unknown): string | null {
const parsed = z.object({ threadId: z.string() }).safeParse(params);
return parsed.success ? parsed.data.threadId : null;
}
/// The notifications this plugin reads. Codex sends others (an MCP
/// server's startup, for one) whose fields share names with these but not
/// their types, so only these are checked against `notification` below.
export const routed = [
"item/agentMessage/delta",
"item/reasoning/textDelta",
"item/reasoning/summaryTextDelta",
"item/reasoning/summaryPartAdded",
"item/started",
"item/completed",
"item/commandExecution/outputDelta",
"item/fileChange/outputDelta",
"item/fileChange/patchUpdated",
"item/mcpToolCall/progress",
"turn/started",
"turn/completed",
"turn/plan/updated",
"thread/tokenUsage/updated",
"thread/started",
"thread/status/changed",
"thread/name/updated",
"error",
"warning",
"guardianWarning",
"deprecationNotice",
"configWarning",
"windows/worldWritableWarning",
"model/rerouted",
"account/rateLimits/updated",
"account/updated",
"skills/changed",
"serverRequest/resolved",
] as const;
export type Routed = (typeof routed)[number];
export function isRouted(method: string): method is Routed {
return (routed as readonly string[]).includes(method);
}
export const notification = z.looseObject({
threadId: text,
turnId: text,
itemId: text,
delta: text,
item: item.nullish(),
turn: turn.nullish(),
thread: thread.nullish(),
changes: z.array(change).nullish(),
plan: z.array(z.object({ step: text, status: text })).nullish(),
tokenUsage: z
.object({
total: z.object({ totalTokens: number }).nullish(),
last: z.object({ totalTokens: number }).nullish(),
modelContextWindow: number,
})
.nullish(),
status: status.nullish(),
threadName: text,
error: turnError.nullish(),
willRetry: z.boolean().nullish(),
message: text,
summary: text,
details: text,
samplePaths: z.array(z.string()).nullish(),
extraCount: number,
failedScan: z.boolean().nullish(),
fromModel: text,
toModel: text,
requestId: z.unknown().optional(),
rateLimits: limits.shape.rateLimits,
thread_id: text,
tool: text,
arguments: z.unknown().optional(),
callId: text,
kind: z.enum(["command", "humanCommand", "writeStdin"]).nullish(),
networkApprovalContext: z.object({ host: z.string(), protocol: z.string() }).nullish(),
proposedExecpolicyAmendment: z.array(z.string()).nullish(),
proposedNetworkPolicyAmendments: z.array(z.object({ host: z.string(), action: z.enum(["allow", "deny"]) })).nullish(),
command: text,
cwd: text,
commandActions: z.array(action).nullish(),
reason: text,
grantRoot: text,
mode: text,
url: text,
_meta: z
.object({ codex_approval_kind: text, persist: z.union([z.string(), z.array(z.string())]).nullish() })
.nullish(),
requestedSchema: elicitation.nullish(),
questions: z.array(requestQuestion).nullish(),
});
const responseSchemas = {
"mcpServer/resource/read": z.looseObject({ contents: z.array(z.unknown()), originCallId: text }),
"mcpServer/tool/call": z.looseObject({
content: z.array(z.unknown()),
structuredContent: z.unknown().optional(),
isError: z.boolean().optional(),
_meta: z.unknown().optional(),
}),
"mcpServerStatus/list": z.object({
data: z.array(z.object({
name: z.string(),
toolsError: text,
tools: z.record(z.string(), z.object({
name: z.string(),
_meta: z.object({ ui: z.object({ visibility: z.array(z.string()).optional() }).optional() }).nullish(),
})),
})),
nextCursor: text,
}),
initialize: z.object({ userAgent: text }),
"thread/read": z.object({ thread: thread.nullish() }),
"thread/start": z.object({ thread: thread.nullish(), modelProvider: text }),
"thread/resume": z.object({ modelProvider: text }),
"thread/fork": z.object({ thread: thread.nullish(), modelProvider: text }),
"thread/list": z.object({ data: z.array(thread).nullish(), nextCursor: text }),
"thread/turns/list": z.object({ data: z.array(turn).nullish(), nextCursor: text }),
"fs/readFile": z.object({ dataBase64: z.string() }),
"model/list": z.object({ data: z.array(model).nullish(), nextCursor: text }),
"modelProvider/list": z.object({ data: z.array(z.object({ id: z.string(), name: z.string() })), defaultProviderId: z.string(), canChangeDefault: z.boolean() }),
"account/gatewayOAuth/read": z.object({ providerId: z.string(), providerName: z.string(), required: z.boolean(), supportsDeviceAuth: z.boolean().optional(), status: text, error: text }),
"account/gatewayOAuth/login": z.object({ prompt: z.object({ loginId: z.string(), verificationUrl: z.string(), userCode: z.string() }).nullable() }),
"account/gatewayOAuth/cancel": z.unknown(),
"config/read": z.object({ config: config.nullish() }),
"account/rateLimits/read": limits,
"account/read": z.object({
account: z.unknown().optional(),
requiresOpenaiAuth: z.boolean().optional(),
workspaceRouting: z.object({ chatgptAccountId: z.string() }).nullish(),
}),
"skills/list": z.object({
data: z
.array(
z.object({
skills: z
.array(
z.object({
name: text,
path: text,
enabled: z.boolean().nullish(),
shortDescription: text,
interface: z.object({ shortDescription: text }).nullish(),
description: text,
scope: text,
}),
)
.nullish(),
}),
)
.nullish(),
}),
"turn/start": z.object({ turn: turn.nullish() }),
"turn/steer": z.object({ turnId: z.string() }),
"turn/interrupt": z.unknown(),
"thread/unsubscribe": z.unknown(),
"thread/revert": z.unknown(),
"thread/compact/start": z.unknown(),
"account/logout": z.unknown(),
"account/login/start": z.object({ loginId: z.string(), authUrl: text, verificationUrl: text }),
"account/login/cancel": z.unknown(),
};
export type Item = z.infer<typeof item>;
export type McpServers = z.infer<(typeof responseSchemas)["mcpServerStatus/list"]>;
export type Thread = z.infer<typeof thread>;
export type Turn = z.infer<typeof turn>;
export type Model = z.infer<typeof model>;
export type Config = z.infer<typeof config>;
export type Notification = z.infer<typeof notification>;
export const loginCompleted = z.object({ loginId: text, success: z.boolean(), error: text });
export type LoginCompleted = z.infer<typeof loginCompleted>;
export type Elicitation = z.infer<typeof elicitation>;
export const responses: { [M in keyof typeof responseSchemas]: z.ZodType<z.infer<(typeof responseSchemas)[M]>> } =
responseSchemas;
No comments yet.