@volter/twin-standard 1.0.30 → 1.0.31

package/dist/src/clients/aws.js

@@ -0,0 +1,137 @@
+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) => ({
+    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) => (e) => new Error(`${what} failed: ${e.name}: ${e.message}`);
+export const cases = [
+    {
+        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) => { 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) => { throw failed('PutObject')(e); });
+                const out = [];
+                const head = await client.send(new s3.HeadObjectCommand({ Bucket: 'client-case-backups', Key: 'platform-state/one.json' })).catch((e) => { 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) => { 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) => { throw failed('GetObject')(e); });
+                const back = await got.Body.transformToByteArray().catch((e) => { 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.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) => { 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) => { 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) => { 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) => { 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) => { throw failed('CompleteMultipartUpload')(e); });
+                const out = [];
+                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) => { 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) => { 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.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) => { throw failed('CreateSecret')(e); });
+                const got = await client.send(new sm.GetSecretValueCommand({ SecretId: 'client-case/db' })).catch((e) => { throw failed('GetSecretValue')(e); });
+                const out = [];
+                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.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) => e);
+                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.message];
+            }
+            finally {
+                client.destroy();
+            }
+        },
+    },
+];

package/dist/src/clients/cerebras.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/cerebras.js

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

package/dist/src/clients/clerk.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/clerk.js

@@ -0,0 +1,99 @@
+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) {
+    globalThis.fetch = c.fetch;
+    return await import('@clerk/backend');
+}
+async function client(c) {
+    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, who) {
+    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 = [
+    {
+        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 = [];
+            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 = [];
+            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;
+                const failures = [];
+                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 = [];
+            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/dist/src/clients/cloudflare.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/cloudflare.js

@@ -0,0 +1,86 @@
+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) {
+    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) => (e) => new Error(`${what} failed: ${e.message}`);
+export const cases = [
+    {
+        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) => { 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) => { throw failed('customHostnames.create')(e); });
+                const out = [];
+                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' }).catch((e) => { 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.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) => { 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) => { 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.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, init) => 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 = [];
+            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/dist/src/clients/elevenlabs.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/elevenlabs.js

@@ -0,0 +1,39 @@
+const SOCKET = 'https://elevenlabs.io/docs/agents-platform/api-reference/agents-platform/websocket';
+async function client(c) {
+    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 = [
+    {
+        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.' } } } }).catch((e) => e);
+            if (agent instanceof Error)
+                return [`agents.create failed: ${agent.message}`];
+            const signed = await el.conversationalAi.conversations.getSignedUrl({ agentId: agent.agentId }).catch((e) => e);
+            if (signed instanceof Error)
+                return [`conversations.getSignedUrl failed: ${signed.message}`];
+            const url = signed.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((done) => {
+                const ws = new WebSocket(url, { createConnection: c.connect });
+                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) => { clearTimeout(timer); ws.close(); try {
+                    done(String(JSON.parse(String(d)).type));
+                }
+                catch {
+                    done(`a frame that is not JSON: ${String(d).slice(0, 40)}`);
+                } });
+                ws.on('error', (e) => { clearTimeout(timer); done(`the socket failed: ${e.message}`); });
+            });
+            return first === 'conversation_initiation_metadata' ? [] : [`the conversation's first event was ${first}`];
+        },
+    },
+];

package/dist/src/clients/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/gemini.js

@@ -0,0 +1,92 @@
+const REFERENCE = 'https://ai.google.dev/api/generate-content';
+const MODEL = 'gemini-3.8-flash';
+const PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZlSAAAAAASUVORK5CYII=';
+async function routed(c, run) {
+    const previous = globalThis.fetch;
+    globalThis.fetch = c.fetch;
+    try {
+        return await run();
+    }
+    finally {
+        globalThis.fetch = previous;
+    }
+}
+async function chat(c, 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 = [
+    {
+        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.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/dist/src/clients/github.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/github.js

@@ -0,0 +1,71 @@
+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) {
+    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, name) {
+    const made = await client.graphql('mutation($name: String!) { createRepository(input: { name: $name, visibility: PUBLIC }) { repository { nameWithOwner } } }', { name });
+    const [owner, repo] = made.createRepository.repository.nameWithOwner.split('/');
+    return { owner, repo };
+}
+export const cases = [
+    {
+        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 = [];
+                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.name}: ${e.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) => e);
+                if (!raised)
+                    return ['reading an issue the repository does not have answered one'];
+                const out = [];
+                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.name}: ${e.message}`];
+            }
+        },
+    },
+];

package/dist/src/clients/groq.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/groq.js

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

package/dist/src/clients/harness.d.ts

@@ -0,0 +1,36 @@
+import { Agent as HttpsAgent } from 'node:https';
+import { type Socket } from 'node:net';
+/** 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 declare function worldProxy(served: number): Promise<number>;
+/** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
+export declare function clientContext(port: number, host: string, env: Record<string, string>, scenarioPath: string): ClientContext;