@ethisyscore/extension-runtime 1.136.0 → 1.137.0

package/dist/mock-host/cli.cjs

@@ -69,6 +69,29 @@ var MCP_ERROR_CODES = [
 function isMcpErrorCode(value) {
   return typeof value === "string" && MCP_ERROR_CODES.includes(value);
 }
+var RETRYABLE = ["rate_limited", "timeout", "unavailable"];
+function isRetryableMcpErrorCode(code) {
+  return RETRYABLE.includes(code);
+}
+var McpToolError = class extends Error {
+  /** Machine-readable classification. `internal` when the host sent none. */
+  code;
+  /**
+   * Marks the instance for {@link isMcpToolError}. A structural marker rather than a prototype
+   * check because the error can be constructed in one bundle and inspected in another, where
+   * `instanceof` compares two different class objects and answers false.
+   */
+  isMcpToolError = true;
+  constructor(message, code = "internal") {
+    super(message);
+    this.name = "McpHostError";
+    this.code = code;
+  }
+  /** True when this failure is worth retrying unchanged. */
+  get retryable() {
+    return isRetryableMcpErrorCode(this.code);
+  }
+};
 function mcpErrorCodeFromHttpStatus(status) {
   switch (status) {
     case 401:
@@ -435,6 +458,9 @@ var WorkerRemoteDomTransport = class {
       case "ethisys:mcp:uploadDocument":
         this.dispatchMcp(message, "ethisys:mcp:uploadDocument:result", (m) => this.handleUploadDocument(m));
         return;
+      case "ethisys:mcp:uploadToStorage":
+        this.dispatchMcp(message, "ethisys:mcp:uploadToStorage:result", (m) => this.handleUploadToStorage(m));
+        return;
       case "ethisys:mcp:abort":
         this.inFlightAborts.get(message.id ?? "")?.abort();
         return;
@@ -672,11 +698,63 @@ var WorkerRemoteDomTransport = class {
       this.replyError(message.id, "ethisys:mcp:uploadDocument:result", err);
     }
   }
-  replyError(id, type, err) {
+  async handleUploadToStorage(message) {
+    const resultType = "ethisys:mcp:uploadToStorage:result";
+    let token;
+    try {
+      token = await this.capabilityTokenProvider();
+    } catch (err) {
+      this.replyError(message.id, resultType, err, true);
+      return;
+    }
+    if (this.disposed) {
+      return;
+    }
+    try {
+      const result = await this.mcpClient.fetch({
+        kind: "uploadToStorage",
+        meta: message.meta,
+        buffer: message.buffer,
+        capabilityToken: token,
+        signal: this.requestSignal(message.id)
+      });
+      this.reportVersionSkew(result);
+      this.safePostMessage({
+        id: message.id,
+        type: resultType,
+        ok: result.ok,
+        data: result.data,
+        error: result.error,
+        code: classifyHostResponse(result),
+        // The HTTP status, on failure only. A bare number carries no host internals, and it
+        // is the only way the plugin can tell 413 (file too large) from 507 (quota) from 503
+        // (storage lock busy): the closed MCP code folds all three into `internal`/`unavailable`.
+        ...!result.ok && typeof result.status === "number" ? { status: result.status } : {}
+      });
+    } catch (err) {
+      this.replyError(message.id, resultType, err, true);
+    }
+  }
+  replyError(id, type, err, includeStatus = false) {
     const message = err instanceof Error ? err.message : "MCP request failed";
-    this.safePostMessage({ id, type, ok: false, error: message, code: classifyHostError(err) });
+    const status = includeStatus ? statusOf(err) : void 0;
+    this.safePostMessage({
+      id,
+      type,
+      ok: false,
+      error: message,
+      code: classifyHostError(err),
+      ...status !== void 0 ? { status } : {}
+    });
   }
 };
+function statusOf(err) {
+  if (err === null || typeof err !== "object") {
+    return void 0;
+  }
+  const candidate = err;
+  return typeof candidate.status === "number" ? candidate.status : typeof candidate.statusCode === "number" ? candidate.statusCode : void 0;
+}
 
 // src/host/worker/component-registry.ts
 var CONTRACT_B_PRIMITIVES = [
@@ -700,6 +778,180 @@ var CONTRACT_B_PRIMITIVES = [
 ];
 new Set(CONTRACT_B_PRIMITIVES);
 
+// src/plugin/pluginStorageUpload.ts
+var PLUGIN_STORAGE_UPLOAD_MAX_BYTES = 30 * 1024 * 1024;
+var PLUGIN_STORAGE_PREFIX_MAX_LENGTH = 84;
+var PLUGIN_STORAGE_PATH_MAX_LENGTH = 128;
+var PluginStorageUploadError = class extends McpToolError {
+  /** What went wrong, in terms a caller branches on. */
+  reason;
+  /** HTTP status from the server, when the host surfaced one. */
+  status;
+  /** Structural marker for {@link isPluginStorageUploadError}. */
+  isPluginStorageUploadError = true;
+  constructor(message, reason, options = {}) {
+    super(message, options.code ?? codeForReason(reason, options.status));
+    this.name = "PluginStorageUploadError";
+    this.reason = reason;
+    this.status = options.status;
+  }
+};
+function validatePluginStoragePrefix(raw) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return { ok: false, error: "A storage path prefix is required." };
+  }
+  if (raw.length > PLUGIN_STORAGE_PREFIX_MAX_LENGTH) {
+    return {
+      ok: false,
+      error: `The storage path prefix must be at most ${PLUGIN_STORAGE_PREFIX_MAX_LENGTH} characters, so the stored path fits ${PLUGIN_STORAGE_PATH_MAX_LENGTH}.`
+    };
+  }
+  if (!/^[A-Za-z0-9_\-/]+$/.test(raw)) {
+    return {
+      ok: false,
+      error: "The storage path prefix may contain only letters, digits, '-', '_' and '/' separators."
+    };
+  }
+  if (raw.split("/").some((segment) => segment.length === 0)) {
+    return {
+      ok: false,
+      error: "The storage path prefix must not start or end with '/' or contain an empty segment."
+    };
+  }
+  return { ok: true, prefix: raw };
+}
+var PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES = Object.freeze({
+  pdf: ["application/pdf"],
+  png: ["image/png"],
+  jpg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  jpeg: ["image/jpeg", "image/pjpeg", "image/jpg"],
+  gif: ["image/gif"],
+  webp: ["image/webp"],
+  doc: ["application/msword"],
+  docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  xls: ["application/vnd.ms-excel"],
+  xlsx: ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  ppt: ["application/vnd.ms-powerpoint"],
+  pptx: ["application/vnd.openxmlformats-officedocument.presentationml.presentation"],
+  odt: ["application/vnd.oasis.opendocument.text"],
+  ods: ["application/vnd.oasis.opendocument.spreadsheet"],
+  odp: ["application/vnd.oasis.opendocument.presentation"],
+  txt: ["text/plain"],
+  csv: ["text/csv", "application/vnd.ms-excel", "application/csv", "text/plain"],
+  zip: ["application/zip", "application/x-zip-compressed", "application/x-zip"],
+  mp3: ["audio/mpeg", "audio/mp3"],
+  m4a: ["audio/mp4", "audio/x-m4a"],
+  mp4: ["video/mp4"]
+});
+var OCTET_STREAM = "application/octet-stream";
+function pluginStorageSafeExtension(fileName) {
+  if (typeof fileName !== "string" || fileName.trim().length === 0) {
+    return "";
+  }
+  const leaf = fileName.split(/[\\/]/).pop() ?? "";
+  const dot = leaf.lastIndexOf(".");
+  if (dot < 0) {
+    return "";
+  }
+  const body = leaf.slice(dot + 1);
+  return /^[A-Za-z0-9]{1,10}$/.test(body) ? `.${body.toLowerCase()}` : "";
+}
+function resolvePluginStorageContentType(fileName, declaredContentType) {
+  const extension = pluginStorageSafeExtension(fileName).slice(1);
+  const allowed = extension.length > 0 && Object.prototype.hasOwnProperty.call(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES, extension) ? PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES[extension] : void 0;
+  if (allowed === void 0) {
+    return {
+      ok: false,
+      error: "This file type is not allowed. Allowed: " + Object.keys(PLUGIN_STORAGE_UPLOAD_CONTENT_TYPES).sort().join(", ") + "."
+    };
+  }
+  const declared = mediaTypeOf(declaredContentType);
+  if (declared === void 0 || declared === OCTET_STREAM || allowed.includes(declared)) {
+    return { ok: true, contentType: allowed[0] };
+  }
+  return {
+    ok: false,
+    error: `The declared content type '${declared}' does not match the file extension '.${extension}'.`
+  };
+}
+function mediaTypeOf(raw) {
+  if (typeof raw !== "string") {
+    return void 0;
+  }
+  const mediaType = raw.split(";")[0].trim().toLowerCase();
+  return /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mediaType) ? mediaType : void 0;
+}
+function codeForReason(reason, status) {
+  if (status !== void 0) {
+    return mcpErrorCodeFromHttpStatus(status);
+  }
+  switch (reason) {
+    case "invalid_prefix":
+    case "too_large":
+    case "unsupported_type":
+      return "invalid_request";
+    case "timeout":
+      return "timeout";
+    case "unauthorized":
+      return "unauthorized";
+    case "forbidden":
+      return "forbidden";
+    case "busy":
+      return "unavailable";
+    case "aborted":
+      return "timeout";
+    default:
+      return "internal";
+  }
+}
+
+// src/mock-host/MockPluginStorage.ts
+var MockPluginStorage = class {
+  files = /* @__PURE__ */ new Map();
+  /** Store `buffer` under a new path below `meta.pathPrefix`. */
+  store(meta, buffer) {
+    const prefix = validatePluginStoragePrefix(meta.pathPrefix);
+    if (!prefix.ok) {
+      throw new PluginStorageUploadError(prefix.error, "invalid_prefix", { status: 400 });
+    }
+    if (buffer.byteLength > PLUGIN_STORAGE_UPLOAD_MAX_BYTES) {
+      throw new PluginStorageUploadError(
+        `The upload exceeds the ${PLUGIN_STORAGE_UPLOAD_MAX_BYTES}-byte limit.`,
+        "too_large",
+        { status: 413 }
+      );
+    }
+    const fileName = meta.fileName && meta.fileName.length > 0 ? meta.fileName : "upload.bin";
+    const type = resolvePluginStorageContentType(fileName, meta.contentType);
+    if (!type.ok) {
+      throw new PluginStorageUploadError(type.error, "unsupported_type", { status: 415 });
+    }
+    const path2 = `${prefix.prefix}/${randomGuidN()}${pluginStorageSafeExtension(fileName)}`;
+    const bytes = new Uint8Array(buffer.slice(0));
+    this.files.set(path2, { path: path2, fileName, contentType: type.contentType, bytes });
+    return { path: path2, fileName, contentType: type.contentType, sizeBytes: bytes.byteLength };
+  }
+  /** The stored file at `path`, or `undefined`. */
+  get(path2) {
+    return this.files.get(path2);
+  }
+  /** Every stored file, in upload order. */
+  list() {
+    return [...this.files.values()];
+  }
+  /** Forget every stored file. */
+  clear() {
+    this.files.clear();
+  }
+};
+function randomGuidN() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // src/mock-host/cli.ts
 async function loadResources(dir) {
   const absDir = path__namespace.resolve(dir);
@@ -945,6 +1197,7 @@ import {
     WorkerRemoteDomTransport,
     SemanticComponentRegistry,
 } from "@ethisyscore/extension-runtime/host";
+import { MockPluginStorage } from "@ethisyscore/extension-runtime/mock-host";
 
 const PRIMITIVES = ${safePrimitives};
 const bundleUrl = ${safeUrl};
@@ -960,12 +1213,18 @@ const registry = SemanticComponentRegistry.fromMap(componentMap);
 
 // Mock-host MCP client: no platform, so every tool/resource call resolves
 // to a friendly placeholder. Authors who need real MCP traffic should run
-// against the full platform host.
+// against the full platform host. uploadToStorage writes into an in-memory
+// plugin storage and returns a server-style {prefix}/{guid}{ext} path; an
+// invalid prefix or an over-size body throws with status 400 / 413, which the
+// transport forwards to the plugin as a typed error.
+const pluginStorage = new MockPluginStorage();
 const mcpClient = {
-    fetch: async (req) => ({
-        ok: true,
-        data: { mockHost: true, kind: req.kind, name: req.name ?? req.uri },
-    }),
+    fetch: async (req) => req.kind === "uploadToStorage"
+        ? { ok: true, data: pluginStorage.store(req.meta, req.buffer) }
+        : {
+            ok: true,
+            data: { mockHost: true, kind: req.kind, name: req.name ?? req.uri },
+        },
 };
 
 // The capability token never crosses the worker boundary \u2014 supply a marker
@@ -988,10 +1247,15 @@ transport.onRemoteDom(() => {
 // devtools (e.g., to terminate the worker between iteration cycles).
 window.__MOCK_HOST_TRANSPORT__ = transport;
 window.__MOCK_HOST_REGISTRY__ = registry;
+window.__MOCK_HOST_PLUGIN_STORAGE__ = pluginStorage;
 `;
 }
+var defaultMockPluginStorage = new MockPluginStorage();
 var defaultMockMcpClient = {
   fetch: async (req) => {
+    if (req.kind === "uploadToStorage") {
+      return { ok: true, data: defaultMockPluginStorage.store(req.meta, req.buffer) };
+    }
     if (req.kind === "uploadDocument") {
       return {
         ok: true,
@@ -1174,6 +1438,8 @@ async function run(args) {
 }
 
 exports.bootContractBHost = bootContractBHost;
+exports.defaultMockMcpClient = defaultMockMcpClient;
+exports.defaultMockPluginStorage = defaultMockPluginStorage;
 exports.loadResources = loadResources;
 exports.loadTools = loadTools;
 exports.normaliseEntry = normaliseEntry;