@neurosquad/card-sdk 1.0.0

package/dist/testing.js

@@ -0,0 +1,1150 @@
+/*! @neurosquad/card-sdk 1.0.0 | MIT */
+
+// src/testing/mockHost.ts
+import {
+  CARD_EVENT_NAMES,
+  CARD_METHOD_NAMES,
+  CARD_PROTOCOL_VERSION,
+  checkRequestHeader,
+  checkSettingValues,
+  coercePortValue,
+  defaultSettings,
+  errorResponse,
+  eventMessage,
+  expandGranted,
+  hostAllowed,
+  isLocalHostname,
+  LIMITS,
+  METHOD_SPECS,
+  messageSize,
+  methodAllowed,
+  normalizeWorkspacePath,
+  okResponse,
+  parseCardMessage,
+  permissionStates,
+  pickInputFor,
+  protectedWriteReason,
+  portSchemas,
+  resolveLocalized,
+  SECRET_PLACEHOLDER_RE,
+  secretPlaceholders,
+  TOPIC_PERMISSION,
+  validateJson,
+  validateManifest,
+  base64ToBytes,
+  bytesToBase64,
+  connect,
+  DEFAULT_DARK_THEME,
+  LARGE_REQUEST_METHODS
+} from "./card-sdk.js";
+var HostError = class extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+};
+var fail = (code, message, data) => {
+  throw new HostError(code, message, data);
+};
+var MINIMAL_MANIFEST = {
+  manifestVersion: 1,
+  name: "mock-card",
+  displayName: "Mock card",
+  version: "0.0.0",
+  protocol: CARD_PROTOCOL_VERSION
+};
+function portInfo(port, language) {
+  return {
+    id: port.id,
+    label: resolveLocalized(port.label, language),
+    ...port.description ? { description: resolveLocalized(port.description, language) } : {},
+    type: port.type,
+    ...port.schema ? { schema: port.schema } : {},
+    mode: port.mode ?? "stream",
+    ...port.response ? { response: port.response } : {},
+    retain: port.retain === true,
+    default: port.default === true
+  };
+}
+var MockHost = class {
+  constructor(options = {}) {
+    this.options = options;
+    const result = validateManifest(options.manifest ?? MINIMAL_MANIFEST);
+    if (!result.ok) {
+      throw new Error(
+        `mock host: invalid manifest \u2014 ${result.issues.map((i) => `${i.path || "/"}: ${i.message}`).join("; ")}`
+      );
+    }
+    this.manifest = result.manifest;
+    const declared = this.manifest.permissions;
+    this.granted = new Set(
+      options.grant === "all" ? declared.map((p) => p.id) : options.grant ?? declared.filter((p) => !p.optional).map((p) => p.id)
+    );
+    this.settingsValues = { ...defaultSettings(this.manifest.settings), ...options.settings };
+    for (const field of this.manifest.settings) {
+      if (field.type !== "secret") continue;
+      const value = options.secrets?.[field.key];
+      if (value !== void 0) this.secretValues.set(field.key, value);
+      this.secretsSet[field.key] = value !== void 0;
+    }
+    for (const [path, data] of Object.entries(options.files ?? {})) this.putFile(path, data);
+    const language = options.context?.i18n?.language ?? "en";
+    const base = {
+      protocol: options.hostProtocol ?? CARD_PROTOCOL_VERSION,
+      appVersion: "0.0.0-mock",
+      instance: {
+        instanceId: "card-1",
+        packageId: `dev:/mock/${this.manifest.name}`,
+        name: this.manifest.name,
+        displayName: resolveLocalized(this.manifest.displayName, language),
+        version: this.manifest.version,
+        commit: null,
+        title: null,
+        size: this.manifest.card.defaultSize,
+        dev: true,
+        ...options.context?.instance
+      },
+      workspace: { id: "workspace-1", name: "Mock workspace" },
+      visibility: "visible",
+      expanded: false,
+      theme: DEFAULT_DARK_THEME,
+      i18n: { language, locale: { en: "en-US", ru: "ru-RU", zh: "zh-CN" }[language] },
+      settings: { values: this.settingsValues, secrets: this.secretsSet },
+      permissions: [],
+      ports: {
+        inputs: this.manifest.ports.inputs.map((p) => portInfo(p, language)),
+        outputs: this.manifest.ports.outputs.map((p) => portInfo(p, language))
+      },
+      peers: [],
+      launch: "created",
+      limits: LIMITS
+    };
+    const { instance: _instance, ...rest } = options.context ?? {};
+    void _instance;
+    this.context = { ...base, ...rest, instance: base.instance };
+    this.context.permissions = this.permissionList();
+    this.context.peers = this.peerInfos();
+    if (this.granted.has("fs.read") || this.granted.has("fs.write")) {
+      this.context.workspace = { ...this.context.workspace, path: "/mock/workspace" };
+    }
+  }
+  /** The validated, normalized manifest. */
+  manifest;
+  /** Every request the card made, in order (after the envelope check). */
+  calls = [];
+  /** Every event sent to the card. */
+  events = [];
+  /** Storage per scope. */
+  storage = {
+    instance: /* @__PURE__ */ new Map(),
+    package: /* @__PURE__ */ new Map()
+  };
+  /** `ports.emit` / `ports.send` deliveries to peers. */
+  deliveries = [];
+  /** Retained values of the card's own outputs. */
+  retained = /* @__PURE__ */ new Map();
+  /** Prompts the card sent to agents. */
+  prompts = [];
+  /** Terminal writes and runs. */
+  terminal = [];
+  /** `host.log` lines. */
+  logs = [];
+  /** `ui.toast` messages. */
+  toasts = [];
+  /** Clipboard writes. */
+  clipboard = [];
+  /** Cards spawned with `card.spawn`. */
+  spawned = [];
+  /** `net.abort` request ids. */
+  aborted = [];
+  /** `host.pong` sequence numbers received. */
+  pongs = [];
+  /** Topics the card is subscribed to (and agent ids for agents.output). */
+  subscriptions = /* @__PURE__ */ new Set();
+  outputAgents = [];
+  /** Header/tile state the card set. */
+  chrome = {
+    title: null,
+    status: null,
+    badge: null,
+    overview: null,
+    attention: null,
+    menu: [],
+    enabledTools: {}
+  };
+  /** Workspace files. */
+  files = /* @__PURE__ */ new Map();
+  context;
+  granted;
+  port = null;
+  ready = false;
+  overrides = /* @__PURE__ */ new Map();
+  lastCall = /* @__PURE__ */ new Map();
+  minuteCalls = /* @__PURE__ */ new Map();
+  toolCalls = /* @__PURE__ */ new Map();
+  portRequests = /* @__PURE__ */ new Map();
+  watchers = /* @__PURE__ */ new Map();
+  seq = 0;
+  counter = 0;
+  settingsValues;
+  secretsSet = {};
+  secretValues = /* @__PURE__ */ new Map();
+  /** Agents whose last status was `working` (the turn rule main applies). */
+  lastStatus = /* @__PURE__ */ new Map();
+  // --- wiring ------------------------------------------------------------------
+  /** A new channel for a card; the returned port goes to `connect({ port })`. Replaces a previous one. */
+  createPort() {
+    this.port?.close();
+    const channel = new MessageChannel();
+    this.port = channel.port1;
+    this.ready = false;
+    this.port.onmessage = (event) => void this.receive(event.data);
+    return channel.port2;
+  }
+  /** Connects a real SDK {@link Card} to this host. */
+  connect(options = {}) {
+    return connect({ ...options, port: this.createPort() });
+  }
+  /** Replaces or adds the handler of a method (runs after the host's schema/permission checks). */
+  handle(method, handler) {
+    this.overrides.set(method, handler);
+    return this;
+  }
+  /** Closes the channel (the card sees UNAVAILABLE on later calls). */
+  close() {
+    this.port?.close();
+    this.port = null;
+  }
+  /** Current HostContext (as it would be sent on `host.ready` now). */
+  get hostContext() {
+    return this.context;
+  }
+  /** Currently granted permission ids (with implications). */
+  get grants() {
+    return expandGranted(this.granted);
+  }
+  // --- driving the card ---------------------------------------------------------
+  /** Sends any event to the card. */
+  emit(event, data) {
+    this.events.push({ event, data });
+    if (this.options.verbose) console.log("[mock host] evt", event, data);
+    this.port?.postMessage(eventMessage(event, data));
+  }
+  /** Sends `host.ping` and resolves when the card's `host.pong` arrives. */
+  ping(timeoutMs = 2e3) {
+    const seq = ++this.seq;
+    this.emit("host.ping", { seq });
+    return this.until(() => this.pongs.includes(seq), timeoutMs, "host.pong").then(() => seq);
+  }
+  setVisibility(state) {
+    this.context = { ...this.context, visibility: state };
+    this.emit("lifecycle.visibility", { state });
+  }
+  setExpanded(expanded) {
+    this.context = { ...this.context, expanded };
+    this.emit("lifecycle.expanded", { expanded });
+  }
+  resize(size) {
+    this.context = { ...this.context, instance: { ...this.context.instance, size } };
+    this.emit("lifecycle.resized", size);
+  }
+  /** Sends `lifecycle.suspend`. */
+  suspend(graceMs = LIMITS.suspendGraceMs) {
+    this.emit("lifecycle.suspend", { graceMs });
+  }
+  setTheme(theme) {
+    this.context = { ...this.context, theme };
+    this.emit("theme.changed", theme);
+  }
+  setLanguage(language) {
+    const i18n = { language, locale: { en: "en-US", ru: "ru-RU", zh: "zh-CN" }[language] };
+    this.context = { ...this.context, i18n };
+    this.emit("i18n.changed", i18n);
+  }
+  /** The user changed settings in the host form (secrets: pass `true`/`false` in `secrets`). */
+  setSettings(values, secrets = {}) {
+    this.settingsValues = { ...this.settingsValues, ...values };
+    this.secretsSet = { ...this.secretsSet, ...secrets };
+    const snapshot = { values: this.settingsValues, secrets: this.secretsSet };
+    this.context = { ...this.context, settings: snapshot };
+    this.emit("settings.changed", snapshot);
+  }
+  /**
+   * The user entered (or cleared, with `null`) a secret setting in the host
+   * form. The card only sees `settings.secrets[key]` flip; the value is used
+   * for `{{secret:key}}` in `net.fetch` headers.
+   */
+  setSecret(key, value) {
+    const field = this.manifest.settings.find((f) => f.key === key && f.type === "secret");
+    if (!field) throw new Error(`mock host: "${key}" is not a secret setting of the manifest`);
+    if (value === null) this.secretValues.delete(key);
+    else this.secretValues.set(key, value);
+    this.setSettings({}, { [key]: value !== null });
+  }
+  /** Grants or revokes permissions (the card gets `permissions.changed`). */
+  setGrants(ids) {
+    this.granted = new Set(ids);
+    const permissions = this.permissionList();
+    this.context = { ...this.context, permissions };
+    this.emit("permissions.changed", permissions);
+  }
+  /** Replaces the connected cards (the card gets `ports.peersChanged`). */
+  setPeers(peers) {
+    this.options.peers = peers;
+    this.context = { ...this.context, peers: this.peerInfos() };
+    this.emit("ports.peersChanged", this.context.peers);
+  }
+  /**
+   * Delivers a value to one of the card's inputs, as if a peer emitted it —
+   * with the app's checks: `from.cardId`, when given, must be a peer whose
+   * arrow points at this card (`upstream` or `both`); the value is converted
+   * from the sender's output type (`from.output` of that peer, or
+   * `from.type`) to the input's type and must fit the input's schema.
+   * Without `from.cardId` the first upstream peer is the sender, or an
+   * anonymous custom card when there is none. Throws when the app would not
+   * deliver the value.
+   */
+  sendPortMessage(input, data, from = {}) {
+    const port = this.context.ports.inputs.find((p) => p.id === input);
+    if (!port) throw new Error(`mock host: the card has no input "${input}"`);
+    const peers = this.options.peers ?? [];
+    let peer;
+    if (from.cardId !== void 0) {
+      peer = peers.find((p) => p.cardId === from.cardId);
+      if (!peer) throw new Error(`mock host: ${from.cardId} is not connected to this card`);
+      if (peer.direction === "downstream") {
+        throw new Error(
+          `mock host: the arrow goes from this card to ${peer.name}; it cannot send here`
+        );
+      }
+    } else peer = peers.find((p) => p.direction !== "downstream");
+    const output = peer?.outputs.find((o) => o.id === from.output) ?? peer?.outputs[0];
+    const sourceType = from.type ?? output?.type ?? port.type;
+    let value;
+    try {
+      value = coercePortValue(sourceType, port.type, data);
+    } catch (error) {
+      throw new Error(
+        `mock host: ${sourceType} does not convert to ${port.type}: ${error.message}`
+      );
+    }
+    for (const schema of portSchemas(port)) {
+      const issues = validateJson(schema, value);
+      if (issues.length > 0) {
+        throw new Error(
+          `mock host: the value does not fit input "${input}" \u2014 ${issues[0].path || "value"} ${issues[0].message}`
+        );
+      }
+    }
+    this.emit("ports.message", {
+      from: peer?.cardId ?? from.cardId ?? "peer-1",
+      fromKind: from.kind ?? peer?.kind ?? "custom",
+      output: output?.id ?? from.output ?? "out",
+      input,
+      type: port.type,
+      sourceType,
+      data: value,
+      at: Date.now()
+    });
+  }
+  /** Asks one of the card's `mode: "request"` inputs and resolves with its reply. */
+  requestPort(input, data, options = {}) {
+    const requestId = `req-${++this.counter}`;
+    const timeoutMs = options.timeoutMs ?? LIMITS.portRequestTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.portRequests.delete(requestId);
+        reject(new HostError("TIMEOUT", `no reply to ${requestId}`));
+      }, timeoutMs);
+      this.portRequests.set(requestId, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      this.emit("ports.request", {
+        requestId,
+        from: options.from ?? "peer-1",
+        input,
+        data,
+        deadline: Date.now() + timeoutMs
+      });
+    });
+  }
+  /**
+   * Calls one of the card's tools as a connected agent would, and resolves
+   * with the result (rejects with the card's error message).
+   */
+  callTool(tool, args = {}, options = {}) {
+    const rejected = (message) => Object.assign(Promise.reject(new HostError("INVALID_PARAMS", message)), { callId: "" });
+    const declared = this.manifest.tools.find((t) => t.name === tool);
+    if (!declared) return rejected(`mock host: the manifest declares no tool "${tool}"`);
+    const issues = validateJson(declared.inputSchema, args);
+    if (issues.length > 0)
+      return rejected(`mock host: invalid tool args \u2014 ${issues[0].path}: ${issues[0].message}`);
+    const callId = `call-${++this.counter}`;
+    const timeoutMs = options.timeoutMs ?? declared.timeoutMs ?? LIMITS.toolTimeoutMs;
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.toolCalls.delete(callId);
+        this.emit("tools.cancel", { callId });
+        reject(new HostError("TIMEOUT", `tool ${tool} timed out`));
+      }, timeoutMs);
+      this.toolCalls.set(callId, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolve(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        }
+      });
+      this.emit("tools.call", {
+        callId,
+        tool,
+        args,
+        agent: options.agent ?? { id: "agent-1", name: "Claude Code" },
+        deadline: Date.now() + timeoutMs
+      });
+    });
+    return Object.assign(promise, { callId });
+  }
+  /** Cancels a running tool call (`tools.cancel`); the promise from callTool rejects. */
+  cancelTool(callId) {
+    const pending = this.toolCalls.get(callId);
+    this.toolCalls.delete(callId);
+    this.emit("tools.cancel", { callId });
+    pending?.reject(new HostError("USER_CANCELLED", "cancelled"));
+  }
+  /**
+   * Changes an agent's status; the card gets `agents.status` if subscribed,
+   * and `agents.turn` by the app's rule: `start` on entering `working`,
+   * `end` on leaving it for `finished` or `needs-input`.
+   */
+  setAgentStatus(agentId, status) {
+    const agent = this.agentList().find((a) => a.id === agentId);
+    if (!agent) throw new Error(`mock host: no agent "${agentId}"`);
+    const previous = this.lastStatus.get(agentId) ?? agent.status;
+    const at = Date.now();
+    agent.status = status;
+    this.lastStatus.set(agentId, status);
+    if (previous === "working" && (status === "finished" || status === "needs-input")) {
+      agent.lastTurn = { startedAt: agent.turnStartedAt ?? null, endedAt: at, endedAs: status };
+    }
+    if (status === "working" && previous !== "working") agent.turnStartedAt = at;
+    else if (status !== "working") delete agent.turnStartedAt;
+    if (this.subscriptions.has("agents.status")) this.emit("agents.status", { agentId, status, at });
+    const phase = status === "working" && previous !== "working" ? "start" : previous === "working" && (status === "finished" || status === "needs-input") ? "end" : null;
+    if (phase && this.subscriptions.has("agents.turn"))
+      this.emit("agents.turn", { agentId, phase, at });
+  }
+  /** Output of an agent; the card gets `agents.output` if subscribed for that agent. */
+  agentOutput(agentId, text) {
+    if (this.subscriptions.has("agents.output") && this.outputAgents.includes(agentId)) {
+      this.emit("agents.output", { agentId, text, at: Date.now() });
+    }
+  }
+  /** Changes a file (or creates it) and notifies matching watchers. */
+  touchFile(path, data) {
+    if (data !== void 0) this.putFile(path, data);
+    for (const [watchId, watch] of this.watchers) {
+      const inside = watch.path === "" || path === watch.path || path.startsWith(`${watch.path}/`);
+      const direct = watch.recursive || !path.slice(watch.path.length + 1).includes("/");
+      if (inside && direct) this.emit("fs.changed", { watchId, path, type: "change" });
+    }
+  }
+  /** Text of a file in the mock workspace, or undefined. */
+  readFile(path) {
+    const file = this.files.get(path);
+    return file ? new TextDecoder().decode(file.data) : void 0;
+  }
+  // --- internals -----------------------------------------------------------------
+  putFile(path, data) {
+    this.files.set(path, {
+      data: typeof data === "string" ? new TextEncoder().encode(data) : data,
+      mtimeMs: Date.now()
+    });
+  }
+  agentList() {
+    return this.options.agents ??= [];
+  }
+  permissionList() {
+    return permissionStates(
+      this.manifest.permissions,
+      expandGranted(this.granted),
+      (text) => resolveLocalized(text, this.context?.i18n.language ?? "en")
+    );
+  }
+  peerInfos() {
+    return (this.options.peers ?? []).map(({ retained: _r, respond: _s, ...peer }) => peer);
+  }
+  peer(cardId) {
+    return (this.options.peers ?? []).find((p) => p.cardId === cardId) ?? fail("NOT_CONNECTED", `card ${cardId} is not connected to this card by an arrow`);
+  }
+  connectedAgent(agentId) {
+    const agent = this.agentList().find((a) => a.id === agentId) ?? fail("NOT_FOUND", `no agent ${agentId}`);
+    if (!agent.connected)
+      fail("NOT_CONNECTED", `agent ${agentId} is not connected to this card by an arrow`);
+    return agent;
+  }
+  until(check, timeoutMs, what) {
+    return new Promise((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        if (check()) resolve();
+        else if (Date.now() - started > timeoutMs)
+          reject(new Error(`mock host: no ${what} in ${timeoutMs} ms`));
+        else setTimeout(tick, 5);
+      };
+      tick();
+    });
+  }
+  reply(message) {
+    this.port?.postMessage(message);
+  }
+  async receive(data) {
+    const requested = data?.method;
+    const parsed = parseCardMessage(
+      data,
+      typeof requested === "string" && LARGE_REQUEST_METHODS.has(requested) ? LIMITS.largeMessageBytes : LIMITS.messageBytes
+    );
+    if (!parsed.ok) {
+      if (parsed.id !== null)
+        this.reply(
+          errorResponse(parsed.id, parsed.error.code, parsed.error.message, parsed.error.data)
+        );
+      return;
+    }
+    const { id, method } = parsed.message;
+    const params = parsed.message.params ?? {};
+    this.calls.push({ method, params });
+    if (this.options.verbose) console.log("[mock host] req", method, params);
+    try {
+      const result = await this.dispatch(method, params);
+      const response = okResponse(id, result);
+      const spec = METHOD_SPECS[method];
+      const max = spec?.largeResponse ? LIMITS.largeMessageBytes : LIMITS.messageBytes;
+      if (messageSize(response) > max)
+        this.reply(errorResponse(id, "TOO_LARGE", "result larger than the limit"));
+      else this.reply(response);
+    } catch (error) {
+      if (error instanceof HostError)
+        this.reply(errorResponse(id, error.code, error.message, error.data));
+      else
+        this.reply(
+          errorResponse(id, "INTERNAL", error instanceof Error ? error.message : String(error))
+        );
+    }
+  }
+  async dispatch(method, params) {
+    if (!this.ready && method !== "host.ready") fail("NOT_READY", "call host.ready first");
+    const spec = METHOD_SPECS[method];
+    if (!spec) fail("METHOD_NOT_FOUND", `no method ${method}`);
+    const issues = validateJson(spec.params, params);
+    if (issues.length > 0)
+      fail("INVALID_PARAMS", `${issues[0].path || "params"}: ${issues[0].message}`, issues);
+    const name = method;
+    if (!methodAllowed(name, this.grants)) {
+      const need = spec.permission;
+      fail("PERMISSION_DENIED", `${method} needs ${String(need)}`, {
+        permission: typeof need === "string" ? need : need?.[0]
+      });
+    }
+    if (spec.visible && this.context.visibility !== "visible")
+      fail("NOT_VISIBLE", `${method} needs the card on screen`);
+    if (this.options.enforceRateLimits) this.throttle(name);
+    const override = this.overrides.get(method);
+    if (override) return override(params, this);
+    return this.builtin(name, params);
+  }
+  throttle(method) {
+    const spec = METHOD_SPECS[method];
+    const now = Date.now();
+    if (spec.minIntervalMs !== void 0) {
+      const last = this.lastCall.get(method);
+      if (last !== void 0 && now - last < spec.minIntervalMs) {
+        fail("RATE_LIMITED", `${method}: once per ${spec.minIntervalMs} ms`, {
+          retryAfterMs: spec.minIntervalMs - (now - last)
+        });
+      }
+      this.lastCall.set(method, now);
+    }
+    if (spec.perMinute !== void 0) {
+      const recent = (this.minuteCalls.get(method) ?? []).filter((t) => now - t < 6e4);
+      if (recent.length >= spec.perMinute) {
+        fail("RATE_LIMITED", `${method}: ${spec.perMinute} per minute`, {
+          retryAfterMs: 6e4 - (now - recent[0])
+        });
+      }
+      recent.push(now);
+      this.minuteCalls.set(method, recent);
+    }
+  }
+  async builtin(method, p) {
+    const str = (key) => p[key];
+    switch (method) {
+      case "host.ready": {
+        if (p["protocol"] > this.context.protocol) {
+          fail("PROTOCOL_MISMATCH", `the host speaks protocol ${this.context.protocol}`);
+        }
+        this.ready = true;
+        return { ...this.context, chrome: this.chromeState() };
+      }
+      case "host.capabilities":
+        return {
+          protocol: this.context.protocol,
+          methods: CARD_METHOD_NAMES,
+          events: CARD_EVENT_NAMES
+        };
+      case "host.log":
+        this.logs.push({ level: str("level"), message: str("message") });
+        return void 0;
+      case "host.pong":
+        this.pongs.push(p["seq"]);
+        return void 0;
+      case "events.subscribe": {
+        const topics = p["topics"];
+        const agentIds = p["agentIds"] ?? [];
+        const granted = topics.filter((topic) => {
+          const need = TOPIC_PERMISSION[topic];
+          if (need && !this.grants.has(need)) return false;
+          if (topic === "agents.output") {
+            if (agentIds.length === 0) return false;
+            for (const id of agentIds) this.connectedAgent(id);
+            this.outputAgents = agentIds;
+          }
+          return true;
+        });
+        granted.forEach((topic) => this.subscriptions.add(topic));
+        return { topics: granted };
+      }
+      case "events.unsubscribe":
+        for (const topic of p["topics"]) this.subscriptions.delete(topic);
+        return void 0;
+      case "card.getInfo":
+        return this.context.instance;
+      case "card.setTitle":
+        this.chrome.title = p["title"];
+        return void 0;
+      case "card.setStatus":
+        this.chrome.status = p;
+        return void 0;
+      case "card.setBadge":
+        this.chrome.badge = p;
+        return void 0;
+      case "card.setOverview":
+        this.chrome.overview = p;
+        return void 0;
+      case "card.attention":
+        this.chrome.attention = p;
+        return void 0;
+      case "card.requestResize": {
+        const { minSize, maxSize } = this.manifest.card;
+        const size = {
+          w: Math.min(maxSize.w, Math.max(minSize.w, p["w"])),
+          h: Math.min(maxSize.h, Math.max(minSize.h, p["h"]))
+        };
+        this.resize(size);
+        return size;
+      }
+      case "card.openLink": {
+        const url = str("url");
+        if (!url.startsWith("https://")) fail("INVALID_PARAMS", "only https links");
+        return { opened: await this.confirmed({ type: "open-link", url }) };
+      }
+      case "card.focus":
+        return void 0;
+      case "card.spawn": {
+        const cardId = `spawned-${++this.counter}`;
+        if (this.spawned.length >= LIMITS.spawnsPerInstance)
+          fail("QUOTA_EXCEEDED", "spawn quota reached");
+        this.spawned.push({
+          cardId,
+          kind: str("kind"),
+          ...p["title"] !== void 0 ? { title: str("title") } : {},
+          ...p["init"] !== void 0 ? { init: p["init"] } : {}
+        });
+        return { cardId };
+      }
+      case "ui.toast":
+        this.toasts.push({ message: str("message"), ...p["tone"] ? { tone: str("tone") } : {} });
+        return void 0;
+      case "ui.confirm":
+        return {
+          confirmed: await this.confirmed({
+            type: "confirm",
+            title: str("title"),
+            message: str("message")
+          })
+        };
+      case "ui.setMenu":
+        this.chrome.menu = p["items"];
+        return void 0;
+      case "settings.get":
+        return { values: this.settingsValues, secrets: this.secretsSet };
+      case "settings.set": {
+        const values = p["values"];
+        const problems = checkSettingValues(this.manifest.settings, values);
+        if (problems.length > 0)
+          fail("INVALID_PARAMS", `${problems[0].key}: ${problems[0].message}`, problems);
+        this.setSettings(values);
+        return { values: this.settingsValues, secrets: this.secretsSet };
+      }
+      case "settings.open":
+        return void 0;
+      case "storage.get": {
+        const map = this.storage[str("scope")];
+        return map.has(str("key")) ? { exists: true, value: map.get(str("key")) } : { exists: false, value: null };
+      }
+      case "storage.set": {
+        const scope = str("scope");
+        const map = this.storage[scope];
+        const size = JSON.stringify(p["value"]).length;
+        if (size > LIMITS.storageValueBytes) fail("TOO_LARGE", "value larger than 1 MB");
+        if (!map.has(str("key")) && map.size >= LIMITS.storageKeys)
+          fail("QUOTA_EXCEEDED", "too many keys");
+        const quota = scope === "instance" ? LIMITS.instanceStorageBytes : LIMITS.packageStorageBytes;
+        const used = this.storageBytes(map) - (map.has(str("key")) ? JSON.stringify(map.get(str("key"))).length : 0);
+        if (used + size + str("key").length > quota)
+          fail("QUOTA_EXCEEDED", "storage quota exceeded");
+        map.set(str("key"), p["value"]);
+        return void 0;
+      }
+      case "storage.delete":
+        this.storage[str("scope")].delete(str("key"));
+        return void 0;
+      case "storage.keys": {
+        const prefix = p["prefix"] ?? "";
+        return {
+          keys: [...this.storage[str("scope")].keys()].filter((k) => k.startsWith(prefix)).sort()
+        };
+      }
+      case "storage.clear":
+        this.storage[str("scope")].clear();
+        return void 0;
+      case "storage.usage": {
+        const scope = str("scope");
+        const map = this.storage[scope];
+        return {
+          bytes: this.storageBytes(map),
+          quota: scope === "instance" ? LIMITS.instanceStorageBytes : LIMITS.packageStorageBytes,
+          keys: map.size
+        };
+      }
+      case "theme.get":
+        return this.context.theme;
+      case "i18n.get":
+        return this.context.i18n;
+      case "workspace.get":
+        return this.context.workspace;
+      case "permissions.list":
+        return this.permissionList();
+      case "permissions.request": {
+        const ids = p["ids"];
+        for (const id of ids) {
+          const declared = this.manifest.permissions.find((perm) => perm.id === id);
+          if (!declared?.optional)
+            fail("PERMISSION_DENIED", `${id} is not a declared optional permission`, {
+              permission: id
+            });
+        }
+        const granted = this.options.requestPermissions ? await this.options.requestPermissions(ids) : ids;
+        const next = [...this.granted, ...granted];
+        this.setGrants(next);
+        return { granted };
+      }
+      case "agents.list":
+        return this.agentList();
+      case "agents.get":
+        return this.agentList().find((a) => a.id === str("agentId")) ?? fail("NOT_FOUND", `no agent ${str("agentId")}`);
+      case "agents.readScreen": {
+        this.connectedAgent(str("agentId"));
+        const text = this.options.screens?.[str("agentId")] ?? "";
+        const lines = p["lines"] ?? LIMITS.screenLines;
+        return { text: text.split("\n").slice(-lines).join("\n") };
+      }
+      case "agents.lastReply": {
+        this.connectedAgent(str("agentId"));
+        const text = this.options.replies?.[str("agentId")] ?? null;
+        return { text, at: text === null ? null : Date.now() };
+      }
+      case "agents.prompt": {
+        const agent = this.connectedAgent(str("agentId"));
+        if (agent.kind !== "ai") fail("NOT_FOUND", `${agent.name} is not an AI agent`);
+        let delivered = "sent";
+        if (p["submit"] === false) delivered = "inserted";
+        else if (agent.status === "working") {
+          const whenBusy = p["whenBusy"] ?? "queue";
+          if (whenBusy === "fail") fail("BUSY", `${agent.name} is working`);
+          delivered = whenBusy === "queue" ? "queued" : "sent";
+        }
+        this.prompts.push({ agentId: agent.id, text: str("text"), delivered });
+        return { delivered };
+      }
+      case "terminals.run":
+      case "terminals.write": {
+        const agent = this.connectedAgent(str("agentId"));
+        if (agent.kind !== "shell") fail("NOT_FOUND", `${agent.name} is not a terminal`);
+        const run = method === "terminals.run";
+        this.terminal.push({
+          agentId: agent.id,
+          text: run ? str("command") : str("text"),
+          kind: run ? "run" : "write"
+        });
+        return run ? { exitCode: 0, output: "", truncated: false, timedOut: false } : void 0;
+      }
+      case "ports.describe":
+        return this.context.ports;
+      case "ports.peers":
+        return this.peerInfos();
+      case "ports.emit":
+      case "ports.send":
+        return {
+          delivered: this.deliver(
+            method === "ports.send" ? str("to") : null,
+            str("port"),
+            p["data"],
+            p["input"]
+          )
+        };
+      case "ports.request": {
+        const peer = this.peer(str("to"));
+        const input = peer.inputs.find((i) => i.id === str("input")) ?? fail("NOT_FOUND", `${peer.name} has no input ${str("input")}`);
+        if (input.mode !== "request") fail("INVALID_PARAMS", `${input.id} is not a request input`);
+        const respond = peer.respond ?? fail("UNAVAILABLE", `${peer.name} does not answer requests in this mock`);
+        return { data: await respond(input.id, p["data"]) };
+      }
+      case "ports.respond": {
+        const pending = this.portRequests.get(str("requestId")) ?? fail("NOT_FOUND", `no request ${str("requestId")}`);
+        this.portRequests.delete(str("requestId"));
+        if (p["error"] !== void 0) pending.reject(new HostError("INTERNAL", str("error")));
+        else pending.resolve(p["data"] ?? null);
+        return void 0;
+      }
+      case "ports.read": {
+        const peer = this.peer(str("from"));
+        const value = peer.retained?.[str("port")];
+        return value === void 0 ? null : { data: value, at: Date.now() };
+      }
+      case "tools.respond": {
+        const pending = this.toolCalls.get(str("callId")) ?? fail("NOT_FOUND", `no tool call ${str("callId")}`);
+        this.toolCalls.delete(str("callId"));
+        if (p["error"] !== void 0) pending.reject(new HostError("INTERNAL", str("error")));
+        else pending.resolve(p["result"]);
+        return void 0;
+      }
+      case "tools.progress":
+        return void 0;
+      case "tools.setEnabled":
+        if (!this.manifest.tools.some((t) => t.name === str("tool")))
+          fail("NOT_FOUND", `no tool ${str("tool")}`);
+        this.chrome.enabledTools[str("tool")] = p["enabled"];
+        return void 0;
+      case "net.fetch":
+        return this.fetch(p);
+      case "net.abort":
+        this.aborted.push(str("requestId"));
+        return void 0;
+      case "clipboard.writeText":
+        this.clipboard.push(str("text"));
+        return void 0;
+      case "usage.summary":
+        return this.options.usage ?? {
+          period: str("period"),
+          from: (/* @__PURE__ */ new Date()).toISOString(),
+          to: (/* @__PURE__ */ new Date()).toISOString(),
+          rows: [],
+          totalCostMicroUsd: 0,
+          partial: false
+        };
+      default:
+        return this.fs(method, p);
+    }
+  }
+  /** HostContext.chrome as the app would send it. */
+  chromeState() {
+    const { title, status, badge, overview, attention } = this.chrome;
+    return {
+      title,
+      status: status && status.text ? { text: status.text, tone: status.tone ?? "default", busy: status.busy === true } : null,
+      badge: badge && (badge.count != null || badge.text) ? { count: badge.count ?? null, text: badge.text ?? null, tone: badge.tone ?? "default" } : null,
+      overview: overview ?? null,
+      attention: attention && attention.level !== "none" ? { level: attention.level, message: attention.message ?? null } : null
+    };
+  }
+  storageBytes(map) {
+    let bytes = 0;
+    for (const [key, value] of map) bytes += key.length + JSON.stringify(value).length;
+    return bytes;
+  }
+  async confirmed(request) {
+    return this.options.confirm ? await this.options.confirm(request) : true;
+  }
+  deliver(to, portId, data, explicitInput) {
+    const output = this.context.ports.outputs.find((o) => o.id === portId) ?? fail("NOT_FOUND", `no output port "${portId}" in the manifest`);
+    for (const schema of portSchemas(output)) {
+      const issues = validateJson(schema, data);
+      if (issues.length > 0)
+        fail(
+          "INVALID_PARAMS",
+          `data for ${portId}: ${issues[0].path || "value"} ${issues[0].message}`,
+          issues
+        );
+    }
+    if (output.retain) this.retained.set(portId, { data, at: Date.now() });
+    const peers = to ? [this.peer(to)] : this.options.peers ?? [];
+    let delivered = 0;
+    for (const peer of peers) {
+      if (peer.direction === "upstream") {
+        if (to)
+          fail("NOT_CONNECTED", `the arrow goes from ${peer.name} to this card, not the other way`);
+        continue;
+      }
+      const input = explicitInput ? peer.inputs.find((i) => i.id === explicitInput) ?? fail("NOT_FOUND", `${peer.name} has no input ${explicitInput}`) : pickInputFor(output.type, peer.inputs);
+      if (!input) continue;
+      if (input.permission && !this.grants.has(input.permission)) {
+        if (to)
+          fail("PERMISSION_DENIED", `${input.id} needs ${input.permission}`, {
+            permission: input.permission
+          });
+        continue;
+      }
+      let value;
+      try {
+        value = coercePortValue(output.type, input.type, data);
+      } catch {
+        if (to) fail("INVALID_PARAMS", `${output.type} does not fit ${input.type}`);
+        continue;
+      }
+      const bad = portSchemas(input).some((schema) => validateJson(schema, value).length > 0);
+      if (bad) {
+        if (to) fail("INVALID_PARAMS", `the value does not fit ${peer.name}'s input ${input.id}`);
+        continue;
+      }
+      this.deliveries.push({
+        to: peer.cardId,
+        output: portId,
+        input: input.id,
+        data: value
+      });
+      delivered++;
+    }
+    return delivered;
+  }
+  async fetch(p) {
+    let url;
+    try {
+      url = new URL(p["url"]);
+    } catch {
+      return fail("INVALID_PARAMS", "not a URL");
+    }
+    const local = isLocalHostname(url.hostname);
+    if (url.username || url.password)
+      fail("INVALID_PARAMS", "credentials in the URL are not allowed");
+    if (local) {
+      if (!this.grants.has("network.local"))
+        fail("PERMISSION_DENIED", "localhost needs network.local", { permission: "network.local" });
+      if (url.protocol !== "http:" && url.protocol !== "https:")
+        fail("HOST_NOT_ALLOWED", "http(s) only");
+    } else {
+      if (url.protocol !== "https:") fail("HOST_NOT_ALLOWED", "https only");
+      const hosts = this.manifest.permissions.find((perm) => perm.id === "network")?.hosts ?? [];
+      if (!this.grants.has("network") || !hostAllowed(hosts, url.hostname, Number(url.port || 443))) {
+        fail("HOST_NOT_ALLOWED", `${url.host} is not in the network permission`);
+      }
+    }
+    if (!this.options.fetch)
+      return fail("NETWORK_ERROR", "the mock host has no fetch handler (MockHostOptions.fetch)");
+    const headers = {};
+    for (const [name, value] of Object.entries(
+      p["headers"] ?? {}
+    )) {
+      const problem = checkRequestHeader(name, value);
+      if (problem) fail("INVALID_PARAMS", problem);
+      const keys = secretPlaceholders(value);
+      for (const key of keys) {
+        if (!this.manifest.settings.some((f) => f.key === key && f.type === "secret"))
+          fail("INVALID_PARAMS", `"${key}" is not a secret setting of this card`);
+        if (!this.secretValues.has(key))
+          fail("INVALID_PARAMS", `the secret setting "${key}" is not set`);
+      }
+      headers[name.toLowerCase()] = keys.length ? value.replace(
+        SECRET_PLACEHOLDER_RE,
+        (_all, key) => this.secretValues.get(key) ?? ""
+      ) : value;
+    }
+    const bodyText = p["body"];
+    const response = await this.options.fetch({
+      url: url.toString(),
+      method: p["method"] ?? "GET",
+      headers,
+      ...bodyText !== void 0 ? { body: p["bodyEncoding"] === "base64" ? base64ToBytes(bodyText) : bodyText } : {}
+    });
+    if (response.error) fail("NETWORK_ERROR", response.error);
+    const requestId = p["requestId"];
+    const type = p["responseType"] ?? "text";
+    const base = {
+      requestId,
+      status: response.status ?? 200,
+      statusText: response.statusText ?? "OK",
+      headers: Object.fromEntries(
+        Object.entries(response.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])
+      ),
+      url: url.toString()
+    };
+    const body = response.body;
+    const asText = () => body === void 0 ? "" : typeof body === "string" ? body : body instanceof Uint8Array ? new TextDecoder().decode(body) : JSON.stringify(body);
+    switch (type) {
+      case "json": {
+        if (body !== void 0 && typeof body !== "string" && !(body instanceof Uint8Array))
+          return { ...base, json: body };
+        if (asText().trim() === "") return { ...base, json: null };
+        try {
+          return { ...base, json: JSON.parse(asText()) };
+        } catch {
+          return fail("NETWORK_ERROR", "response is not JSON");
+        }
+      }
+      case "base64":
+        return {
+          ...base,
+          body: bytesToBase64(
+            body instanceof Uint8Array ? body : new TextEncoder().encode(asText())
+          )
+        };
+      case "stream": {
+        const chunks = response.stream ?? [asText()];
+        setTimeout(() => {
+          chunks.forEach(
+            (chunk) => this.emit("net.chunk", {
+              requestId,
+              chunk: typeof chunk === "string" ? chunk : bytesToBase64(chunk),
+              encoding: typeof chunk === "string" ? "text" : "base64",
+              done: false
+            })
+          );
+          this.emit("net.chunk", { requestId, chunk: "", encoding: "text", done: true });
+        }, 0);
+        return base;
+      }
+      default:
+        return { ...base, body: asText() };
+    }
+  }
+  /** The app's write rules: any `.git` segment, agent config (`.claude/`, `CLAUDE.md`, `.mcp.json`…). */
+  assertWritable(path) {
+    const reason = protectedWriteReason(path);
+    if (reason) fail("FS_DENIED", reason);
+  }
+  fs(method, p) {
+    const pathOf = (key = "path") => {
+      const checked = normalizeWorkspacePath(p[key]);
+      return checked.ok ? checked.value : fail("FS_DENIED", checked.error);
+    };
+    const isDir = (path) => path === "" || [...this.files.keys()].some((file) => file.startsWith(`${path}/`));
+    const stat = (path) => {
+      const file = this.files.get(path);
+      if (file) return { path, type: "file", size: file.data.length, mtimeMs: file.mtimeMs };
+      if (isDir(path)) return { path, type: "directory", size: 0, mtimeMs: 0 };
+      return fail("NOT_FOUND", `${path} does not exist`);
+    };
+    switch (method) {
+      case "fs.stat":
+        return stat(pathOf());
+      case "fs.list": {
+        const root = pathOf();
+        if (!isDir(root)) fail("NOT_FOUND", `${root} is not a folder`);
+        const prefix = root ? `${root}/` : "";
+        const entries = /* @__PURE__ */ new Map();
+        for (const [path, file] of this.files) {
+          if (!path.startsWith(prefix)) continue;
+          const rest = path.slice(prefix.length).split("/");
+          if (p["recursive"] === true) {
+            for (let i = 1; i < rest.length; i++) {
+              const dir = prefix + rest.slice(0, i).join("/");
+              entries.set(dir, { path: dir, type: "directory" });
+            }
+            entries.set(path, { path, type: "file", size: file.data.length });
+          } else if (rest.length === 1)
+            entries.set(path, { path, type: "file", size: file.data.length });
+          else entries.set(prefix + rest[0], { path: prefix + rest[0], type: "directory" });
+        }
+        const max = p["maxEntries"] ?? LIMITS.fsListEntries;
+        const all = [...entries.values()].sort((a, b) => a.path < b.path ? -1 : 1);
+        return { entries: all.slice(0, max), truncated: all.length > max };
+      }
+      case "fs.read": {
+        const path = pathOf();
+        const file = this.files.get(path) ?? fail("NOT_FOUND", `${path} does not exist`);
+        const max = p["maxBytes"] ?? LIMITS.fsReadBytes;
+        const bytes = file.data.subarray(0, max);
+        const encoding = p["encoding"] ?? "utf8";
+        return {
+          data: encoding === "base64" ? bytesToBase64(bytes) : new TextDecoder().decode(bytes),
+          encoding,
+          size: file.data.length,
+          truncated: file.data.length > max
+        };
+      }
+      case "fs.write": {
+        const path = pathOf();
+        if (path === "") fail("FS_DENIED", "the workspace folder itself cannot be changed");
+        this.assertWritable(path);
+        const existing = this.files.get(path);
+        if (p["ifMtimeMs"] !== void 0 && existing && existing.mtimeMs !== p["ifMtimeMs"]) {
+          fail("FS_ERROR", "the file changed since it was read", {
+            conflict: true,
+            mtimeMs: existing.mtimeMs
+          });
+        }
+        const parent = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+        if (parent && !isDir(parent) && p["createDirs"] !== true)
+          fail("FS_ERROR", `folder ${parent} does not exist`);
+        const data = p["encoding"] === "base64" ? base64ToBytes(p["data"]) : p["data"];
+        this.putFile(path, data);
+        const file = this.files.get(path);
+        if (existing && file.mtimeMs <= existing.mtimeMs) file.mtimeMs = existing.mtimeMs + 1;
+        this.touchFile(path);
+        return stat(path);
+      }
+      case "fs.mkdir": {
+        const path = pathOf();
+        this.assertWritable(path);
+        this.files.set(`${path}/.keep`, { data: new Uint8Array(), mtimeMs: Date.now() });
+        return { path, type: "directory", size: 0, mtimeMs: Date.now() };
+      }
+      case "fs.trash": {
+        const path = pathOf();
+        this.assertWritable(path);
+        stat(path);
+        for (const file of [...this.files.keys()])
+          if (file === path || file.startsWith(`${path}/`)) this.files.delete(file);
+        return void 0;
+      }
+      case "fs.watch": {
+        if (this.watchers.size >= LIMITS.fsWatchers) fail("QUOTA_EXCEEDED", "too many watchers");
+        const watchId = `watch-${++this.counter}`;
+        this.watchers.set(watchId, { path: pathOf(), recursive: p["recursive"] === true });
+        return { watchId };
+      }
+      case "fs.unwatch":
+        this.watchers.delete(p["watchId"]);
+        return void 0;
+      default:
+        return fail("METHOD_NOT_FOUND", `the mock host does not implement ${method}`);
+    }
+  }
+};
+function createMockHost(options = {}) {
+  return new MockHost(options);
+}
+export {
+  MockHost,
+  createMockHost
+};