@nextclaw/ncp-agent-runtime 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -1,11 +1,71 @@
-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 StoredAttachmentRecord = {
+    id: string;
+    uri: string;
+    storageKey: string;
+    originalName: string;
+    storedName: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: string;
+    sha256: string;
+};
+type SaveAttachmentParams = {
+    fileName: string;
+    mimeType?: string | null;
+    bytes: Uint8Array;
+    createdAt?: Date;
+};
+type AttachmentTextSnapshot = {
+    text: string;
+    truncated: boolean;
+    record: StoredAttachmentRecord;
+};
+declare function isTextLikeAttachment(params: {
+    mimeType?: string | null;
+    fileName?: string | null;
+}): boolean;
+declare class LocalAttachmentStore {
+    readonly rootDir: string;
+    constructor(options: {
+        rootDir: string;
+    });
+    saveAttachment(params: SaveAttachmentParams): Promise<StoredAttachmentRecord>;
+    getAttachmentByUri(uri: string): StoredAttachmentRecord | null;
+    readAttachmentBytes(uri: string): Promise<Buffer | null>;
+    readAttachmentBytesSync(uri: string): Buffer | null;
+    readTextSnapshotSync(uri: string, options: {
+        maxBytes: number;
+    }): AttachmentTextSnapshot | null;
+    statAttachment(uri: string): Promise<StoredAttachmentRecord | null>;
+    resolveContentPath(uri: string): string | null;
+    private resolveStorageKeyDirectory;
+}
+declare function buildAttachmentContentPath(params: {
+    basePath: string;
+    attachmentUri: string;
+}): string;
+
+type DefaultNcpContextBuilderOptions = {
+    toolRegistry?: NcpToolRegistry;
+    attachmentStore?: LocalAttachmentStore | null;
+    attachmentTextMaxBytes?: number;
+};
 declare class DefaultNcpContextBuilder implements NcpContextBuilder {
     private readonly toolRegistry?;
-    constructor(toolRegistry?: NcpToolRegistry | undefined);
+    private readonly attachmentStore?;
+    private readonly attachmentTextMaxBytes?;
+    constructor(toolRegistry?: NcpToolRegistry);
+    constructor(options?: DefaultNcpContextBuilderOptions);
     prepare: (input: NcpAgentRunInput, options?: NcpContextPrepareOptions) => NcpLLMApiInput;
 }
 
+declare function buildNcpUserContent(parts: NcpMessagePart[], options?: {
+    attachmentStore?: LocalAttachmentStore | null;
+    maxTextBytes?: number;
+}): string | OpenAIContentPart[];
+
 declare class DefaultNcpRoundBuffer implements NcpRoundBuffer {
     private text;
     private readonly toolCalls;
@@ -77,4 +137,4 @@ declare class DefaultNcpAgentRuntime implements NcpAgentRuntime {
     private tapStream;
 }
 
-export { DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi };
+export { type AttachmentTextSnapshot, DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAttachmentStore, type SaveAttachmentParams, type StoredAttachmentRecord, buildAttachmentContentPath, buildNcpUserContent, isTextLikeAttachment };

package/dist/index.js

@@ -1,14 +1,342 @@
+// src/attachment-store.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+var ATTACHMENT_URI_SCHEME = "attachment://local/";
+function normalizeSegment(value) {
+  return value.replace(/[^\w.-]+/g, "_").replace(/^_+|_+$/g, "") || "attachment.bin";
+}
+function normalizeOriginalName(value) {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : "attachment.bin";
+}
+function normalizeMimeType(value) {
+  const normalized = value?.trim().toLowerCase() ?? "";
+  return normalized.length > 0 ? normalized : "application/octet-stream";
+}
+function buildAttachmentId() {
+  return `att_${Date.now().toString(36)}_${randomUUID().slice(0, 8)}`;
+}
+function ensureAttachmentRoot(rootDir) {
+  const normalized = rootDir.trim();
+  if (!normalized) {
+    throw new Error("LocalAttachmentStore requires a non-empty rootDir.");
+  }
+  return resolve(normalized);
+}
+function buildStorageKey(timestamp, attachmentId) {
+  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}/${attachmentId}`;
+}
+function buildAttachmentUri(storageKey) {
+  return `${ATTACHMENT_URI_SCHEME}${storageKey}`;
+}
+function parseAttachmentUri(uri) {
+  const normalized = uri.trim();
+  if (!normalized.startsWith(ATTACHMENT_URI_SCHEME)) {
+    return null;
+  }
+  const storageKey = normalized.slice(ATTACHMENT_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("Attachment storage key must not be empty.");
+  }
+  const segments = normalized.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error(`Invalid attachment storage key: ${storageKey}`);
+  }
+  return segments.join("/");
+}
+function hydrateStoredAttachmentRecord(value) {
+  const originalName = normalizeOriginalName(value.originalName);
+  return {
+    ...value,
+    originalName,
+    storedName: normalizeSegment(value.storedName || originalName),
+    mimeType: normalizeMimeType(value.mimeType)
+  };
+}
+function isTextLikeAttachment(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 LocalAttachmentStore = class {
+  rootDir;
+  constructor(options) {
+    this.rootDir = ensureAttachmentRoot(options.rootDir);
+  }
+  async saveAttachment(params) {
+    const createdAt = params.createdAt ?? /* @__PURE__ */ new Date();
+    const id = buildAttachmentId();
+    const storageKey = buildStorageKey(createdAt, id);
+    const attachmentDir = this.resolveStorageKeyDirectory(storageKey);
+    const originalName = normalizeOriginalName(params.fileName);
+    const storedName = normalizeSegment(originalName);
+    const mimeType = normalizeMimeType(params.mimeType);
+    const bytes = Buffer.from(params.bytes);
+    const record = {
+      id,
+      uri: buildAttachmentUri(storageKey),
+      storageKey,
+      originalName,
+      storedName,
+      mimeType,
+      sizeBytes: bytes.length,
+      createdAt: createdAt.toISOString(),
+      sha256: createHash("sha256").update(bytes).digest("hex")
+    };
+    await mkdir(attachmentDir, { recursive: true });
+    await writeFile(join(attachmentDir, storedName), bytes);
+    await writeFile(
+      join(attachmentDir, "meta.json"),
+      `${JSON.stringify(record)}
+`,
+      "utf8"
+    );
+    return record;
+  }
+  getAttachmentByUri(uri) {
+    const storageKey = parseAttachmentUri(uri);
+    if (!storageKey) {
+      return null;
+    }
+    const metaPath = join(this.resolveStorageKeyDirectory(storageKey), "meta.json");
+    if (!existsSync(metaPath)) {
+      return null;
+    }
+    const text = readFileSync(metaPath, "utf8");
+    return hydrateStoredAttachmentRecord(JSON.parse(text));
+  }
+  async readAttachmentBytes(uri) {
+    const record = this.getAttachmentByUri(uri);
+    if (!record) {
+      return null;
+    }
+    const filePath = join(this.resolveStorageKeyDirectory(record.storageKey), record.storedName);
+    try {
+      return await readFile(filePath);
+    } catch {
+      return null;
+    }
+  }
+  readAttachmentBytesSync(uri) {
+    const record = this.getAttachmentByUri(uri);
+    if (!record) {
+      return null;
+    }
+    const filePath = join(this.resolveStorageKeyDirectory(record.storageKey), record.storedName);
+    return existsSync(filePath) ? readFileSync(filePath) : null;
+  }
+  readTextSnapshotSync(uri, options) {
+    const record = this.getAttachmentByUri(uri);
+    if (!record || !isTextLikeAttachment({ mimeType: record.mimeType, fileName: record.originalName })) {
+      return null;
+    }
+    const bytes = this.readAttachmentBytesSync(uri);
+    if (!bytes) {
+      return null;
+    }
+    const truncated = bytes.length > options.maxBytes;
+    const snapshotBytes = truncated ? bytes.subarray(0, options.maxBytes) : bytes;
+    return {
+      text: snapshotBytes.toString("utf8"),
+      truncated,
+      record
+    };
+  }
+  async statAttachment(uri) {
+    const record = this.getAttachmentByUri(uri);
+    if (!record) {
+      return null;
+    }
+    const filePath = join(this.resolveStorageKeyDirectory(record.storageKey), record.storedName);
+    try {
+      await stat(filePath);
+      return record;
+    } catch {
+      return null;
+    }
+  }
+  resolveContentPath(uri) {
+    const record = this.getAttachmentByUri(uri);
+    if (!record) {
+      return null;
+    }
+    return join(this.resolveStorageKeyDirectory(record.storageKey), record.storedName);
+  }
+  resolveStorageKeyDirectory(storageKey) {
+    return join(this.rootDir, ensureStorageKey(storageKey));
+  }
+};
+function buildAttachmentContentPath(params) {
+  const query = new URLSearchParams({ uri: params.attachmentUri });
+  return `${params.basePath}?${query.toString()}`;
+}
+
+// src/user-content.ts
+var DEFAULT_ATTACHMENT_TEXT_MAX_BYTES = 32 * 1024;
+function readOptionalString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function decodeInlineBase64(base64) {
+  try {
+    return Buffer.from(base64, "base64");
+  } catch {
+    return null;
+  }
+}
+function formatTextAttachmentBlock(params) {
+  const fileName = readOptionalString(params.fileName) ?? "attachment";
+  const mimeType = readOptionalString(params.mimeType) ?? "application/octet-stream";
+  const suffix = params.truncated ? "\n[Attachment truncated]" : "";
+  return `[Attachment: ${fileName}]
+[MIME: ${mimeType}]
+${params.text}${suffix}`;
+}
+function resolveImageDataUrl(part, attachmentStore) {
+  const attachmentUri = readOptionalString(part.attachmentUri);
+  const mimeType = readOptionalString(part.mimeType);
+  if (attachmentUri && mimeType?.startsWith("image/")) {
+    const bytes = attachmentStore?.readAttachmentBytesSync(attachmentUri);
+    if (bytes) {
+      return `data:${mimeType};base64,${bytes.toString("base64")}`;
+    }
+  }
+  const url = readOptionalString(part.url);
+  if (url) {
+    return url;
+  }
+  const contentBase64 = readOptionalString(part.contentBase64);
+  if (!mimeType || !contentBase64 || !mimeType.startsWith("image/")) {
+    return null;
+  }
+  return `data:${mimeType};base64,${contentBase64}`;
+}
+function resolveTextAttachmentBlock(part, options) {
+  const attachmentUri = readOptionalString(part.attachmentUri);
+  const fileName = readOptionalString(part.name);
+  const mimeType = readOptionalString(part.mimeType);
+  const maxTextBytes = options.maxTextBytes ?? DEFAULT_ATTACHMENT_TEXT_MAX_BYTES;
+  if (attachmentUri) {
+    const snapshot = options.attachmentStore?.readTextSnapshotSync(attachmentUri, {
+      maxBytes: maxTextBytes
+    });
+    if (snapshot) {
+      return formatTextAttachmentBlock({
+        fileName: snapshot.record.originalName,
+        mimeType: snapshot.record.mimeType,
+        text: snapshot.text,
+        truncated: snapshot.truncated
+      });
+    }
+  }
+  const contentBase64 = readOptionalString(part.contentBase64);
+  if (!contentBase64 || !isTextLikeAttachment({ mimeType, fileName })) {
+    return null;
+  }
+  const bytes = decodeInlineBase64(contentBase64);
+  if (!bytes) {
+    return null;
+  }
+  const truncated = bytes.length > maxTextBytes;
+  const text = (truncated ? bytes.subarray(0, maxTextBytes) : bytes).toString("utf8");
+  return formatTextAttachmentBlock({
+    fileName,
+    mimeType,
+    text,
+    truncated
+  });
+}
+function buildNcpUserContent(parts, options = {}) {
+  const content = [];
+  for (const part of parts) {
+    if ((part.type === "text" || part.type === "rich-text") && part.text.trim().length > 0) {
+      content.push({ type: "text", text: part.text });
+      continue;
+    }
+    if (part.type !== "file") {
+      continue;
+    }
+    const textAttachmentBlock = resolveTextAttachmentBlock(part, options);
+    if (textAttachmentBlock) {
+      content.push({ type: "text", text: textAttachmentBlock });
+      continue;
+    }
+    const imageUrl = resolveImageDataUrl(part, options.attachmentStore);
+    if (!imageUrl) {
+      continue;
+    }
+    content.push({
+      type: "image_url",
+      image_url: {
+        url: imageUrl
+      }
+    });
+  }
+  if (content.length === 0) {
+    return "";
+  }
+  if (content.length === 1 && content[0]?.type === "text") {
+    return content[0].text;
+  }
+  return content;
+}
+
 // src/context-builder.ts
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function readOptionalString(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";
+}
 function mergeMessageAndRequestMetadata(input) {
   const messageMetadata = input.messages.slice().reverse().find((message) => isRecord(message.metadata))?.metadata;
   return {
@@ -23,18 +351,32 @@ 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") {
-    const text = parts.filter((p) => p.type === "text").map((p) => p.text).join("");
+    if (role === "user") {
+      return [
+        {
+          role,
+          content: buildNcpUserContent(parts, {
+            attachmentStore: options.attachmentStore,
+            maxTextBytes: options.attachmentTextMaxBytes
+          })
+        }
+      ];
+    }
+    const text = parts.filter(isTextLikePart).map((part) => part.text).join("");
     return [{ role, content: text }];
   }
   if (role === "assistant") {
@@ -93,8 +435,17 @@ function messageToOpenAI(msg) {
   return [];
 }
 var DefaultNcpContextBuilder = class {
-  constructor(toolRegistry) {
-    this.toolRegistry = toolRegistry;
+  toolRegistry;
+  attachmentStore;
+  attachmentTextMaxBytes;
+  constructor(toolRegistryOrOptions) {
+    if (isDefaultNcpContextBuilderOptions(toolRegistryOrOptions)) {
+      this.toolRegistry = toolRegistryOrOptions.toolRegistry;
+      this.attachmentStore = toolRegistryOrOptions.attachmentStore;
+      this.attachmentTextMaxBytes = toolRegistryOrOptions.attachmentTextMaxBytes;
+      return;
+    }
+    this.toolRegistry = toolRegistryOrOptions;
   }
   prepare = (input, options) => {
     const maxMessages = options?.maxMessages ?? 50;
@@ -107,10 +458,20 @@ var DefaultNcpContextBuilder = class {
       messages.push({ role: "system", content: systemPrompt });
     }
     for (const msg of sessionMessages.slice(-maxMessages)) {
-      messages.push(...messageToOpenAI(msg));
+      messages.push(
+        ...messageToOpenAI(msg, {
+          attachmentStore: this.attachmentStore,
+          attachmentTextMaxBytes: this.attachmentTextMaxBytes
+        })
+      );
     }
     for (const msg of input.messages) {
-      messages.push(...messageToOpenAI(msg));
+      messages.push(
+        ...messageToOpenAI(msg, {
+          attachmentStore: this.attachmentStore,
+          attachmentTextMaxBytes: this.attachmentTextMaxBytes
+        })
+      );
     }
     const toolDefinitions = this.toolRegistry?.getToolDefinitions() ?? [];
     const filteredToolDefinitions = requestedToolNames.length > 0 ? toolDefinitions.filter((definition) => requestedToolNames.includes(definition.name)) : toolDefinitions;
@@ -125,8 +486,8 @@ 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
     };
   };
 };
@@ -795,5 +1156,9 @@ export {
   DefaultNcpRoundBuffer,
   DefaultNcpStreamEncoder,
   DefaultNcpToolRegistry,
-  EchoNcpLLMApi
+  EchoNcpLLMApi,
+  LocalAttachmentStore,
+  buildAttachmentContentPath,
+  buildNcpUserContent,
+  isTextLikeAttachment
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-agent-runtime",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "private": false,
   "description": "Default agent runtime implementation built on NCP interfaces.",
   "type": "module",
@@ -15,17 +15,19 @@
     "dist"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.3.2"
+    "@nextclaw/ncp": "0.3.3"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
     "prettier": "^3.3.3",
     "tsup": "^8.3.5",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.2"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --out-dir dist",
     "lint": "eslint .",
+    "test": "vitest run",
     "tsc": "tsc -p tsconfig.json"
   }
 }