@full-self-developing/fsd 1.0.0

package/extensions/codex/openclaw.plugin.json

@@ -0,0 +1,403 @@
+{
+  "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
+          },
+          "postToolRawAssistantCompletionIdleTimeoutMs": {
+            "type": "number",
+            "minimum": 1
+          },
+          "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"
+          },
+          "experimental": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "sandboxExecServer": {
+                "type": "boolean",
+                "default": false
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "codexDynamicToolsLoading": {
+      "label": "Dynamic Tools Loading",
+      "help": "Use searchable to defer OpenClaw dynamic tools behind Codex tool search, or direct to expose them in the initial context.",
+      "advanced": true
+    },
+    "codexDynamicToolsExclude": {
+      "label": "Dynamic Tool Excludes",
+      "help": "Additional OpenClaw 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, OpenClaw 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 OpenClaw'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. OpenClaw 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 OpenClaw interrupts the turn while waiting for turn/completed.",
+      "advanced": true
+    },
+    "appServer.postToolRawAssistantCompletionIdleTimeoutMs": {
+      "label": "Post-Tool Raw Assistant Completion Idle Timeout",
+      "help": "Completion-idle guard after a tool handoff when Codex emits raw assistant completion or progress without turn/completed. Defaults to the assistant completion idle timeout when unset.",
+      "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
+    },
+    "appServer.experimental": {
+      "label": "Experimental",
+      "help": "Experimental Codex app-server integrations.",
+      "advanced": true
+    },
+    "appServer.experimental.sandboxExecServer": {
+      "label": "Sandbox Exec Server",
+      "help": "Route native Codex execution through an OpenClaw sandbox-backed exec-server when OpenClaw sandboxing is active.",
+      "advanced": true
+    }
+  }
+}

package/extensions/codex/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@openclaw/codex",
+  "version": "2026.5.21",
+  "description": "OpenClaw Codex harness and model provider plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@openai/codex": "0.132.0",
+    "ajv": "8.20.0",
+    "ws": "8.20.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@openclaw/codex",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.5.1-beta.1"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.21"
+    },
+    "build": {
+      "openclawVersion": "2026.5.21"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true,
+      "bundleRuntimeDependencies": false
+    }
+  }
+}

package/extensions/codex/prompt-overlay-runtime-contract.test.ts

@@ -0,0 +1,48 @@
+import {
+  codexPromptOverlayContext,
+  GPT5_CONTRACT_MODEL_ID,
+  NON_GPT5_CONTRACT_MODEL_ID,
+  sharedGpt5PersonalityConfig,
+} from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { describe, expect, it } from "vitest";
+import { buildCodexProvider } from "./provider.js";
+
+describe("Codex prompt overlay runtime contract", () => {
+  it("adds the shared GPT-5 behavior contract to Codex GPT-5 provider runs", () => {
+    const provider = buildCodexProvider();
+    const contribution = provider.resolveSystemPromptContribution?.(
+      codexPromptOverlayContext({ modelId: GPT5_CONTRACT_MODEL_ID }),
+    );
+
+    expect(contribution?.stablePrefix).toContain("<persona_latch>");
+    expect(contribution?.sectionOverrides?.interaction_style).toContain(
+      "Live chat tone: short, natural, human.",
+    );
+    expect(contribution?.sectionOverrides?.interaction_style).not.toContain(
+      "Use heartbeats to create useful proactive progress",
+    );
+  });
+
+  it("respects shared GPT-5 prompt overlay config for Codex runs", () => {
+    const provider = buildCodexProvider();
+    const contribution = provider.resolveSystemPromptContribution?.(
+      codexPromptOverlayContext({
+        modelId: GPT5_CONTRACT_MODEL_ID,
+        config: sharedGpt5PersonalityConfig("off"),
+      }),
+    );
+
+    expect(contribution?.stablePrefix).toContain("<persona_latch>");
+    expect(contribution?.sectionOverrides).toStrictEqual({});
+  });
+
+  it("does not add the shared GPT-5 overlay to non-GPT-5 Codex provider runs", () => {
+    const provider = buildCodexProvider();
+
+    expect(
+      provider.resolveSystemPromptContribution?.(
+        codexPromptOverlayContext({ modelId: NON_GPT5_CONTRACT_MODEL_ID }),
+      ),
+    ).toBeUndefined();
+  });
+});

package/extensions/codex/prompt-overlay.ts

@@ -0,0 +1,21 @@
+import {
+  GPT5_BEHAVIOR_CONTRACT,
+  GPT5_HEARTBEAT_PROMPT_OVERLAY,
+  renderGpt5PromptOverlay,
+  resolveGpt5SystemPromptContribution,
+} from "openclaw/plugin-sdk/provider-model-shared";
+
+export const CODEX_GPT5_BEHAVIOR_CONTRACT = GPT5_BEHAVIOR_CONTRACT;
+export const CODEX_GPT5_HEARTBEAT_PROMPT_OVERLAY = GPT5_HEARTBEAT_PROMPT_OVERLAY;
+
+export function resolveCodexSystemPromptContribution(
+  params: Parameters<typeof resolveGpt5SystemPromptContribution>[0],
+) {
+  return resolveGpt5SystemPromptContribution(params);
+}
+
+export function renderCodexPromptOverlay(
+  params: Parameters<typeof renderGpt5PromptOverlay>[0],
+): string | undefined {
+  return renderGpt5PromptOverlay(params);
+}

package/extensions/codex/provider-catalog.ts

@@ -0,0 +1,83 @@
+import type {
+  ModelDefinitionConfig,
+  ModelProviderConfig,
+} from "openclaw/plugin-sdk/provider-model-shared";
+import type { CodexAppServerModel } from "./src/app-server/models.js";
+
+export const CODEX_PROVIDER_ID = "codex";
+export const CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+export const CODEX_APP_SERVER_AUTH_MARKER = "codex-app-server";
+
+const DEFAULT_CONTEXT_WINDOW = 272_000;
+const DEFAULT_MAX_TOKENS = 128_000;
+
+export const FALLBACK_CODEX_MODELS = [
+  {
+    id: "gpt-5.5",
+    model: "gpt-5.5",
+    displayName: "gpt-5.5",
+    description: "Latest frontier agentic coding model.",
+    isDefault: true,
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+  {
+    id: "gpt-5.4-mini",
+    model: "gpt-5.4-mini",
+    displayName: "GPT-5.4-Mini",
+    description: "Smaller frontier agentic coding model.",
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+  {
+    id: "gpt-5.2",
+    model: "gpt-5.2",
+    displayName: "gpt-5.2",
+    inputModalities: ["text", "image"],
+    supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+  },
+] satisfies CodexAppServerModel[];
+
+export function buildCodexModelDefinition(model: {
+  id: string;
+  model: string;
+  displayName?: string;
+  inputModalities: string[];
+  supportedReasoningEfforts: string[];
+}): ModelDefinitionConfig {
+  const id = model.id.trim() || model.model.trim();
+  return {
+    id,
+    name: model.displayName?.trim() || id,
+    api: "openai-codex-responses",
+    reasoning: model.supportedReasoningEfforts.length > 0 || shouldDefaultToReasoningModel(id),
+    input: model.inputModalities.includes("image") ? ["text", "image"] : ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: DEFAULT_CONTEXT_WINDOW,
+    maxTokens: DEFAULT_MAX_TOKENS,
+    compat: {
+      supportsReasoningEffort: model.supportedReasoningEfforts.length > 0,
+      supportsUsageInStreaming: true,
+    },
+  };
+}
+
+export function buildCodexProviderConfig(models: CodexAppServerModel[]): ModelProviderConfig {
+  return {
+    baseUrl: CODEX_BASE_URL,
+    apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+    auth: "token",
+    api: "openai-codex-responses",
+    models: models.map(buildCodexModelDefinition),
+  };
+}
+
+function shouldDefaultToReasoningModel(modelId: string): boolean {
+  const lower = modelId.toLowerCase();
+  return (
+    lower.startsWith("gpt-5") ||
+    lower.startsWith("o1") ||
+    lower.startsWith("o3") ||
+    lower.startsWith("o4")
+  );
+}

package/extensions/codex/provider-discovery.ts

@@ -0,0 +1,45 @@
+import type { ProviderCatalogContext } from "openclaw/plugin-sdk/provider-catalog-shared";
+import type { ProviderPlugin } from "openclaw/plugin-sdk/provider-model-shared";
+import {
+  buildCodexProviderConfig,
+  CODEX_APP_SERVER_AUTH_MARKER,
+  CODEX_PROVIDER_ID,
+  FALLBACK_CODEX_MODELS,
+} from "./provider-catalog.js";
+
+function resolveCodexPluginConfig(ctx: ProviderCatalogContext): unknown {
+  return (ctx.config.plugins?.entries as Record<string, { config?: unknown } | undefined>)?.codex
+    ?.config;
+}
+
+async function runCodexCatalog(ctx: ProviderCatalogContext) {
+  const { buildCodexProviderCatalog } = await import("./provider.js");
+  return await buildCodexProviderCatalog({
+    env: ctx.env,
+    pluginConfig: resolveCodexPluginConfig(ctx),
+  });
+}
+
+export const codexProviderDiscovery: ProviderPlugin = {
+  id: CODEX_PROVIDER_ID,
+  label: "Codex",
+  docsPath: "/providers/models",
+  auth: [],
+  catalog: {
+    order: "late",
+    run: runCodexCatalog,
+  },
+  staticCatalog: {
+    order: "late",
+    run: async () => ({
+      provider: buildCodexProviderConfig(FALLBACK_CODEX_MODELS),
+    }),
+  },
+  resolveSyntheticAuth: () => ({
+    apiKey: CODEX_APP_SERVER_AUTH_MARKER,
+    source: "codex-app-server",
+    mode: "token",
+  }),
+};
+
+export default codexProviderDiscovery;