@gakr-gakr/codex 0.1.0

package/autobot.plugin.json

@@ -0,0 +1,374 @@
+{
+  "id": "codex",
+  "name": "Codex",
+  "description": "Codex app-server harness and Codex-managed GPT model catalog.",
+  "providers": ["codex"],
+  "contracts": {
+    "mediaUnderstandingProviders": ["codex"],
+    "migrationProviders": ["codex"]
+  },
+  "mediaUnderstandingProviderMetadata": {
+    "codex": {
+      "capabilities": ["image"],
+      "defaultModels": {
+        "image": "gpt-5.5"
+      }
+    }
+  },
+  "providerCatalogEntry": "./provider-discovery.ts",
+  "syntheticAuthRefs": ["codex"],
+  "nonSecretAuthMarkers": ["codex-app-server"],
+  "activation": {
+    "onStartup": false,
+    "onAgentHarnesses": ["codex"]
+  },
+  "commandAliases": [
+    {
+      "name": "codex",
+      "kind": "runtime-slash",
+      "cliCommand": "plugins"
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "codexDynamicToolsLoading": {
+        "type": "string",
+        "enum": ["searchable", "direct"],
+        "default": "searchable"
+      },
+      "codexDynamicToolsExclude": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": []
+      },
+      "discovery": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "timeoutMs": {
+            "type": "number",
+            "minimum": 1,
+            "default": 2500
+          }
+        }
+      },
+      "computerUse": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false
+          },
+          "autoInstall": {
+            "type": "boolean",
+            "default": false
+          },
+          "marketplaceDiscoveryTimeoutMs": {
+            "type": "number",
+            "minimum": 1,
+            "default": 60000
+          },
+          "marketplaceSource": {
+            "type": "string"
+          },
+          "marketplacePath": {
+            "type": "string"
+          },
+          "marketplaceName": {
+            "type": "string"
+          },
+          "pluginName": {
+            "type": "string",
+            "default": "computer-use"
+          },
+          "mcpServerName": {
+            "type": "string",
+            "default": "computer-use"
+          }
+        }
+      },
+      "codexPlugins": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false
+          },
+          "allow_destructive_actions": {
+            "type": "boolean",
+            "default": true
+          },
+          "plugins": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "marketplaceName": {
+                  "type": "string",
+                  "enum": ["openai-curated"]
+                },
+                "pluginName": {
+                  "type": "string"
+                },
+                "allow_destructive_actions": {
+                  "type": "boolean"
+                }
+              }
+            }
+          }
+        }
+      },
+      "appServer": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": ["yolo", "guardian"],
+            "default": "yolo"
+          },
+          "transport": {
+            "type": "string",
+            "enum": ["stdio", "websocket"],
+            "default": "stdio"
+          },
+          "command": { "type": "string" },
+          "args": {
+            "oneOf": [
+              {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              { "type": "string" }
+            ]
+          },
+          "url": { "type": "string" },
+          "authToken": { "type": "string" },
+          "headers": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "clearEnv": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "codeModeOnly": {
+            "type": "boolean",
+            "default": false
+          },
+          "requestTimeoutMs": {
+            "type": "number",
+            "minimum": 1,
+            "default": 60000
+          },
+          "turnCompletionIdleTimeoutMs": {
+            "type": "number",
+            "minimum": 1,
+            "default": 60000
+          },
+          "approvalPolicy": {
+            "type": "string",
+            "enum": ["never", "on-request", "on-failure", "untrusted"]
+          },
+          "sandbox": {
+            "type": "string",
+            "enum": ["read-only", "workspace-write", "danger-full-access"]
+          },
+          "approvalsReviewer": {
+            "type": "string",
+            "enum": ["user", "auto_review", "guardian_subagent"]
+          },
+          "serviceTier": { "type": ["string", "null"] },
+          "defaultWorkspaceDir": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "codexDynamicToolsLoading": {
+      "label": "Dynamic Tools Loading",
+      "help": "Use searchable to defer AutoBot dynamic tools behind Codex tool search, or direct to expose them in the initial context.",
+      "advanced": true
+    },
+    "codexDynamicToolsExclude": {
+      "label": "Dynamic Tool Excludes",
+      "help": "Additional AutoBot dynamic tool names to omit from Codex app-server turns.",
+      "advanced": true
+    },
+    "discovery": {
+      "label": "Model Discovery",
+      "help": "Plugin-owned controls for discovering Codex app-server models."
+    },
+    "discovery.enabled": {
+      "label": "Enable Discovery",
+      "help": "When false, AutoBot keeps the Codex harness available but uses the bundled fallback model list."
+    },
+    "discovery.timeoutMs": {
+      "label": "Discovery Timeout",
+      "help": "Maximum time to wait for Codex app-server model discovery before falling back to the bundled model list.",
+      "advanced": true
+    },
+    "computerUse": {
+      "label": "Computer Use",
+      "help": "Controls Codex app-server setup for the Computer Use plugin.",
+      "advanced": true
+    },
+    "computerUse.enabled": {
+      "label": "Enable Computer Use",
+      "help": "When true, Codex-mode turns require the configured Computer Use MCP server to be available.",
+      "advanced": true
+    },
+    "computerUse.autoInstall": {
+      "label": "Auto Install",
+      "help": "Install the configured Computer Use plugin when Codex-mode turns start.",
+      "advanced": true
+    },
+    "computerUse.marketplaceDiscoveryTimeoutMs": {
+      "label": "Marketplace Discovery Timeout",
+      "help": "Maximum time to wait for Codex app-server to finish loading marketplaces during Computer Use install.",
+      "advanced": true
+    },
+    "computerUse.marketplaceSource": {
+      "label": "Marketplace Source",
+      "help": "Optional Codex marketplace source to add before installing Computer Use.",
+      "advanced": true
+    },
+    "computerUse.marketplacePath": {
+      "label": "Marketplace Path",
+      "help": "Optional local Codex marketplace file path containing the Computer Use plugin.",
+      "advanced": true
+    },
+    "computerUse.marketplaceName": {
+      "label": "Marketplace Name",
+      "help": "Optional registered Codex marketplace name containing the Computer Use plugin.",
+      "advanced": true
+    },
+    "computerUse.pluginName": {
+      "label": "Plugin Name",
+      "help": "Codex marketplace plugin name for Computer Use.",
+      "advanced": true
+    },
+    "computerUse.mcpServerName": {
+      "label": "MCP Server Name",
+      "help": "MCP server name exposed by the Computer Use plugin.",
+      "advanced": true
+    },
+    "codexPlugins": {
+      "label": "Native Codex Plugins",
+      "help": "Controls native Codex plugin availability for Codex harness turns.",
+      "advanced": true
+    },
+    "codexPlugins.enabled": {
+      "label": "Enable Native Plugins",
+      "help": "Expose explicit migrated Codex plugin entries to Codex harness turns.",
+      "advanced": true
+    },
+    "codexPlugins.allow_destructive_actions": {
+      "label": "Allow Destructive Plugin Actions",
+      "help": "Default policy for plugin app write or destructive action elicitations. Defaults to true.",
+      "advanced": true
+    },
+    "codexPlugins.plugins": {
+      "label": "Migrated Plugin Entries",
+      "help": "Explicit migration-authored plugin entries. The wildcard key * is not supported.",
+      "advanced": true
+    },
+    "appServer": {
+      "label": "App Server",
+      "help": "Runtime controls for connecting to Codex app-server.",
+      "advanced": true
+    },
+    "appServer.mode": {
+      "label": "Execution Mode",
+      "help": "Use yolo for unchained local execution or guardian for Codex guardian-reviewed approvals.",
+      "advanced": true
+    },
+    "appServer.transport": {
+      "label": "Transport",
+      "help": "Use stdio to spawn Codex locally, or websocket to connect to an already-running app-server.",
+      "advanced": true
+    },
+    "appServer.command": {
+      "label": "Command",
+      "help": "Executable used for stdio transport. Leave unset to use AutoBot's managed Codex binary.",
+      "advanced": true
+    },
+    "appServer.args": {
+      "label": "Arguments",
+      "help": "Arguments used for stdio transport. Defaults to app-server --listen stdio://.",
+      "advanced": true
+    },
+    "appServer.url": {
+      "label": "WebSocket URL",
+      "help": "Codex app-server WebSocket URL when transport is websocket.",
+      "advanced": true
+    },
+    "appServer.authToken": {
+      "label": "Auth Token",
+      "help": "Bearer token sent to the WebSocket app-server.",
+      "sensitive": true,
+      "advanced": true
+    },
+    "appServer.headers": {
+      "label": "Headers",
+      "help": "Additional headers sent to the WebSocket app-server.",
+      "advanced": true
+    },
+    "appServer.clearEnv": {
+      "label": "Clear Environment",
+      "help": "Environment variable names removed from the spawned stdio app-server process after overrides are applied.",
+      "advanced": true
+    },
+    "appServer.codeModeOnly": {
+      "label": "Code Mode Only",
+      "help": "Expose Codex's code-mode-only tool surface. AutoBot dynamic tools remain available through Codex nested tool calls.",
+      "advanced": true
+    },
+    "appServer.requestTimeoutMs": {
+      "label": "Request Timeout",
+      "help": "Maximum time to wait for Codex app-server control-plane requests.",
+      "advanced": true
+    },
+    "appServer.turnCompletionIdleTimeoutMs": {
+      "label": "Turn Completion Idle Timeout",
+      "help": "Maximum quiet time after Codex accepts a turn or after a turn-scoped app-server request before AutoBot interrupts the turn while waiting for turn/completed.",
+      "advanced": true
+    },
+    "appServer.approvalPolicy": {
+      "label": "Approval Policy",
+      "help": "Codex native approval policy sent to thread start, resume, and turns.",
+      "advanced": true
+    },
+    "appServer.sandbox": {
+      "label": "Sandbox",
+      "help": "Codex native sandbox mode sent to thread start and resume.",
+      "advanced": true
+    },
+    "appServer.approvalsReviewer": {
+      "label": "Approvals Reviewer",
+      "help": "Use user approvals or Codex auto_review for native app-server approvals. guardian_subagent remains accepted for compatibility.",
+      "advanced": true
+    },
+    "appServer.serviceTier": {
+      "label": "Service Tier",
+      "help": "Optional Codex app-server service tier. Use priority, flex, or null. Legacy fast is accepted as priority.",
+      "advanced": true
+    },
+    "appServer.defaultWorkspaceDir": {
+      "label": "Default Workspace",
+      "help": "Workspace used by /codex bind when --cwd is omitted.",
+      "advanced": true
+    }
+  }
+}

package/doctor-contract-api.ts

@@ -0,0 +1,68 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { DoctorSessionRouteStateOwner } from "autobot/plugin-sdk/runtime-doctor";
+
+type LegacyConfigRule = {
+  path: string[];
+  message: string;
+  match: (value: unknown) => boolean;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function hasRetiredDynamicToolsProfile(value: unknown): boolean {
+  return Object.prototype.hasOwnProperty.call(asRecord(value) ?? {}, "codexDynamicToolsProfile");
+}
+
+export const legacyConfigRules: LegacyConfigRule[] = [
+  {
+    path: ["plugins", "entries", "codex", "config"],
+    message:
+      'plugins.entries.codex.config.codexDynamicToolsProfile is retired; Codex app-server always keeps Codex-native workspace tools native. Run "autobot doctor --fix".',
+    match: hasRetiredDynamicToolsProfile,
+  },
+];
+
+export function normalizeCompatibilityConfig({ cfg }: { cfg: AutoBotConfig }): {
+  config: AutoBotConfig;
+  changes: string[];
+} {
+  const rawEntry = asRecord(cfg.plugins?.entries?.codex);
+  const rawPluginConfig = asRecord(rawEntry?.config);
+  if (!rawPluginConfig || !hasRetiredDynamicToolsProfile(rawPluginConfig)) {
+    return { config: cfg, changes: [] };
+  }
+
+  const nextConfig = structuredClone(cfg) as AutoBotConfig & {
+    plugins?: Record<string, unknown>;
+  };
+  const nextPlugins = asRecord(nextConfig.plugins);
+  const nextEntries = asRecord(nextPlugins?.entries);
+  const nextEntry = asRecord(nextEntries?.codex);
+  const nextPluginConfig = asRecord(nextEntry?.config);
+  if (!nextPluginConfig) {
+    return { config: cfg, changes: [] };
+  }
+
+  delete nextPluginConfig.codexDynamicToolsProfile;
+  return {
+    config: nextConfig,
+    changes: [
+      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
+    ],
+  };
+}
+
+export const sessionRouteStateOwners: DoctorSessionRouteStateOwner[] = [
+  {
+    id: "codex",
+    label: "Codex",
+    providerIds: ["codex", "codex-cli", "openai-codex"],
+    runtimeIds: ["codex", "codex-cli"],
+    cliSessionKeys: ["codex-cli"],
+    authProfilePrefixes: ["codex:", "codex-cli:", "openai-codex:"],
+  },
+];

package/harness.ts

@@ -0,0 +1,72 @@
+import type { AgentHarness } from "autobot/plugin-sdk/agent-harness-runtime";
+import type {
+  CodexAppServerListModelsOptions,
+  CodexAppServerModel,
+  CodexAppServerModelListResult,
+} from "./src/app-server/models.js";
+
+const DEFAULT_CODEX_HARNESS_PROVIDER_IDS = new Set(["codex"]);
+
+export type { CodexAppServerListModelsOptions, CodexAppServerModel, CodexAppServerModelListResult };
+
+export function createCodexAppServerAgentHarness(options?: {
+  id?: string;
+  label?: string;
+  providerIds?: Iterable<string>;
+  pluginConfig?: unknown;
+  resolvePluginConfig?: () => unknown;
+}): AgentHarness {
+  const providerIds = new Set(
+    [...(options?.providerIds ?? DEFAULT_CODEX_HARNESS_PROVIDER_IDS)].map((id) =>
+      id.trim().toLowerCase(),
+    ),
+  );
+  return {
+    id: options?.id ?? "codex",
+    label: options?.label ?? "Codex agent harness",
+    deliveryDefaults: {
+      sourceVisibleReplies: "message_tool",
+    },
+    supports: (ctx) => {
+      const provider = ctx.provider.trim().toLowerCase();
+      if (providerIds.has(provider)) {
+        return { supported: true, priority: 100 };
+      }
+      return {
+        supported: false,
+        reason: `provider is not one of: ${[...providerIds].toSorted().join(", ")}`,
+      };
+    },
+    runAttempt: async (params) => {
+      const { runCodexAppServerAttempt } = await import("./src/app-server/run-attempt.js");
+      return runCodexAppServerAttempt(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+        nativeHookRelay: { enabled: true },
+      });
+    },
+    runSideQuestion: async (params) => {
+      const { runCodexAppServerSideQuestion } = await import("./src/app-server/side-question.js");
+      return runCodexAppServerSideQuestion(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+        nativeHookRelay: { enabled: true },
+      });
+    },
+    compact: async (params) => {
+      const { maybeCompactCodexAppServerSession } = await import("./src/app-server/compact.js");
+      return maybeCompactCodexAppServerSession(params, {
+        pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
+      });
+    },
+    reset: async (params) => {
+      if (params.sessionFile) {
+        const { clearCodexAppServerBinding } = await import("./src/app-server/session-binding.js");
+        await clearCodexAppServerBinding(params.sessionFile);
+      }
+    },
+    dispose: async () => {
+      const { clearSharedCodexAppServerClientAndWait } =
+        await import("./src/app-server/shared-client.js");
+      await clearSharedCodexAppServerClientAndWait();
+    },
+  };
+}

package/index.ts

@@ -0,0 +1,124 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { mutateConfigFile } from "autobot/plugin-sdk/config-mutation";
+import { resolveLivePluginConfigObject } from "autobot/plugin-sdk/plugin-config-runtime";
+import { definePluginEntry } from "autobot/plugin-sdk/plugin-entry";
+import { createCodexAppServerAgentHarness } from "./harness.js";
+import { buildCodexMediaUnderstandingProvider } from "./media-understanding-provider.js";
+import { buildCodexProvider } from "./provider.js";
+import type { CodexPluginsConfigBlock } from "./src/command-plugins-management.js";
+import { createCodexCommand } from "./src/commands.js";
+import {
+  handleCodexConversationBindingResolved,
+  handleCodexConversationInboundClaim,
+} from "./src/conversation-binding.js";
+import { buildCodexMigrationProvider } from "./src/migration/provider.js";
+import {
+  createCodexCliSessionNodeHostCommands,
+  createCodexCliSessionNodeInvokePolicies,
+  listCodexCliSessionsOnNode,
+  resumeCodexCliSessionOnNode,
+  resolveCodexCliSessionForBindingOnNode,
+} from "./src/node-cli-sessions.js";
+
+export default definePluginEntry({
+  id: "codex",
+  name: "Codex",
+  description: "Codex app-server harness and Codex-managed GPT model catalog.",
+  register(api) {
+    const resolveCurrentPluginConfig = () =>
+      resolveLivePluginConfigObject(
+        api.runtime.config?.current
+          ? () => api.runtime.config.current() as AutoBotConfig
+          : undefined,
+        "codex",
+        api.pluginConfig as Record<string, unknown>,
+      ) ?? api.pluginConfig;
+    api.registerAgentHarness(
+      createCodexAppServerAgentHarness({ resolvePluginConfig: resolveCurrentPluginConfig }),
+    );
+    api.registerProvider(buildCodexProvider({ pluginConfig: api.pluginConfig }));
+    api.registerMediaUnderstandingProvider(
+      buildCodexMediaUnderstandingProvider({ pluginConfig: api.pluginConfig }),
+    );
+    api.registerMigrationProvider(buildCodexMigrationProvider({ runtime: api.runtime }));
+    for (const command of createCodexCliSessionNodeHostCommands()) {
+      api.registerNodeHostCommand(command);
+    }
+    for (const policy of createCodexCliSessionNodeInvokePolicies()) {
+      api.registerNodeInvokePolicy(policy);
+    }
+    api.registerCommand(
+      createCodexCommand({
+        pluginConfig: api.pluginConfig,
+        deps: {
+          listCodexCliSessionsOnNode: (params) =>
+            listCodexCliSessionsOnNode({ runtime: api.runtime, ...params }),
+          resolveCodexCliSessionForBindingOnNode: (params) =>
+            resolveCodexCliSessionForBindingOnNode({ runtime: api.runtime, ...params }),
+          codexPluginsManagementIo: {
+            readConfig: () => {
+              const current = (api.runtime.config?.current?.() ?? {}) as AutoBotConfig;
+              const plugins = (current as Record<string, unknown>).plugins;
+              if (!plugins || typeof plugins !== "object") {
+                return Promise.resolve({});
+              }
+              const entries = (plugins as Record<string, unknown>).entries;
+              if (!entries || typeof entries !== "object") {
+                return Promise.resolve({});
+              }
+              const codexEntry = (entries as Record<string, unknown>).codex;
+              if (!codexEntry || typeof codexEntry !== "object") {
+                return Promise.resolve({});
+              }
+              const config = (codexEntry as Record<string, unknown>).config;
+              if (!config || typeof config !== "object") {
+                return Promise.resolve({});
+              }
+              const codexPlugins = (config as Record<string, unknown>).codexPlugins;
+              if (!codexPlugins || typeof codexPlugins !== "object") {
+                return Promise.resolve({});
+              }
+              const declared = (codexPlugins as Record<string, unknown>).plugins;
+              if (!declared || typeof declared !== "object") {
+                return Promise.resolve({
+                  enabled: (codexPlugins as Record<string, unknown>).enabled === true,
+                });
+              }
+              return Promise.resolve({
+                enabled: (codexPlugins as Record<string, unknown>).enabled === true,
+                plugins: declared as Record<string, never>,
+              });
+            },
+            mutate: async (update) => {
+              await mutateConfigFile({
+                mutate: (draft) => {
+                  const root = draft as Record<string, unknown>;
+                  root.plugins = (root.plugins ?? {}) as Record<string, unknown>;
+                  const pluginsBlock = root.plugins as Record<string, unknown>;
+                  pluginsBlock.entries = (pluginsBlock.entries ?? {}) as Record<string, unknown>;
+                  const entries = pluginsBlock.entries as Record<string, unknown>;
+                  entries.codex = (entries.codex ?? {}) as Record<string, unknown>;
+                  const codexEntry = entries.codex as Record<string, unknown>;
+                  codexEntry.config = (codexEntry.config ?? {}) as Record<string, unknown>;
+                  const config = codexEntry.config as Record<string, unknown>;
+                  config.codexPlugins = (config.codexPlugins ?? {}) as Record<string, unknown>;
+                  const codexPlugins = config.codexPlugins as Record<string, unknown>;
+                  codexPlugins.plugins = (codexPlugins.plugins ?? {}) as Record<string, unknown>;
+                  update(codexPlugins as CodexPluginsConfigBlock);
+                },
+              });
+            },
+          },
+        },
+      }),
+    );
+    api.on("inbound_claim", (event, ctx) =>
+      handleCodexConversationInboundClaim(event, ctx, {
+        pluginConfig: resolveCurrentPluginConfig(),
+        resumeCodexCliSessionOnNode: (params) =>
+          resumeCodexCliSessionOnNode({ runtime: api.runtime, ...params }),
+      }),
+    );
+    api.onConversationBindingResolved?.(handleCodexConversationBindingResolved);
+  },
+});