@volter/twin-standard 1.0.30 → 1.0.32

package/src/clients/aws.ts

@@ -0,0 +1,119 @@
+// AWS's own clients, driving the aws pack as its applications do: @aws-sdk/client-s3 (as LibreChat, Twenty, Rallly and the
+// platform's backups store their files) and @aws-sdk/client-secrets-manager, unmodified, with the access key the credential
+// door issues, in us-east-1, each addressing AWS's own endpoints (S3's virtual-hosted buckets, Secrets Manager's Regional
+// host) through an HTTPS agent as a World routes them. The S3 client computes and checks its default checksums as it does
+// against AWS (a CRC32 sent with each upload, and checked on each download that answers one).
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const PUT = 'https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html';
+const COMPLETE = 'https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html';
+const SECRET = 'https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html';
+
+const options = (c: ClientContext) => ({
+  region: 'us-east-1',
+  credentials: { accessKeyId: c.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: c.env.AWS_SECRET_ACCESS_KEY ?? '' },
+  requestHandler: { httpsAgent: c.agent, requestTimeout: 10_000 },
+  maxAttempts: 1,
+});
+
+const failed = (what: string) => (e: unknown): Error => new Error(`${what} failed: ${(e as Error).name}: ${(e as Error).message}`);
+
+export const cases: ClientCase[] = [
+  {
+    id: 's3-object-round-trip',
+    asks: 'an object put with its type and metadata into a bucket the client made is found by HeadObject with them, listed under its prefix, and read back byte for byte, the client checking the CRC32 it sent',
+    source: `${PUT} "Adds an object to a bucket."`,
+    async run(c) {
+      const s3 = await import('@aws-sdk/client-s3');
+      const client = new s3.S3Client(options(c));
+      const body = new TextEncoder().encode('{"madeAt":"2026-01-06T02:00:00.000Z","files":{}}');
+      try {
+        await client.send(new s3.CreateBucketCommand({ Bucket: 'client-case-backups' })).catch((e: unknown) => { throw failed('CreateBucket')(e); });
+        await client.send(new s3.PutObjectCommand({ Bucket: 'client-case-backups', Key: 'platform-state/one.json', Body: body, ContentType: 'application/json', Metadata: { source: 'client-case' } }))
+          .catch((e: unknown) => { throw failed('PutObject')(e); });
+        const out: string[] = [];
+        const head = await client.send(new s3.HeadObjectCommand({ Bucket: 'client-case-backups', Key: 'platform-state/one.json' })).catch((e: unknown) => { throw failed('HeadObject')(e); });
+        if (head.ContentType !== 'application/json') out.push(`HeadObject answered the type ${String(head.ContentType)}, not the one put`);
+        if (head.Metadata?.source !== 'client-case') out.push('HeadObject answered no x-amz-meta-source');
+        if (head.ContentLength !== body.length) out.push(`HeadObject answered ${String(head.ContentLength)} bytes, not ${body.length}`);
+        const listed = await client.send(new s3.ListObjectsV2Command({ Bucket: 'client-case-backups', Prefix: 'platform-state/' })).catch((e: unknown) => { throw failed('ListObjectsV2')(e); });
+        if (!(listed.Contents ?? []).some((o) => o.Key === 'platform-state/one.json')) out.push('ListObjectsV2 does not list the object put under its prefix');
+        const got = await client.send(new s3.GetObjectCommand({ Bucket: 'client-case-backups', Key: 'platform-state/one.json' })).catch((e: unknown) => { throw failed('GetObject')(e); });
+        const back = await got.Body!.transformToByteArray().catch((e: unknown) => { throw failed('reading GetObject\'s body')(e); });
+        if (back.length !== body.length || back.some((b, i) => b !== body[i])) out.push(`GetObject answered ${back.length} bytes, not the ${body.length} put`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 's3-multipart-upload',
+    asks: 'an upload of two parts, the first 5 MiB, completes into one object whose ETag names its two parts and whose bytes are the parts in order',
+    source: `${COMPLETE} "Completes a multipart upload by assembling previously uploaded parts."`,
+    async run(c) {
+      const s3 = await import('@aws-sdk/client-s3');
+      const client = new s3.S3Client(options(c));
+      const first = new Uint8Array(5 * 1024 * 1024).fill(97);
+      const second = new TextEncoder().encode('the recording\'s last bytes');
+      try {
+        await client.send(new s3.CreateBucketCommand({ Bucket: 'client-case-recordings' })).catch((e: unknown) => { throw failed('CreateBucket')(e); });
+        const made = await client.send(new s3.CreateMultipartUploadCommand({ Bucket: 'client-case-recordings', Key: 'calls/call.m4a', ContentType: 'audio/mp4' }))
+          .catch((e: unknown) => { throw failed('CreateMultipartUpload')(e); });
+        const UploadId = made.UploadId;
+        if (!UploadId) return ['CreateMultipartUpload answered no UploadId'];
+        const one = await client.send(new s3.UploadPartCommand({ Bucket: 'client-case-recordings', Key: 'calls/call.m4a', UploadId, PartNumber: 1, Body: first })).catch((e: unknown) => { throw failed('UploadPart 1')(e); });
+        const two = await client.send(new s3.UploadPartCommand({ Bucket: 'client-case-recordings', Key: 'calls/call.m4a', UploadId, PartNumber: 2, Body: second })).catch((e: unknown) => { throw failed('UploadPart 2')(e); });
+        const done = await client.send(new s3.CompleteMultipartUploadCommand({ Bucket: 'client-case-recordings', Key: 'calls/call.m4a', UploadId,
+          MultipartUpload: { Parts: [{ PartNumber: 1, ETag: one.ETag }, { PartNumber: 2, ETag: two.ETag }] } })).catch((e: unknown) => { throw failed('CompleteMultipartUpload')(e); });
+        const out: string[] = [];
+        if (!/-2"$/.test(String(done.ETag))) out.push(`the completed object's ETag ${String(done.ETag)} does not name its two parts`);
+        const got = await client.send(new s3.GetObjectCommand({ Bucket: 'client-case-recordings', Key: 'calls/call.m4a' })).catch((e: unknown) => { throw failed('GetObject')(e); });
+        const back = await got.Body!.transformToByteArray();
+        if (back.length !== first.length + second.length || back[0] !== 97 || back[back.length - 1] !== second[second.length - 1]) out.push(`GetObject answered ${back.length} bytes, not the parts joined (${first.length + second.length})`);
+        if (got.ContentType !== 'audio/mp4') out.push(`the object's type is ${String(got.ContentType)}, not the one its upload began with`);
+        const left = await client.send(new s3.ListMultipartUploadsCommand({ Bucket: 'client-case-recordings' })).catch((e: unknown) => { throw failed('ListMultipartUploads')(e); });
+        if ((left.Uploads ?? []).some((u) => u.UploadId === UploadId)) out.push('the completed upload is still listed in progress');
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'secrets-manager-create-and-read',
+    asks: 'a secret stored with its value is read back as the current version, labelled AWSCURRENT',
+    source: `${SECRET} "Retrieves the contents of the encrypted fields SecretString or SecretBinary from the specified version of a secret"`,
+    async run(c) {
+      const sm = await import('@aws-sdk/client-secrets-manager');
+      const client = new sm.SecretsManagerClient(options(c));
+      const SecretString = '{"username":"api","password":"client-case-password"}';
+      try {
+        const made = await client.send(new sm.CreateSecretCommand({ Name: 'client-case/db', SecretString })).catch((e: unknown) => { throw failed('CreateSecret')(e); });
+        const got = await client.send(new sm.GetSecretValueCommand({ SecretId: 'client-case/db' })).catch((e: unknown) => { throw failed('GetSecretValue')(e); });
+        const out: string[] = [];
+        if (got.SecretString !== SecretString) out.push('GetSecretValue answered another value than the one stored');
+        if (got.VersionId !== made.VersionId) out.push(`GetSecretValue answered version ${String(got.VersionId)}, not the ${String(made.VersionId)} CreateSecret made`);
+        if (!(got.VersionStages ?? []).includes('AWSCURRENT')) out.push('the version read is not labelled AWSCURRENT');
+        if (!String(made.ARN).startsWith('arn:aws:secretsmanager:us-east-1:')) out.push(`CreateSecret answered the ARN ${String(made.ARN)}, not one in us-east-1, the Region it was called in`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 's3-backup-bucket-created-when-missing',
+    asks: 'HeadBucket rejects with HTTP 404 for a missing backup bucket; the backup job catches it and creates the bucket, which then answers HTTP 200',
+    source: 'https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html "The specified bucket does not exist."',
+    async run(c) {
+      const s3 = await import('@aws-sdk/client-s3');
+      const client = new s3.S3Client({ ...options(c), forcePathStyle: true });
+      const Bucket = 'client-case-backup-new-bucket';
+      try {
+        const missing = await client.send(new s3.HeadBucketCommand({ Bucket })).then(() => undefined,
+          (e: unknown) => e as { $metadata?: { httpStatusCode?: number } });
+        if (missing?.$metadata?.httpStatusCode !== 404) return ['HeadBucket did not reject the missing bucket with HTTP 404'];
+        // apps/platform/src/backup.ts catches the SDK rejection before creating the bucket.
+        await client.send(new s3.CreateBucketCommand({ Bucket }));
+        const found = await client.send(new s3.HeadBucketCommand({ Bucket }));
+        return found.$metadata.httpStatusCode === 200 ? [] : ['HeadBucket did not find the newly created backup bucket'];
+      } catch (e) { return [(e as Error).message]; }
+      finally { client.destroy(); }
+    },
+  },
+];

package/src/clients/cerebras.ts

@@ -0,0 +1,4 @@
+// Cerebras's chat through openai-node (its OpenAI-compatible API), the shared chat cases.
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = chatCases({ key: 'CEREBRAS_API_KEY', base: (host) => `https://${host}/v1`, model: 'test-model' });

package/src/clients/clerk.ts

@@ -0,0 +1,97 @@
+// Official @clerk/backend 2.33.3: runhuman pins 2.30.1 (through @clerk/fastify 2.6.19, its pnpm-lock.yaml), and 2.33.3 is
+// that line's fix for GHSA-w24r-5266-9c3c, which the release scan refuses; the case drives it as
+// runhuman's API server uses it: createClerkClient({ secretKey }), the paginated membership lists it reads roles and
+// permissions from, the error's status it branches on, and the session token its Fastify plugin verifies.
+// The SDK binds the global fetch when it is first imported, so the World's routed fetch is set before that import.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const ORG_MEMBERSHIPS = 'https://clerk.com/docs/references/backend/organization/get-organization-membership-list';
+const USER_MEMBERSHIPS = 'https://clerk.com/docs/references/backend/user/get-organization-membership-list';
+const OVERVIEW = 'https://clerk.com/docs/references/backend/overview';
+const VERIFY = 'https://clerk.com/docs/references/backend/verify-token';
+
+async function sdk(c: ClientContext) {
+  globalThis.fetch = c.fetch;
+  return await import('@clerk/backend');
+}
+async function client(c: ClientContext) {
+  const { createClerkClient } = await sdk(c);
+  return createClerkClient({ secretKey: c.env.CLERK_SECRET_KEY });
+}
+/** A person and an organization they created (Organizations turned on first, as an application's instance has them). */
+async function founded(c: ClientContext, who: string) {
+  const clerk = await client(c);
+  await clerk.instance.updateOrganizationSettings({ enabled: true });
+  const user = await clerk.users.createUser({ emailAddress: [`${who}@sdk-case.example`], firstName: who, skipPasswordRequirement: true });
+  const org = await clerk.organizations.createOrganization({ name: `${who}'s team`, createdBy: user.id });
+  return { clerk, user, org };
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'organization-membership-list-paginated',
+    asks: "the organization's memberships come back as { data, totalCount }, each membership's public user data and creation time read as the SDK's objects",
+    source: `${ORG_MEMBERSHIPS} "Returns a PaginatedResourceResponse object with a data property containing an array of OrganizationMembership objects and a totalCount property"`,
+    async run(c) {
+      const { clerk, user, org } = await founded(c, 'marta');
+      const { data, totalCount } = await clerk.organizations.getOrganizationMembershipList({ organizationId: org.id, limit: 100 });
+      const failures: string[] = [];
+      if (totalCount !== 1 || data.length !== 1) failures.push(`the creator's organization lists ${data.length} memberships of ${totalCount}, not its one`);
+      const m = data[0];
+      if (m?.publicUserData?.userId !== user.id) failures.push('the membership names no publicUserData.userId of its member');
+      if (m?.publicUserData?.identifier !== 'marta@sdk-case.example') failures.push('the membership lost its member\'s identifier');
+      if (typeof m?.createdAt !== 'number' || Number.isNaN(new Date(m.createdAt).getTime())) failures.push('the membership\'s createdAt is no time');
+      return failures;
+    },
+  },
+  {
+    id: 'user-membership-list-names-organization-and-permissions',
+    asks: "a user's memberships come back as { data, totalCount }, each naming its organization and the permissions its role grants",
+    source: `${USER_MEMBERSHIPS} "Returns a PaginatedResourceResponse object with a data property that contains an array of OrganizationMembership objects"`,
+    async run(c) {
+      const { clerk, user, org } = await founded(c, 'rui');
+      const { data, totalCount } = await clerk.users.getOrganizationMembershipList({ userId: user.id, limit: 100 });
+      const failures: string[] = [];
+      const m = data.find((x) => x.organization?.id === org.id);
+      if (totalCount !== 1 || !m) failures.push(`the creator's memberships (${totalCount}) do not name the organization made`);
+      else if (!Array.isArray(m.permissions) || !m.permissions.length) failures.push(`the creator's membership (${m.role}) carries no permissions`);
+      return failures;
+    },
+  },
+  {
+    id: 'api-error-carries-status-and-code',
+    asks: "a refused call throws ClerkAPIResponseError carrying the HTTP status and the errors Clerk answered: an unknown user's memberships are a 404, which runhuman's isMember reads as no membership (packages/api/src/services/clerk/clerk-org.api.ts:51-63)",
+    source: `${OVERVIEW} "The clerkClient methods throw errors ( ClerkAPIResponseError ) when something goes wrong."`,
+    async run(c) {
+      const clerk = await client(c);
+      await clerk.instance.updateOrganizationSettings({ enabled: true });
+      try {
+        await clerk.users.getOrganizationMembershipList({ userId: 'user_2missing0000000000000000', limit: 100 });
+        return ["an unknown user's memberships were answered"];
+      } catch (e) {
+        const error = e as { status?: number; errors?: Array<{ code?: string }> };
+        const failures: string[] = [];
+        if (error.status !== 404) failures.push(`the error's status is ${error.status}, not 404`);
+        if (error.errors?.[0]?.code !== 'resource_not_found') failures.push(`the error's first code is ${error.errors?.[0]?.code}, not resource_not_found`);
+        return failures;
+      }
+    },
+  },
+  {
+    id: 'session-token-verified-against-jwks',
+    asks: "a session's token verifies with the secret key alone, the SDK fetching the instance's JWKS from the Backend API",
+    source: `${VERIFY} "Otherwise, performs a network call to retrieve the JWKS from the Backend API"`,
+    async run(c) {
+      const { verifyToken } = await sdk(c);
+      const clerk = await client(c);
+      const user = await clerk.users.createUser({ emailAddress: ['ines@sdk-case.example'], skipPasswordRequirement: true });
+      const session = await clerk.sessions.createSession({ userId: user.id });
+      const { jwt } = await clerk.sessions.getToken(session.id);
+      const payload = await verifyToken(jwt, { secretKey: c.env.CLERK_SECRET_KEY });
+      const failures: string[] = [];
+      if (payload.sub !== user.id) failures.push(`the verified token's sub is ${String(payload.sub)}, not the user`);
+      if (payload.sid !== session.id) failures.push(`the verified token's sid is ${String(payload.sid)}, not the session`);
+      return failures;
+    },
+  },
+];

package/src/clients/cloudflare.ts

@@ -0,0 +1,80 @@
+// Cloudflare's own clients, driving the cloudflare pack as its applications do: the official TypeScript library
+// (`cloudflare`, as Twenty calls custom hostnames and an operator makes a Turnstile widget) with the account token the
+// credential door issues, and aws4fetch (as RH2 and Dub reach R2's S3 API) with the R2 keys it issues, signing for the
+// account's own R2 endpoint.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const HOSTNAMES = 'https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/';
+const WIDGETS = 'https://developers.cloudflare.com/turnstile/get-started/widget-management/api/';
+const AWS4FETCH = 'https://developers.cloudflare.com/r2/examples/aws/aws4fetch/';
+
+async function cloudflare(c: ClientContext) {
+  const { default: Cloudflare } = await import('cloudflare');
+  return new Cloudflare({ apiToken: c.env.CLOUDFLARE_API_TOKEN ?? '', fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+}
+
+const failed = (what: string) => (e: unknown): Error => new Error(`${what} failed: ${(e as Error).message}`);
+
+export const cases: ClientCase[] = [
+  {
+    id: 'custom-hostname-pending-and-found',
+    asks: 'a custom hostname registered on a zone is pending, with the ownership verification its customer publishes, and is found again by its hostname',
+    source: `${HOSTNAMES} "validate hostname ownership and affect the custom hostname"`,
+    async run(c) {
+      const cf = await cloudflare(c);
+      const account = c.env.CLOUDFLARE_ACCOUNT_ID ?? '';
+      try {
+        const zone = await cf.zones.create({ account: { id: account }, name: 'client-case.example', type: 'full' }).catch((e: unknown) => { throw failed('zones.create')(e); });
+        const made = await cf.customHostnames.create({ zone_id: zone.id, hostname: 'shop.customer-case.example', ssl: { method: 'txt', type: 'dv' } })
+          .catch((e: unknown) => { throw failed('customHostnames.create')(e); });
+        const out: string[] = [];
+        if (made.status !== 'pending') out.push(`a new custom hostname is ${String(made.status)}, not pending`);
+        if (!made.ownership_verification?.name || !made.ownership_verification?.value) out.push('a new custom hostname names no ownership verification record');
+        const page = await cf.customHostnames.list({ zone_id: zone.id, hostname: 'shop.customer-case.example' as never }).catch((e: unknown) => { throw failed('customHostnames.list')(e); });
+        const found = page.getPaginatedItems();
+        if (found.length !== 1 || found[0]?.id !== made.id) out.push(`the hostname filter found ${found.length} hostname(s), not the one made`);
+        return out;
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'turnstile-widget-secret-at-detail',
+    asks: "a widget made through the API answers its sitekey and secret, and its detail answers the same secret",
+    source: `${WIDGETS} "Turnstile Widget Details"`,
+    async run(c) {
+      const cf = await cloudflare(c);
+      const account_id = c.env.CLOUDFLARE_ACCOUNT_ID ?? '';
+      try {
+        const widget = await cf.turnstile.widgets.create({ account_id, domains: ['client-case.example'], mode: 'managed', name: 'client case sign-up' })
+          .catch((e: unknown) => { throw failed('turnstile.widgets.create')(e); });
+        if (!widget.sitekey || !widget.secret) return ['the new widget answers no sitekey or no secret'];
+        const detail = await cf.turnstile.widgets.get(widget.sitekey, { account_id }).catch((e: unknown) => { throw failed('turnstile.widgets.get')(e); });
+        return detail.secret === widget.secret ? [] : ['the widget\'s detail answers another secret than its creation'];
+      } catch (e) { return [(e as Error).message]; }
+    },
+  },
+  {
+    id: 'r2-object-round-trip-aws4fetch',
+    asks: "an object put through aws4fetch at the account's R2 endpoint is listed by ListObjectsV2 and read back byte for byte",
+    source: `${AWS4FETCH} "ListObjectsV2Result"`,
+    async run(c) {
+      const { AwsClient } = await import('aws4fetch');
+      const r2 = new AwsClient({ accessKeyId: c.env.R2_ACCESS_KEY_ID ?? '', secretAccessKey: c.env.R2_SECRET_ACCESS_KEY ?? '', service: 's3', region: 'auto' });
+      const base = c.env.R2_ENDPOINT ?? '';
+      const send = async (url: string, init?: RequestInit): Promise<Response> => c.fetch(await r2.sign(url, init));
+      const bytes = new TextEncoder().encode('a recording, as RH2 imports it\n');
+      const made = await send(`${base}/client-case-recordings`, { method: 'PUT' });
+      if (!made.ok) return [`CreateBucket answered ${made.status}`];
+      const put = await send(`${base}/client-case-recordings/rooms/r1.txt`, { method: 'PUT', body: bytes, headers: { 'content-type': 'text/plain' } });
+      if (!put.ok) return [`PutObject answered ${put.status}`];
+      const out: string[] = [];
+      const listed = await (await send(`${base}/client-case-recordings?list-type=2`)).text();
+      if (!listed.includes('<Key>rooms/r1.txt</Key>')) out.push('ListObjectsV2 does not list the object put');
+      const got = await send(`${base}/client-case-recordings/rooms/r1.txt`);
+      const back = new Uint8Array(await got.arrayBuffer());
+      if (got.status !== 200 || back.length !== bytes.length || back.some((b, i) => b !== bytes[i])) out.push(`GetObject answered ${got.status} with ${back.length} bytes, not the ${bytes.length} put`);
+      if (got.headers.get('content-type') !== 'text/plain') out.push(`GetObject answered the type ${String(got.headers.get('content-type'))}, not the one put`);
+      return out;
+    },
+  },
+];

package/src/clients/elevenlabs.ts

@@ -0,0 +1,38 @@
+// ElevenLabs' own client (@elevenlabs/elevenlabs-js), driving the elevenlabs pack as Volter Harness's voice does: an agent
+// made, a signed URL asked for, and the conversation's WebSocket opened at it (the ws library, as a Node application opens
+// it), its first event the one ElevenLabs documents.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const SOCKET = 'https://elevenlabs.io/docs/agents-platform/api-reference/agents-platform/websocket';
+
+async function client(c: ClientContext) {
+  const { ElevenLabsClient } = await import('@elevenlabs/elevenlabs-js');
+  return new ElevenLabsClient({ apiKey: c.env.ELEVENLABS_API_KEY ?? '', baseUrl: `https://${c.host}`, fetch: c.fetch, maxRetries: 0, timeoutInSeconds: 10 });
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'agent-conversation-opens',
+    asks: "an agent's conversation opened at its signed URL answers the client's initiation data with conversation_initiation_metadata",
+    source: `${SOCKET} "conversation_initiation_client_data"`,
+    async run(c) {
+      const el = await client(c);
+      const agent = await el.conversationalAi.agents.create({ name: 'Conformance', conversationConfig: { agent: { firstMessage: 'Hello.', prompt: { prompt: 'Answer briefly.' } } } } as never).catch((e: unknown) => e as Error);
+      if (agent instanceof Error) return [`agents.create failed: ${agent.message}`];
+      const signed = await el.conversationalAi.conversations.getSignedUrl({ agentId: (agent as { agentId: string }).agentId }).catch((e: unknown) => e as Error);
+      if (signed instanceof Error) return [`conversations.getSignedUrl failed: ${signed.message}`];
+      const url = (signed as { signedUrl: string }).signedUrl;
+      if (!url.startsWith('wss://')) return [`the signed URL is not ElevenLabs' secure socket: ${url.slice(0, 60)}`];
+      const { WebSocket } = await import('ws');
+      const first = await new Promise<string>((done) => {
+        const ws = new WebSocket(url, { createConnection: c.connect } as never);
+        const timer = setTimeout(() => { ws.close(); done('no event in 10 s'); }, 10_000);
+        // the client's first frame, as ElevenLabs' SDKs send it: its initiation data
+        ws.on('open', () => ws.send(JSON.stringify({ type: 'conversation_initiation_client_data' })));
+        ws.on('message', (d: Buffer) => { clearTimeout(timer); ws.close(); try { done(String((JSON.parse(String(d)) as { type?: string }).type)); } catch { done(`a frame that is not JSON: ${String(d).slice(0, 40)}`); } });
+        ws.on('error', (e: Error) => { clearTimeout(timer); done(`the socket failed: ${e.message}`); });
+      });
+      return first === 'conversation_initiation_metadata' ? [] : [`the conversation's first event was ${first}`];
+    },
+  },
+];

package/src/clients/gemini.ts

@@ -0,0 +1,89 @@
+// Gemini's official SDKs at the versions LibreChat pins: chat uses the Generative AI SDK,
+// and its image tool uses Google Gen AI. Requests use the World's proxy through global fetch,
+// the transport both unmodified SDKs use.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const REFERENCE = 'https://ai.google.dev/api/generate-content';
+const MODEL = 'gemini-3.8-flash';
+const PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZlSAAAAAASUVORK5CYII=';
+
+async function routed<T>(c: ClientContext, run: () => Promise<T>): Promise<T> {
+  const previous = globalThis.fetch;
+  globalThis.fetch = c.fetch;
+  try { return await run(); } finally { globalThis.fetch = previous; }
+}
+
+async function chat(c: ClientContext, model = MODEL) {
+  const { GoogleGenerativeAI } = await import('@google/generative-ai');
+  return new GoogleGenerativeAI(c.env.GOOGLE_API_KEY ?? '').getGenerativeModel({ model }, { baseUrl: `https://${c.host}` });
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'generative-ai-stream-aggregate',
+    asks: 'the chat SDK decodes SSE chunks and aggregates their text into the final response',
+    source: `${REFERENCE} "a stream of GenerateContentResponse instances"`,
+    async run(c) {
+      return routed(c, async () => {
+        c.scenario({ handlers: [{ id: 'words', on: { userTextIncludes: 'workshop' }, respond: { text: 'A scripted workshop reply.' } }] });
+        const result = await (await chat(c)).generateContentStream('Plan the workshop.');
+        let text = '';
+        for await (const chunk of result.stream) text += chunk.text();
+        const response = await result.response;
+        return text === 'A scripted workshop reply.' && response.text() === text && response.candidates?.[0]?.finishReason === 'STOP'
+          ? [] : ['SSE text, aggregate response or final finish reason did not survive the SDK'];
+      });
+    },
+  },
+  {
+    id: 'generative-ai-function-continuation',
+    asks: 'the SDK exposes function calls and sends their result as the next chat turn',
+    source: `${REFERENCE} "Function Calling"`,
+    async run(c) {
+      return routed(c, async () => {
+        const { SchemaType } = await import('@google/generative-ai');
+        c.scenario({ handlers: [
+          { id: 'returned', on: { toolResultFor: 'lookup_company', lastMessageIsToolResult: true }, respond: { text: 'Tidewater renewal is in October.' } },
+          { id: 'lookup', on: { hasTool: 'lookup_company' }, respond: { functionCalls: [{ name: 'lookup_company', args: { company: 'Tidewater' } }] } },
+        ] });
+        const session = (await chat(c)).startChat({ tools: [{ functionDeclarations: [{ name: 'lookup_company', parameters: { type: SchemaType.OBJECT, properties: { company: { type: SchemaType.STRING } }, required: ['company'] } }] }] });
+        const first = await session.sendMessage('Find the company renewal.');
+        const call = first.response.functionCalls()?.[0];
+        if (call?.name !== 'lookup_company' || (call.args as Record<string, unknown>).company !== 'Tidewater') return ['the SDK lost the function name or arguments'];
+        const next = await session.sendMessage([{ functionResponse: { name: call.name, response: { renewal: 'October' } } }]);
+        return next.response.text() === 'Tidewater renewal is in October.' ? [] : ['the SDK chat history/function response failed to continue the turn'];
+      });
+    },
+  },
+  {
+    id: 'generative-ai-typed-refusal',
+    asks: 'a missing model becomes the chat SDK HTTP error with its status and Google error details',
+    source: 'https://cloud.google.com/apis/design/errors "NOT_FOUND"',
+    async run(c) {
+      return routed(c, async () => {
+        const { GoogleGenerativeAIFetchError } = await import('@google/generative-ai');
+        try { await (await chat(c, 'missing-model')).generateContent('Hello'); }
+        catch (error) { return error instanceof GoogleGenerativeAIFetchError && error.status === 404 ? [] : ['missing model was not the SDK 404 error']; }
+        return ['missing model unexpectedly generated content'];
+      });
+    },
+  },
+  {
+    id: 'genai-image-parts',
+    asks: 'the image SDK reads generated text and inline image bytes from response parts',
+    source: `${REFERENCE} "inlineData"`,
+    async run(c) {
+      return routed(c, async () => {
+        const { GoogleGenAI } = await import('@google/genai');
+        c.scenario({ handlers: [{ id: 'picture', on: { userTextIncludes: 'square illustration' }, respond: {
+          text: 'A synthetic square illustration.', parts: [{ inlineData: { mimeType: 'image/png', data: PNG } }],
+        } }] });
+        const ai = new GoogleGenAI({ apiKey: c.env.GEMINI_API_KEY ?? '', httpOptions: { baseUrl: `https://${c.host}` } });
+        const response = await ai.models.generateContent({ model: 'gemini-3.1-flash-image', contents: 'Make a square illustration.', config: { responseModalities: ['TEXT', 'IMAGE'] } });
+        const image = response.candidates?.[0]?.content?.parts?.find((p) => p.inlineData)?.inlineData;
+        return response.text === 'A synthetic square illustration.' && image?.mimeType === 'image/png' && image.data === PNG
+          ? [] : ['the image SDK lost text, MIME type or fixture bytes'];
+      });
+    },
+  },
+];

package/src/clients/github.ts

@@ -0,0 +1,67 @@
+// GitHub's own client (Octokit, @octokit/rest), driving the github pack as its applications do: twin-world's on-call
+// recipe (cookbook/on-call-agent) reads a new issue by its number and answers on it with the ticket it filed, through
+// Octokit with the World's GITHUB_TOKEN; and Octokit raises its typed error, with the response's status, when GitHub
+// refuses (the recipe's issue read of a number the repository does not have). The repository the issue lives in is made
+// as `gh repo create` makes one, by GraphQL's createRepository, through Octokit's own GraphQL call.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const SCRIPTING = 'https://docs.github.com/en/rest/guides/scripting-with-the-rest-api-and-javascript';
+const ISSUES = 'https://docs.github.com/en/rest/issues/issues';
+const COMMENTS = 'https://docs.github.com/en/rest/issues/comments';
+
+async function octokit(c: ClientContext) {
+  const { Octokit } = await import('@octokit/rest');
+  return new Octokit({ auth: c.env.GITHUB_TOKEN ?? '', request: { fetch: c.fetch } });
+}
+
+/** A public repository of the token's own account, made as `gh repo create` makes one (GraphQL's createRepository). */
+async function repository(client: Awaited<ReturnType<typeof octokit>>, name: string): Promise<{ owner: string; repo: string }> {
+  const made = await client.graphql<{ createRepository: { repository: { nameWithOwner: string } } }>(
+    'mutation($name: String!) { createRepository(input: { name: $name, visibility: PUBLIC }) { repository { nameWithOwner } } }', { name });
+  const [owner, repo] = made.createRepository.repository.nameWithOwner.split('/') as [string, string];
+  return { owner, repo };
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'on-call-triage',
+    asks: 'the on-call recipe reads a new issue by its number and answers on it, through Octokit: the issue as filed, the comment as written, and the issue counting it',
+    source: `${ISSUES} "Any user with pull access to a repository can create an issue."; ${COMMENTS} "You can use the REST API to list comments on issues and pull requests. Every pull request is an issue, but not every issue is a pull request."`,
+    async run(c) {
+      try {
+        const client = await octokit(c);
+        const { owner, repo } = await repository(client, 'storefront');
+        const filed = (await client.rest.issues.create({ owner, repo, title: 'Checkout fails on Safari', body: 'The pay button does nothing on Safari 18.' })).data;
+        const issue = (await client.rest.issues.get({ owner, repo, issue_number: filed.number })).data;
+        const out: string[] = [];
+        if (issue.number !== filed.number) out.push(`issues.get answered issue ${issue.number}, not ${filed.number}`);
+        if (issue.title !== 'Checkout fails on Safari') out.push(`the issue's title is ${JSON.stringify(issue.title)}`);
+        if (issue.state !== 'open') out.push(`the issue is ${issue.state}, not open`);
+        const body = 'Tracked as OPS-1. A bug: the checkout button on Safari.';
+        const comment = (await client.rest.issues.createComment({ owner, repo, issue_number: issue.number, body })).data;
+        if (comment.body !== body) out.push(`the comment's body is ${JSON.stringify(comment.body)}`);
+        if (comment.user?.login !== owner) out.push(`the comment is ${String(comment.user?.login)}'s, not the token's own ${owner}`);
+        const after = (await client.rest.issues.get({ owner, repo, issue_number: issue.number })).data;
+        if (after.comments !== 1) out.push(`the issue counts ${after.comments} comments, not the one made`);
+        return out;
+      } catch (e) { return [`the recipe's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'missing-issue-raises',
+    asks: "reading an issue the repository does not have raises Octokit's HttpError with the response's status, 404",
+    source: `${SCRIPTING} "If an API error occurs even after retries, Octokit.js throws an error that includes the HTTP status code of the response ( response.status ) and the response headers ( response.headers )."`,
+    async run(c) {
+      try {
+        const client = await octokit(c);
+        const { owner, repo } = await repository(client, 'pager');
+        const raised = await client.rest.issues.get({ owner, repo, issue_number: 4242 }).then(() => undefined, (e: unknown) => e as { name?: string; status?: number });
+        if (!raised) return ['reading an issue the repository does not have answered one'];
+        const out: string[] = [];
+        if (raised.name !== 'HttpError') out.push(`it raised ${String(raised.name)}, not Octokit's HttpError`);
+        if (raised.status !== 404) out.push(`its status is ${String(raised.status)}, not 404`);
+        return out;
+      } catch (e) { return [`the case's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+];

package/src/clients/groq.ts

@@ -0,0 +1,4 @@
+// Groq's chat through openai-node (its OpenAI-compatible API), the shared chat cases.
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = chatCases({ key: 'GROQ_API_KEY', base: (host) => `https://${host}/openai/v1`, model: 'test-model' });

package/src/clients/harness.ts

@@ -0,0 +1,101 @@
+// THE VENDOR'S OWN CLIENT — how conformance drives a pack the way an application does (docs/contributing/architecture.md,
+// "Conformance"): the vendor's official SDK, unmodified, in a Node process as an application runs it, against the pack
+// served as a World runs it. Its credentials are the ones the pack's own credential door issued; its connections reach the
+// served port as a World's interception routes the vendor's hosts, the vendor's URL and Host unchanged (an HTTP request
+// over node:http with its Host kept, a socket's TCP connection made to the served port). A case's expectations are the
+// vendor's documented semantics, each cited, never the pack author's life.
+import { createServer, request as httpRequest } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { connect, type AddressInfo, type Socket } from 'node:net';
+import { writeFileSync } from 'node:fs';
+
+/** What a case is given. */
+export type ClientContext = {
+  /** the vendor's API host, as its client addresses it (the descriptor's first host) */
+  host: string;
+  /** the credentials the pack's credential door issued, by the environment variable a World sets each in */
+  env: Record<string, string>;
+  /** fetch as a World routes it: a URL on the vendor's host reaches the served pack, its Host kept */
+  fetch: typeof fetch;
+  /** a TCP connection to the served pack, for a socket client (the ws library's `createConnection`): the client keeps
+   *  the vendor's URL and Host, and its TLS-less connection lands on the served port, as the World's interception does */
+  connect: () => Socket;
+  /** an HTTPS agent as a World routes it, for a client that takes an agent (Slack's, Stripe's): its connections reach the
+   *  served port, the client's URL and Host unchanged */
+  agent: HttpsAgent;
+  /** writes the World's scenario file (read at the pack's next turn) */
+  scenario: (doc: unknown) => void;
+};
+
+/** One expectation of the vendor's documented behaviour, driven through its client. */
+export type ClientCase = {
+  id: string;
+  /** what the vendor documents, as the case holds the pack to it */
+  asks: string;
+  /** the page that documents it: `<url> "<words>"` */
+  source: string;
+  /** what fails, each named; empty when the pack holds it */
+  run: (c: ClientContext) => Promise<string[]>;
+};
+
+/** The World's proxy in front of a pack served on `served`: it ends the caller's TLS (here, none was begun) and forwards
+ *  each request and socket upgrade to the pack with `x-forwarded-proto: https`, the vendor's Host unchanged, as a World's
+ *  proxy forwards a caller of the vendor's https host (twin-fetch.ts, twinPublicBase: the links and socket URLs the pack
+ *  answers are then the vendor's secure ones). Answers the proxy's port. */
+export async function worldProxy(served: number): Promise<number> {
+  const server = createServer((req, res) => {
+    const forward = httpRequest({ host: '127.0.0.1', port: served, method: req.method, path: req.url, headers: { ...req.headers, 'x-forwarded-proto': 'https' } }, (answer) => {
+      res.writeHead(answer.statusCode ?? 502, answer.headers);
+      answer.pipe(res);
+    });
+    forward.on('error', () => { res.writeHead(502); res.end(); });
+    req.pipe(forward);
+  });
+  server.on('upgrade', (req, socket, head) => {
+    const upstream = connect(served, '127.0.0.1', () => {
+      const lines = [`${req.method} ${req.url} HTTP/1.1`, ...Object.entries({ ...req.headers, 'x-forwarded-proto': 'https' }).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map((x) => `${k}: ${x}`)), '', ''];
+      upstream.write(lines.join('\r\n'));
+      if (head.length) upstream.write(head);
+      upstream.pipe(socket);
+      socket.pipe(upstream);
+    });
+    upstream.on('error', () => socket.destroy());
+    socket.on('error', () => upstream.destroy());
+  });
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()));
+  server.unref();
+  return (server.address() as AddressInfo).port;
+}
+
+/** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
+export function clientContext(port: number, host: string, env: Record<string, string>, scenarioPath: string): ClientContext {
+  const routedFetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : Buffer.from(await request.arrayBuffer());
+    const headers: Record<string, string> = Object.fromEntries(request.headers);
+    headers.host = url.host;
+    return new Promise<Response>((resolve, reject) => {
+      const sent = httpRequest({ host: '127.0.0.1', port, method: request.method, path: `${url.pathname}${url.search}`, headers }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (c: Buffer) => chunks.push(c));
+        res.on('end', () => {
+          const answer = new Headers();
+          for (const [k, v] of Object.entries(res.headers)) if (v !== undefined) for (const one of Array.isArray(v) ? v : [v]) answer.append(k, one);
+          resolve(new Response(res.statusCode === 204 || res.statusCode === 304 ? null : Buffer.concat(chunks), { status: res.statusCode ?? 0, headers: answer }));
+        });
+        res.on('error', reject);
+      });
+      sent.on('error', reject);
+      sent.end(body);
+    });
+  }) as typeof fetch;
+  const agent = new (class extends HttpsAgent {
+    createConnection(): Socket { return connect(port, '127.0.0.1'); }
+  })({ keepAlive: false });
+  return {
+    host, env, fetch: routedFetch, agent,
+    connect: () => connect(port, '127.0.0.1'),
+    scenario: (doc) => writeFileSync(scenarioPath, JSON.stringify(doc)),
+  };
+}

package/src/clients/merge.ts

@@ -0,0 +1,9 @@
+// Merge Gateway through the SDKs its callers use: openai-node on its chat completions, Anthropic's SDK on its Messages
+// surface (both of its OpenAI- and Anthropic-compatible APIs), the shared cases.
+import { messagesCases } from './anthropic-messages.ts';
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = [
+  ...chatCases({ key: 'MERGE_GATEWAY_API_KEY', base: (host) => `https://${host}/v1`, model: 'zai/glm-5.3-flash' }),
+  ...messagesCases({ key: 'MERGE_GATEWAY_API_KEY', base: (host) => `https://${host}`, model: 'zai/glm-5.3-flash', toolTurn: { toolCalls: [{ name: 'lookup', arguments: {} }] } }),
+];