@nextclaw/ncp-agent-runtime 0.2.4 → 0.3.0

package/dist/index.d.ts

@@ -1,69 +1,93 @@
 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 = {
+type StoredAssetRecord = {
     id: string;
     uri: string;
     storageKey: string;
-    originalName: string;
+    fileName: string;
     storedName: string;
     mimeType: string;
     sizeBytes: number;
     createdAt: string;
     sha256: string;
 };
-type SaveAttachmentParams = {
+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;
 };
-type AttachmentTextSnapshot = {
-    text: string;
-    truncated: boolean;
-    record: StoredAttachmentRecord;
-};
-declare function isTextLikeAttachment(params: {
+declare function isTextLikeAsset(params: {
     mimeType?: string | null;
     fileName?: string | null;
 }): boolean;
-declare class LocalAttachmentStore {
+declare class LocalAssetStore {
     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>;
+    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 buildAttachmentContentPath(params: {
+declare function buildAssetContentPath(params: {
     basePath: string;
-    attachmentUri: string;
+    assetUri: string;
 }): string;
 
 type DefaultNcpContextBuilderOptions = {
     toolRegistry?: NcpToolRegistry;
-    attachmentStore?: LocalAttachmentStore | null;
-    attachmentTextMaxBytes?: number;
+    assetStore?: LocalAssetStore | null;
 };
 declare class DefaultNcpContextBuilder implements NcpContextBuilder {
     private readonly toolRegistry?;
-    private readonly attachmentStore?;
-    private readonly attachmentTextMaxBytes?;
+    private readonly assetStore?;
     constructor(toolRegistry?: NcpToolRegistry);
     constructor(options?: DefaultNcpContextBuilderOptions);
     prepare: (input: NcpAgentRunInput, options?: NcpContextPrepareOptions) => NcpLLMApiInput;
 }
 
 declare function buildNcpUserContent(parts: NcpMessagePart[], options?: {
-    attachmentStore?: LocalAttachmentStore | null;
-    maxTextBytes?: number;
+    assetStore?: LocalAssetStore | null;
 }): string | OpenAIContentPart[];
 
 declare class DefaultNcpRoundBuffer implements NcpRoundBuffer {
@@ -137,4 +161,4 @@ declare class DefaultNcpAgentRuntime implements NcpAgentRuntime {
     private tapStream;
 }
 
-export { type AttachmentTextSnapshot, DefaultNcpAgentRuntime, type DefaultNcpAgentRuntimeConfig, DefaultNcpContextBuilder, DefaultNcpRoundBuffer, DefaultNcpStreamEncoder, DefaultNcpToolRegistry, EchoNcpLLMApi, LocalAttachmentStore, type SaveAttachmentParams, type StoredAttachmentRecord, buildAttachmentContentPath, buildNcpUserContent, isTextLikeAttachment };
+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,217 +1,4 @@
-// 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;
@@ -219,74 +6,47 @@ function readOptionalString(value) {
   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";
+function formatAssetReferenceBlock(params) {
+  const fileName = readOptionalString(params.fileName) ?? "asset";
   const mimeType = readOptionalString(params.mimeType) ?? "application/octet-stream";
-  const suffix = params.truncated ? "\n[Attachment truncated]" : "";
-  return `[Attachment: ${fileName}]
-[MIME: ${mimeType}]
-${params.text}${suffix}`;
+  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 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);
+function resolveAssetReferenceBlock(part, assetStore) {
   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
+  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 (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;
+  if (url || part.contentBase64) {
+    return formatAssetReferenceBlock({
+      fileName,
+      mimeType,
+      url,
+      sizeBytes
+    });
   }
-  const truncated = bytes.length > maxTextBytes;
-  const text = (truncated ? bytes.subarray(0, maxTextBytes) : bytes).toString("utf8");
-  return formatTextAttachmentBlock({
-    fileName,
-    mimeType,
-    text,
-    truncated
-  });
+  return null;
 }
 function buildNcpUserContent(parts, options = {}) {
   const content = [];
@@ -298,21 +58,10 @@ function buildNcpUserContent(parts, options = {}) {
     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;
+    const assetReferenceBlock = resolveAssetReferenceBlock(part, options.assetStore);
+    if (assetReferenceBlock) {
+      content.push({ type: "text", text: assetReferenceBlock });
     }
-    content.push({
-      type: "image_url",
-      image_url: {
-        url: imageUrl
-      }
-    });
   }
   if (content.length === 0) {
     return "";
@@ -370,8 +119,7 @@ function messageToOpenAI(msg, options) {
         {
           role,
           content: buildNcpUserContent(parts, {
-            attachmentStore: options.attachmentStore,
-            maxTextBytes: options.attachmentTextMaxBytes
+            assetStore: options.assetStore
           })
         }
       ];
@@ -436,13 +184,11 @@ function messageToOpenAI(msg, options) {
 }
 var DefaultNcpContextBuilder = class {
   toolRegistry;
-  attachmentStore;
-  attachmentTextMaxBytes;
+  assetStore;
   constructor(toolRegistryOrOptions) {
     if (isDefaultNcpContextBuilderOptions(toolRegistryOrOptions)) {
       this.toolRegistry = toolRegistryOrOptions.toolRegistry;
-      this.attachmentStore = toolRegistryOrOptions.attachmentStore;
-      this.attachmentTextMaxBytes = toolRegistryOrOptions.attachmentTextMaxBytes;
+      this.assetStore = toolRegistryOrOptions.assetStore;
       return;
     }
     this.toolRegistry = toolRegistryOrOptions;
@@ -460,16 +206,14 @@ var DefaultNcpContextBuilder = class {
     for (const msg of sessionMessages.slice(-maxMessages)) {
       messages.push(
         ...messageToOpenAI(msg, {
-          attachmentStore: this.attachmentStore,
-          attachmentTextMaxBytes: this.attachmentTextMaxBytes
+          assetStore: this.assetStore
         })
       );
     }
     for (const msg of input.messages) {
       messages.push(
         ...messageToOpenAI(msg, {
-          attachmentStore: this.attachmentStore,
-          attachmentTextMaxBytes: this.attachmentTextMaxBytes
+          assetStore: this.assetStore
         })
       );
     }
@@ -492,6 +236,259 @@ var DefaultNcpContextBuilder = class {
   };
 };
 
+// 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 = "";
@@ -1157,8 +1154,8 @@ export {
   DefaultNcpStreamEncoder,
   DefaultNcpToolRegistry,
   EchoNcpLLMApi,
-  LocalAttachmentStore,
-  buildAttachmentContentPath,
+  LocalAssetStore,
+  buildAssetContentPath,
   buildNcpUserContent,
-  isTextLikeAttachment
+  isTextLikeAsset
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-agent-runtime",
-  "version": "0.2.4",
+  "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.3"
+    "@nextclaw/ncp": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",