@ethisyscore/extension-runtime 1.136.0 → 1.138.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:
@@ -122,6 +145,157 @@ function classifyHostError(err) {
   return "internal";
 }
 
+// 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;
+  /**
+   * Seconds the server asked the caller to wait (`Retry-After`), on a `rate_limited` failure
+   * when the host forwarded the header. Absent otherwise.
+   */
+  retryAfterSeconds;
+  /** 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;
+    if (options.retryAfterSeconds !== void 0) {
+      this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+  }
+};
+function parsePluginStorageRetryAfter(raw, nowMs = Date.now()) {
+  if (typeof raw === "number") {
+    return Number.isFinite(raw) && raw >= 0 ? Math.ceil(raw) : void 0;
+  }
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    return void 0;
+  }
+  const text = raw.trim();
+  if (/^\d+$/.test(text)) {
+    return Number(text);
+  }
+  const at = /[A-Za-z]/.test(text) ? Date.parse(text) : Number.NaN;
+  return Number.isNaN(at) ? void 0 : Math.max(0, Math.ceil((at - nowMs) / 1e3));
+}
+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 "rate_limited":
+      return "rate_limited";
+    case "aborted":
+      return "timeout";
+    default:
+      return "internal";
+  }
+}
+
 // src/host/version-skew.ts
 var EXTENSION_VERSION_HEADER = "x-extension-version";
 var EXTENSION_ACTIVE_VERSION_HEADER = "x-extension-active-version";
@@ -435,6 +609,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 +849,76 @@ 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 } : {},
+        // The server's `Retry-After` (429), as whole seconds, so a plugin can show how long
+        // to wait. Never acted on here: an upload is not retried automatically.
+        ...retryAfterField(result)
+      });
+    } 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;
+    const retryAfterSeconds = includeStatus && err !== null && typeof err === "object" ? parsePluginStorageRetryAfter(err.retryAfterSeconds) : void 0;
+    this.safePostMessage({
+      id,
+      type,
+      ok: false,
+      error: message,
+      code: classifyHostError(err),
+      ...status !== void 0 ? { status } : {},
+      ...retryAfterSeconds !== void 0 ? { retryAfterSeconds } : {}
+    });
   }
 };
+function retryAfterField(result) {
+  if (result.ok || !result.headers) {
+    return {};
+  }
+  const key = Object.keys(result.headers).find((k) => k.toLowerCase() === "retry-after");
+  const seconds = key === void 0 ? void 0 : parsePluginStorageRetryAfter(result.headers[key]);
+  return seconds === void 0 ? {} : { retryAfterSeconds: seconds };
+}
+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 +942,83 @@ var CONTRACT_B_PRIMITIVES = [
 ];
 new Set(CONTRACT_B_PRIMITIVES);
 
+// src/mock-host/MockPluginStorage.ts
+var MockPluginStorage = class {
+  files = /* @__PURE__ */ new Map();
+  rateLimit;
+  now;
+  windowStartMs = 0;
+  windowCount = 0;
+  constructor(options = {}) {
+    this.rateLimit = options.rateLimit;
+    this.now = options.now ?? Date.now;
+  }
+  /** Store `buffer` under a new path below `meta.pathPrefix`. */
+  store(meta, buffer) {
+    this.enforceRateLimit();
+    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 kernel refuses before the handler runs, so this is checked before anything else. */
+  enforceRateLimit() {
+    if (this.rateLimit === void 0) {
+      return;
+    }
+    const windowMs = (this.rateLimit.windowSeconds ?? 60) * 1e3;
+    const now = this.now();
+    if (this.windowCount === 0 || now - this.windowStartMs >= windowMs) {
+      this.windowStartMs = now;
+      this.windowCount = 0;
+    }
+    this.windowCount += 1;
+    if (this.windowCount > this.rateLimit.maxRequests) {
+      const retryAfterSeconds = Math.max(1, Math.ceil((this.windowStartMs + windowMs - now) / 1e3));
+      throw new PluginStorageUploadError(
+        "Rate limit exceeded. Please try again later.",
+        "rate_limited",
+        { status: 429, retryAfterSeconds }
+      );
+    }
+  }
+  /** 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 +1264,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 +1280,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 +1314,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 +1505,8 @@ async function run(args) {
 }
 
 exports.bootContractBHost = bootContractBHost;
+exports.defaultMockMcpClient = defaultMockMcpClient;
+exports.defaultMockPluginStorage = defaultMockPluginStorage;
 exports.loadResources = loadResources;
 exports.loadTools = loadTools;
 exports.normaliseEntry = normaliseEntry;