@nextclaw/nextclaw-ncp-runtime-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,9 @@
+# @nextclaw/nextclaw-ncp-runtime-codex-sdk
+
+Optional NCP runtime adapter backed by OpenAI official `@openai/codex-sdk`.
+
+## Build
+
+```bash
+pnpm -C packages/extensions/nextclaw-ncp-runtime-codex-sdk build
+```

package/codex-sdk-loader.cjs

@@ -0,0 +1,11 @@
+async function loadCodexConstructor() {
+  const mod = await import("@openai/codex-sdk");
+  if (!mod || typeof mod.Codex !== "function") {
+    throw new Error("[codex-ncp-runtime] failed to load Codex constructor from @openai/codex-sdk");
+  }
+  return mod.Codex;
+}
+
+module.exports = {
+  loadCodexConstructor,
+};

package/dist/codex-sdk-ncp-event-mapper.d.ts

@@ -0,0 +1,23 @@
+import { ThreadEvent } from '@openai/codex-sdk';
+import { NcpEndpointEvent } from '@nextclaw/ncp';
+
+type ItemTextSnapshot = {
+    text: string;
+    started: boolean;
+};
+type ToolSnapshot = {
+    started: boolean;
+    argsEmitted: boolean;
+    ended: boolean;
+};
+declare function mapCodexItemEvent(params: {
+    sessionId: string;
+    messageId: string;
+    event: Extract<ThreadEvent, {
+        type: "item.started" | "item.updated" | "item.completed";
+    }>;
+    itemTextById: Map<string, ItemTextSnapshot>;
+    toolStateById: Map<string, ToolSnapshot>;
+}): AsyncGenerator<NcpEndpointEvent>;
+
+export { type ItemTextSnapshot, type ToolSnapshot, mapCodexItemEvent };

package/dist/codex-sdk-ncp-event-mapper.js

@@ -0,0 +1,232 @@
+import { NcpEventType } from "@nextclaw/ncp";
+function buildToolDescriptor(item) {
+  switch (item.type) {
+    case "mcp_tool_call":
+      return {
+        toolName: item.server ? `mcp:${item.server}.${item.tool}` : `mcp:${item.tool}`,
+        args: item.arguments
+      };
+    case "command_execution":
+      return {
+        toolName: "command_execution",
+        args: {
+          command: item.command
+        }
+      };
+    case "web_search":
+      return {
+        toolName: "web_search",
+        args: {
+          query: item.query
+        }
+      };
+    case "file_change":
+      return {
+        toolName: "file_change",
+        args: {
+          changes: item.changes
+        }
+      };
+    case "todo_list":
+      return {
+        toolName: "todo_list",
+        args: {
+          items: item.items
+        }
+      };
+    case "error":
+      return {
+        toolName: "error",
+        args: {
+          message: item.message
+        }
+      };
+  }
+}
+function buildToolResult(item) {
+  switch (item.type) {
+    case "mcp_tool_call":
+      return item.status === "failed" ? { ok: false, error: item.error ?? { message: "MCP tool call failed." } } : {
+        ok: item.status === "completed",
+        status: item.status,
+        result: item.result ?? null
+      };
+    case "command_execution":
+      return {
+        status: item.status,
+        command: item.command,
+        aggregated_output: item.aggregated_output,
+        ...typeof item.exit_code === "number" ? { exit_code: item.exit_code } : {}
+      };
+    case "web_search":
+      return {
+        status: "completed",
+        query: item.query
+      };
+    case "file_change":
+      return {
+        status: item.status,
+        changes: item.changes
+      };
+    case "todo_list":
+      return {
+        status: "completed",
+        items: item.items
+      };
+    case "error":
+      return {
+        ok: false,
+        error: {
+          message: item.message
+        }
+      };
+  }
+}
+function stringifyToolArgs(args) {
+  try {
+    return JSON.stringify(args ?? {});
+  } catch {
+    return JSON.stringify({
+      __serialization_error__: "tool arguments are not JSON serializable"
+    });
+  }
+}
+function isToolLikeItem(item) {
+  return item.type === "mcp_tool_call" || item.type === "command_execution" || item.type === "web_search" || item.type === "file_change" || item.type === "todo_list" || item.type === "error";
+}
+async function* mapCodexItemEvent(params) {
+  const { sessionId, messageId, event, itemTextById, toolStateById } = params;
+  const { item } = event;
+  if (item.type === "agent_message") {
+    const currentText = item.text ?? "";
+    const previous2 = itemTextById.get(item.id) ?? { text: "", started: false };
+    if (!previous2.started) {
+      yield {
+        type: NcpEventType.MessageTextStart,
+        payload: {
+          sessionId,
+          messageId
+        }
+      };
+    }
+    if (currentText.length > previous2.text.length) {
+      const delta = currentText.slice(previous2.text.length);
+      yield {
+        type: NcpEventType.MessageTextDelta,
+        payload: {
+          sessionId,
+          messageId,
+          delta
+        }
+      };
+    }
+    itemTextById.set(item.id, {
+      text: currentText,
+      started: true
+    });
+    if (event.type === "item.completed") {
+      yield {
+        type: NcpEventType.MessageTextEnd,
+        payload: {
+          sessionId,
+          messageId
+        }
+      };
+    }
+    return;
+  }
+  if (item.type === "reasoning") {
+    const currentText = item.text ?? "";
+    const previous2 = itemTextById.get(item.id) ?? { text: "", started: false };
+    if (!previous2.started) {
+      yield {
+        type: NcpEventType.MessageReasoningStart,
+        payload: {
+          sessionId,
+          messageId
+        }
+      };
+    }
+    if (currentText.length > previous2.text.length) {
+      const delta = currentText.slice(previous2.text.length);
+      yield {
+        type: NcpEventType.MessageReasoningDelta,
+        payload: {
+          sessionId,
+          messageId,
+          delta
+        }
+      };
+    }
+    itemTextById.set(item.id, {
+      text: currentText,
+      started: true
+    });
+    if (event.type === "item.completed") {
+      yield {
+        type: NcpEventType.MessageReasoningEnd,
+        payload: {
+          sessionId,
+          messageId
+        }
+      };
+    }
+    return;
+  }
+  if (!isToolLikeItem(item)) {
+    return;
+  }
+  const previous = toolStateById.get(item.id) ?? {
+    started: false,
+    argsEmitted: false,
+    ended: false
+  };
+  const descriptor = buildToolDescriptor(item);
+  if (!previous.started) {
+    yield {
+      type: NcpEventType.MessageToolCallStart,
+      payload: {
+        sessionId,
+        messageId,
+        toolCallId: item.id,
+        toolName: descriptor.toolName
+      }
+    };
+    previous.started = true;
+  }
+  if (!previous.argsEmitted) {
+    yield {
+      type: NcpEventType.MessageToolCallArgs,
+      payload: {
+        sessionId,
+        toolCallId: item.id,
+        args: stringifyToolArgs(descriptor.args)
+      }
+    };
+    previous.argsEmitted = true;
+  }
+  if (!previous.ended) {
+    yield {
+      type: NcpEventType.MessageToolCallEnd,
+      payload: {
+        sessionId,
+        toolCallId: item.id
+      }
+    };
+    previous.ended = true;
+  }
+  if (event.type === "item.updated" || event.type === "item.completed") {
+    yield {
+      type: NcpEventType.MessageToolCallResult,
+      payload: {
+        sessionId,
+        toolCallId: item.id,
+        content: buildToolResult(item)
+      }
+    };
+  }
+  toolStateById.set(item.id, previous);
+}
+export {
+  mapCodexItemEvent
+};

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { CodexOptions, ThreadOptions } from '@openai/codex-sdk';
+import { NcpAgentRuntime, NcpAgentRunInput, NcpAgentRunOptions, NcpEndpointEvent } from '@nextclaw/ncp';
+
+type CodexSdkNcpAgentRuntimeConfig = {
+    sessionId: string;
+    apiKey: string;
+    apiBase?: string;
+    model?: string;
+    threadId?: string | null;
+    codexPathOverride?: string;
+    env?: Record<string, string>;
+    cliConfig?: CodexOptions["config"];
+    threadOptions?: ThreadOptions;
+    sessionMetadata?: Record<string, unknown>;
+    setSessionMetadata?: (nextMetadata: Record<string, unknown>) => void;
+    inputBuilder?: (input: NcpAgentRunInput) => Promise<string> | string;
+};
+declare class CodexSdkNcpAgentRuntime implements NcpAgentRuntime {
+    private readonly config;
+    private codexPromise;
+    private thread;
+    private threadId;
+    private readonly sessionMetadata;
+    constructor(config: CodexSdkNcpAgentRuntimeConfig);
+    run(input: NcpAgentRunInput, options?: NcpAgentRunOptions): AsyncGenerator<NcpEndpointEvent>;
+    private getCodex;
+    private resolveThread;
+    private buildTurnInput;
+    private updateThreadId;
+}
+
+export { CodexSdkNcpAgentRuntime, type CodexSdkNcpAgentRuntimeConfig };

package/dist/index.js

@@ -0,0 +1,227 @@
+import { createRequire } from "node:module";
+import { NcpEventType } from "@nextclaw/ncp";
+import {
+  mapCodexItemEvent
+} from "./codex-sdk-ncp-event-mapper.js";
+const require2 = createRequire(import.meta.url);
+const codexLoader = require2("../codex-sdk-loader.cjs");
+function createId(prefix) {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+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 toAbortError(reason) {
+  if (reason instanceof Error) {
+    return reason;
+  }
+  const message = typeof reason === "string" && reason.trim() ? reason.trim() : "operation aborted";
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+class CodexSdkNcpAgentRuntime {
+  constructor(config) {
+    this.config = config;
+    this.threadId = config.threadId?.trim() || null;
+    this.sessionMetadata = {
+      ...config.sessionMetadata ? structuredClone(config.sessionMetadata) : {}
+    };
+  }
+  codexPromise = null;
+  thread = null;
+  threadId;
+  sessionMetadata;
+  async *run(input, options) {
+    const messageId = createId("codex-message");
+    const runId = createId("codex-run");
+    const itemTextById = /* @__PURE__ */ new Map();
+    const toolStateById = /* @__PURE__ */ new Map();
+    let finished = false;
+    yield {
+      type: NcpEventType.RunStarted,
+      payload: {
+        sessionId: input.sessionId,
+        messageId,
+        runId
+      }
+    };
+    yield {
+      type: NcpEventType.RunMetadata,
+      payload: {
+        sessionId: input.sessionId,
+        messageId,
+        runId,
+        metadata: {
+          kind: "ready",
+          runId,
+          sessionId: input.sessionId,
+          supportsAbort: true
+        }
+      }
+    };
+    const thread = await this.resolveThread();
+    const turnInput = await this.buildTurnInput(input);
+    const streamed = await thread.runStreamed(turnInput, {
+      ...options?.signal ? { signal: options.signal } : {}
+    });
+    try {
+      for await (const event of streamed.events) {
+        if (options?.signal?.aborted) {
+          throw toAbortError(options.signal.reason);
+        }
+        if (event.type === "thread.started") {
+          this.updateThreadId(event.thread_id);
+          continue;
+        }
+        if (event.type === "turn.failed") {
+          yield {
+            type: NcpEventType.RunError,
+            payload: {
+              sessionId: input.sessionId,
+              messageId,
+              runId,
+              error: event.error.message
+            }
+          };
+          finished = true;
+          return;
+        }
+        if (event.type === "error") {
+          yield {
+            type: NcpEventType.RunError,
+            payload: {
+              sessionId: input.sessionId,
+              messageId,
+              runId,
+              error: event.message
+            }
+          };
+          finished = true;
+          return;
+        }
+        if (event.type === "item.started" || event.type === "item.updated" || event.type === "item.completed") {
+          yield* mapCodexItemEvent({
+            sessionId: input.sessionId,
+            messageId,
+            event,
+            itemTextById,
+            toolStateById
+          });
+          continue;
+        }
+        if (event.type === "turn.completed") {
+          yield {
+            type: NcpEventType.RunMetadata,
+            payload: {
+              sessionId: input.sessionId,
+              messageId,
+              runId,
+              metadata: {
+                kind: "final",
+                sessionId: input.sessionId
+              }
+            }
+          };
+          yield {
+            type: NcpEventType.RunFinished,
+            payload: {
+              sessionId: input.sessionId,
+              messageId,
+              runId
+            }
+          };
+          finished = true;
+          return;
+        }
+      }
+      if (!finished) {
+        yield {
+          type: NcpEventType.RunMetadata,
+          payload: {
+            sessionId: input.sessionId,
+            messageId,
+            runId,
+            metadata: {
+              kind: "final",
+              sessionId: input.sessionId
+            }
+          }
+        };
+        yield {
+          type: NcpEventType.RunFinished,
+          payload: {
+            sessionId: input.sessionId,
+            messageId,
+            runId
+          }
+        };
+      }
+    } catch (error) {
+      if (options?.signal?.aborted) {
+        throw toAbortError(options.signal.reason);
+      }
+      throw error;
+    }
+  }
+  async getCodex() {
+    if (!this.codexPromise) {
+      this.codexPromise = codexLoader.loadCodexConstructor().then(
+        (Ctor) => new Ctor({
+          apiKey: this.config.apiKey,
+          baseUrl: this.config.apiBase,
+          ...this.config.codexPathOverride ? { codexPathOverride: this.config.codexPathOverride } : {},
+          ...this.config.env ? { env: this.config.env } : {},
+          ...this.config.cliConfig ? { config: this.config.cliConfig } : {}
+        })
+      );
+    }
+    return this.codexPromise;
+  }
+  async resolveThread() {
+    if (this.thread) {
+      return this.thread;
+    }
+    const codex = await this.getCodex();
+    const threadOptions = {
+      ...this.config.threadOptions,
+      ...this.config.model ? { model: this.config.model } : {}
+    };
+    this.thread = this.threadId ? codex.resumeThread(this.threadId, threadOptions) : codex.startThread(threadOptions);
+    return this.thread;
+  }
+  async buildTurnInput(input) {
+    if (this.config.inputBuilder) {
+      return await this.config.inputBuilder(input);
+    }
+    return readUserText(input);
+  }
+  updateThreadId(nextThreadId) {
+    const normalizedThreadId = nextThreadId.trim();
+    if (!normalizedThreadId || normalizedThreadId === this.threadId) {
+      return;
+    }
+    this.threadId = normalizedThreadId;
+    const nextMetadata = {
+      ...this.sessionMetadata,
+      session_type: "codex",
+      codex_thread_id: normalizedThreadId
+    };
+    this.sessionMetadata.codex_thread_id = normalizedThreadId;
+    this.sessionMetadata.session_type = "codex";
+    this.config.setSessionMetadata?.(nextMetadata);
+  }
+}
+export {
+  CodexSdkNcpAgentRuntime
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nextclaw/nextclaw-ncp-runtime-codex-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Optional NCP runtime adapter backed by OpenAI Codex SDK.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "codex-sdk-loader.cjs",
+    "README.md"
+  ],
+  "dependencies": {
+    "@openai/codex-sdk": "^0.107.0",
+    "@nextclaw/ncp": "0.3.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"
+  }
+}