@nextclaw/ncp-agent-runtime 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -1,11 +1,95 @@
-import { NcpContextBuilder, NcpToolRegistry, NcpAgentRunInput, NcpContextPrepareOptions, NcpLLMApiInput, NcpRoundBuffer, NcpToolCallResult, NcpStreamEncoder, NcpAssistantReasoningNormalizationMode, OpenAIChatChunk, NcpEncodeContext, NcpEndpointEvent, NcpTool, NcpToolDefinition, NcpLLMApi, NcpLLMApiOptions, NcpAgentRuntime, NcpAgentConversationStateManager, NcpAgentRunOptions } from '@nextclaw/ncp';
+import { NcpContextBuilder, NcpToolRegistry, NcpAgentRunInput, NcpContextPrepareOptions, NcpLLMApiInput, NcpMessagePart, OpenAIContentPart, NcpRoundBuffer, NcpToolCallResult, NcpStreamEncoder, NcpAssistantReasoningNormalizationMode, OpenAIChatChunk, NcpEncodeContext, NcpEndpointEvent, NcpTool, NcpToolDefinition, NcpLLMApi, NcpLLMApiOptions, NcpAgentRuntime, NcpAgentConversationStateManager, NcpAgentRunOptions } from '@nextclaw/ncp';
 
+type StoredAssetRecord = {
+    id: string;
+    uri: string;
+    storageKey: string;
+    fileName: string;
+    storedName: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: string;
+    sha256: string;
+};
+type AssetRef = {
+    uri: string;
+};
+type AssetMeta = {
+    uri: string;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: string;
+};
+type AssetPutInput = {
+    kind: "path";
+    path: string;
+    fileName?: string;
+    mimeType?: string | null;
+    createdAt?: Date;
+} | {
+    kind: "bytes";
+    bytes: Uint8Array;
+    fileName: string;
+    mimeType?: string | null;
+    createdAt?: Date;
+};
+declare function isTextLikeAsset(params: {
+    mimeType?: string | null;
+    fileName?: string | null;
+}): boolean;
+declare class LocalAssetStore {
+    readonly rootDir: string;
+    constructor(options: {
+        rootDir: string;
+    });
+    put(input: AssetPutInput): Promise<AssetRef>;
+    putBytes(params: {
+        fileName: string;
+        mimeType?: string | null;
+        bytes: Uint8Array;
+        createdAt?: Date;
+    }): Promise<StoredAssetRecord>;
+    putPath(params: {
+        path: string;
+        fileName?: string;
+        mimeType?: string | null;
+        createdAt?: Date;
+    }): Promise<StoredAssetRecord>;
+    export(ref: AssetRef, targetPath: string): Promise<string>;
+    stat(ref: AssetRef): Promise<AssetMeta | null>;
+    getByUri(uri: string): StoredAssetRecord | null;
+    statRecord(uri: string): Promise<StoredAssetRecord | null>;
+    readAssetBytes(uri: string): Promise<Buffer | null>;
+    resolveContentPath(uri: string): string | null;
+    private putFromPath;
+    private putFromBytes;
+    private buildRecord;
+    private writeMeta;
+    private resolveContentPathOrThrow;
+    private resolveStorageKeyDirectory;
+}
+declare function buildAssetContentPath(params: {
+    basePath: string;
+    assetUri: string;
+}): string;
+
+type DefaultNcpContextBuilderOptions = {
+    toolRegistry?: NcpToolRegistry;
+    assetStore?: LocalAssetStore | null;
+};
 declare class DefaultNcpContextBuilder implements NcpContextBuilder {
     private readonly toolRegistry?;
-    constructor(toolRegistry?: NcpToolRegistry | undefined);
+    private readonly assetStore?;
+    constructor(toolRegistry?: NcpToolRegistry);
+    constructor(options?: DefaultNcpContextBuilderOptions);
     prepare: (input: NcpAgentRunInput, options?: NcpContextPrepareOptions) => NcpLLMApiInput;
 }
 
+declare function buildNcpUserContent(parts: NcpMessagePart[], options?: {
+    assetStore?: LocalAssetStore | null;
+}): string | OpenAIContentPart[];
+
 declare class DefaultNcpRoundBuffer implements NcpRoundBuffer {
     private text;
     private readonly toolCalls;
@@ -77,4 +161,4 @@ declare class DefaultNcpAgentRuntime implements NcpAgentRuntime {
     private tapStream;
 }
 
-export { DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi };
+export { type AssetMeta, type AssetPutInput, type AssetRef, DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAssetStore, type StoredAssetRecord, buildAssetContentPath, buildNcpUserContent, isTextLikeAsset };

package/dist/index.js

@@ -1,7 +1,4 @@
-// src/context-builder.ts
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
+// src/user-content.ts
 function readOptionalString(value) {
   if (typeof value !== "string") {
     return null;
@@ -9,30 +6,62 @@ function readOptionalString(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : null;
 }
-function isRenderableImagePart(part) {
-  return part.type === "file" && typeof part.mimeType === "string" && part.mimeType.startsWith("image/") && (typeof part.url === "string" && part.url.trim().length > 0 || typeof part.contentBase64 === "string" && part.contentBase64.trim().length > 0);
+function formatAssetReferenceBlock(params) {
+  const fileName = readOptionalString(params.fileName) ?? "asset";
+  const mimeType = readOptionalString(params.mimeType) ?? "application/octet-stream";
+  const assetUri = readOptionalString(params.assetUri);
+  const url = readOptionalString(params.url);
+  const sizeText = typeof params.sizeBytes === "number" && Number.isFinite(params.sizeBytes) ? String(params.sizeBytes) : null;
+  const lines = [
+    `[Asset: ${fileName}]`,
+    `[MIME: ${mimeType}]`,
+    ...assetUri ? [`[Asset URI: ${assetUri}]`] : [],
+    ...sizeText ? [`[Size Bytes: ${sizeText}]`] : [],
+    ...url ? [`[Preview URL: ${url}]`] : [],
+    "[Instruction: This file is not embedded in the prompt. If you need to inspect or transform it, use asset_export to copy it to a normal file path first.]"
+  ];
+  return lines.join("\n");
+}
+function resolveAssetReferenceBlock(part, assetStore) {
+  const fileName = readOptionalString(part.name);
+  const mimeType = readOptionalString(part.mimeType);
+  const assetUri = readOptionalString(part.assetUri);
+  const url = readOptionalString(part.url);
+  const sizeBytes = typeof part.sizeBytes === "number" ? part.sizeBytes : void 0;
+  if (assetUri) {
+    const stored = assetStore?.getByUri(assetUri);
+    return formatAssetReferenceBlock({
+      fileName: stored?.fileName ?? fileName,
+      mimeType: stored?.mimeType ?? mimeType,
+      assetUri,
+      url,
+      sizeBytes: stored?.sizeBytes ?? sizeBytes
+    });
+  }
+  if (url || part.contentBase64) {
+    return formatAssetReferenceBlock({
+      fileName,
+      mimeType,
+      url,
+      sizeBytes
+    });
+  }
+  return null;
 }
-function toOpenAIUserContent(parts) {
+function buildNcpUserContent(parts, options = {}) {
   const content = [];
   for (const part of parts) {
-    if (part.type === "text" && part.text.trim().length > 0) {
+    if ((part.type === "text" || part.type === "rich-text") && part.text.trim().length > 0) {
       content.push({ type: "text", text: part.text });
       continue;
     }
-    if (part.type === "rich-text" && part.text.trim().length > 0) {
-      content.push({ type: "text", text: part.text });
+    if (part.type !== "file") {
       continue;
     }
-    if (!isRenderableImagePart(part)) {
-      continue;
+    const assetReferenceBlock = resolveAssetReferenceBlock(part, options.assetStore);
+    if (assetReferenceBlock) {
+      content.push({ type: "text", text: assetReferenceBlock });
     }
-    const url = typeof part.url === "string" && part.url.trim().length > 0 ? part.url.trim() : `data:${part.mimeType};base64,${part.contentBase64?.trim() ?? ""}`;
-    content.push({
-      type: "image_url",
-      image_url: {
-        url
-      }
-    });
   }
   if (content.length === 0) {
     return "";
@@ -42,6 +71,18 @@ function toOpenAIUserContent(parts) {
   }
   return content;
 }
+
+// src/context-builder.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalString2(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
 function isTextLikePart(part) {
   return part.type === "text" || part.type === "rich-text";
 }
@@ -59,19 +100,29 @@ function readRequestedToolNames(metadata) {
   }
   const deduped = /* @__PURE__ */ new Set();
   for (const item of raw) {
-    const value = readOptionalString(item);
+    const value = readOptionalString2(item);
     if (value) {
       deduped.add(value);
     }
   }
   return [...deduped];
 }
-function messageToOpenAI(msg) {
+function isDefaultNcpContextBuilderOptions(value) {
+  return Boolean(value) && typeof value === "object" && !("getToolDefinitions" in value);
+}
+function messageToOpenAI(msg, options) {
   const role = msg.role;
   const parts = msg.parts ?? [];
   if (role === "user" || role === "system") {
     if (role === "user") {
-      return [{ role, content: toOpenAIUserContent(parts) }];
+      return [
+        {
+          role,
+          content: buildNcpUserContent(parts, {
+            assetStore: options.assetStore
+          })
+        }
+      ];
     }
     const text = parts.filter(isTextLikePart).map((part) => part.text).join("");
     return [{ role, content: text }];
@@ -132,8 +183,15 @@ function messageToOpenAI(msg) {
   return [];
 }
 var DefaultNcpContextBuilder = class {
-  constructor(toolRegistry) {
-    this.toolRegistry = toolRegistry;
+  toolRegistry;
+  assetStore;
+  constructor(toolRegistryOrOptions) {
+    if (isDefaultNcpContextBuilderOptions(toolRegistryOrOptions)) {
+      this.toolRegistry = toolRegistryOrOptions.toolRegistry;
+      this.assetStore = toolRegistryOrOptions.assetStore;
+      return;
+    }
+    this.toolRegistry = toolRegistryOrOptions;
   }
   prepare = (input, options) => {
     const maxMessages = options?.maxMessages ?? 50;
@@ -146,10 +204,18 @@ var DefaultNcpContextBuilder = class {
       messages.push({ role: "system", content: systemPrompt });
     }
     for (const msg of sessionMessages.slice(-maxMessages)) {
-      messages.push(...messageToOpenAI(msg));
+      messages.push(
+        ...messageToOpenAI(msg, {
+          assetStore: this.assetStore
+        })
+      );
     }
     for (const msg of input.messages) {
-      messages.push(...messageToOpenAI(msg));
+      messages.push(
+        ...messageToOpenAI(msg, {
+          assetStore: this.assetStore
+        })
+      );
     }
     const toolDefinitions = this.toolRegistry?.getToolDefinitions() ?? [];
     const filteredToolDefinitions = requestedToolNames.length > 0 ? toolDefinitions.filter((definition) => requestedToolNames.includes(definition.name)) : toolDefinitions;
@@ -164,12 +230,265 @@ var DefaultNcpContextBuilder = class {
     return {
       messages,
       tools: tools && tools.length > 0 ? tools : void 0,
-      model: readOptionalString(requestMetadata.model) ?? readOptionalString(requestMetadata.llm_model) ?? readOptionalString(requestMetadata.agent_model) ?? void 0,
-      thinkingLevel: readOptionalString(requestMetadata.thinking) ?? readOptionalString(requestMetadata.thinking_level) ?? readOptionalString(requestMetadata.thinkingLevel) ?? readOptionalString(requestMetadata.thinking_effort) ?? readOptionalString(requestMetadata.thinkingEffort) ?? null
+      model: readOptionalString2(requestMetadata.model) ?? readOptionalString2(requestMetadata.llm_model) ?? readOptionalString2(requestMetadata.agent_model) ?? void 0,
+      thinkingLevel: readOptionalString2(requestMetadata.thinking) ?? readOptionalString2(requestMetadata.thinking_level) ?? readOptionalString2(requestMetadata.thinkingLevel) ?? readOptionalString2(requestMetadata.thinking_effort) ?? readOptionalString2(requestMetadata.thinkingEffort) ?? null
     };
   };
 };
 
+// src/asset-store.ts
+import { createHash, randomUUID } from "crypto";
+import { copyFileSync, existsSync, readFileSync } from "fs";
+import { copyFile, mkdir, readFile, stat, writeFile } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+var ASSET_URI_SCHEME = "asset://store/";
+function normalizeSegment(value) {
+  return value.replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "") || "asset.bin";
+}
+function normalizeFileName(value) {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : "asset.bin";
+}
+function normalizeMimeType(value) {
+  const normalized = value?.trim().toLowerCase() ?? "";
+  return normalized.length > 0 ? normalized : "application/octet-stream";
+}
+function buildAssetId() {
+  return `asset_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+function ensureAssetRoot(rootDir) {
+  const normalized = rootDir.trim();
+  if (!normalized) {
+    throw new Error("LocalAssetStore requires a non-empty rootDir.");
+  }
+  return resolve(normalized);
+}
+function buildStorageKey(timestamp, assetId) {
+  const year = String(timestamp.getFullYear());
+  const month = String(timestamp.getMonth() + 1).padStart(2, "0");
+  const day = String(timestamp.getDate()).padStart(2, "0");
+  return `${year}/${month}/${day}/${assetId}`;
+}
+function buildAssetUri(storageKey) {
+  return `${ASSET_URI_SCHEME}${storageKey}`;
+}
+function parseAssetUri(uri) {
+  const normalized = uri.trim();
+  if (!normalized.startsWith(ASSET_URI_SCHEME)) {
+    return null;
+  }
+  const storageKey = normalized.slice(ASSET_URI_SCHEME.length).replace(/^\/+/, "").trim();
+  return storageKey.length > 0 ? storageKey : null;
+}
+function ensureStorageKey(storageKey) {
+  const normalized = storageKey.trim().replace(/^\/+|\/+$/g, "");
+  if (!normalized) {
+    throw new Error("Asset storage key must not be empty.");
+  }
+  const segments = normalized.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(`Invalid asset storage key: ${storageKey}`);
+  }
+  return segments.join("/");
+}
+function hydrateStoredAssetRecord(value) {
+  const fileName = normalizeFileName(value.fileName);
+  return {
+    ...value,
+    fileName,
+    storedName: normalizeSegment(value.storedName || fileName),
+    mimeType: normalizeMimeType(value.mimeType)
+  };
+}
+function toAssetMeta(record) {
+  return {
+    uri: record.uri,
+    fileName: record.fileName,
+    mimeType: record.mimeType,
+    sizeBytes: record.sizeBytes,
+    createdAt: record.createdAt
+  };
+}
+function isTextLikeAsset(params) {
+  const mimeType = normalizeMimeType(params.mimeType);
+  if (mimeType.startsWith("text/") || mimeType === "application/json" || mimeType === "application/xml" || mimeType === "text/xml" || mimeType === "application/yaml" || mimeType === "text/yaml" || mimeType === "application/x-yaml" || mimeType === "text/csv") {
+    return true;
+  }
+  const normalizedName = (params.fileName ?? "").trim().toLowerCase();
+  return [
+    ".json",
+    ".md",
+    ".txt",
+    ".csv",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".ts",
+    ".tsx",
+    ".jsx",
+    ".py",
+    ".rb",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".swift",
+    ".php",
+    ".css",
+    ".scss",
+    ".html",
+    ".sql",
+    ".sh"
+  ].some((suffix) => normalizedName.endsWith(suffix));
+}
+var LocalAssetStore = class {
+  rootDir;
+  constructor(options) {
+    this.rootDir = ensureAssetRoot(options.rootDir);
+  }
+  async put(input) {
+    const record = input.kind === "path" ? await this.putFromPath(input) : await this.putFromBytes({
+      fileName: input.fileName,
+      mimeType: input.mimeType,
+      bytes: input.bytes,
+      createdAt: input.createdAt
+    });
+    return { uri: record.uri };
+  }
+  async putBytes(params) {
+    return this.putFromBytes(params);
+  }
+  async putPath(params) {
+    return this.putFromPath({
+      kind: "path",
+      ...params
+    });
+  }
+  async export(ref, targetPath) {
+    const record = await this.statRecord(ref.uri);
+    if (!record) {
+      throw new Error(`Asset not found: ${ref.uri}`);
+    }
+    const outputPath = resolve(targetPath);
+    await ensureParentDirectory(outputPath);
+    await copyFile(this.resolveContentPathOrThrow(record), outputPath);
+    return outputPath;
+  }
+  async stat(ref) {
+    const record = await this.statRecord(ref.uri);
+    return record ? toAssetMeta(record) : null;
+  }
+  getByUri(uri) {
+    const storageKey = parseAssetUri(uri);
+    if (!storageKey) {
+      return null;
+    }
+    const metaPath = join(this.resolveStorageKeyDirectory(storageKey), "meta.json");
+    if (!existsSync(metaPath)) {
+      return null;
+    }
+    const text = readFileSync(metaPath, "utf8");
+    return hydrateStoredAssetRecord(JSON.parse(text));
+  }
+  async statRecord(uri) {
+    const record = this.getByUri(uri);
+    if (!record) {
+      return null;
+    }
+    try {
+      await stat(this.resolveContentPathOrThrow(record));
+      return record;
+    } catch {
+      return null;
+    }
+  }
+  async readAssetBytes(uri) {
+    const record = await this.statRecord(uri);
+    if (!record) {
+      return null;
+    }
+    try {
+      return await readFile(this.resolveContentPathOrThrow(record));
+    } catch {
+      return null;
+    }
+  }
+  resolveContentPath(uri) {
+    const record = this.getByUri(uri);
+    return record ? this.resolveContentPathOrThrow(record) : null;
+  }
+  async putFromPath(input) {
+    const sourcePath = resolve(input.path);
+    const sourceStats = await stat(sourcePath);
+    if (!sourceStats.isFile()) {
+      throw new Error(`Asset source path is not a file: ${sourcePath}`);
+    }
+    const bytes = readFileSync(sourcePath);
+    const record = this.buildRecord({
+      fileName: input.fileName ?? basename(sourcePath),
+      mimeType: input.mimeType,
+      bytes,
+      createdAt: input.createdAt
+    });
+    const assetDir = this.resolveStorageKeyDirectory(record.storageKey);
+    await mkdir(assetDir, { recursive: true });
+    copyFileSync(sourcePath, join(assetDir, record.storedName));
+    await this.writeMeta(assetDir, record);
+    return record;
+  }
+  async putFromBytes(params) {
+    const bytes = Buffer.from(params.bytes);
+    const record = this.buildRecord({
+      fileName: params.fileName,
+      mimeType: params.mimeType,
+      bytes,
+      createdAt: params.createdAt
+    });
+    const assetDir = this.resolveStorageKeyDirectory(record.storageKey);
+    await mkdir(assetDir, { recursive: true });
+    await writeFile(join(assetDir, record.storedName), bytes);
+    await this.writeMeta(assetDir, record);
+    return record;
+  }
+  buildRecord(params) {
+    const createdAt = params.createdAt ?? /* @__PURE__ */ new Date();
+    const id = buildAssetId();
+    const storageKey = buildStorageKey(createdAt, id);
+    const fileName = normalizeFileName(params.fileName);
+    return {
+      id,
+      uri: buildAssetUri(storageKey),
+      storageKey,
+      fileName,
+      storedName: normalizeSegment(fileName),
+      mimeType: normalizeMimeType(params.mimeType),
+      sizeBytes: params.bytes.length,
+      createdAt: createdAt.toISOString(),
+      sha256: createHash("sha256").update(params.bytes).digest("hex")
+    };
+  }
+  async writeMeta(assetDir, record) {
+    await writeFile(join(assetDir, "meta.json"), `${JSON.stringify(record)}
+`, "utf8");
+  }
+  resolveContentPathOrThrow(record) {
+    return join(this.resolveStorageKeyDirectory(record.storageKey), record.storedName);
+  }
+  resolveStorageKeyDirectory(storageKey) {
+    return join(this.rootDir, ensureStorageKey(storageKey));
+  }
+};
+function buildAssetContentPath(params) {
+  const query = new URLSearchParams({ uri: params.assetUri });
+  return `${params.basePath}?${query.toString()}`;
+}
+async function ensureParentDirectory(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+
 // src/round-buffer.ts
 var DefaultNcpRoundBuffer = class {
   text = "";
@@ -834,5 +1153,9 @@ export {
   DefaultNcpRoundBuffer,
   DefaultNcpStreamEncoder,
   DefaultNcpToolRegistry,
-  EchoNcpLLMApi
+  EchoNcpLLMApi,
+  LocalAssetStore,
+  buildAssetContentPath,
+  buildNcpUserContent,
+  isTextLikeAsset
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-agent-runtime",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "private": false,
   "description": "Default agent runtime implementation built on NCP interfaces.",
   "type": "module",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.3.2"
+    "@nextclaw/ncp": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",