@nextclaw/ncp-agent-runtime 0.3.8 → 0.3.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NcpAgentConversationStateManager, NcpAgentRunInput, NcpAgentRunOptions, NcpAgentRuntime, NcpAssistantReasoningNormalizationMode, NcpContextBuilder, NcpContextPrepareOptions, NcpEncodeContext, NcpEndpointEvent, NcpLLMApi, NcpLLMApiInput, NcpLLMApiOptions, NcpMessagePart, NcpRoundBuffer, NcpStreamEncoder, NcpTool, NcpToolCallResult, NcpToolDefinition, NcpToolRegistry, OpenAIChatChunk, OpenAIContentPart } from "@nextclaw/ncp";
+import { NcpAgentConversationStateManager, NcpAgentRunInput, NcpAgentRunOptions, NcpAgentRuntime, NcpAssistantReasoningNormalizationMode, NcpContextBuilder, NcpContextPrepareOptions, NcpEncodeContext, NcpEndpointEvent, NcpInvalidToolArgumentsResult, NcpLLMApi, NcpLLMApiInput, NcpLLMApiOptions, NcpMessagePart, NcpRoundBuffer, NcpStreamEncoder, NcpTool, NcpToolCallResult, NcpToolDefinition, NcpToolRegistry, OpenAIChatChunk, OpenAIContentPart, OpenAITool } from "@nextclaw/ncp";
 
 //#region src/asset-store.d.ts
 type StoredAssetRecord = {
@@ -166,7 +166,50 @@ declare class DefaultNcpAgentRuntime implements NcpAgentRuntime {
    * The stream encoder does not emit RunFinished; it only converts chunks to NCP events.
    */
   private runLoop;
+  private executeToolCall;
+  private resolveValidationIssues;
+  private executeValidatedToolCall;
   private tapStream;
 }
 //#endregion
-export { type AssetMeta, type AssetPutInput, type AssetRef, DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAssetStore, type StoredAssetRecord, buildAssetContentPath, buildNcpUserContent, isTextLikeAsset };
+//#region src/utils.d.ts
+type ParsedToolArgs = {
+  ok: true;
+  rawText: string;
+  value: Record<string, unknown>;
+} | {
+  ok: false;
+  rawText: string;
+  issues: string[];
+};
+declare function genId(): string;
+declare function getOpenAiFunctionParametersSchemaIssues(schema: Record<string, unknown> | undefined): string[];
+declare function assertOpenAiFunctionParametersSchema(params: {
+  toolName: string;
+  schema: Record<string, unknown> | undefined;
+}): void;
+declare function buildOpenAiFunctionTool(definition: NcpToolDefinition): OpenAITool;
+declare function parseToolArgs(args: unknown): ParsedToolArgs;
+declare function validateToolArgs(args: Record<string, unknown>, schema: Record<string, unknown> | undefined): string[];
+declare function createInvalidToolArgumentsResult(params: {
+  toolCallId: string;
+  toolName: string;
+  rawArgumentsText: string;
+  issues: string[];
+}): NcpInvalidToolArgumentsResult;
+declare function createToolExecutionFailedResult(params: {
+  toolCallId: string;
+  toolName: string;
+  error: unknown;
+}): {
+  ok: false;
+  error: {
+    code: "tool_execution_failed";
+    message: string;
+    toolCallId: string;
+    toolName: string;
+  };
+};
+declare function appendToolRoundToInput(input: NcpLLMApiInput, reasoning: string, text: string, toolResults: ReadonlyArray<NcpToolCallResult>): NcpLLMApiInput;
+//#endregion
+export { type AssetMeta, type AssetPutInput, type AssetRef, DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAssetStore, type StoredAssetRecord, appendToolRoundToInput, assertOpenAiFunctionParametersSchema, buildAssetContentPath, buildNcpUserContent, buildOpenAiFunctionTool, createInvalidToolArgumentsResult, createToolExecutionFailedResult, genId, getOpenAiFunctionParametersSchemaIssues, isTextLikeAsset, parseToolArgs, validateToolArgs };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import AjvPkg from "ajv";
 import { createHash, randomUUID } from "node:crypto";
 import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
@@ -146,6 +147,177 @@ function buildNcpUserContent(parts, options = {}) {
 	return content;
 }
 //#endregion
+//#region src/utils.ts
+const toolSchemaValidator = new AjvPkg({
+	allErrors: true,
+	strict: false,
+	removeAdditional: false
+});
+const validatorCache = /* @__PURE__ */ new WeakMap();
+const DISALLOWED_OPENAI_TOOL_SCHEMA_TOP_LEVEL_KEYWORDS = [
+	"oneOf",
+	"anyOf",
+	"allOf",
+	"enum",
+	"not"
+];
+function genId() {
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function isRecord$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringifyRawArgs(args) {
+	if (typeof args === "string") return args;
+	if (args && typeof args === "object" && !Array.isArray(args)) try {
+		return JSON.stringify(args);
+	} catch {
+		return "[unserializable-object]";
+	}
+	return String(args ?? "");
+}
+function getOpenAiFunctionParametersSchemaIssues(schema) {
+	if (!schema) return ["parameters must be declared as a JSON Schema object"];
+	if (!isRecord$1(schema)) return ["parameters must be a JSON Schema object"];
+	const issues = [];
+	if (schema.type !== "object") issues.push("root schema must set type to \"object\"");
+	for (const keyword of DISALLOWED_OPENAI_TOOL_SCHEMA_TOP_LEVEL_KEYWORDS) if (keyword in schema) issues.push(`root schema must not declare top-level "${keyword}"`);
+	return issues;
+}
+function assertOpenAiFunctionParametersSchema(params) {
+	const issues = getOpenAiFunctionParametersSchemaIssues(params.schema);
+	if (issues.length === 0) return;
+	throw new Error(`Tool "${params.toolName}" declares an unsupported OpenAI-compatible parameters schema: ${issues.join("; ")}. See docs/internal/openai-tool-schema.md.`);
+}
+function buildOpenAiFunctionTool(definition) {
+	assertOpenAiFunctionParametersSchema({
+		toolName: definition.name,
+		schema: definition.parameters
+	});
+	return {
+		type: "function",
+		function: {
+			name: definition.name,
+			description: definition.description,
+			parameters: definition.parameters
+		}
+	};
+}
+function parseToolArgs(args) {
+	if (args && typeof args === "object" && !Array.isArray(args)) return {
+		ok: true,
+		rawText: stringifyRawArgs(args),
+		value: args
+	};
+	const rawText = stringifyRawArgs(args);
+	if (typeof args !== "string") return {
+		ok: false,
+		rawText,
+		issues: ["Tool arguments must be a JSON object string."]
+	};
+	const trimmed = args.trim();
+	if (!trimmed) return {
+		ok: false,
+		rawText,
+		issues: ["Tool arguments are empty."]
+	};
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {
+			ok: false,
+			rawText,
+			issues: ["Tool arguments JSON must decode to an object."]
+		};
+		return {
+			ok: true,
+			rawText,
+			value: parsed
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			rawText,
+			issues: [error instanceof Error ? error.message : "Failed to parse tool arguments JSON."]
+		};
+	}
+}
+function validateToolArgs(args, schema) {
+	if (!schema) return [];
+	const validate = getOrCreateValidator(schema);
+	if (validate(args)) return [];
+	return formatSchemaIssues(validate.errors);
+}
+function getOrCreateValidator(schema) {
+	const cached = validatorCache.get(schema);
+	if (cached) return cached;
+	const validate = toolSchemaValidator.compile(schema);
+	validatorCache.set(schema, validate);
+	return validate;
+}
+function formatSchemaIssues(errors) {
+	if (!errors || errors.length === 0) return ["Tool arguments do not match the declared schema."];
+	return errors.map((error) => {
+		const instancePath = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+		if (error.keyword === "required" && "missingProperty" in error.params && typeof error.params.missingProperty === "string") return `${instancePath ? `${instancePath}.${error.params.missingProperty}` : error.params.missingProperty} is required`;
+		if (error.keyword === "additionalProperties" && "additionalProperty" in error.params && typeof error.params.additionalProperty === "string") return `${instancePath ? `${instancePath}.${error.params.additionalProperty}` : error.params.additionalProperty} is not allowed`;
+		return `${instancePath || "parameter"}: ${error.message ?? "invalid"}`;
+	});
+}
+function createInvalidToolArgumentsResult(params) {
+	const { toolCallId, toolName, rawArgumentsText, issues } = params;
+	return {
+		ok: false,
+		error: {
+			code: "invalid_tool_arguments",
+			message: "Tool arguments are invalid.",
+			toolCallId,
+			toolName,
+			rawArgumentsText,
+			issues
+		}
+	};
+}
+function createToolExecutionFailedResult(params) {
+	const { toolCallId, toolName, error } = params;
+	return {
+		ok: false,
+		error: {
+			code: "tool_execution_failed",
+			message: error instanceof Error ? error.message : String(error),
+			toolCallId,
+			toolName
+		}
+	};
+}
+function appendToolRoundToInput(input, reasoning, text, toolResults) {
+	const assistantMsg = {
+		role: "assistant",
+		content: text || null,
+		...reasoning ? { reasoning_content: reasoning } : {},
+		tool_calls: toolResults.map((tr) => ({
+			id: tr.toolCallId,
+			type: "function",
+			function: {
+				name: tr.toolName,
+				arguments: tr.rawArgsText
+			}
+		}))
+	};
+	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
+		]
+	};
+}
+//#endregion
 //#region src/context-builder.ts
 function isRecord(value) {
 	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -261,14 +433,7 @@ var DefaultNcpContextBuilder = class {
 		for (const msg of sessionMessages.slice(-maxMessages)) messages.push(...messageToOpenAI(msg, { assetStore: this.assetStore }));
 		for (const msg of input.messages) messages.push(...messageToOpenAI(msg, { assetStore: this.assetStore }));
 		const toolDefinitions = this.toolRegistry?.getToolDefinitions() ?? [];
-		const tools = (requestedToolNames.length > 0 ? toolDefinitions.filter((definition) => requestedToolNames.includes(definition.name)) : toolDefinitions).map((definition) => ({
-			type: "function",
-			function: {
-				name: definition.name,
-				description: definition.description,
-				parameters: definition.parameters
-			}
-		}));
+		const tools = (requestedToolNames.length > 0 ? toolDefinitions.filter((definition) => requestedToolNames.includes(definition.name)) : toolDefinitions).map(buildOpenAiFunctionTool);
 		return {
 			messages,
 			tools: tools && tools.length > 0 ? tools : void 0,
@@ -858,143 +1023,6 @@ var EchoNcpLLMApi = class {
 	};
 };
 //#endregion
-//#region src/utils.ts
-function genId() {
-	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
-}
-function stringifyRawArgs(args) {
-	if (typeof args === "string") return args;
-	if (args && typeof args === "object" && !Array.isArray(args)) try {
-		return JSON.stringify(args);
-	} catch {
-		return "[unserializable-object]";
-	}
-	return String(args ?? "");
-}
-function parseToolArgs(args) {
-	if (args && typeof args === "object" && !Array.isArray(args)) return {
-		ok: true,
-		rawText: stringifyRawArgs(args),
-		value: args
-	};
-	const rawText = stringifyRawArgs(args);
-	if (typeof args !== "string") return {
-		ok: false,
-		rawText,
-		issues: ["Tool arguments must be a JSON object string."]
-	};
-	const trimmed = args.trim();
-	if (!trimmed) return {
-		ok: false,
-		rawText,
-		issues: ["Tool arguments are empty."]
-	};
-	try {
-		const parsed = JSON.parse(trimmed);
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {
-			ok: false,
-			rawText,
-			issues: ["Tool arguments JSON must decode to an object."]
-		};
-		return {
-			ok: true,
-			rawText,
-			value: parsed
-		};
-	} catch (error) {
-		return {
-			ok: false,
-			rawText,
-			issues: [error instanceof Error ? error.message : "Failed to parse tool arguments JSON."]
-		};
-	}
-}
-function validateToolArgs(args, schema) {
-	if (!schema) return [];
-	return validateToolValue(args, schema, "");
-}
-function validateToolValue(value, schema, path) {
-	const label = path || "parameter";
-	const type = typeof schema.type === "string" ? schema.type : void 0;
-	if (type && !matchesSchemaType(value, type)) return [`${label} should be ${type}`];
-	const errors = [];
-	if (schema.enum && !schema.enum.includes(value)) errors.push(`${label} must be one of ${JSON.stringify(schema.enum)}`);
-	if (typeof value === "number") {
-		if (schema.minimum !== void 0 && value < schema.minimum) errors.push(`${label} must be >= ${schema.minimum}`);
-		if (schema.maximum !== void 0 && value > schema.maximum) errors.push(`${label} must be <= ${schema.maximum}`);
-	}
-	if (typeof value === "string") {
-		if (schema.minLength !== void 0 && value.length < schema.minLength) errors.push(`${label} must be at least ${schema.minLength} chars`);
-		if (schema.maxLength !== void 0 && value.length > schema.maxLength) errors.push(`${label} must be at most ${schema.maxLength} chars`);
-	}
-	if (type === "object") {
-		const objectValue = value;
-		for (const key of schema.required ?? []) if (!(key in objectValue)) errors.push(`missing required ${path ? `${path}.${key}` : key}`);
-		const properties = schema.properties ?? {};
-		for (const [key, childValue] of Object.entries(objectValue)) {
-			const childSchema = properties[key];
-			if (!childSchema) continue;
-			errors.push(...validateToolValue(childValue, childSchema, path ? `${path}.${key}` : key));
-		}
-	}
-	if (type === "array" && schema.items && Array.isArray(value)) value.forEach((item, index) => {
-		errors.push(...validateToolValue(item, schema.items, `${label}[${index}]`));
-	});
-	return errors;
-}
-function matchesSchemaType(value, type) {
-	switch (type) {
-		case "string": return typeof value === "string";
-		case "integer": return typeof value === "number" && Number.isInteger(value);
-		case "number": return typeof value === "number";
-		case "boolean": return typeof value === "boolean";
-		case "array": return Array.isArray(value);
-		case "object": return typeof value === "object" && value !== null && !Array.isArray(value);
-		default: return true;
-	}
-}
-function createInvalidToolArgumentsResult(params) {
-	return {
-		ok: false,
-		error: {
-			code: "invalid_tool_arguments",
-			message: "Tool arguments are invalid.",
-			toolCallId: params.toolCallId,
-			toolName: params.toolName,
-			rawArgumentsText: params.rawArgumentsText,
-			issues: params.issues
-		}
-	};
-}
-function appendToolRoundToInput(input, reasoning, text, toolResults) {
-	const assistantMsg = {
-		role: "assistant",
-		content: text || null,
-		...reasoning ? { reasoning_content: reasoning } : {},
-		tool_calls: toolResults.map((tr) => ({
-			id: tr.toolCallId,
-			type: "function",
-			function: {
-				name: tr.toolName,
-				arguments: tr.rawArgsText
-			}
-		}))
-	};
-	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
-		]
-	};
-}
-//#endregion
 //#region src/round-collector.ts
 var DefaultNcpRoundCollector = class {
 	rawText = "";
@@ -1115,43 +1143,14 @@ var DefaultNcpAgentRuntime = class {
 			for await (const event of this.streamEncoder.encode(tappedStream, ctx)) yield event;
 			const toolResults = [];
 			for (const toolCall of roundCollector.getToolCalls()) {
-				const tool = this.toolRegistry.getTool(toolCall.toolName);
-				const parsedArgs = parseToolArgs(toolCall.args);
-				let result;
-				let args = null;
-				if (!parsedArgs.ok) result = createInvalidToolArgumentsResult({
-					toolCallId: toolCall.toolCallId,
-					toolName: toolCall.toolName,
-					rawArgumentsText: parsedArgs.rawText,
-					issues: parsedArgs.issues
-				});
-				else {
-					const schemaIssues = validateToolArgs(parsedArgs.value, tool?.parameters);
-					const validationIssues = schemaIssues.length > 0 ? schemaIssues : typeof tool?.validateArgs === "function" ? tool.validateArgs(parsedArgs.value) : [];
-					if (validationIssues.length > 0) result = createInvalidToolArgumentsResult({
-						toolCallId: toolCall.toolCallId,
-						toolName: toolCall.toolName,
-						rawArgumentsText: parsedArgs.rawText,
-						issues: validationIssues
-					});
-					else {
-						args = parsedArgs.value;
-						result = await this.toolRegistry.execute(toolCall.toolCallId, toolCall.toolName, parsedArgs.value);
-					}
-				}
-				toolResults.push({
-					toolCallId: toolCall.toolCallId,
-					toolName: toolCall.toolName,
-					args,
-					rawArgsText: parsedArgs.rawText,
-					result
-				});
+				const toolResult = await this.executeToolCall(toolCall);
+				toolResults.push(toolResult);
 				yield {
 					type: NcpEventType.MessageToolCallResult,
 					payload: {
 						sessionId: ctx.sessionId,
 						toolCallId: toolCall.toolCallId,
-						content: result
+						content: toolResult.result
 					}
 				};
 			}
@@ -1170,6 +1169,58 @@ var DefaultNcpAgentRuntime = class {
 			currentInput = appendToolRoundToInput(currentInput, roundCollector.getReasoning(), roundCollector.getText(), toolResults);
 		}
 	};
+	executeToolCall = async function(toolCall) {
+		const tool = this.toolRegistry.getTool(toolCall.toolName);
+		const parsedArgs = parseToolArgs(toolCall.args);
+		if (!parsedArgs.ok) return {
+			toolCallId: toolCall.toolCallId,
+			toolName: toolCall.toolName,
+			args: null,
+			rawArgsText: parsedArgs.rawText,
+			result: createInvalidToolArgumentsResult({
+				toolCallId: toolCall.toolCallId,
+				toolName: toolCall.toolName,
+				rawArgumentsText: parsedArgs.rawText,
+				issues: parsedArgs.issues
+			})
+		};
+		const validationIssues = this.resolveValidationIssues(parsedArgs.value, tool);
+		if (validationIssues.length > 0) return {
+			toolCallId: toolCall.toolCallId,
+			toolName: toolCall.toolName,
+			args: null,
+			rawArgsText: parsedArgs.rawText,
+			result: createInvalidToolArgumentsResult({
+				toolCallId: toolCall.toolCallId,
+				toolName: toolCall.toolName,
+				rawArgumentsText: parsedArgs.rawText,
+				issues: validationIssues
+			})
+		};
+		return {
+			toolCallId: toolCall.toolCallId,
+			toolName: toolCall.toolName,
+			args: parsedArgs.value,
+			rawArgsText: parsedArgs.rawText,
+			result: await this.executeValidatedToolCall(toolCall, parsedArgs.value)
+		};
+	};
+	resolveValidationIssues = function(args, tool) {
+		const schemaIssues = validateToolArgs(args, tool?.parameters);
+		if (schemaIssues.length > 0) return schemaIssues;
+		return typeof tool?.validateArgs === "function" ? tool.validateArgs(args) : [];
+	};
+	executeValidatedToolCall = async function(toolCall, args) {
+		try {
+			return await this.toolRegistry.execute(toolCall.toolCallId, toolCall.toolName, args);
+		} catch (error) {
+			return createToolExecutionFailedResult({
+				toolCallId: toolCall.toolCallId,
+				toolName: toolCall.toolName,
+				error
+			});
+		}
+	};
 	tapStream = async function* (stream, onChunk) {
 		for await (const chunk of stream) {
 			onChunk(chunk);
@@ -1178,4 +1229,4 @@ var DefaultNcpAgentRuntime = class {
 	};
 };
 //#endregion
-export { DefaultNcpAgentRuntime, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAssetStore, buildAssetContentPath, buildNcpUserContent, isTextLikeAsset };
+export { DefaultNcpAgentRuntime, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAssetStore, appendToolRoundToInput, assertOpenAiFunctionParametersSchema, buildAssetContentPath, buildNcpUserContent, buildOpenAiFunctionTool, createInvalidToolArgumentsResult, createToolExecutionFailedResult, genId, getOpenAiFunctionParametersSchemaIssues, isTextLikeAsset, parseToolArgs, validateToolArgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-agent-runtime",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "private": false,
   "description": "Default agent runtime implementation built on NCP interfaces.",
   "type": "module",
@@ -15,6 +15,7 @@
     "dist"
   ],
   "dependencies": {
+    "ajv": "^8.17.1",
     "@nextclaw/ncp": "0.5.0"
   },
   "devDependencies": {