@nextclaw/ncp-agent-runtime 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/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { NcpContextBuilder, NcpToolRegistry, NcpAgentRunInput, NcpContextPrepareOptions, NcpLLMApiInput, NcpRoundBuffer, NcpToolCallResult, NcpStreamEncoder, OpenAIChatChunk, NcpEncodeContext, NcpEndpointEvent, NcpTool, NcpToolDefinition, NcpLLMApi, NcpLLMApiOptions, NcpAgentRuntime, NcpAgentConversationStateManager, NcpAgentRunOptions } from '@nextclaw/ncp';
+
+declare class DefaultNcpContextBuilder implements NcpContextBuilder {
+    private readonly toolRegistry?;
+    constructor(toolRegistry?: NcpToolRegistry | undefined);
+    prepare: (input: NcpAgentRunInput, options?: NcpContextPrepareOptions) => NcpLLMApiInput;
+}
+
+declare class DefaultNcpRoundBuffer implements NcpRoundBuffer {
+    private text;
+    private readonly toolCalls;
+    private pending;
+    appendText: (delta: string) => void;
+    getText: () => string;
+    appendToolCall: (result: NcpToolCallResult) => void;
+    getToolCalls: () => ReadonlyArray<NcpToolCallResult>;
+    startToolCall: (toolCallId: string, toolName: string) => void;
+    appendToolCallArgs: (args: unknown) => void;
+    consumePendingToolCall: () => {
+        toolCallId: string;
+        toolName: string;
+        args: unknown;
+    } | null;
+    clear: () => void;
+}
+
+/**
+ * Converts LLM stream chunks to NCP events (text, reasoning, tool calls).
+ * Does not emit RunFinished; that is the runtime's responsibility after the loop completes.
+ */
+declare class DefaultNcpStreamEncoder implements NcpStreamEncoder {
+    encode: (stream: AsyncIterable<OpenAIChatChunk>, context: NcpEncodeContext) => AsyncGenerator<NcpEndpointEvent>;
+}
+
+declare class DefaultNcpToolRegistry implements NcpToolRegistry {
+    private readonly tools;
+    constructor(tools?: ReadonlyArray<NcpTool>);
+    register: (tool: NcpTool) => void;
+    listTools: () => ReadonlyArray<NcpTool>;
+    getTool: (name: string) => NcpTool | undefined;
+    getToolDefinitions: () => ReadonlyArray<NcpToolDefinition>;
+    execute: (_toolCallId: string, toolName: string, args: unknown) => Promise<unknown>;
+}
+
+declare class EchoNcpLLMApi implements NcpLLMApi {
+    generate: (input: NcpLLMApiInput, options?: NcpLLMApiOptions) => AsyncGenerator<OpenAIChatChunk>;
+}
+
+type DefaultNcpAgentRuntimeConfig = {
+    contextBuilder: NcpContextBuilder;
+    llmApi: NcpLLMApi;
+    toolRegistry: NcpToolRegistry;
+    stateManager: NcpAgentConversationStateManager;
+    streamEncoder?: NcpStreamEncoder;
+};
+declare class DefaultNcpAgentRuntime implements NcpAgentRuntime {
+    private readonly contextBuilder;
+    private readonly llmApi;
+    private readonly toolRegistry;
+    private readonly stateManager;
+    private readonly streamEncoder;
+    constructor(config: DefaultNcpAgentRuntimeConfig);
+    run: (this: DefaultNcpAgentRuntime, input: NcpAgentRunInput, options?: NcpAgentRunOptions) => AsyncGenerator<NcpEndpointEvent>;
+    /**
+     * Agent loop: LLM stream → encoder events → tool execution (if any) → next round or finish.
+     * RunFinished is emitted only when the entire loop completes (no more tool calls).
+     * The stream encoder does not emit RunFinished; it only converts chunks to NCP events.
+     */
+    private runLoop;
+}
+
+export { DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi };

package/dist/index.js

@@ -0,0 +1,454 @@
+// src/context-builder.ts
+function messageToOpenAI(msg) {
+  const role = msg.role;
+  const parts = msg.parts ?? [];
+  if (role === "user" || role === "system") {
+    const text = parts.filter((p) => p.type === "text").map((p) => p.text).join("");
+    return [{ role, content: text }];
+  }
+  if (role === "assistant") {
+    const texts = [];
+    const toolInvocations = [];
+    for (const p of parts) {
+      if (p.type === "text") {
+        texts.push(p.text);
+      }
+      if (p.type === "tool-invocation" && p.state === "result" && p.result !== void 0) {
+        toolInvocations.push({
+          toolCallId: p.toolCallId ?? "",
+          toolName: p.toolName,
+          args: p.args ?? {},
+          result: p.result
+        });
+      }
+    }
+    const text = texts.join("");
+    const out = [];
+    if (toolInvocations.length > 0) {
+      out.push({
+        role: "assistant",
+        content: text || null,
+        tool_calls: toolInvocations.map((t) => ({
+          id: t.toolCallId,
+          type: "function",
+          function: {
+            name: t.toolName,
+            arguments: typeof t.args === "string" ? t.args : JSON.stringify(t.args ?? {})
+          }
+        }))
+      });
+      for (const t of toolInvocations) {
+        out.push({
+          role: "tool",
+          content: typeof t.result === "string" ? t.result : JSON.stringify(t.result),
+          tool_call_id: t.toolCallId
+        });
+      }
+    } else {
+      out.push({ role: "assistant", content: text });
+    }
+    return out;
+  }
+  return [];
+}
+var DefaultNcpContextBuilder = class {
+  constructor(toolRegistry) {
+    this.toolRegistry = toolRegistry;
+  }
+  prepare = (input, options) => {
+    const maxMessages = options?.maxMessages ?? 50;
+    const sessionMessages = options?.sessionMessages ?? [];
+    const systemPrompt = options?.systemPrompt;
+    const messages = [];
+    if (systemPrompt) {
+      messages.push({ role: "system", content: systemPrompt });
+    }
+    for (const msg of sessionMessages.slice(-maxMessages)) {
+      messages.push(...messageToOpenAI(msg));
+    }
+    for (const msg of input.messages) {
+      messages.push(...messageToOpenAI(msg));
+    }
+    const tools = this.toolRegistry ? this.toolRegistry.getToolDefinitions().map((d) => ({
+      type: "function",
+      function: {
+        name: d.name,
+        description: d.description,
+        parameters: d.parameters
+      }
+    })) : void 0;
+    return {
+      messages,
+      tools: tools && tools.length > 0 ? tools : void 0
+    };
+  };
+};
+
+// src/round-buffer.ts
+var DefaultNcpRoundBuffer = class {
+  text = "";
+  toolCalls = [];
+  pending = null;
+  appendText = (delta) => {
+    this.text += delta;
+  };
+  getText = () => {
+    return this.text;
+  };
+  appendToolCall = (result) => {
+    this.toolCalls.push(result);
+  };
+  getToolCalls = () => {
+    return [...this.toolCalls];
+  };
+  startToolCall = (toolCallId, toolName) => {
+    this.pending = { toolCallId, toolName, args: void 0 };
+  };
+  appendToolCallArgs = (args) => {
+    if (this.pending) this.pending.args = args;
+  };
+  consumePendingToolCall = () => {
+    const p = this.pending;
+    this.pending = null;
+    return p;
+  };
+  clear = () => {
+    this.text = "";
+    this.toolCalls.length = 0;
+    this.pending = null;
+  };
+};
+
+// src/stream-encoder.ts
+import {
+  NcpEventType as NcpEventType2
+} from "@nextclaw/ncp";
+
+// src/stream-encoder.utils.ts
+import { NcpEventType } from "@nextclaw/ncp";
+function getToolCallIndex(toolDelta, fallback) {
+  const idx = toolDelta.index;
+  return typeof idx === "number" && Number.isFinite(idx) ? idx : fallback;
+}
+function applyToolDelta(current, toolDelta) {
+  const next = { ...current, argumentsText: current.argumentsText };
+  if (typeof toolDelta.id === "string" && toolDelta.id.trim()) {
+    next.id = toolDelta.id;
+  }
+  const fn = toolDelta.function;
+  if (fn && typeof fn === "object" && !Array.isArray(fn)) {
+    if (typeof fn.name === "string" && fn.name.trim()) {
+      next.name = fn.name.trim();
+    }
+    if (typeof fn.arguments === "string" && fn.arguments.length > 0) {
+      next.argumentsText += fn.arguments;
+    }
+  }
+  return next;
+}
+function* emitTextDeltas(delta, ctx, state) {
+  const content = delta.content;
+  if (typeof content !== "string" || content.length === 0) return state;
+  if (!state.textStarted) {
+    yield { type: NcpEventType.MessageTextStart, payload: ctx };
+    yield { type: NcpEventType.MessageTextDelta, payload: { ...ctx, delta: content } };
+    return { textStarted: true };
+  }
+  yield { type: NcpEventType.MessageTextDelta, payload: { ...ctx, delta: content } };
+  return state;
+}
+function* emitReasoningDelta(delta, ctx) {
+  const reasoning = delta.reasoning_content ?? delta.reasoning;
+  if (typeof reasoning !== "string" || !reasoning) return;
+  yield { type: NcpEventType.MessageReasoningDelta, payload: { ...ctx, delta: reasoning } };
+}
+function* emitToolCallDeltas(delta, buffers, sessionId) {
+  const toolDeltas = delta.tool_calls;
+  if (!Array.isArray(toolDeltas)) return;
+  for (const toolDelta of toolDeltas) {
+    const index = getToolCallIndex(toolDelta, buffers.size);
+    const prev = buffers.get(index) ?? { argumentsText: "" };
+    const current = applyToolDelta(prev, toolDelta);
+    if (current.id && current.name && !current.emittedStart) {
+      yield {
+        type: NcpEventType.MessageToolCallStart,
+        payload: { sessionId, toolCallId: current.id, toolName: current.name }
+      };
+      buffers.set(index, { ...current, emittedStart: true });
+    } else {
+      buffers.set(index, current);
+    }
+  }
+}
+function* flushToolCalls(buffers, sessionId) {
+  const ordered = Array.from(buffers.entries()).sort(([a], [b]) => a - b);
+  for (const [, buf] of ordered) {
+    if (!buf.id || !buf.name) continue;
+    yield {
+      type: NcpEventType.MessageToolCallArgs,
+      payload: { sessionId, toolCallId: buf.id, args: buf.argumentsText }
+    };
+    yield {
+      type: NcpEventType.MessageToolCallEnd,
+      payload: { sessionId, toolCallId: buf.id }
+    };
+  }
+}
+
+// src/stream-encoder.ts
+var DefaultNcpStreamEncoder = class {
+  encode = async function* (stream, context) {
+    const { sessionId, messageId } = context;
+    let state = { textStarted: false };
+    const toolCallBuffers = /* @__PURE__ */ new Map();
+    for await (const chunk of stream) {
+      const choice = chunk.choices?.[0];
+      if (!choice) continue;
+      const delta = choice.delta;
+      if (delta) {
+        const nextState = yield* emitTextDeltas(delta, { sessionId, messageId }, state);
+        state = nextState;
+        yield* emitReasoningDelta(delta, { sessionId, messageId });
+        yield* emitToolCallDeltas(delta, toolCallBuffers, sessionId);
+      }
+      const finishReason = choice.finish_reason;
+      if (typeof finishReason === "string" && finishReason.trim().length > 0) {
+        yield* flushToolCalls(toolCallBuffers, sessionId);
+        if (state.textStarted) {
+          yield { type: NcpEventType2.MessageTextEnd, payload: { sessionId, messageId } };
+        }
+      }
+    }
+  };
+};
+
+// src/tool-registry.ts
+var DefaultNcpToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  constructor(tools = []) {
+    for (const t of tools) {
+      this.tools.set(t.name, t);
+    }
+  }
+  register = (tool) => {
+    this.tools.set(tool.name, tool);
+  };
+  listTools = () => {
+    return [...this.tools.values()];
+  };
+  getTool = (name) => {
+    return this.tools.get(name);
+  };
+  getToolDefinitions = () => {
+    return this.listTools().map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters
+    }));
+  };
+  execute = async (_toolCallId, toolName, args) => {
+    const tool = this.tools.get(toolName);
+    return tool ? await tool.execute(args) : void 0;
+  };
+};
+
+// src/llm-api-echo.ts
+function getLastUserContent(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.role !== "user") continue;
+    if (typeof m.content === "string") return m.content;
+    if (Array.isArray(m.content)) {
+      return m.content.map((p) => p.type === "text" ? p.text : "").join("");
+    }
+  }
+  return "";
+}
+var EchoNcpLLMApi = class {
+  generate = async function* (input, options) {
+    const text = getLastUserContent(input.messages);
+    const signal = options?.signal;
+    for (const char of text) {
+      if (signal?.aborted) break;
+      yield {
+        choices: [{ index: 0, delta: { content: char } }]
+      };
+    }
+    yield {
+      choices: [
+        {
+          index: 0,
+          delta: {},
+          finish_reason: "stop"
+        }
+      ],
+      usage: { prompt_tokens: 0, completion_tokens: text.length, total_tokens: text.length }
+    };
+  };
+};
+
+// src/runtime.ts
+import {
+  NcpEventType as NcpEventType3
+} from "@nextclaw/ncp";
+
+// src/utils.ts
+function genId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function parseToolArgs(args) {
+  if (typeof args === "string") {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return args;
+    }
+  }
+  return args;
+}
+function appendToolRoundToInput(input, text, toolResults) {
+  const assistantMsg = {
+    role: "assistant",
+    content: text || null,
+    tool_calls: toolResults.map((tr) => ({
+      id: tr.toolCallId,
+      type: "function",
+      function: {
+        name: tr.toolName,
+        arguments: typeof tr.args === "string" ? tr.args : JSON.stringify(tr.args ?? {})
+      }
+    }))
+  };
+  const toolMsgs = toolResults.map((tr) => ({
+    role: "tool",
+    content: typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result ?? {}),
+    tool_call_id: tr.toolCallId
+  }));
+  return {
+    ...input,
+    messages: [...input.messages, assistantMsg, ...toolMsgs]
+  };
+}
+
+// src/runtime.ts
+var DefaultNcpAgentRuntime = class {
+  contextBuilder;
+  llmApi;
+  toolRegistry;
+  stateManager;
+  streamEncoder;
+  constructor(config) {
+    this.contextBuilder = config.contextBuilder;
+    this.llmApi = config.llmApi;
+    this.toolRegistry = config.toolRegistry;
+    this.stateManager = config.stateManager;
+    this.streamEncoder = config.streamEncoder ?? new DefaultNcpStreamEncoder();
+  }
+  run = async function* (input, options) {
+    const ctx = {
+      messageId: genId(),
+      runId: genId(),
+      sessionId: input.sessionId,
+      correlationId: input.correlationId
+    };
+    const sessionMessages = this.stateManager.getSnapshot().messages;
+    const modelInput = this.contextBuilder.prepare(input, {
+      sessionMessages
+    });
+    for (const msg of input.messages) {
+      const messageSent = {
+        type: NcpEventType3.MessageSent,
+        payload: { sessionId: input.sessionId, message: msg }
+      };
+      await this.stateManager.dispatch(messageSent);
+    }
+    const runStarted = {
+      type: NcpEventType3.RunStarted,
+      payload: { sessionId: ctx.sessionId, messageId: ctx.messageId, runId: ctx.runId }
+    };
+    await this.stateManager.dispatch(runStarted);
+    yield runStarted;
+    for await (const event of this.runLoop(modelInput, ctx, options)) {
+      await this.stateManager.dispatch(event);
+      yield event;
+    }
+  };
+  /**
+   * Agent loop: LLM stream → encoder events → tool execution (if any) → next round or finish.
+   * RunFinished is emitted only when the entire loop completes (no more tool calls).
+   * The stream encoder does not emit RunFinished; it only converts chunks to NCP events.
+   */
+  async *runLoop(llmInput, ctx, options) {
+    const roundBuffer = new DefaultNcpRoundBuffer();
+    let currentInput = llmInput;
+    let done = false;
+    while (!done && !options?.signal?.aborted) {
+      roundBuffer.clear();
+      const stream = this.llmApi.generate(currentInput, { signal: options?.signal });
+      for await (const event of this.streamEncoder.encode(stream, ctx)) {
+        yield event;
+        switch (event.type) {
+          case NcpEventType3.MessageToolCallStart:
+            roundBuffer.startToolCall(event.payload.toolCallId, event.payload.toolName);
+            break;
+          case NcpEventType3.MessageToolCallArgs:
+            roundBuffer.appendToolCallArgs(event.payload.args);
+            break;
+          case NcpEventType3.MessageToolCallEnd: {
+            const pending = roundBuffer.consumePendingToolCall();
+            if (pending) {
+              const parsedArgs = parseToolArgs(pending.args);
+              const result = await this.toolRegistry.execute(
+                pending.toolCallId,
+                pending.toolName,
+                parsedArgs
+              );
+              roundBuffer.appendToolCall({
+                toolCallId: pending.toolCallId,
+                toolName: pending.toolName,
+                args: parsedArgs,
+                result
+              });
+              yield {
+                type: NcpEventType3.MessageToolCallResult,
+                payload: {
+                  sessionId: ctx.sessionId,
+                  toolCallId: pending.toolCallId,
+                  content: result
+                }
+              };
+            }
+            break;
+          }
+          case NcpEventType3.MessageTextDelta:
+            roundBuffer.appendText(event.payload.delta);
+            break;
+          default:
+            break;
+        }
+      }
+      const toolResults = roundBuffer.getToolCalls();
+      if (toolResults.length === 0) {
+        yield {
+          type: NcpEventType3.RunFinished,
+          payload: { sessionId: ctx.sessionId, messageId: ctx.messageId, runId: ctx.runId }
+        };
+        done = true;
+        break;
+      }
+      currentInput = appendToolRoundToInput(
+        currentInput,
+        roundBuffer.getText(),
+        toolResults
+      );
+    }
+  }
+};
+export {
+  DefaultNcpAgentRuntime,
+  DefaultNcpContextBuilder,
+  DefaultNcpRoundBuffer,
+  DefaultNcpStreamEncoder,
+  DefaultNcpToolRegistry,
+  EchoNcpLLMApi
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nextclaw/ncp-agent-runtime",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Default agent runtime implementation built on NCP interfaces.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nextclaw/ncp": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "prettier": "^3.3.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}