@capybara-hq/testing 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/fake-channel.d.ts

@@ -71,6 +71,12 @@ export interface FakeDirectoryBook {
     /** 整轮同步开始的次数（不带游标的请求数）。 */
     starts(): number;
 }
+/** Which `/send` or `/update` requests a {@link FakeChannelServer.failNext} failure applies to. */
+export interface FakeChannelFailMatch {
+    chatId?: string;
+    /** The message's text contains it. */
+    textIncludes?: string;
+}
 /** 插件工具经 `POST /posts` 发出的一条记录。 */
 export interface FakeChannelPost {
     body: Record<string, unknown>;
@@ -101,8 +107,11 @@ export interface FakeChannelServer {
      * 让接下来 `count` 次 `/send`（或 `/update`）返回该状态码（不记录）；`retryAfterMs` 与 `reason` 放进响应体，
      * 测试插件据此抛 `ChannelSendError`（429 / 5xx 可重试，带等待时长；其他不可重试，带失败原因）。
      * `delayMs`：失败响应推迟这么久才返回（模拟慢的失败请求，让会话的后续事件在投递任务持锁期间到达）。
+     * `match`: only matching requests count and fail; a string is a chat id, an object also matches
+     * text (`textIncludes`: the message's text contains it). Without it the next requests to any chat
+     * fail, so a late delivery from an earlier test can take the failure meant for the request under test.
      */
-    failNext(path: "/send" | "/update", status: number, count?: number, retryAfterMs?: number, reason?: "auth" | "target_gone" | "rejected" | "too_large", delayMs?: number): void;
+    failNext(path: "/send" | "/update", status: number, count?: number, retryAfterMs?: number, reason?: "auth" | "target_gone" | "rejected" | "too_large", delayMs?: number, match?: string | FakeChannelFailMatch): void;
     /**
      * Delay the response of the next `count` successful `/send` (or `/update`) requests by `delayMs`.
      * The message is recorded (visible in `sent` / `updated`) as soon as the request arrives; only the

package/dist/fake-channel.js

@@ -61,7 +61,11 @@ export async function startFakeChannelServer(opts = {}) {
     };
     const sendOrUpdate = async (req, res, path) => {
         const body = await readBody(req);
-        const f = failures.find((x) => x.path === path && x.left > 0);
+        const parsed = JSON.parse(body);
+        const matches = (m) => m === undefined ||
+            ((m.chatId === undefined || m.chatId === parsed.target?.chatId) &&
+                (m.textIncludes === undefined || (parsed.message?.text ?? "").includes(m.textIncludes)));
+        const f = failures.find((x) => x.path === path && x.left > 0 && matches(x.match));
         if (f) {
             f.left--;
             if (f.delayMs !== undefined)
@@ -203,7 +207,7 @@ export async function startFakeChannelServer(opts = {}) {
         duplicateSends,
         posts,
         users,
-        failNext(path, status, count = 1, retryAfterMs, reason, delayMs) {
+        failNext(path, status, count = 1, retryAfterMs, reason, delayMs, match) {
             failures.push({
                 path,
                 status,
@@ -211,6 +215,9 @@ export async function startFakeChannelServer(opts = {}) {
                 ...(retryAfterMs !== undefined && { retryAfterMs }),
                 ...(reason !== undefined && { reason }),
                 ...(delayMs !== undefined && { delayMs }),
+                ...(match !== undefined && {
+                    match: typeof match === "string" ? { chatId: match } : match,
+                }),
             });
         },
         delayNext(path, delayMs, opts = {}) {

package/dist/fake-git-server.js

@@ -129,8 +129,10 @@ function serveCgi(root, req, res) {
         res.writeHead(h.status, h.headers);
         res.write(head.subarray(h.bodyStart));
     });
+    // A child that could not be spawned emits 'error' and then 'close': only the first writes a head
+    // (a second writeHead throws ERR_HTTP_HEADERS_SENT, an uncaught exception).
     p.on("close", () => {
-        if (!headDone)
+        if (!headDone && !res.headersSent)
             res.writeHead(502);
         res.end();
     });

package/dist/fixtures.d.ts

@@ -17,8 +17,10 @@
  * | `fake-bootstrap-b` | `object-store@1` kept in its own PG table; `bucket` + secret `secretKey` |
  * | `fake-dep-provider` / `fake-dep-requirer` | a dependency pair on `counter@1` (the requirer's plugin.json depends on the provider) |
  * | `fake-im` | a whole IM platform for `startFakeChannelServer`: `channel@1` (cards, edits, threads, webhook inbound), `identity-source@1`, `directory@1` (org config `url` of a directory book) and tool `post_announcement` (default policy ask, posts to the platform); deployment config `platformUrl`, `tenant`, `clientId`, secret `clientSecret`. Its `src/index.ts` also exports `makeFakeImChannel`, `fakeImIdentitySource`, `fakeImDirectory` for test extensions that need one part |
+ * | `fake-web` / `fake-web-2` | `web-search@1` and `web-fetch@1`, scripted by a prefix of the query or of the fetched URL's path (`error:<kind>`, `throw:`, `hang:`, `redirect:<url>`, `junk:`, `empty:`, `big:<n>`; see `makeFakeWeb`); results name the provider; org config secret `token`, `configured()` iff it is set (throws for `throw:configured`); calls recorded on `globalThis.__fakeWeb` (`fakeWebProbe`) |
+ * | `fake-config-form` | display name 表单样例 / Form sample; no extension point: an openai-compatible-shaped deployment config (endpoints with a preset menu, an API key per endpoint in the secret record `apiKeys`, model rows, advanced fields, localized custom issues) carrying the config form hints of the extension config forms spec §6, for the web form e2e |
  */
-export declare const FAKE_EXTENSIONS: readonly ["fake-connector", "fake-openapi", "fake-object-store", "fake-tools-ui", "fake-storage-user", "fake-embed", "fake-bootstrap-a", "fake-bootstrap-b", "fake-dep-provider", "fake-dep-requirer", "fake-im"];
+export declare const FAKE_EXTENSIONS: readonly ["fake-connector", "fake-openapi", "fake-object-store", "fake-tools-ui", "fake-storage-user", "fake-embed", "fake-bootstrap-a", "fake-bootstrap-b", "fake-dep-provider", "fake-dep-requirer", "fake-im", "fake-web", "fake-web-2", "fake-config-form"];
 /** The name of a fake extension (also its plugin and extension name). */
 export type FakeExtensionName = (typeof FAKE_EXTENSIONS)[number];
 /** The plugin directory of a fake (pack layout), for `packFixture` or a packer of your own. */

package/dist/fixtures.js

@@ -20,6 +20,8 @@ import { fileURLToPath } from "node:url";
  * | `fake-bootstrap-b` | `object-store@1` kept in its own PG table; `bucket` + secret `secretKey` |
  * | `fake-dep-provider` / `fake-dep-requirer` | a dependency pair on `counter@1` (the requirer's plugin.json depends on the provider) |
  * | `fake-im` | a whole IM platform for `startFakeChannelServer`: `channel@1` (cards, edits, threads, webhook inbound), `identity-source@1`, `directory@1` (org config `url` of a directory book) and tool `post_announcement` (default policy ask, posts to the platform); deployment config `platformUrl`, `tenant`, `clientId`, secret `clientSecret`. Its `src/index.ts` also exports `makeFakeImChannel`, `fakeImIdentitySource`, `fakeImDirectory` for test extensions that need one part |
+ * | `fake-web` / `fake-web-2` | `web-search@1` and `web-fetch@1`, scripted by a prefix of the query or of the fetched URL's path (`error:<kind>`, `throw:`, `hang:`, `redirect:<url>`, `junk:`, `empty:`, `big:<n>`; see `makeFakeWeb`); results name the provider; org config secret `token`, `configured()` iff it is set (throws for `throw:configured`); calls recorded on `globalThis.__fakeWeb` (`fakeWebProbe`) |
+ * | `fake-config-form` | display name 表单样例 / Form sample; no extension point: an openai-compatible-shaped deployment config (endpoints with a preset menu, an API key per endpoint in the secret record `apiKeys`, model rows, advanced fields, localized custom issues) carrying the config form hints of the extension config forms spec §6, for the web form e2e |
  */
 export const FAKE_EXTENSIONS = [
     "fake-connector",
@@ -33,6 +35,9 @@ export const FAKE_EXTENSIONS = [
     "fake-dep-provider",
     "fake-dep-requirer",
     "fake-im",
+    "fake-web",
+    "fake-web-2",
+    "fake-config-form",
 ];
 /** `fixtures/extensions/` of this package (same path from `src/` and from `dist/`). */
 const FIXTURES_DIR = fileURLToPath(new URL("../fixtures/extensions/", import.meta.url));

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { type ConversationEvent, createDb, gatewayReplicasKey, type KernelConfig
 export { createFreshDatabase, startTestPostgres, startTestRedis, startTestS3, TEST_S3_IMAGE, type TestContainer, type TestS3, } from "./containers.js";
 export { createDualReplicaHarness, type DualReplicaOptions, type ExtraReplicaHandle, type Harness, REPLICA_HEADER, type ReplicaHandle, type ReplicaResponse, replicaOf, } from "./dual-replica.js";
 export { assertExtensionSecretsReachable, extensionDeploymentSecretValues, } from "./extension-config.js";
-export { FAKE_CHANNEL_BAD_SECRET, FAKE_WEBHOOK_SIGNATURE_HEADER, type FakeChannelPost, type FakeChannelSent, type FakeChannelServer, type FakeChannelServerOptions, type FakeChannelStream, type FakeChannelUser, type FakeDirectoryBook, type FakeSenderProfile, fakeCardAction, fakeDirectoryMember, fakeDm, fakeGroupMessage, fakeWebhookChallenge, fakeWebhookEvents, signFakeWebhook, startFakeChannelServer, } from "./fake-channel.js";
+export { FAKE_CHANNEL_BAD_SECRET, FAKE_WEBHOOK_SIGNATURE_HEADER, type FakeChannelFailMatch, type FakeChannelPost, type FakeChannelSent, type FakeChannelServer, type FakeChannelServerOptions, type FakeChannelStream, type FakeChannelUser, type FakeDirectoryBook, type FakeSenderProfile, fakeCardAction, fakeDirectoryMember, fakeDm, fakeGroupMessage, fakeWebhookChallenge, fakeWebhookEvents, signFakeWebhook, startFakeChannelServer, } from "./fake-channel.js";
 export { type FakeE2BCall, type FakeE2BMatch, type FakeE2BOptions, type FakeE2BSandbox, type FakeE2BServer, startFakeE2B, } from "./fake-e2b.js";
 export { type FakeGitCommitOptions, type FakeGitRequest, type FakeGitServer, startFakeGitServer, } from "./fake-git-server.js";
 export { encryptLarkWebhook, type FakeLarkAck, type FakeLarkApi, type FakeLarkButton, type FakeLarkCall, type FakeLarkDepartment, type FakeLarkFailure, type FakeLarkMessage, type FakeLarkOptions, type FakeLarkServer, type FakeLarkUser, findLarkButton, larkCardAction, larkMessageEvent, signLarkWebhook, startFakeLark, } from "./fake-lark.js";

package/fixtures/extensions/fake-config-form/.capybara-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-config-form",
+  "displayName": {
+    "zh": "表单样例",
+    "en": "Form sample"
+  },
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: an openai-compatible-shaped deployment config schema with config form hints"
+}

package/fixtures/extensions/fake-config-form/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-config-form",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: an openai-compatible-shaped deployment config schema with config form hints",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-config-form/src/index.ts

@@ -0,0 +1,205 @@
+import {
+  type ConfigUiHints,
+  defineExtension,
+  type LocalizedName,
+  secret,
+  ui,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+/**
+ * Test fake of a hinted deployment config (extension config forms spec §6): the shape of
+ * openai-compatible's config (endpoints with models, API keys in a top-level secret record keyed by
+ * endpoint name) with the hints that plugin carries, so the web form (presets, item secrets, model
+ * rows, advanced fields, localized custom issues) is tested without an official plugin. It provides
+ * nothing and calls no service: setup only validates the config. Display name 表单样例 / Form sample.
+ */
+
+const T = (zh: string, en: string): LocalizedName => ({ zh, en });
+const flag = (zh: string, en: string, help?: LocalizedName) =>
+  ui(z.boolean().optional(), { label: T(zh, en), widget: "checkbox", ...(help && { help }) });
+
+/** Whether a dialect accepts PDF documents (as in openai-compatible: generic and qwen). */
+const acceptsPdf = (dialect: string): boolean => dialect === "generic" || dialect === "qwen";
+
+const EndpointModelSchema = ui(
+  z.object({
+    id: ui(z.string().min(1), { label: T("模型 ID", "Model ID"), placeholder: "deepseek-chat" }),
+    contextWindow: ui(z.number().int().positive(), {
+      label: T("上下文窗口", "Context window"),
+      unit: T("tokens", "tokens"),
+    }),
+    maxOutputTokens: ui(z.number().int().positive(), {
+      label: T("最大输出", "Max output"),
+      unit: T("tokens", "tokens"),
+    }),
+    vision: flag("图片", "Images"),
+    documents: flag(
+      "PDF 文档",
+      "PDF documents",
+      T("仅通用与通义千问方言支持", "Only the generic and Qwen dialects accept PDF"),
+    ),
+    reasoning: flag("推理", "Reasoning"),
+    caching: ui(z.boolean().optional(), {
+      label: T("缓存", "Caching"),
+      widget: "tristate",
+      help: T("默认按方言", "Default follows the dialect"),
+      advanced: true,
+    }),
+    streamIdleTimeoutMs: ui(z.number().int().positive().optional(), {
+      label: T("流空闲超时", "Stream idle timeout"),
+      unit: T("毫秒", "ms"),
+      advanced: true,
+    }),
+  }),
+  { layout: "row" },
+);
+
+const EndpointSchema = z.strictObject({
+  name: ui(z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/), {
+    label: T("名称", "Name"),
+    help: T("对外模型 ID 为 <名称>/<模型 ID>", "Models are exposed as <name>/<model id>"),
+  }),
+  baseUrl: ui(z.string().url(), {
+    label: T("接口地址", "Base URL"),
+    widget: "url",
+    placeholder: "https://api.example.com/v1",
+  }),
+  dialect: ui(z.enum(["generic", "deepseek", "qwen", "ark"]), {
+    label: T("方言", "Dialect"),
+    options: [
+      { value: "generic", label: T("通用（vLLM 等）", "Generic (vLLM, …)") },
+      { value: "deepseek", label: T("DeepSeek", "DeepSeek") },
+      { value: "qwen", label: T("通义千问（百炼）", "Qwen (Model Studio)") },
+      { value: "ark", label: T("火山方舟", "Volcano Ark") },
+    ],
+  }),
+  midConversationSystem: ui(z.boolean().optional(), {
+    label: T("对话中途的 system 消息", "Mid-conversation system messages"),
+    widget: "tristate",
+    advanced: true,
+  }),
+  models: ui(
+    z
+      .array(EndpointModelSchema)
+      .min(1)
+      .refine((ms) => new Set(ms.map((m) => m.id)).size === ms.length, {
+        params: { ui: "duplicateModel" },
+      }),
+    {
+      label: T("模型", "Models"),
+      item: { title: "{id}", addLabel: T("添加模型", "Add model"), reorder: true },
+    },
+  ),
+});
+
+const ENDPOINTS: ConfigUiHints = {
+  label: T("端点", "Endpoints"),
+  item: {
+    title: "{name}",
+    subtitle: "{baseUrl}",
+    addLabel: T("添加端点", "Add endpoint"),
+    reorder: true,
+  },
+  secrets: [
+    {
+      path: "apiKeys",
+      keyBy: "name",
+      after: "baseUrl",
+      label: T("API 密钥", "API key"),
+      help: T(
+        "留空则请求不带凭据（如内网 vLLM）",
+        "Leave empty for services without a key (e.g. an internal vLLM)",
+      ),
+    },
+  ],
+  presets: [
+    {
+      id: "deepseek",
+      label: T("DeepSeek", "DeepSeek"),
+      values: { name: "deepseek", baseUrl: "https://api.deepseek.com", dialect: "deepseek" },
+    },
+    {
+      id: "qwen",
+      label: T("通义千问（百炼）", "Qwen (Model Studio)"),
+      values: {
+        name: "qwen",
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        dialect: "qwen",
+      },
+    },
+    {
+      id: "ark",
+      label: T("火山方舟", "Volcano Ark"),
+      values: { name: "ark", baseUrl: "https://ark.cn-beijing.volces.com/api/v3", dialect: "ark" },
+    },
+    {
+      id: "generic",
+      label: T("其他兼容服务", "Other compatible service"),
+      values: { dialect: "generic" },
+    },
+  ],
+};
+
+/** The deployment config: endpoints, and their API keys by endpoint name. */
+export const FakeConfigFormSchema = ui(
+  z
+    .object({
+      endpoints: ui(
+        z
+          .array(EndpointSchema)
+          .min(1)
+          .refine((es) => new Set(es.map((e) => e.name)).size === es.length, {
+            params: { ui: "duplicateEndpoint" },
+          }),
+        ENDPOINTS,
+      ),
+      apiKeys: secret(z.record(z.string(), z.string().min(1))).default({}),
+    })
+    .superRefine((cfg, ctx) => {
+      cfg.endpoints.forEach((e, i) => {
+        if (acceptsPdf(e.dialect)) return;
+        e.models.forEach((m, j) => {
+          if (m.documents !== true) return;
+          ctx.addIssue({
+            code: "custom",
+            path: ["endpoints", i, "models", j, "documents"],
+            message: `dialect "${e.dialect}" does not accept PDF documents; documents must be false`,
+            params: { ui: "pdfDialect" },
+          });
+        });
+      });
+      const names = new Set(cfg.endpoints.map((e) => e.name));
+      for (const key of Object.keys(cfg.apiKeys)) {
+        if (names.has(key)) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: ["apiKeys", key],
+          message: `apiKeys["${key}"] does not match any endpoint name`,
+          params: { ui: "unknownKey" },
+        });
+      }
+    }),
+  {
+    messages: {
+      duplicateEndpoint: T("端点名称重复", "Endpoint names must be unique"),
+      duplicateModel: T("模型 ID 重复", "Model ids must be unique within an endpoint"),
+      pdfDialect: T(
+        "该方言不支持 PDF，请取消勾选",
+        "This dialect does not accept PDF; clear the box",
+      ),
+      unknownKey: T("密钥没有对应的端点", "This key has no endpoint"),
+    },
+  },
+);
+
+export default defineExtension({
+  name: "fake-config-form",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [],
+  config: { deployment: FakeConfigFormSchema },
+  setup(ctx) {
+    FakeConfigFormSchema.parse(ctx.config ?? {});
+  },
+});

package/fixtures/extensions/fake-storage-user/src/index.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 
 /**
  * Test fake of an extension that uses `ctx.storage` (`permissions.storage`): tool `note`
- * (model-visible `fake-storage-user__note`) writes the text to `notes/<conversationId>.txt`, which
+ * (model-visible `plugin__fake-storage-user__note`) writes the text to `notes/<conversationId>.txt`, which
  * the kernel prefixes with `plugins/fake-storage-user/<orgId>/`, and returns the stored size; tool
  * `read_note` returns it (or says there is none). Needs an `object-store@1` provider.
  */

package/fixtures/extensions/fake-tools-ui/skills/fake-notes/SKILL.md

@@ -4,4 +4,4 @@ description: Keep a short item list for the conversation with the fake-tools-ui
 ---
 # fake-notes
 
-Call `fake-tools-ui__write` with every item of the list.
+Call `plugin__fake-tools-ui__write` with every item of the list.

package/fixtures/extensions/fake-tools-ui/src/index.ts

@@ -11,7 +11,7 @@ import { z } from "zod";
  * Test fake of a tool + UI extension: the kernel contracts an extension tool, a schema-rendered
  * view, a migration and a full plugin bundle exercise, without the official todo plugin. Like todo
  * it needs no object store (storage is `fake-storage-user`'s).
- * - tool `write` (model-visible `fake-tools-ui__write`, default policy allow): replaces the
+ * - tool `write` (model-visible `plugin__fake-tools-ui__write`, default policy allow): replaces the
  *   conversation's item list in the extension's own table, then invalidates the view `tasks`;
  * - view `tasks` (conversation tab): badge `<done>/<total>` and a checklist;
  * - the plugin also ships the skill `fake-notes` and the connector template `fake-notes`

package/fixtures/extensions/fake-web/.capybara-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-web",
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: a scripted web search and web fetch provider (web-search@1, web-fetch@1)"
+}

package/fixtures/extensions/fake-web/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-web",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: a scripted web search and web fetch provider (web-search@1, web-fetch@1)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-web/src/index.ts

@@ -0,0 +1,22 @@
+import { defineExtension } from "@capybara-hq/plugin-sdk";
+import { FakeWebOrgConfig, makeFakeWeb } from "./web.js";
+
+export { type FakeWebCall, FakeWebOrgConfig, fakeWebProbe, makeFakeWeb } from "./web.js";
+
+/**
+ * Test fake: a scripted web provider (`web-search@1` and `web-fetch@1`; see `makeFakeWeb` for the
+ * scripts). Org config `{ token? }` (secret); `configured()` is true iff the token is set.
+ * `fake-web-2` is the same with its own name, for the org default provider.
+ */
+export default defineExtension({
+  name: "fake-web",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: ["web-search@1", "web-fetch@1"],
+  config: { org: FakeWebOrgConfig },
+  setup(ctx) {
+    const { search, fetch } = makeFakeWeb("fake-web");
+    ctx.provide("web-search@1", search);
+    ctx.provide("web-fetch@1", fetch);
+  },
+});

package/fixtures/extensions/fake-web/src/web.ts

@@ -0,0 +1,183 @@
+import {
+  secret,
+  type WebFetchPage,
+  type WebFetchProvider,
+  WebProviderError,
+  type WebProviderErrorKind,
+  type WebSearchProvider,
+  type WebSearchResult,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+// fake-web/src/web.ts and fake-web-2/src/web.ts are byte-identical (a plugin imports only from its
+// own directory); test/fixtures.test.ts of @capybara-hq/testing keeps them equal.
+
+/**
+ * Org config of the fake web providers: `configured()` is true iff `token` is set (and throws for
+ * the token `throw:configured`).
+ */
+export const FakeWebOrgConfig = z.object({ token: secret(z.string().min(1)).optional() });
+
+/** One provider call, recorded on `globalThis.__fakeWeb` (in-process kernels only). */
+export interface FakeWebCall {
+  provider: string;
+  op: "search" | "fetch";
+  /** The query (search) or the URL (fetch). */
+  input: string;
+}
+
+/** The probe tests read: every call of every fake web provider in this process. */
+export function fakeWebProbe(): { calls: FakeWebCall[] } {
+  const g = globalThis as { __fakeWeb?: { calls: FakeWebCall[] } };
+  g.__fakeWeb ??= { calls: [] };
+  return g.__fakeWeb;
+}
+
+// capybara:allow-module-state a read-only constant list
+const KINDS: readonly WebProviderErrorKind[] = [
+  "not_found",
+  "blocked",
+  "auth",
+  "rate_limited",
+  "unavailable",
+  "invalid",
+];
+
+/** True iff the token is set; the token `throw:configured` makes it throw. */
+const configured = (orgConfig: unknown): boolean => {
+  const token = (orgConfig as { token?: unknown } | null)?.token;
+  if (token === "throw:configured") throw new Error("fake web: configured() failed");
+  return typeof token === "string" && token.length > 0;
+};
+
+/** The script of a fetch: the decoded URL path (and query) after the first `/`. */
+function fetchScript(url: string): string {
+  try {
+    const u = new URL(url);
+    return decodeURIComponent(u.pathname.slice(1)) + u.search;
+  } catch {
+    return "";
+  }
+}
+
+/** Rejects with the signal's reason once it aborts (`hang:`). */
+function hang(signal: AbortSignal): Promise<never> {
+  return new Promise((_, reject) => {
+    if (signal.aborted) reject(signal.reason);
+    else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+
+/** The scripted failures shared by search and fetch; returns normally for other scripts. */
+async function scriptedFailure(name: string, script: string, signal: AbortSignal): Promise<void> {
+  if (script.startsWith("error:")) {
+    const kind = script.slice("error:".length).split(/[\s/?]/)[0] as WebProviderErrorKind;
+    if (!KINDS.includes(kind)) throw new Error(`${name}: unknown scripted error kind ${kind}`);
+    throw new WebProviderError(`${name}: scripted ${kind} failure`, { kind });
+  }
+  if (script.startsWith("throw:")) {
+    throw new Error(`${name} internal failure: ${script.slice("throw:".length)}`);
+  }
+  if (script.startsWith("hang:")) await hang(signal);
+}
+
+/**
+ * The two providers of a fake web extension named `name`. Behavior is scripted by a prefix of the
+ * search `query`, or of the fetched URL's path after the first `/` (e.g.
+ * `https://example.com/redirect:https://other.com/x`):
+ * - `error:<kind>`: throws `WebProviderError` of that kind;
+ * - `throw:<text>`: throws a plain `Error` whose message names the provider and carries `<text>`;
+ * - `hang:`: waits until the signal aborts, then rejects with its reason;
+ * - `redirect:<url>` (fetch): the page's `finalUrl` is `<url>`;
+ * - `redirect-long:<n>` (fetch): the page's `finalUrl` is `https://example.com/` followed by `n`
+ *   characters;
+ * - `junk:` (search): unusable results (relative URL, `javascript:`, `ftp:`, empty title) plus one
+ *   usable result and a second result with its URL; `junk:all`: only the four unusable ones;
+ * - `idn:` (search): one result on the IDN host `bücher.example` (its URL parses to the punycode
+ *   host `xn--bcher-kva.example`) and one on example.org;
+ * - `empty:`: no results (search) / an empty `markdown` (fetch);
+ * - `big:<n>`: `n` results, ignoring `maxResults` (search) / `n` characters of markdown (fetch).
+ * Anything else: three results on docs.example.com, example.org and www.example.net (search) or
+ * a short page (fetch). Every title, snippet and page names the provider.
+ */
+export function makeFakeWeb(name: string): { search: WebSearchProvider; fetch: WebFetchProvider } {
+  const search: WebSearchProvider = {
+    configured,
+    async search({ query, signal }) {
+      fakeWebProbe().calls.push({ provider: name, op: "search", input: query });
+      await scriptedFailure(name, query, signal);
+      if (query.startsWith("empty:")) return { results: [] };
+      if (query.startsWith("idn:")) {
+        return {
+          results: [
+            { title: `${name} idn`, url: `https://bücher.example/${name}/1` },
+            { title: `${name} other`, url: `https://example.org/${name}/2` },
+          ],
+        };
+      }
+      if (query.startsWith("junk:")) {
+        const bad: WebSearchResult[] = [
+          { title: `${name} relative`, url: "/relative/path" },
+          { title: `${name} script`, url: "javascript:alert(1)" },
+          { title: `${name} ftp`, url: "ftp://example.com/file" },
+          { title: "", url: "https://example.com/untitled" },
+        ];
+        if (query.startsWith("junk:all")) return { results: bad };
+        return {
+          results: [
+            ...bad,
+            { title: `${name} first`, url: "https://example.com/dup" },
+            { title: `${name} again`, url: "https://example.com/dup" },
+          ],
+        };
+      }
+      if (query.startsWith("big:")) {
+        const n = Number.parseInt(query.slice("big:".length), 10) || 0;
+        return {
+          results: Array.from({ length: n }, (_, i) => ({
+            title: `${name} result ${i + 1}`,
+            url: `https://example.com/${name}/${i + 1}`,
+            snippet: `${name} snippet ${i + 1} for ${query}`,
+          })),
+        };
+      }
+      const hosts = ["docs.example.com", "example.org", "www.example.net"];
+      const results: WebSearchResult[] = hosts.map((h, i) => ({
+        title: `${name} result ${i + 1}`,
+        url: `https://${h}/${name}/${i + 1}`,
+        snippet: `${name} snippet ${i + 1} for ${query}`,
+        publishedAt: "2026-11-01",
+      }));
+      return { results };
+    },
+  };
+  const fetch: WebFetchProvider = {
+    configured,
+    async fetch({ url, signal }): Promise<WebFetchPage> {
+      fakeWebProbe().calls.push({ provider: name, op: "fetch", input: url });
+      const script = fetchScript(url);
+      await scriptedFailure(name, script, signal);
+      if (script.startsWith("redirect-long:")) {
+        const n = Number.parseInt(script.slice("redirect-long:".length), 10) || 0;
+        const finalUrl = `https://example.com/${"a".repeat(n)}`;
+        return { finalUrl, title: `${name} redirect`, markdown: "Moved." };
+      }
+      if (script.startsWith("redirect:")) {
+        const finalUrl = script.slice("redirect:".length);
+        return { finalUrl, title: `${name} redirect`, markdown: `Moved to ${finalUrl}.` };
+      }
+      if (script.startsWith("empty:")) return { finalUrl: url, markdown: "" };
+      if (script.startsWith("big:")) {
+        const n = Number.parseInt(script.slice("big:".length), 10) || 0;
+        return { finalUrl: url, title: `${name} big page`, markdown: "x".repeat(n) };
+      }
+      return {
+        finalUrl: url,
+        title: `${name} page`,
+        markdown: `# Page from ${name}\n\nFetched ${url} with ${name}.`,
+        contentType: "text/html",
+      };
+    },
+  };
+  return { search, fetch };
+}

package/fixtures/extensions/fake-web-2/.capybara-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-web-2",
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: a scripted web search and web fetch provider (web-search@1, web-fetch@1)"
+}

package/fixtures/extensions/fake-web-2/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-web-2",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: a scripted web search and web fetch provider (web-search@1, web-fetch@1)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-web-2/src/index.ts

@@ -0,0 +1,16 @@
+import { defineExtension } from "@capybara-hq/plugin-sdk";
+import { FakeWebOrgConfig, makeFakeWeb } from "./web.js";
+
+/** Test fake: `fake-web` under another name (a second provider of `web-search@1` / `web-fetch@1`). */
+export default defineExtension({
+  name: "fake-web-2",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: ["web-search@1", "web-fetch@1"],
+  config: { org: FakeWebOrgConfig },
+  setup(ctx) {
+    const { search, fetch } = makeFakeWeb("fake-web-2");
+    ctx.provide("web-search@1", search);
+    ctx.provide("web-fetch@1", fetch);
+  },
+});

package/fixtures/extensions/fake-web-2/src/web.ts

@@ -0,0 +1,183 @@
+import {
+  secret,
+  type WebFetchPage,
+  type WebFetchProvider,
+  WebProviderError,
+  type WebProviderErrorKind,
+  type WebSearchProvider,
+  type WebSearchResult,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+// fake-web/src/web.ts and fake-web-2/src/web.ts are byte-identical (a plugin imports only from its
+// own directory); test/fixtures.test.ts of @capybara-hq/testing keeps them equal.
+
+/**
+ * Org config of the fake web providers: `configured()` is true iff `token` is set (and throws for
+ * the token `throw:configured`).
+ */
+export const FakeWebOrgConfig = z.object({ token: secret(z.string().min(1)).optional() });
+
+/** One provider call, recorded on `globalThis.__fakeWeb` (in-process kernels only). */
+export interface FakeWebCall {
+  provider: string;
+  op: "search" | "fetch";
+  /** The query (search) or the URL (fetch). */
+  input: string;
+}
+
+/** The probe tests read: every call of every fake web provider in this process. */
+export function fakeWebProbe(): { calls: FakeWebCall[] } {
+  const g = globalThis as { __fakeWeb?: { calls: FakeWebCall[] } };
+  g.__fakeWeb ??= { calls: [] };
+  return g.__fakeWeb;
+}
+
+// capybara:allow-module-state a read-only constant list
+const KINDS: readonly WebProviderErrorKind[] = [
+  "not_found",
+  "blocked",
+  "auth",
+  "rate_limited",
+  "unavailable",
+  "invalid",
+];
+
+/** True iff the token is set; the token `throw:configured` makes it throw. */
+const configured = (orgConfig: unknown): boolean => {
+  const token = (orgConfig as { token?: unknown } | null)?.token;
+  if (token === "throw:configured") throw new Error("fake web: configured() failed");
+  return typeof token === "string" && token.length > 0;
+};
+
+/** The script of a fetch: the decoded URL path (and query) after the first `/`. */
+function fetchScript(url: string): string {
+  try {
+    const u = new URL(url);
+    return decodeURIComponent(u.pathname.slice(1)) + u.search;
+  } catch {
+    return "";
+  }
+}
+
+/** Rejects with the signal's reason once it aborts (`hang:`). */
+function hang(signal: AbortSignal): Promise<never> {
+  return new Promise((_, reject) => {
+    if (signal.aborted) reject(signal.reason);
+    else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+
+/** The scripted failures shared by search and fetch; returns normally for other scripts. */
+async function scriptedFailure(name: string, script: string, signal: AbortSignal): Promise<void> {
+  if (script.startsWith("error:")) {
+    const kind = script.slice("error:".length).split(/[\s/?]/)[0] as WebProviderErrorKind;
+    if (!KINDS.includes(kind)) throw new Error(`${name}: unknown scripted error kind ${kind}`);
+    throw new WebProviderError(`${name}: scripted ${kind} failure`, { kind });
+  }
+  if (script.startsWith("throw:")) {
+    throw new Error(`${name} internal failure: ${script.slice("throw:".length)}`);
+  }
+  if (script.startsWith("hang:")) await hang(signal);
+}
+
+/**
+ * The two providers of a fake web extension named `name`. Behavior is scripted by a prefix of the
+ * search `query`, or of the fetched URL's path after the first `/` (e.g.
+ * `https://example.com/redirect:https://other.com/x`):
+ * - `error:<kind>`: throws `WebProviderError` of that kind;
+ * - `throw:<text>`: throws a plain `Error` whose message names the provider and carries `<text>`;
+ * - `hang:`: waits until the signal aborts, then rejects with its reason;
+ * - `redirect:<url>` (fetch): the page's `finalUrl` is `<url>`;
+ * - `redirect-long:<n>` (fetch): the page's `finalUrl` is `https://example.com/` followed by `n`
+ *   characters;
+ * - `junk:` (search): unusable results (relative URL, `javascript:`, `ftp:`, empty title) plus one
+ *   usable result and a second result with its URL; `junk:all`: only the four unusable ones;
+ * - `idn:` (search): one result on the IDN host `bücher.example` (its URL parses to the punycode
+ *   host `xn--bcher-kva.example`) and one on example.org;
+ * - `empty:`: no results (search) / an empty `markdown` (fetch);
+ * - `big:<n>`: `n` results, ignoring `maxResults` (search) / `n` characters of markdown (fetch).
+ * Anything else: three results on docs.example.com, example.org and www.example.net (search) or
+ * a short page (fetch). Every title, snippet and page names the provider.
+ */
+export function makeFakeWeb(name: string): { search: WebSearchProvider; fetch: WebFetchProvider } {
+  const search: WebSearchProvider = {
+    configured,
+    async search({ query, signal }) {
+      fakeWebProbe().calls.push({ provider: name, op: "search", input: query });
+      await scriptedFailure(name, query, signal);
+      if (query.startsWith("empty:")) return { results: [] };
+      if (query.startsWith("idn:")) {
+        return {
+          results: [
+            { title: `${name} idn`, url: `https://bücher.example/${name}/1` },
+            { title: `${name} other`, url: `https://example.org/${name}/2` },
+          ],
+        };
+      }
+      if (query.startsWith("junk:")) {
+        const bad: WebSearchResult[] = [
+          { title: `${name} relative`, url: "/relative/path" },
+          { title: `${name} script`, url: "javascript:alert(1)" },
+          { title: `${name} ftp`, url: "ftp://example.com/file" },
+          { title: "", url: "https://example.com/untitled" },
+        ];
+        if (query.startsWith("junk:all")) return { results: bad };
+        return {
+          results: [
+            ...bad,
+            { title: `${name} first`, url: "https://example.com/dup" },
+            { title: `${name} again`, url: "https://example.com/dup" },
+          ],
+        };
+      }
+      if (query.startsWith("big:")) {
+        const n = Number.parseInt(query.slice("big:".length), 10) || 0;
+        return {
+          results: Array.from({ length: n }, (_, i) => ({
+            title: `${name} result ${i + 1}`,
+            url: `https://example.com/${name}/${i + 1}`,
+            snippet: `${name} snippet ${i + 1} for ${query}`,
+          })),
+        };
+      }
+      const hosts = ["docs.example.com", "example.org", "www.example.net"];
+      const results: WebSearchResult[] = hosts.map((h, i) => ({
+        title: `${name} result ${i + 1}`,
+        url: `https://${h}/${name}/${i + 1}`,
+        snippet: `${name} snippet ${i + 1} for ${query}`,
+        publishedAt: "2026-11-01",
+      }));
+      return { results };
+    },
+  };
+  const fetch: WebFetchProvider = {
+    configured,
+    async fetch({ url, signal }): Promise<WebFetchPage> {
+      fakeWebProbe().calls.push({ provider: name, op: "fetch", input: url });
+      const script = fetchScript(url);
+      await scriptedFailure(name, script, signal);
+      if (script.startsWith("redirect-long:")) {
+        const n = Number.parseInt(script.slice("redirect-long:".length), 10) || 0;
+        const finalUrl = `https://example.com/${"a".repeat(n)}`;
+        return { finalUrl, title: `${name} redirect`, markdown: "Moved." };
+      }
+      if (script.startsWith("redirect:")) {
+        const finalUrl = script.slice("redirect:".length);
+        return { finalUrl, title: `${name} redirect`, markdown: `Moved to ${finalUrl}.` };
+      }
+      if (script.startsWith("empty:")) return { finalUrl: url, markdown: "" };
+      if (script.startsWith("big:")) {
+        const n = Number.parseInt(script.slice("big:".length), 10) || 0;
+        return { finalUrl: url, title: `${name} big page`, markdown: "x".repeat(n) };
+      }
+      return {
+        finalUrl: url,
+        title: `${name} page`,
+        markdown: `# Page from ${name}\n\nFetched ${url} with ${name}.`,
+        contentType: "text/html",
+      };
+    },
+  };
+  return { search, fetch };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/testing",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.5",
   "description": "Test helpers for Capybara: test containers, dual-replica harness and fake third-party servers",
   "license": "Apache-2.0",
   "repository": {
@@ -47,17 +47,17 @@
     "tsx": "^4.23.15",
     "ws": "^8.22.0",
     "zod": "^4.6.7",
-    "@capybara-hq/kernel": "^0.1.0-rc.2"
+    "@capybara-hq/kernel": "^0.1.0-rc.4"
   },
   "devDependencies": {
     "@types/pg": "^8.23.1",
     "@types/ws": "^8.18.2",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2"
   },
   "peerDependencies": {
     "vitest": "^5.0.5",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
-    "@capybara-hq/plugin-tools": "^0.1.0-rc.2"
+    "@capybara-hq/plugin-tools": "^0.1.0-rc.4",
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2"
   },
   "peerDependenciesMeta": {
     "@capybara-hq/plugin-tools": {