@capybara-hq/testing 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/dual-replica.d.ts

@@ -8,7 +8,10 @@ export interface DualReplicaOptions {
      * this package is installed from npm; nothing needs to be set in `NODE_OPTIONS`.
      */
     extensions: string[];
-    /** 解析裸包名插件的目录，默认调用方的 `process.cwd()`（与 `createKernel` 的 resolveFrom 同义）。 */
+    /**
+     * Where extensions named by package resolve from; default the caller's `process.cwd()` (the
+     * `resolveFrom` of `createKernelApp`).
+     */
     resolveFrom?: string;
     /** 部署级插件配置，按插件名索引。 */
     extensionConfig?: Record<string, unknown>;

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/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

@@ -3,11 +3,11 @@
  * package and the SDK: the database helpers and types, and model-visible texts, queue names and
  * keys the kernel owns (assert on them instead of copying their values).
  */
-export { type ConversationEvent, createDb, gatewayReplicasKey, type Kernel, type KernelConfig, type KernelDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
+export { type ConversationEvent, createDb, gatewayReplicasKey, type KernelConfig, type KernelSchemaDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
 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";
@@ -19,7 +19,7 @@ export { type FakeOAuthClient, type FakeOAuthServer, type FakeOAuthServerOptions
 export { defaultFakeOpenApiSpec, type FakeOpenApiRequest, type FakeOpenApiServer, type FakeOpenApiServerOptions, type FakePet, startFakeOpenApiServer, } from "./fake-openapi-server.js";
 export { type FakeSlackAck, type FakeSlackCall, type FakeSlackFailure, type FakeSlackMessage, type FakeSlackOptions, type FakeSlackServer, type FakeSlackUser, findSlackButton, signSlackWebhook, slackBlockAction, slackDmEvent, slackEventCallback, slackInteractiveForm, slackMentionEvent, startFakeSlack, } from "./fake-slack.js";
 export { FAKE_EXTENSIONS, type FakeExtensionName, fakeExtensionDir, fakeExtensionEntry, type PackedFixture, packFixture, } from "./fixtures.js";
-export { cardRecorded, cookieRequest, createAgent, createConversation, createLocalAccount, createOrg, eventsOf, joinOrg, type KernelRequest, type KernelRequestOptions, type KernelResponse, login, pidOwningLocalPort, postMessage, sleep, startTestKernel, TEST_PASSWORD, testKernelConfig, truncateTables, waitFor, waitForEvent, waitForTerminal, } from "./kernel-helpers.js";
+export { cardRecorded, cookieRequest, createAgent, createConversation, createLocalAccount, createOrg, eventsOf, joinOrg, type KernelApp, type KernelRequest, type KernelRequestOptions, type KernelResponse, login, pidOwningLocalPort, postMessage, sleep, startTestKernel, TEST_PASSWORD, type TestKernel, testKernelConfig, truncateTables, waitFor, waitForEvent, waitForTerminal, } from "./kernel-helpers.js";
 export { isPngBase64, pdfBase64, pdfSampleWord, redPngBase64, solidPngBase64, } from "./media-samples.js";
 export { type ConformanceTarget, checkDeclaredParameters, describeModelProviderConformance, MEDIA_SAMPLES, thinkingReplayParams, } from "./model-conformance.js";
 export { openSse, type SseClient, type SseMessage } from "./sse.js";

package/dist/kernel-helpers.d.ts

@@ -1,4 +1,4 @@
-import { type ConversationEvent, type Kernel, type KernelConfig, type KernelDb, type KernelHttp, type LogLevel } from "@capybara-hq/kernel";
+import { type ConversationEvent, type KernelConfig, type KernelHttp, type KernelSchemaDb, type LogLevel, startKernelApp } from "@capybara-hq/kernel";
 import { type Kysely } from "kysely";
 /**
  * Helpers for extension tests that run a real kernel: in process (`startTestKernel` +
@@ -33,11 +33,32 @@ export declare function testKernelConfig(urls: {
  * it before creating anything.
  */
 export declare function assertOfflineOfficialMarketplace(config: KernelConfig, allow?: boolean): void;
+/** The kernel's Nest application (what `createKernelApp` / `startKernelApp` return). */
+export type KernelApp = Awaited<ReturnType<typeof startKernelApp>>;
+/** A running in-process kernel ({@link startTestKernel}). */
+export interface TestKernel {
+    /**
+     * The kernel's Nest application. Core's own tests reach a kernel service with `app.get(Class)`;
+     * a plugin test cannot import kernel classes (`plugin-test-imports`), so it drives the kernel
+     * through `http` and the helpers of this package.
+     */
+    readonly app: KernelApp;
+    /** In-process HTTP: `inject` requests, list the routes. */
+    readonly http: KernelHttp;
+    /**
+     * The port the kernel listens on (an ephemeral one with `http.port: 0`); undefined after
+     * `close()`.
+     */
+    readonly port: number | undefined;
+    /** Stops the kernel (the stop phases within their budgets, then Redis and the pool); idempotent. */
+    close(): Promise<void>;
+}
 /**
- * Creates and starts an in-process kernel. Logs are discarded unless `log` is given (JSON lines at
- * `log.level` and above go to `log.write`, e.g. to assert a secret never reaches the log).
- * Extensions named by package resolve from `resolveFrom` (default `process.cwd()`). Stop it with
- * `stop()`.
+ * Creates and starts an in-process kernel (`startKernelApp`; it listens on `config.http.port`).
+ * The kernel gets no process-wide signal handlers: a test stops it with `close()`. Logs are
+ * discarded unless `log` is given (JSON lines at `log.level` and above go to `log.write`, e.g. to
+ * assert a secret never reaches the log). Extensions named by package resolve from `resolveFrom`
+ * (default `process.cwd()`).
  */
 export declare function startTestKernel(config: KernelConfig, opts?: {
     resolveFrom?: string;
@@ -47,7 +68,7 @@ export declare function startTestKernel(config: KernelConfig, opts?: {
     };
     /** Only for a test about the real default: allow the official marketplace at its real URL. */
     allowOfficialMarketplace?: boolean;
-}): Promise<Kernel>;
+}): Promise<TestKernel>;
 /** Options of a {@link KernelRequest} call (`http.inject` options; `csrf: false` drops the header). */
 export type KernelRequestOptions = Parameters<KernelHttp["inject"]>[0] & {
     csrf?: boolean;
@@ -61,16 +82,16 @@ export type KernelRequest = (opts: KernelRequestOptions) => Promise<KernelRespon
 /** A request function with its own cookie jar (signed out until a response sets cookies). */
 export declare function cookieRequest(http: KernelHttp): KernelRequest;
 /** Creates a local account with {@link TEST_PASSWORD}; returns its id. */
-export declare function createLocalAccount(db: KernelDb, login: string, displayName?: string): Promise<string>;
+export declare function createLocalAccount(db: KernelSchemaDb, login: string, displayName?: string): Promise<string>;
 /** Signs in over HTTP and returns the user's request function. */
-export declare function login(k: Pick<Kernel, "http">, name: string, password?: string): Promise<KernelRequest>;
+export declare function login(k: Pick<TestKernel, "http">, name: string, password?: string): Promise<KernelRequest>;
 /** Creates an org as `req`'s user (who becomes its owner); returns its id. */
 export declare function createOrg(req: KernelRequest, name?: string): Promise<string>;
 /**
  * A new account joins the org through an invitation (created by `owner`, accepted with `login`
  * and {@link TEST_PASSWORD}); returns the account id and its signed-in request function.
  */
-export declare function joinOrg(k: Pick<Kernel, "http">, owner: KernelRequest, orgId: string, name: string, role?: "member" | "admin"): Promise<{
+export declare function joinOrg(k: Pick<TestKernel, "http">, owner: KernelRequest, orgId: string, name: string, role?: "member" | "admin"): Promise<{
     accountId: string;
     req: KernelRequest;
 }>;
@@ -90,17 +111,17 @@ export declare function createConversation(req: KernelRequest, orgId: string, ag
 /** Posts a user message; returns its event seq. */
 export declare function postMessage(req: KernelRequest, orgId: string, conversationId: string, text: string): Promise<number>;
 /** Every event of a conversation, in seq order (read from the database). */
-export declare function eventsOf(db: KernelDb, conversationId: string): Promise<ConversationEvent[]>;
+export declare function eventsOf(db: KernelSchemaDb, conversationId: string): Promise<ConversationEvent[]>;
 /** Waits for the first event matching `pred` and returns it. */
-export declare function waitForEvent(db: KernelDb, conversationId: string, pred: (e: ConversationEvent) => boolean, timeoutMs?: number, label?: string): Promise<ConversationEvent>;
+export declare function waitForEvent(db: KernelSchemaDb, conversationId: string, pred: (e: ConversationEvent) => boolean, timeoutMs?: number, label?: string): Promise<ConversationEvent>;
 /** Waits for the conversation's `n`-th terminal event (run_finished / run_failed / run_aborted). */
-export declare function waitForTerminal(db: KernelDb, conversationId: string, n?: number, timeoutMs?: number): Promise<ConversationEvent[]>;
+export declare function waitForTerminal(db: KernelSchemaDb, conversationId: string, n?: number, timeoutMs?: number): Promise<ConversationEvent[]>;
 /**
  * Waits until an IM card's message id is recorded (`channel_card_messages`). The kernel writes it in
  * the transaction after the card is sent; a click before that is treated as "not a card of this
  * conversation", so a test waits for this before it clicks, not only for the platform to get it.
  */
-export declare function cardRecorded(db: KernelDb, card: {
+export declare function cardRecorded(db: KernelSchemaDb, card: {
     messageId: string;
 } | {
     kind: "approval" | "question";

package/dist/kernel-helpers.js

@@ -1,7 +1,8 @@
 import { execFile } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { readdir, readFile, readlink } from "node:fs/promises";
 import { promisify } from "node:util";
-import { AccountsService, createKernel, createLogger, KernelConfigSchema, MARKETPLACE_OFFICIAL_URL_DEFAULT, } from "@capybara-hq/kernel";
+import { AccountsModule, AccountsService, closeKernelApp, createLogger, KernelConfigSchema, kernelAppHttp, kernelAppPort, MARKETPLACE_OFFICIAL_URL_DEFAULT, openKernelCliOverPool, startKernelApp, } from "@capybara-hq/kernel";
 import { sql } from "kysely";
 /**
  * Helpers for extension tests that run a real kernel: in process (`startTestKernel` +
@@ -60,20 +61,33 @@ export function assertOfflineOfficialMarketplace(config, allow = false) {
         "marketplaces.official.url at a fake, or build the config with testKernelConfig");
 }
 /**
- * Creates and starts an in-process kernel. Logs are discarded unless `log` is given (JSON lines at
- * `log.level` and above go to `log.write`, e.g. to assert a secret never reaches the log).
- * Extensions named by package resolve from `resolveFrom` (default `process.cwd()`). Stop it with
- * `stop()`.
+ * Creates and starts an in-process kernel (`startKernelApp`; it listens on `config.http.port`).
+ * The kernel gets no process-wide signal handlers: a test stops it with `close()`. Logs are
+ * discarded unless `log` is given (JSON lines at `log.level` and above go to `log.write`, e.g. to
+ * assert a secret never reaches the log). Extensions named by package resolve from `resolveFrom`
+ * (default `process.cwd()`).
  */
 export async function startTestKernel(config, opts = {}) {
     assertOfflineOfficialMarketplace(config, opts.allowOfficialMarketplace);
-    const k = await createKernel(config, {
+    const app = await startKernelApp(config, {
         env: {},
         logger: createLogger(opts.log?.level ?? "error", { write: opts.log?.write ?? (() => { }) }),
         ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
-    });
-    await k.start();
-    return k;
+    }, 
+    // A signal source of its own: a test kernel never handles the process's SIGTERM / SIGINT
+    { signals: new EventEmitter() });
+    return testKernelOf(app);
+}
+/** The {@link TestKernel} view of a started kernel application. */
+function testKernelOf(app) {
+    return {
+        app,
+        http: kernelAppHttp(app),
+        get port() {
+            return kernelAppPort(app);
+        },
+        close: () => closeKernelApp(app),
+    };
 }
 /** A request function with its own cookie jar (signed out until a response sets cookies). */
 export function cookieRequest(http) {
@@ -110,7 +124,21 @@ function expectStatus(res, status, what) {
 }
 /** Creates a local account with {@link TEST_PASSWORD}; returns its id. */
 export async function createLocalAccount(db, login, displayName = login) {
-    return (await new AccountsService(db).createLocal({ login, password: TEST_PASSWORD, displayName })).id;
+    // the accounts module over the caller's Kysely; closing the context leaves it open
+    const app = await openKernelCliOverPool(db, {
+        logger: createLogger("error"),
+        modules: [AccountsModule],
+    });
+    try {
+        return (await app.get(AccountsService).createLocal({
+            login,
+            password: TEST_PASSWORD,
+            displayName,
+        })).id;
+    }
+    finally {
+        await app.close();
+    }
 }
 /** Signs in over HTTP and returns the user's request function. */
 export async function login(k, name, password = TEST_PASSWORD) {

package/dist/replica-runner.js

@@ -1,5 +1,10 @@
-import { createKernel, KernelConfigSchema } from "@capybara-hq/kernel";
-let kernel;
+import { EventEmitter } from "node:events";
+import { KernelConfigSchema, kernelAppPort, startKernelApp } from "@capybara-hq/kernel";
+/**
+ * The replica's signal source: the stop message (or the parent going away) raises SIGTERM on it, so
+ * the kernel stops through the same shutdown path as `capybara start` — also while it is starting.
+ */
+const signals = new EventEmitter();
 const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** 深合并：普通对象逐键递归，其余（含数组）由 `over` 整体替换。 */
 function deepMerge(base, over) {
@@ -27,22 +32,25 @@ async function startKernel(c) {
         log: { level: "error" },
     };
     const config = KernelConfigSchema.parse(deepMerge(base, c.overrides));
-    kernel = await createKernel(config, {
+    const app = await startKernelApp(config, {
         resolveFrom: c.resolveFrom,
         ...(c.bootstrap !== undefined && { bootstrap: c.bootstrap }),
         ...(c.bootstrapManifest !== undefined && { bootstrapManifest: c.bootstrapManifest }),
-    });
-    await kernel.start();
-    process.send?.({ type: "ready", port: kernel.port });
+    }, { signals, exit: (code) => process.exit(code) });
+    process.send?.({ type: "ready", port: kernelAppPort(app) });
 }
 let exiting = false;
-/** 停内核后退出；内核停机卡住时 10 秒后强制退出。 */
+/** Stops the kernel, then exits; a stop stuck for 10 s exits with 1. */
 function shutdown() {
     if (exiting)
         return;
     exiting = true;
     setTimeout(() => process.exit(1), 10_000).unref();
-    (kernel?.stop() ?? Promise.resolve()).finally(() => process.exit(0));
+    // No kernel handlers yet (still building) or any more (the start failed): nothing to stop
+    if (signals.listenerCount("SIGTERM") === 0)
+        process.exit(0);
+    else
+        signals.emit("SIGTERM", "SIGTERM");
 }
 // 父进程（含被 SIGKILL）消失后 IPC 通道断开，副本自行退出，不留孤儿
 process.on("disconnect", shutdown);

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.2",
+  "version": "0.1.0-rc.4",
   "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.1"
+    "@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-tools": "^0.1.0-rc.2",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.2",
+    "@capybara-hq/plugin-tools": "^0.1.0-rc.4"
   },
   "peerDependenciesMeta": {
     "@capybara-hq/plugin-tools": {