@nextclaw/nextclaw-engine-claude-agent-sdk 0.2.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,34 @@
+# @nextclaw/nextclaw-engine-claude-agent-sdk
+
+Independent NextClaw engine plugin that registers `claude-agent-sdk` using Anthropic official `@anthropic-ai/claude-agent-sdk`.
+
+## Build
+
+```bash
+pnpm -C packages/extensions/nextclaw-engine-plugin-claude-agent-sdk build
+```
+
+## Usage (local path)
+
+Add plugin load path to config:
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": [
+        "/absolute/path/to/packages/extensions/nextclaw-engine-plugin-claude-agent-sdk"
+      ]
+    }
+  },
+  "agents": {
+    "defaults": {
+      "engine": "claude-agent-sdk",
+      "model": "claude-sonnet-4-6",
+      "engineConfig": {
+        "apiKey": "sk-ant-xxx"
+      }
+    }
+  }
+}
+```

package/claude-agent-sdk-loader.cjs

@@ -0,0 +1,17 @@
+let cachedModule = null;
+
+async function loadClaudeAgentSdkModule() {
+  if (cachedModule) {
+    return cachedModule;
+  }
+  const mod = await import("@anthropic-ai/claude-agent-sdk");
+  if (!mod || typeof mod.query !== "function") {
+    throw new Error("[claude-agent-sdk] failed to load query() from @anthropic-ai/claude-agent-sdk");
+  }
+  cachedModule = mod;
+  return cachedModule;
+}
+
+module.exports = {
+  loadClaudeAgentSdkModule
+};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AgentEngineFactoryContext, AgentEngine } from '@nextclaw/core';
+
+type PluginApi = {
+    registerEngine: (factory: (context: AgentEngineFactoryContext) => AgentEngine, opts?: {
+        kind?: string;
+    }) => 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,432 @@
+import { createRequire } from "node:module";
+import {
+  getApiBase,
+  getProvider,
+  SkillsLoader
+} from "@nextclaw/core";
+function readString(input, key) {
+  const value = input[key];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function readBoolean(input, key) {
+  const value = input[key];
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return void 0;
+}
+function readNumber(input, key) {
+  const value = input[key];
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return void 0;
+}
+function readRecord(input, key) {
+  const value = input[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function readStringRecord(input, key) {
+  const value = readRecord(input, key);
+  if (!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 readStringOrNullRecord(input, key) {
+  const value = readRecord(input, key);
+  if (!value) {
+    return void 0;
+  }
+  const out = {};
+  for (const [entryKey, entryValue] of Object.entries(value)) {
+    if (typeof entryValue === "string") {
+      out[entryKey] = entryValue.trim();
+      continue;
+    }
+    if (entryValue === null) {
+      out[entryKey] = null;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function readStringArray(input, key) {
+  const value = input[key];
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const normalized = value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readRequestedSkills(metadata) {
+  if (!metadata) {
+    return [];
+  }
+  const raw = metadata.requested_skills ?? metadata.requestedSkills;
+  const values = [];
+  if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      if (typeof entry !== "string") {
+        continue;
+      }
+      const trimmed = entry.trim();
+      if (trimmed) {
+        values.push(trimmed);
+      }
+    }
+  } else if (typeof raw === "string") {
+    values.push(
+      ...raw.split(/[,\s]+/g).map((entry) => entry.trim()).filter(Boolean)
+    );
+  }
+  return Array.from(new Set(values)).slice(0, 8);
+}
+function readPermissionMode(input, key) {
+  const value = readString(input, key);
+  if (value === "default" || value === "acceptEdits" || value === "bypassPermissions" || value === "plan" || value === "dontAsk") {
+    return value;
+  }
+  return void 0;
+}
+function readSettingSources(input, key) {
+  const list = readStringArray(input, key);
+  if (!list) {
+    return void 0;
+  }
+  const out = [];
+  for (const entry of list) {
+    if (entry === "user" || entry === "project" || entry === "local") {
+      out.push(entry);
+    }
+  }
+  return out.length > 0 ? out : void 0;
+}
+function readExecutable(input, key) {
+  const value = readString(input, key);
+  if (value === "node" || value === "bun" || value === "deno") {
+    return value;
+  }
+  return void 0;
+}
+function normalizeClaudeModel(value) {
+  const trimmed = value.trim();
+  if (!trimmed.includes("/")) {
+    return trimmed;
+  }
+  const parts = trimmed.split("/").filter(Boolean);
+  return parts[parts.length - 1] ?? trimmed;
+}
+function resolveEngineConfig(config, model, engineConfig) {
+  const provider = getProvider(config, model);
+  const apiKey = readString(engineConfig, "apiKey") ?? provider?.apiKey ?? void 0;
+  const apiBase = readString(engineConfig, "apiBase") ?? getApiBase(config, model) ?? void 0;
+  return { apiKey, apiBase };
+}
+const require2 = createRequire(import.meta.url);
+const claudeAgentLoader = require2("../claude-agent-sdk-loader.cjs");
+class PluginClaudeAgentSdkEngine {
+  constructor(options) {
+    this.options = options;
+    this.defaultModel = options.model;
+    this.skillsLoader = new SkillsLoader(options.workspace);
+  }
+  kind = "claude-agent-sdk";
+  sdkModulePromise = null;
+  sessionIdsByKey = /* @__PURE__ */ new Map();
+  defaultModel;
+  skillsLoader;
+  async handleInbound(params) {
+    const reply = await this.processDirect({
+      content: params.message.content,
+      sessionKey: params.sessionKey,
+      channel: params.message.channel,
+      chatId: params.message.chatId,
+      metadata: params.message.metadata
+    });
+    if (!reply.trim()) {
+      return null;
+    }
+    const outbound = {
+      channel: params.message.channel,
+      chatId: params.message.chatId,
+      content: reply,
+      media: [],
+      metadata: {}
+    };
+    if (params.publishResponse ?? true) {
+      await this.options.bus.publishOutbound(outbound);
+    }
+    return outbound;
+  }
+  async processDirect(params) {
+    const sessionKey = typeof params.sessionKey === "string" && params.sessionKey.trim() ? params.sessionKey : "cli:direct";
+    const channel = typeof params.channel === "string" && params.channel.trim() ? params.channel : "cli";
+    const chatId = typeof params.chatId === "string" && params.chatId.trim() ? params.chatId : "direct";
+    const session = this.options.sessionManager.getOrCreate(sessionKey);
+    const modelInput = readString(params.metadata ?? {}, "model") ?? this.defaultModel;
+    const model = normalizeClaudeModel(modelInput);
+    const requestedSkills = readRequestedSkills(params.metadata ?? {});
+    const userExtra = { channel, chatId };
+    if (requestedSkills.length > 0) {
+      userExtra.requested_skills = requestedSkills;
+    }
+    const userEvent = this.options.sessionManager.addMessage(session, "user", params.content, userExtra);
+    params.onSessionEvent?.(userEvent);
+    const sdk = await this.getSdkModule();
+    const abortController = new AbortController();
+    const timeout = this.createRequestTimeout(abortController);
+    const queryOptions = this.buildQueryOptions(sessionKey, model, abortController);
+    const requestedSkillsContent = this.skillsLoader.loadSkillsForContext(requestedSkills);
+    const prompt = requestedSkillsContent.trim().length > 0 ? [
+      "## Requested Skills",
+      "Use the following selected skills for this turn:",
+      requestedSkillsContent,
+      "## User Message",
+      params.content
+    ].join("\n\n") : params.content;
+    const query = sdk.query({
+      prompt,
+      options: queryOptions
+    });
+    const assistantMessages = [];
+    let resultReply = "";
+    try {
+      for await (const message of query) {
+        this.trackSessionId(sessionKey, message);
+        const streamEvent = this.options.sessionManager.appendEvent(session, {
+          type: this.toSessionEventType(message),
+          data: { message },
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        params.onSessionEvent?.(streamEvent);
+        const delta = this.extractAssistantDelta(message);
+        if (delta) {
+          params.onAssistantDelta?.(delta);
+        }
+        const assistantText = this.extractAssistantText(message);
+        if (assistantText) {
+          assistantMessages.push(assistantText);
+        }
+        const result = this.extractResultMessage(message);
+        if (!result) {
+          continue;
+        }
+        if (!result.ok) {
+          throw new Error(result.error);
+        }
+        resultReply = result.text;
+      }
+    } finally {
+      if (timeout !== null) {
+        clearTimeout(timeout);
+      }
+      query.close();
+    }
+    const assistantReply = assistantMessages.join("\n").trim();
+    const reply = assistantReply || resultReply.trim();
+    const assistantEvent = this.options.sessionManager.addMessage(session, "assistant", reply, {
+      channel,
+      chatId
+    });
+    params.onSessionEvent?.(assistantEvent);
+    this.options.sessionManager.save(session);
+    return reply;
+  }
+  applyRuntimeConfig(_config) {
+  }
+  async getSdkModule() {
+    if (!this.sdkModulePromise) {
+      this.sdkModulePromise = claudeAgentLoader.loadClaudeAgentSdkModule();
+    }
+    return this.sdkModulePromise;
+  }
+  buildQueryOptions(sessionKey, model, abortController) {
+    const env = {
+      ...process.env,
+      ...this.options.env ?? {}
+    };
+    if (this.options.apiKey) {
+      env.ANTHROPIC_API_KEY = this.options.apiKey;
+    }
+    if (this.options.apiBase) {
+      env.ANTHROPIC_BASE_URL = this.options.apiBase;
+      env.ANTHROPIC_API_URL = this.options.apiBase;
+    }
+    const options = {
+      ...this.options.baseQueryOptions,
+      abortController,
+      cwd: this.options.workspace,
+      model,
+      env
+    };
+    const resumeSessionId = this.sessionIdsByKey.get(sessionKey);
+    if (resumeSessionId) {
+      options.resume = resumeSessionId;
+    }
+    if (options.permissionMode === "bypassPermissions" && options.allowDangerouslySkipPermissions !== true) {
+      options.allowDangerouslySkipPermissions = true;
+    }
+    return options;
+  }
+  createRequestTimeout(abortController) {
+    if (this.options.requestTimeoutMs <= 0) {
+      return null;
+    }
+    const timeout = setTimeout(() => {
+      abortController.abort();
+    }, this.options.requestTimeoutMs);
+    timeout.unref?.();
+    return timeout;
+  }
+  trackSessionId(sessionKey, message) {
+    const maybeSessionId = message && typeof message === "object" && "session_id" in message ? message.session_id : void 0;
+    if (typeof maybeSessionId === "string" && maybeSessionId.trim()) {
+      this.sessionIdsByKey.set(sessionKey, maybeSessionId.trim());
+    }
+  }
+  toSessionEventType(message) {
+    const baseType = message && typeof message === "object" && "type" in message && typeof message.type === "string" ? message.type : "unknown";
+    const maybeSubtype = message && typeof message === "object" && "subtype" in message ? message.subtype : void 0;
+    if (typeof maybeSubtype === "string" && maybeSubtype.trim()) {
+      return `engine.claude.${baseType}.${maybeSubtype.trim()}`;
+    }
+    return `engine.claude.${baseType}`;
+  }
+  extractAssistantText(message) {
+    if (message.type !== "assistant") {
+      return "";
+    }
+    const payload = message.message;
+    const content = payload?.content;
+    if (typeof content === "string") {
+      return content.trim();
+    }
+    if (!Array.isArray(content)) {
+      return "";
+    }
+    const text = content.map((block) => {
+      if (!block || typeof block !== "object") {
+        return "";
+      }
+      const candidate = block;
+      if (candidate.type !== "text" || typeof candidate.text !== "string") {
+        return "";
+      }
+      return candidate.text;
+    }).join("").trim();
+    return text;
+  }
+  extractAssistantDelta(message) {
+    if (message.type !== "stream_event") {
+      return "";
+    }
+    const event = message.event;
+    if (!event || typeof event !== "object") {
+      return "";
+    }
+    const eventObj = event;
+    if (eventObj.type === "content_block_delta") {
+      const delta = eventObj.delta;
+      if (delta?.type === "text_delta" && typeof delta.text === "string") {
+        return delta.text;
+      }
+    }
+    if (typeof eventObj.text === "string") {
+      return eventObj.text;
+    }
+    return "";
+  }
+  extractResultMessage(message) {
+    if (message.type !== "result") {
+      return null;
+    }
+    if (message.subtype === "success") {
+      return { ok: true, text: typeof message.result === "string" ? message.result : "" };
+    }
+    const errors = Array.isArray(message.errors) ? message.errors.map((entry) => String(entry)).filter(Boolean) : [];
+    return {
+      ok: false,
+      error: errors.join("; ") || `claude-agent-sdk execution failed: ${message.subtype}`
+    };
+  }
+}
+const plugin = {
+  id: "nextclaw-engine-claude-agent-sdk",
+  name: "NextClaw Claude Agent SDK Engine",
+  description: "Registers engine kind `claude-agent-sdk` backed by Anthropic Claude Agent SDK.",
+  configSchema: {
+    type: "object",
+    additionalProperties: true,
+    properties: {}
+  },
+  register(api) {
+    api.registerEngine(
+      (context) => {
+        const engineConfig = context.engineConfig ?? {};
+        const modelInput = readString(engineConfig, "model") ?? context.model;
+        const model = normalizeClaudeModel(modelInput);
+        const resolved = resolveEngineConfig(context.config, modelInput, engineConfig);
+        const permissionMode = readPermissionMode(engineConfig, "permissionMode") ?? "bypassPermissions";
+        const allowDangerouslySkipPermissions = readBoolean(engineConfig, "allowDangerouslySkipPermissions");
+        const includePartialMessages = readBoolean(engineConfig, "includePartialMessages") ?? true;
+        const maxTurns = readNumber(engineConfig, "maxTurns") ?? context.maxIterations;
+        const maxThinkingTokens = readNumber(engineConfig, "maxThinkingTokens");
+        const requestTimeoutMs = Math.max(0, Math.trunc(readNumber(engineConfig, "requestTimeoutMs") ?? 3e4));
+        const baseQueryOptions = {
+          permissionMode,
+          includePartialMessages,
+          maxTurns,
+          additionalDirectories: readStringArray(engineConfig, "additionalDirectories"),
+          allowedTools: readStringArray(engineConfig, "allowedTools"),
+          disallowedTools: readStringArray(engineConfig, "disallowedTools"),
+          settingSources: readSettingSources(engineConfig, "settingSources"),
+          pathToClaudeCodeExecutable: readString(engineConfig, "pathToClaudeCodeExecutable") ?? readString(engineConfig, "claudeCodePath"),
+          executable: readExecutable(engineConfig, "executable"),
+          executableArgs: readStringArray(engineConfig, "executableArgs"),
+          extraArgs: readStringOrNullRecord(engineConfig, "extraArgs"),
+          sandbox: readRecord(engineConfig, "sandbox"),
+          persistSession: readBoolean(engineConfig, "persistSession"),
+          continue: readBoolean(engineConfig, "continue"),
+          ...typeof maxThinkingTokens === "number" ? { maxThinkingTokens } : {}
+        };
+        if (typeof allowDangerouslySkipPermissions === "boolean") {
+          baseQueryOptions.allowDangerouslySkipPermissions = allowDangerouslySkipPermissions;
+        }
+        return new PluginClaudeAgentSdkEngine({
+          bus: context.bus,
+          sessionManager: context.sessionManager,
+          model,
+          workspace: readString(engineConfig, "workingDirectory") ?? context.workspace,
+          apiKey: resolved.apiKey,
+          apiBase: resolved.apiBase,
+          env: readStringRecord(engineConfig, "env"),
+          baseQueryOptions,
+          requestTimeoutMs
+        });
+      },
+      { kind: "claude-agent-sdk" }
+    );
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "nextclaw-engine-claude-agent-sdk",
+  "name": "NextClaw Claude Agent SDK Engine",
+  "description": "Registers engine kind `claude-agent-sdk` backed by Anthropic Claude Agent SDK.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nextclaw/nextclaw-engine-claude-agent-sdk",
+  "version": "0.2.0",
+  "private": false,
+  "description": "NextClaw Claude Agent SDK engine plugin backed by Anthropic official SDK.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "claude-agent-sdk-loader.cjs",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.63",
+    "@nextclaw/core": "^0.7.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}