@nextclaw/nextclaw-ncp-runtime-plugin-codex-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @nextclaw/nextclaw-ncp-runtime-plugin-codex-sdk
+
+Plugin package that registers the `codex` NCP session type for NextClaw.
+
+It composes the pure runtime library from `@nextclaw/nextclaw-ncp-runtime-codex-sdk` and exposes it through the standard plugin system.
+
+## Build
+
+```bash
+pnpm -C packages/extensions/nextclaw-ncp-runtime-plugin-codex-sdk build
+```

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import { Config } from '@nextclaw/core';
+import { NcpAgentRuntime } from '@nextclaw/ncp';
+import { RuntimeFactoryParams } from '@nextclaw/ncp-toolkit';
+
+type PluginApi = {
+    config: Config;
+    pluginConfig?: Record<string, unknown>;
+    registerNcpAgentRuntime: (registration: {
+        kind: string;
+        label?: string;
+        createRuntime: (params: RuntimeFactoryParams) => NcpAgentRuntime;
+    }) => void;
+};
+type PluginDefinition = {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: Record<string, unknown>;
+    register: (api: PluginApi) => void;
+};
+declare const plugin: PluginDefinition;
+
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,168 @@
+import {
+  getApiBase,
+  getProvider,
+  getWorkspacePath,
+  SkillsLoader
+} from "@nextclaw/core";
+import {
+  CodexSdkNcpAgentRuntime
+} from "@nextclaw/nextclaw-ncp-runtime-codex-sdk";
+const PLUGIN_ID = "nextclaw-ncp-runtime-plugin-codex-sdk";
+const CODEX_RUNTIME_KIND = "codex";
+function readString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function readBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function readRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const values = value.map((entry) => readString(entry)).filter((entry) => Boolean(entry));
+  return values.length > 0 ? values : void 0;
+}
+function readStringRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const out = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue !== "string") {
+      continue;
+    }
+    const normalized = entryValue.trim();
+    if (!normalized) {
+      continue;
+    }
+    out[entryKey] = normalized;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function readThinkingLevel(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "minimal" || normalized === "low" || normalized === "medium" || normalized === "high" || normalized === "xhigh") {
+    return normalized;
+  }
+  return void 0;
+}
+function readRequestedSkills(metadata) {
+  const raw = metadata.requested_skills ?? metadata.requestedSkills;
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.map((entry) => readString(entry)).filter((entry) => Boolean(entry)).slice(0, 8);
+}
+function readUserText(input) {
+  for (let index = input.messages.length - 1; index >= 0; index -= 1) {
+    const message = input.messages[index];
+    if (message?.role !== "user") {
+      continue;
+    }
+    const text = message.parts.filter((part) => part.type === "text").map((part) => part.text).join("").trim();
+    if (text) {
+      return text;
+    }
+  }
+  return "";
+}
+function buildCodexInputBuilder(workspace) {
+  const skillsLoader = new SkillsLoader(workspace);
+  return async (input) => {
+    const userText = readUserText(input);
+    const metadata = input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata) ? input.metadata : {};
+    const requestedSkills = readRequestedSkills(metadata);
+    const requestedSkillsContent = skillsLoader.loadSkillsForContext(requestedSkills);
+    if (requestedSkillsContent.trim().length === 0) {
+      return userText;
+    }
+    return [
+      "## Requested Skills",
+      `Selected skill names: ${requestedSkills.join(", ")}`,
+      requestedSkillsContent,
+      "## User Message",
+      userText
+    ].join("\n\n");
+  };
+}
+function resolveCodexModel(params) {
+  return readString(params.sessionMetadata.preferred_model) ?? readString(params.sessionMetadata.model) ?? readString(params.pluginConfig.model) ?? params.config.agents.defaults.model;
+}
+const plugin = {
+  id: PLUGIN_ID,
+  name: "NextClaw Codex NCP Runtime",
+  description: "Registers NCP session type `codex` backed by OpenAI Codex SDK.",
+  configSchema: {
+    type: "object",
+    additionalProperties: true,
+    properties: {}
+  },
+  register(api) {
+    const pluginConfig = readRecord(api.pluginConfig) ?? {};
+    api.registerNcpAgentRuntime({
+      kind: CODEX_RUNTIME_KIND,
+      label: "Codex",
+      createRuntime: (runtimeParams) => {
+        const nextConfig = api.config;
+        const model = resolveCodexModel({
+          config: nextConfig,
+          pluginConfig,
+          sessionMetadata: runtimeParams.sessionMetadata
+        });
+        const provider = getProvider(nextConfig, model);
+        const apiKey = readString(pluginConfig.apiKey) ?? provider?.apiKey ?? void 0;
+        if (!apiKey) {
+          throw new Error(
+            `[codex] missing apiKey. Set plugins.entries.${PLUGIN_ID}.config.apiKey or providers.*.apiKey for model "${model}".`
+          );
+        }
+        const workspace = getWorkspacePath(
+          readString(pluginConfig.workingDirectory) ?? nextConfig.agents.defaults.workspace
+        );
+        const thinkingLevel = readThinkingLevel(runtimeParams.sessionMetadata.preferred_thinking) ?? readThinkingLevel(runtimeParams.sessionMetadata.thinking) ?? void 0;
+        return new CodexSdkNcpAgentRuntime({
+          sessionId: runtimeParams.sessionId,
+          apiKey,
+          apiBase: readString(pluginConfig.apiBase) ?? getApiBase(nextConfig, model) ?? void 0,
+          model,
+          threadId: readString(runtimeParams.sessionMetadata.codex_thread_id) ?? null,
+          codexPathOverride: readString(pluginConfig.codexPathOverride),
+          env: readStringRecord(pluginConfig.env),
+          cliConfig: readRecord(pluginConfig.config),
+          sessionMetadata: runtimeParams.sessionMetadata,
+          setSessionMetadata: runtimeParams.setSessionMetadata,
+          inputBuilder: buildCodexInputBuilder(workspace),
+          threadOptions: {
+            model,
+            sandboxMode: readString(pluginConfig.sandboxMode),
+            workingDirectory: workspace,
+            skipGitRepoCheck: readBoolean(pluginConfig.skipGitRepoCheck),
+            modelReasoningEffort: thinkingLevel,
+            networkAccessEnabled: readBoolean(pluginConfig.networkAccessEnabled),
+            webSearchMode: readString(pluginConfig.webSearchMode),
+            webSearchEnabled: readBoolean(pluginConfig.webSearchEnabled),
+            approvalPolicy: readString(pluginConfig.approvalPolicy),
+            additionalDirectories: readStringArray(pluginConfig.additionalDirectories)
+          }
+        });
+      }
+    });
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,98 @@
+{
+  "id": "nextclaw-ncp-runtime-plugin-codex-sdk",
+  "kind": "agent-runtime",
+  "name": "NextClaw Codex NCP Runtime",
+  "description": "Registers NCP session type `codex` backed by OpenAI Codex SDK.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {
+      "apiKey": {
+        "type": "string"
+      },
+      "apiBase": {
+        "type": "string"
+      },
+      "model": {
+        "type": "string"
+      },
+      "workingDirectory": {
+        "type": "string"
+      },
+      "sandboxMode": {
+        "type": "string",
+        "enum": ["read-only", "workspace-write", "danger-full-access"]
+      },
+      "skipGitRepoCheck": {
+        "type": "boolean"
+      },
+      "networkAccessEnabled": {
+        "type": "boolean"
+      },
+      "webSearchMode": {
+        "type": "string",
+        "enum": ["disabled", "cached", "live"]
+      },
+      "webSearchEnabled": {
+        "type": "boolean"
+      },
+      "approvalPolicy": {
+        "type": "string",
+        "enum": ["never", "on-request", "on-failure", "untrusted"]
+      },
+      "codexPathOverride": {
+        "type": "string"
+      },
+      "additionalDirectories": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        }
+      },
+      "env": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "config": {
+        "type": "object",
+        "additionalProperties": true
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Codex API Key",
+      "help": "Optional. Falls back to the selected provider API key when omitted.",
+      "sensitive": true
+    },
+    "apiBase": {
+      "label": "Codex API Base"
+    },
+    "model": {
+      "label": "Default Model"
+    },
+    "workingDirectory": {
+      "label": "Working Directory",
+      "advanced": true
+    },
+    "sandboxMode": {
+      "label": "Sandbox Mode",
+      "advanced": true
+    },
+    "approvalPolicy": {
+      "label": "Approval Policy",
+      "advanced": true
+    },
+    "networkAccessEnabled": {
+      "label": "Enable Network",
+      "advanced": true
+    },
+    "webSearchEnabled": {
+      "label": "Enable Web Search",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nextclaw/nextclaw-ncp-runtime-plugin-codex-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "NextClaw plugin that registers Codex SDK as an optional NCP runtime.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "dependencies": {
+    "@nextclaw/nextclaw-ncp-runtime-codex-sdk": "0.1.0",
+    "@nextclaw/ncp": "0.3.0",
+    "@nextclaw/ncp-toolkit": "0.3.0",
+    "@nextclaw/core": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}