@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.1

package/dist/fixtures.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Fake extensions, one or more per extension point, that core tests load instead of the official
+ * plugins (they live in `fixtures/extensions/<name>` of this package, in the pack layout:
+ * `package.json`, `.capybara-plugin/plugin.json`, `src/index.ts`, plus `migrations/`, `skills/`,
+ * `connectors/` where they have them). Each imports only `@capybara-hq/plugin-sdk`, zod and
+ * third-party packages this package depends on.
+ *
+ * | name | provides / covers |
+ * |---|---|
+ * | `fake-connector` | `connector@1` kind `fake`: an MCP client for `startFakeMcpServer` (auth, one 401 retry, connectorData routes from `_meta["fake/route"]`, onToolsChanged, onElicit incl. `-32042`, resources, prompts, inspect); endpoint `{ url, headers?, notesText? }`; template `fake-demo`; deployment config `allowInsecureLoopback` (default true), `inspectAuth` (`bearer` / `api_key`), `kind` (default `fake`; `mcp` lets clients that know only the official kinds drive it) |
+ * | `fake-openapi` | `connector@1` kind `openapi` (the web wizard's OpenAPI flow): reads a small JSON document (`securitySchemes` as auth hints, `operations` as tools) from the endpoint's `specUrl`, calls operations over HTTP with the injected auth; endpoint `{ specUrl, baseUrl?, operations? }`; deployment config `allowInsecureLoopback` (default true) |
+ * | `fake-object-store` | `object-store@1` on the `startTestS3()` container (deployment config as `TestS3` gives it; POST-policy presign) |
+ * | `fake-tools-ui` | tool `write`, view `tasks`, a migration, skill `fake-notes`, template `fake-notes` (for fake-connector); no storage |
+ * | `fake-storage-user` | tools `note` / `read_note` through `ctx.storage` (`permissions.storage`) |
+ * | `fake-embed` | embeds `panel` (page) and `panel-conv` (conversation), static `/ui/panel.js`, token-checked routes, SSE over `ctx.bus` |
+ * | `fake-bootstrap-a` | `model-provider@2` with a required secret `apiKey` (pending configuration until set) |
+ * | `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 |
+ */
+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"];
+/** 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. */
+export declare function fakeExtensionDir(name: FakeExtensionName): string;
+/**
+ * The extension entry `src/index.ts` of a fake, for kernel configs that load extensions by path
+ * (`extensions: [fakeExtensionEntry("fake-connector")]`). `createDualReplicaHarness` loads it in
+ * its replicas wherever this package is installed (they run under tsx for TypeScript entries). An
+ * in-process kernel under vitest loads it when vitest transforms the kernel (in this repository, or
+ * with the core packages inlined: `server.deps.inline`); elsewhere, pack the fake with
+ * {@link packFixture} (Node does not strip types under node_modules).
+ */
+export declare function fakeExtensionEntry(name: FakeExtensionName): string;
+/** The result of {@link packFixture}. */
+export interface PackedFixture {
+    /** Path of the tgz in `outDir`. */
+    file: string;
+    bytes: Uint8Array;
+    /** Hex sha256 of the tgz. */
+    sha256: string;
+}
+/**
+ * Packs a fake extension into a plugin tgz with the plugin packer (the same bytes `pnpm
+ * pack-plugin` would produce: single-file ESM bundle, static manifest in plugin.json, migrations,
+ * skills and templates), writes it to `outDir` and returns its path, bytes and sha256. Packing
+ * leaves no files in the fixture directory.
+ */
+export declare function packFixture(name: FakeExtensionName, outDir: string): Promise<PackedFixture>;

package/dist/fixtures.js

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Fake extensions, one or more per extension point, that core tests load instead of the official
+ * plugins (they live in `fixtures/extensions/<name>` of this package, in the pack layout:
+ * `package.json`, `.capybara-plugin/plugin.json`, `src/index.ts`, plus `migrations/`, `skills/`,
+ * `connectors/` where they have them). Each imports only `@capybara-hq/plugin-sdk`, zod and
+ * third-party packages this package depends on.
+ *
+ * | name | provides / covers |
+ * |---|---|
+ * | `fake-connector` | `connector@1` kind `fake`: an MCP client for `startFakeMcpServer` (auth, one 401 retry, connectorData routes from `_meta["fake/route"]`, onToolsChanged, onElicit incl. `-32042`, resources, prompts, inspect); endpoint `{ url, headers?, notesText? }`; template `fake-demo`; deployment config `allowInsecureLoopback` (default true), `inspectAuth` (`bearer` / `api_key`), `kind` (default `fake`; `mcp` lets clients that know only the official kinds drive it) |
+ * | `fake-openapi` | `connector@1` kind `openapi` (the web wizard's OpenAPI flow): reads a small JSON document (`securitySchemes` as auth hints, `operations` as tools) from the endpoint's `specUrl`, calls operations over HTTP with the injected auth; endpoint `{ specUrl, baseUrl?, operations? }`; deployment config `allowInsecureLoopback` (default true) |
+ * | `fake-object-store` | `object-store@1` on the `startTestS3()` container (deployment config as `TestS3` gives it; POST-policy presign) |
+ * | `fake-tools-ui` | tool `write`, view `tasks`, a migration, skill `fake-notes`, template `fake-notes` (for fake-connector); no storage |
+ * | `fake-storage-user` | tools `note` / `read_note` through `ctx.storage` (`permissions.storage`) |
+ * | `fake-embed` | embeds `panel` (page) and `panel-conv` (conversation), static `/ui/panel.js`, token-checked routes, SSE over `ctx.bus` |
+ * | `fake-bootstrap-a` | `model-provider@2` with a required secret `apiKey` (pending configuration until set) |
+ * | `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 |
+ */
+export const FAKE_EXTENSIONS = [
+    "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",
+];
+/** `fixtures/extensions/` of this package (same path from `src/` and from `dist/`). */
+const FIXTURES_DIR = fileURLToPath(new URL("../fixtures/extensions/", import.meta.url));
+/** The plugin directory of a fake (pack layout), for `packFixture` or a packer of your own. */
+export function fakeExtensionDir(name) {
+    return join(FIXTURES_DIR, name);
+}
+/**
+ * The extension entry `src/index.ts` of a fake, for kernel configs that load extensions by path
+ * (`extensions: [fakeExtensionEntry("fake-connector")]`). `createDualReplicaHarness` loads it in
+ * its replicas wherever this package is installed (they run under tsx for TypeScript entries). An
+ * in-process kernel under vitest loads it when vitest transforms the kernel (in this repository, or
+ * with the core packages inlined: `server.deps.inline`); elsewhere, pack the fake with
+ * {@link packFixture} (Node does not strip types under node_modules).
+ */
+export function fakeExtensionEntry(name) {
+    return join(FIXTURES_DIR, name, "src/index.ts");
+}
+/**
+ * The plugin packer of `@capybara-hq/plugin-tools` (an optional peer dependency of this package:
+ * install it to use {@link packFixture}), imported lazily so only callers of {@link packFixture}
+ * need it. It is a peer, not a dependency, because plugin-tools depends on the kernel, which tests
+ * with this package; the specifier is a variable so TypeScript does not pull the packer into this
+ * package's build.
+ */
+const PACKER_MODULE = "@capybara-hq/plugin-tools/pack";
+async function packer() {
+    let mod;
+    try {
+        mod = (await import(PACKER_MODULE));
+    }
+    catch (e) {
+        const err = e;
+        const missing = err.code === "ERR_MODULE_NOT_FOUND" &&
+            String(err.message).includes("@capybara-hq/plugin-tools");
+        if (!missing)
+            throw e;
+        throw new Error("packFixture needs the plugin packer: install @capybara-hq/plugin-tools (a devDependency)");
+    }
+    if (typeof mod.packPlugin !== "function") {
+        throw new Error(`${PACKER_MODULE} has no packPlugin export`);
+    }
+    return mod.packPlugin;
+}
+/**
+ * Packs a fake extension into a plugin tgz with the plugin packer (the same bytes `pnpm
+ * pack-plugin` would produce: single-file ESM bundle, static manifest in plugin.json, migrations,
+ * skills and templates), writes it to `outDir` and returns its path, bytes and sha256. Packing
+ * leaves no files in the fixture directory.
+ */
+export async function packFixture(name, outDir) {
+    if (!FAKE_EXTENSIONS.includes(name))
+        throw new Error(`unknown fake extension ${String(name)}`);
+    const pack = await packer();
+    const r = await pack(fakeExtensionDir(name), outDir);
+    return { file: r.file, bytes: new Uint8Array(await readFile(r.file)), sha256: r.sha256 };
+}

package/dist/global-setup.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Vitest `globalSetup`: start one PostgreSQL 17 and one Valkey for the whole run and publish their
+ * addresses through `CAPYBARA_TEST_PG_ADMIN_URL` / `CAPYBARA_TEST_REDIS_URL`. Workers (forks pool)
+ * are spawned after this runs and inherit `process.env`, so `startTestPostgres()` /
+ * `startTestRedis({ shared: true })` in any test file see them.
+ *
+ * - `CAPYBARA_TEST_NO_SHARED=1` disables sharing: nothing starts, every file starts its own containers.
+ * - An address already present in the environment (e.g. a CI service container) is used as is.
+ *   For an external Redis the allocator wraps on its `CONFIG GET databases` value (at least 2 needed;
+ *   start it with `--databases 1024` for headroom). Where `CONFIG` is disabled the server is assumed
+ *   to have 1024 databases, so it must be started with `--databases 1024`.
+ *   An external PostgreSQL is not cleaned up: `cap_*` databases of crashed or killed runs (stop()
+ *   never ran) accumulate on a long-lived server and need dropping by hand now and then.
+ */
+export default function setup(): Promise<() => Promise<void>>;

package/dist/global-setup.js

@@ -0,0 +1,58 @@
+import { PG_ADMIN_URL_ENV, REDIS_DATABASES_ENV, REDIS_URL_ENV, SHARED_REDIS_DATABASES, sharingDisabled, startPostgresContainer, startRedisContainer, withRedis, } from "./containers.js";
+/**
+ * Vitest `globalSetup`: start one PostgreSQL 17 and one Valkey for the whole run and publish their
+ * addresses through `CAPYBARA_TEST_PG_ADMIN_URL` / `CAPYBARA_TEST_REDIS_URL`. Workers (forks pool)
+ * are spawned after this runs and inherit `process.env`, so `startTestPostgres()` /
+ * `startTestRedis({ shared: true })` in any test file see them.
+ *
+ * - `CAPYBARA_TEST_NO_SHARED=1` disables sharing: nothing starts, every file starts its own containers.
+ * - An address already present in the environment (e.g. a CI service container) is used as is.
+ *   For an external Redis the allocator wraps on its `CONFIG GET databases` value (at least 2 needed;
+ *   start it with `--databases 1024` for headroom). Where `CONFIG` is disabled the server is assumed
+ *   to have 1024 databases, so it must be started with `--databases 1024`.
+ *   An external PostgreSQL is not cleaned up: `cap_*` databases of crashed or killed runs (stop()
+ *   never ran) accumulate on a long-lived server and need dropping by hand now and then.
+ */
+export default async function setup() {
+    if (sharingDisabled())
+        return async () => { };
+    const wanted = [];
+    if (!process.env[PG_ADMIN_URL_ENV]) {
+        wanted.push([PG_ADMIN_URL_ENV, () => startPostgresContainer({ tuned: true })]);
+    }
+    const externalRedis = process.env[REDIS_URL_ENV];
+    const setDatabases = externalRedis !== undefined && externalRedis !== "";
+    if (setDatabases) {
+        process.env[REDIS_DATABASES_ENV] = String(await redisDatabases(externalRedis));
+    }
+    else {
+        wanted.push([REDIS_URL_ENV, () => startRedisContainer({ databases: SHARED_REDIS_DATABASES })]);
+    }
+    const started = await Promise.allSettled(wanted.map(([, start]) => start()));
+    const owned = started.flatMap((s) => (s.status === "fulfilled" ? [s.value] : []));
+    const failed = started.find((s) => s.status === "rejected");
+    if (failed) {
+        await Promise.allSettled(owned.map((c) => c.stop()));
+        throw failed.reason;
+    }
+    wanted.forEach(([env], i) => {
+        process.env[env] = owned[i].url;
+    });
+    return async () => {
+        for (const [env] of wanted)
+            delete process.env[env];
+        if (setDatabases)
+            delete process.env[REDIS_DATABASES_ENV];
+        await Promise.allSettled(owned.map((c) => c.stop()));
+    };
+}
+/** `CONFIG GET databases` of an external Redis; {@link SHARED_REDIS_DATABASES} when CONFIG is disabled. */
+async function redisDatabases(url) {
+    const reply = await withRedis(url, (r) => r.config("GET", "databases").catch(() => undefined));
+    const n = reply === undefined ? SHARED_REDIS_DATABASES : Number(reply[1]);
+    if (!Number.isInteger(n) || n < 2) {
+        throw new Error(`${REDIS_URL_ENV} must point at a Redis with at least 2 databases (got ${reply?.[1]}); ` +
+            "start it with --databases 1024");
+    }
+    return n;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Kernel names an extension's kernel-level tests need, re-exported so they import only this
+ * 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 { 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 { 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";
+export { type FakeMarketplace, type FakeMarketplaceRequest, startFakeMarketplace, } from "./fake-marketplace.js";
+export { type FakeMcpCallInfo, type FakeMcpHandlerContext, type FakeMcpPrompt, type FakeMcpRequest, type FakeMcpResource, FakeMcpRpcError, type FakeMcpServer, type FakeMcpServerOptions, type FakeMcpTool, startFakeMcpServer, } from "./fake-mcp-server.js";
+export { type FakeModelServer, type FakeRequest, type FakeResponse, startFakeModelServer, } from "./fake-model-server.js";
+export { type FakeNpmPackage, type FakeNpmRegistry, npmProvenanceAttestations, startFakeNpmRegistry, } from "./fake-npm-registry.js";
+export { type FakeOAuthClient, type FakeOAuthServer, type FakeOAuthServerOptions, type FakeTokenRequest, startFakeOAuthServer, } from "./fake-oauth-server.js";
+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 { 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/index.js

@@ -0,0 +1,25 @@
+/**
+ * Kernel names an extension's kernel-level tests need, re-exported so they import only this
+ * 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 { createDb, gatewayReplicasKey, 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, } from "./containers.js";
+export { createDualReplicaHarness, REPLICA_HEADER, replicaOf, } from "./dual-replica.js";
+export { assertExtensionSecretsReachable, extensionDeploymentSecretValues, } from "./extension-config.js";
+export { FAKE_CHANNEL_BAD_SECRET, FAKE_WEBHOOK_SIGNATURE_HEADER, fakeCardAction, fakeDirectoryMember, fakeDm, fakeGroupMessage, fakeWebhookChallenge, fakeWebhookEvents, signFakeWebhook, startFakeChannelServer, } from "./fake-channel.js";
+export { startFakeE2B, } from "./fake-e2b.js";
+export { startFakeGitServer, } from "./fake-git-server.js";
+export { encryptLarkWebhook, findLarkButton, larkCardAction, larkMessageEvent, signLarkWebhook, startFakeLark, } from "./fake-lark.js";
+export { startFakeMarketplace, } from "./fake-marketplace.js";
+export { FakeMcpRpcError, startFakeMcpServer, } from "./fake-mcp-server.js";
+export { startFakeModelServer, } from "./fake-model-server.js";
+export { npmProvenanceAttestations, startFakeNpmRegistry, } from "./fake-npm-registry.js";
+export { startFakeOAuthServer, } from "./fake-oauth-server.js";
+export { defaultFakeOpenApiSpec, startFakeOpenApiServer, } from "./fake-openapi-server.js";
+export { findSlackButton, signSlackWebhook, slackBlockAction, slackDmEvent, slackEventCallback, slackInteractiveForm, slackMentionEvent, startFakeSlack, } from "./fake-slack.js";
+export { FAKE_EXTENSIONS, fakeExtensionDir, fakeExtensionEntry, packFixture, } from "./fixtures.js";
+export { cardRecorded, cookieRequest, createAgent, createConversation, createLocalAccount, createOrg, eventsOf, joinOrg, login, pidOwningLocalPort, postMessage, sleep, startTestKernel, TEST_PASSWORD, testKernelConfig, truncateTables, waitFor, waitForEvent, waitForTerminal, } from "./kernel-helpers.js";
+export { isPngBase64, pdfBase64, pdfSampleWord, redPngBase64, solidPngBase64, } from "./media-samples.js";
+export { checkDeclaredParameters, describeModelProviderConformance, MEDIA_SAMPLES, thinkingReplayParams, } from "./model-conformance.js";
+export { openSse } from "./sse.js";

package/dist/kernel-helpers.d.ts

@@ -0,0 +1,125 @@
+import { type ConversationEvent, type Kernel, type KernelConfig, type KernelDb, type KernelHttp, type LogLevel } from "@capybara-hq/kernel";
+import { type Kysely } from "kysely";
+/**
+ * Helpers for extension tests that run a real kernel: in process (`startTestKernel` +
+ * `http.inject`) or as two replicas (`createDualReplicaHarness`). They only use the kernel's public
+ * API and HTTP routes, so a plugin's tests can use them without reaching into kernel sources.
+ */
+/** The password `createLocalAccount` gives accounts (and `login` / `joinOrg` use by default). */
+export declare const TEST_PASSWORD = "correct horse battery";
+export declare const sleep: (ms: number) => Promise<void>;
+/** Polls `fn` until it returns a value other than null / undefined / false; throws on timeout. */
+export declare function waitFor<T>(fn: () => Promise<T | null | undefined | false>, timeoutMs?: number, label?: string, stepMs?: number): Promise<T>;
+/**
+ * A kernel config for tests: the given PG / Redis, a fixed master key, an ephemeral HTTP port,
+ * auto-approved extension permissions, short run-lock timings and the official marketplace off
+ * (it is on by default and its address is on the internet). `overrides` are top-level config keys
+ * and win; `runtime` is merged into the defaults, and `marketplaces` too, so other marketplace
+ * settings keep the official one off unless `marketplaces.official` turns it on.
+ */
+export declare function testKernelConfig(urls: {
+    pg: string;
+    redis: string;
+}, overrides: Record<string, unknown> & {
+    extensions: string[];
+    runtime?: Record<string, unknown>;
+    marketplaces?: Record<string, unknown> & {
+        official?: Record<string, unknown>;
+    };
+}): KernelConfig;
+/**
+ * Throws when `config` would make a test kernel fetch the real official marketplace (enabled, at its
+ * default address on the internet): tests turn it off or point it at a fake. A kernel helper calls
+ * it before creating anything.
+ */
+export declare function assertOfflineOfficialMarketplace(config: KernelConfig, allow?: boolean): 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()`.
+ */
+export declare function startTestKernel(config: KernelConfig, opts?: {
+    resolveFrom?: string;
+    log?: {
+        level: LogLevel;
+        write: (line: string) => void;
+    };
+    /** Only for a test about the real default: allow the official marketplace at its real URL. */
+    allowOfficialMarketplace?: boolean;
+}): Promise<Kernel>;
+/** Options of a {@link KernelRequest} call (`http.inject` options; `csrf: false` drops the header). */
+export type KernelRequestOptions = Parameters<KernelHttp["inject"]>[0] & {
+    csrf?: boolean;
+};
+export type KernelResponse = Awaited<ReturnType<KernelHttp["inject"]>>;
+/**
+ * A signed-in user's request function: `http.inject` with the session cookies (kept from each
+ * response) and the `X-Capybara-Csrf` header.
+ */
+export type KernelRequest = (opts: KernelRequestOptions) => Promise<KernelResponse>;
+/** 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>;
+/** 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>;
+/** 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<{
+    accountId: string;
+    req: KernelRequest;
+}>;
+/**
+ * Creates an org-visible agent; returns its id. Without `tools` the agent has none (model-fake then
+ * answers ordinary messages instead of calling the first tool).
+ */
+export declare function createAgent(req: KernelRequest, orgId: string, opts?: {
+    model?: {
+        provider: string;
+        model: string;
+    };
+    tools?: unknown[];
+}): Promise<string>;
+/** Creates a conversation with the agent; returns its id. */
+export declare function createConversation(req: KernelRequest, orgId: string, agentId: string): Promise<string>;
+/** 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[]>;
+/** 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>;
+/** 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[]>;
+/**
+ * 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: {
+    messageId: string;
+} | {
+    kind: "approval" | "question";
+}, timeoutMs?: number): Promise<void>;
+/**
+ * `TRUNCATE <tables> CASCADE` between tests, retried on deadlock / lock timeout: a kernel with the
+ * worker role keeps scanning in the background (channel supervisor, deliveries, maintenance), and a
+ * background join holding one table while waiting for another deadlocks with TRUNCATE's ordered
+ * ACCESS EXCLUSIVE locks. TRUNCATE is atomic, so a retry is safe. `tables` is inlined into the SQL:
+ * pass only table names written in the test.
+ */
+export declare function truncateTables<DB>(db: Kysely<DB>, tables: string): Promise<void>;
+/**
+ * Finds which of `pids` owns the local TCP port `port` (the client side of a connection). Dual
+ * replica tests use it to map a fake platform's long-connection peer port (`socketPeerPorts()`) to
+ * a replica process: a real extension connecting to a fake platform carries no pid marker.
+ *
+ * Linux reads `/proc/net/tcp{,6}` for the socket inode and looks for it under `/proc/<pid>/fd`,
+ * falling back to `ss -tnp`, then `lsof`; other platforms (macOS) use `lsof`. Undefined when not
+ * found.
+ */
+export declare function pidOwningLocalPort(port: number, pids: readonly number[]): Promise<number | undefined>;