Shaduf.Research preview
BuildSDK versions and @typesafe-ai/sdk 0.7.0 failure path checked ; images read at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 and @typesafe-ai/sdk 0.7.0 ; title ; Workers binding as audited 29 Sep 2026; @typesafe-ai/sdk and @ai-sdk/typesafe-ai versions rechecked (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.30 noted, not re-read) and (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.31 and ai 7.0.159 noted, not re-read) and (@typesafe-ai/sdk unchanged; @ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 noted) · @ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 and 7.0.166 compared with the previous versions (@typesafe-ai/sdk unchanged)

Jev TypeScript (TypeSafe AI): @typesafe-ai/sdk vs AI SDK vs fetch, with timeouts and missing-key errors

There are four ways to call Jev from TypeScript: TypeSafe's own SDK, the Vercel AI SDK's experimental_decide (formerly experimental_evaluate), a plain HTTP request, and the Cloudflare Workers binding. They differ in runtime, key variable, field names, default retries and timeouts. This page compares them at pinned versions and lists thirteen TypeScript-specific mistakes.

Short answer

TypeScript today: @typesafe-ai/sdk is at 0.7.0 (14 Oct 2026; adds experimental image support). It throws at client creation without a key; checked at 0.7.0 (18 Oct 2026), the failure path is unchanged from 0.6.0, except that input errors now reject the returned promise. The AI SDK provider (3.0.26 on 23 Oct 2026) throws LoadAPIKeyError at the first call (read at 3.0.18); ai 7.0.128 renamed experimental_evaluate to experimental_decide. Documented 14 Oct 2026; package versions and 0.7.0 failure path 18 Oct 2026

For TypeSafe direct on Node 22 or later, use the official @typesafe-ai/sdk (0.7.0 since 14 Oct 2026, needs Node 22; 0.6.0 runs on Node 20; defaults and error classes read at 0.6.0 and checked unchanged at 0.7.0 on 18 Oct 2026). If you use Vercel AI Gateway or already use the AI SDK, use AI SDK experimental_decide (ai 7.0.128 or later; the older name experimental_evaluate still works as a deprecated alias at 7.0.140). For other runtimes or routes, use raw fetch and add your own retry and timeout. Documented package sources and docs, checked 29 Sep 2026

Version check, 18 Oct 2026; image path 23 Oct 2026; versions rechecked 9 Nov 2026

Versions rechecked 9 Nov 2026: @typesafe-ai/sdk is still 0.7.0. @ai-sdk/typesafe-ai 3.0.35 (7 Nov 2026), compared with 3.0.34 on 9 Nov 2026: it now rejects empty Choice or Score criteria and empty Score levels before sending, sends primitive JSON state as text, and returns Score legends in provider metadata; the image and error handling lines are not in that diff. ai 7.0.165 (7 Nov) and 7.0.166 (9 Nov 2026): the decide functions are unchanged from 7.0.164 (compared 9 Nov 2026); the changes are telemetry and documentation. The readings on this page stay at the versions named in them; the provider versions between 3.0.26 and 3.0.34 were not compared line by line. Documented npm registry and package tarballs, 9 Nov 2026, 11:10 UTC; R29-S18, R29-S19, R29-S20 Change, 9 Nov 2026: this recheck added; the 8 Nov and 31 Oct rechecks moved into the list of earlier version checks. No reading changed.

Checked at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 (23 Oct 2026): it still sends the images header automatically for PNG or JPEG image parts, and since 3.0.21 also for Box questions (src/typesafe-ai-decision-model.ts L245–248); other media types and image URLs are rejected before the call (L148–158). @typesafe-ai/sdk 0.7.0: the SDK does not check image format or size; it sends what you give it and the API returns 400 or 413. You add the opt-in header yourself (dist/index.mjs L226–264). Images are experimental and opt-in; TypeSafe says they are not yet ready for production. Documented npm package files read 23 Oct 2026, 05:23–05:29 UTC; the 3.0.26 src/ is identical to 3.0.24. Nothing was installed or run and no image was sent. R22-S106, R22-S116, R22-S108, R22-S100 All SDKs and integrations read: Jev with images: does your SDK or integration send them?

Checked at @typesafe-ai/sdk 0.7.0 (18 Oct 2026): the failure path is the same as 0.6.0: a missing key throws TypeSafeError in the constructor, 10,000 ms per attempt, 2 retries on 408, 429 and 5xx with 500 ms to 5 s back-off, the same error classes, and jev-latest by default. New in 0.7.0: input errors such as empty questions or missing state now reject the returned promise instead of throwing at the call, request bodies of 1 KiB or more are zstd-compressed by default on Node 22.15+ (compression: false turns this off), and the package now needs Node 22. Documented read at the published 0.7.0 and 0.6.0 packages, 18 Oct 2026, 05:18 UTC; 0.7.0 dist/index.mjs: error classes L147, L172–178; retry and back-off L52–65; timeout L909; missing key L754, L903; default model L905; promise rejection L946–961; compression L523–524, L911; package.json L31 (engine >=22, was >=20). Nothing was installed or run. R18-S227, R18-S228, R18-S229

On 18 Oct 2026, 05:17 UTC, jev-latest still pointed to jev-1.13.0 and jev-preview to jev-1.14.0; TypeSafe has said jev-latest moves to 1.14 about a week after 14 Oct, with no date published (R18-S05). Update, 24 Oct 2026: the default model of @typesafe-ai/sdk 0.7.0 is jev-latest (dist/index.mjs L905), which on TypeSafe's API pointed to jev-1.14.0 on 24 Oct 2026, 05:12 UTC (it pointed to jev-1.13.0 until at least 23 Oct 2026, 05:45 UTC). Pin jev-1.13.0 if your thresholds were tuned on 1.13. The SDK versions are unchanged (@typesafe-ai/sdk 0.7.0, @ai-sdk/typesafe-ai 3.0.26 on npm, 24 Oct 2026, 05:18 UTC), so the published file:line pins still apply (R23-S05, R23-S41). Pin jev-1.13.0 or jev-1.14.0 if you need stable answers. Images and Box are experimental and not production-ready per TypeSafe.

AI SDK: @ai-sdk/typesafe-ai 3.0.21 (16 Oct) is a patch release; the page's reading is at 3.0.20. Checked at ai 7.0.143 (18 Oct 2026): patch release; failure path not re-read. Documented npm registry, 18 Oct 2026, 05:23 UTC (R18-S57)

Examples: the @typesafe-ai/sdk example below stays pinned at 0.6.0 (Node 20) and the AI SDK example at ai 7.0.122 and @ai-sdk/typesafe-ai 3.0.10, the versions they were written for. On 0.7.0, wrap the call in try/await so input errors are caught with API errors.

Change, 31 Oct 2026: version recheck added at the top of this box (@typesafe-ai/sdk 0.7.0 unchanged; @ai-sdk/typesafe-ai 3.0.30 → 3.0.31 and ai 7.0.157 → 7.0.159 noted, patches, not re-read) and in the facts below; the 30 Oct recheck moved into the list of earlier version checks (R25-S36).

Change, 30 Oct 2026: version recheck added at the top of this box (@typesafe-ai/sdk 0.7.0 unchanged; @ai-sdk/typesafe-ai 3.0.26 → 3.0.30 and ai 7.0.152 → 7.0.157 noted, patches, not re-read) and in the facts below (R24-S35, R24-S39).

Change, 24 Oct 2026: the alias paragraph adds the 24 Oct check (on TypeSafe's API jev-latest, the SDK default, pointed to jev-1.14.0, first seen 05:12 UTC); SDK versions unchanged; ai 7.0.152 noted in the facts (not re-read) (R23-S05, R23-S41).

Change, 23 Oct 2026: image handling read at @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 (header now also sent for Box questions) and at @typesafe-ai/sdk 0.7.0 (no client-side format or size check); provider version 3.0.21 → 3.0.26 in the short answer and facts. The failure-path readings are unchanged.

Change, 18 Oct 2026: the failure path of @typesafe-ai/sdk 0.7.0 was read and is unchanged from 0.6.0 (this box said "0.7.0's error path not yet re-read"); three smaller changes added (rejected promise for input errors, zstd request compression, Node 22). @ai-sdk/typesafe-ai 3.0.20 → 3.0.21 and ai 7.0.140 → 7.0.143 noted (patches; not re-read).

Earlier version checks (13, newest first)
  • Versions rechecked 8 Nov 2026: @typesafe-ai/sdk is still 0.7.0; @ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 (7 Nov 2026) are newer than the versions this page describes; not re-read. The readings on this page stay at the versions named in them. Documented npm registry, 8 Nov 2026, 05:25 UTC; R28-S47 Change, 8 Nov 2026: this recheck added; the 31 Oct recheck below is kept as dated. No reading changed. (@ai-sdk/typesafe-ai 3.0.35 and ai 7.0.165 were compared on 9 Nov 2026, see the recheck above.)
  • Versions rechecked 31 Oct 2026: @typesafe-ai/sdk is still 0.7.0; @ai-sdk/typesafe-ai 3.0.31 was released on 30 Oct 2026 (15:39 UTC; patch); this site last read the provider at 3.0.26 (image path; its failure path at 3.0.18); newer version exists, not re-read. ai 7.0.159 was published on 30 Oct 2026 (22:18 UTC, after 7.0.158 at 15:38 UTC; patch; not re-read). The readings on this page stay at the versions named in them, and the examples stay at their pinned versions. The 30 Oct recheck is now in the list of earlier version checks below. Documented npm registry, 31 Oct 2026, 05:14 UTC; R25-S36
  • Versions rechecked 30 Oct 2026: @typesafe-ai/sdk is still 0.7.0; @ai-sdk/typesafe-ai 3.0.30 was released on 29 Oct 2026; this site last read the provider at 3.0.26 (image path; its failure path at 3.0.18); 3.0.30 was not re-read. The provider had four patch releases after the 24 Oct check (3.0.27 on 24 Oct to 3.0.30 on 29 Oct, 17:10 UTC); ai 7.0.157 was published on 29 Oct 2026 (patch; not re-read). Documented npm registry and the SDK's release feed (latest v0.7.0, 14 Oct), 30 Oct 2026, 05:20–05:21 UTC; R24-S35, R24-S39
  • 16 Oct 2026, 05:25 UTC: @typesafe-ai/sdk 0.6.0 → 0.7.0 (npm, 14 Oct 2026, 21:25 UTC) and @ai-sdk/typesafe-ai 3.0.18 → 3.0.20. 0.7.0 adds image and Box types; its README says "Image support is experimental", opt in with the TypeSafe-Danger-Zone-Images: true header via defaultHeaders (README L42-47); default model still jev-latest (dist/index.mjs L905). The error path was then read at 0.6.0 only. Read from the published package; nothing was installed or run. Documented (R17-S38, R17-S05, R17-S09)
  • 14 Oct 2026: Checked at @typesafe-ai/sdk 0.6.0 (released 15 Sep 2026; still the latest), ai 7.0.140 (released 14 Oct 2026, 04:19 UTC) and @ai-sdk/typesafe-ai 3.0.18 (released 12 Oct 2026, 17:47 UTC). Defaults: @typesafe-ai/sdk 10 s timeout and a missing key throws TypeSafeError when the client is created; AI SDK maxRetries 2, no timeout option on the decision call (pass abortSignal), and with the TypeSafe provider a missing key throws LoadAPIKeyError at the first call. Read 14 Oct 2026 from the published packages (nothing installed or run). The Cloudflare Workers binding row was not re-read (audited 29 Sep 2026). Documented R16-S207, R16-S208 (@typesafe-ai/sdk); R16-S209, R16-S215, R16-S216 (ai); R16-S210 to R16-S214 (provider); R13-S306, R13-S307, R13-S310 (0.6.0 defaults) Examples: the AI SDK example below was written for ai 7.0.122 and @ai-sdk/typesafe-ai 3.0.10; current versions are 7.0.140 and 3.0.18. experimental_evaluate and evaluationModel still work at those versions as deprecated aliases of experimental_decide and decisionModel. Change, 14 Oct 2026: ai 7.0.122 → 7.0.140 and provider 3.0.10 → 3.0.18 in the facts and comparison table; the AI SDK function is now experimental_decide (renamed in 7.0.128); new provider cells (base URL, missing key); new gotcha TS13 (state arrays); new page title. @typesafe-ai/sdk stays at 0.6.0.
  • 13 Oct 2026, 05:22 UTC: @ai-sdk/typesafe-ai 3.0.18 and ai 7.0.138 released 12 Oct 2026 (patches); not re-audited. @typesafe-ai/sdk is still 0.6.0. Documented (npm: @ai-sdk/typesafe-ai, npm: ai, R15-S52)
  • 11 Oct 2026, 05:22 UTC: No newer release of ai (7.0.137), @ai-sdk/typesafe-ai (3.0.17) or @typesafe-ai/sdk (0.6.0) since 10 Oct. @effect/ai-typesafe 4.0.3 was published on 10 Oct 2026 (patch; framework integrations audits 4.0.1); not re-audited. The @typesafe-ai/sdk 0.6.0 defaults in the table below were re-read from the published package on 11 Oct: 10,000 ms per attempt, maxRetries 2, no total retry budget; a missing key throws TypeSafeError in the constructor. (R13-S35, R13-S306, R13-S307, R13-S310)
  • 10 Oct 2026, 05:18 UTC: Newer patch releases: ai 7.0.137 and @ai-sdk/typesafe-ai 3.0.17 (8–9 Oct 2026); not re-audited. (ai 7.0.137 published 9 Oct, 14:54 UTC, with 7.0.134–7.0.136 also since 8 Oct; @ai-sdk/typesafe-ai 3.0.17 published 8 Oct, 21:40 UTC; @typesafe-ai/sdk still 0.6.0; R12-S35, R12-S48.)
  • 8 Oct 2026, 05:14 UTC: Newer patch releases: ai 7.0.133 and @ai-sdk/typesafe-ai 3.0.16, 8 Oct 2026; not re-audited. (ai 7.0.133 published 00:30 UTC, 7.0.131 and 7.0.132 on 7 Oct; @ai-sdk/typesafe-ai 3.0.16 published 00:32 UTC; were 7.0.130 and 3.0.15.) @typesafe-ai/sdk is still 0.6.0. Documented (npm: ai, npm: @ai-sdk/typesafe-ai, npm: @typesafe-ai/sdk, R11-S35)
  • 7 Oct 2026, 05:19 UTC: newer patch releases: ai 7.0.130 and @ai-sdk/typesafe-ai 3.0.15, 7 Oct 2026 (01:47 and 01:41 UTC; 7.0.129 and 3.0.14 came out on 6 Oct, 22:23 and 22:20 UTC; were 7.0.128 and 3.0.13); not re-audited. @typesafe-ai/sdk is still 0.6.0. Documented (npm: ai, npm: @ai-sdk/typesafe-ai and npm: @typesafe-ai/sdk, R10-S35)
  • 6 Oct 2026, 05:15 UTC: newer patch releases: ai 7.0.128 and @ai-sdk/typesafe-ai 3.0.13, 5 Oct 2026 (18:25 and 18:26 UTC; were 7.0.127 and 3.0.12); not re-audited. @typesafe-ai/sdk is still 0.6.0. Documented (npm: ai, R9-S36; npm: @ai-sdk/typesafe-ai, R9-S37; npm: @typesafe-ai/sdk, R9-S35)
  • 2 Oct 2026, 05:14 UTC (updated 8 Oct): Newer releases appeared after this page's audit: ai 7.0.123 to 7.0.126 (30 Sep) and now 7.0.127 (1 Oct, 19:20 UTC), and @ai-sdk/typesafe-ai 3.0.11 and 3.0.12 (30 Sep, 02:20 and 17:49 UTC) (npm: ai, npm: @ai-sdk/typesafe-ai, checked 2 Oct 2026, 05:14 UTC). This page's audit used ai 7.0.122 and @ai-sdk/typesafe-ai 3.0.10. The new releases were not re-audited: the defaults, field names and gotchas below apply to the audited versions. @typesafe-ai/sdk is unchanged at 0.6.0 and @ai-sdk/typesafe-ai at 3.0.12 (checked 2 Oct 2026, 05:14 UTC). Documented
  • 29 Sep 2026, 07:14–07:16 UTC: page audited at @typesafe-ai/sdk 0.6.0, ai 7.0.122 and @ai-sdk/typesafe-ai 3.0.10.
Official SDK
@typesafe-ai/sdk 0.7.0, npm 14 Oct 2026, 21:25 UTC; still the latest on 18 Oct 2026 (R18-S227), on 30 Oct 2026, 05:21 UTC (R24-S35, R24-S39) and on 31 Oct 2026, 05:14 UTC (npm; R25-S36). Defaults and error classes on this page read at 0.6.0, npm 15 Sep 2026, 18:17 UTC; tag 66880cc; checked unchanged at 0.7.0 on 18 Oct 2026 (R18-S229); 0.7.0 needs Node 22; MIT
Images
Experimental, not production-ready per TypeSafe. @typesafe-ai/sdk 0.7.0: opt in with the TypeSafe-Danger-Zone-Images: true header via defaultHeaders (README L42-47); it does not check image format or size (dist/index.mjs L226–264; read 23 Oct 2026, R22-S108). @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 send it automatically for PNG or JPEG image parts and, since 3.0.21, Box questions; other media types and image URLs are rejected before the call (read 23 Oct 2026; R22-S106, R22-S116)
AI SDK core
ai 7.0.143, 16 Oct 2026, 20:10 UTC (checked 18 Oct 2026; patch, not re-read; R18-S57). ai 7.0.152 was published on 23 Oct 2026; not re-read (R23-S41). ai 7.0.157 was published on 29 Oct 2026, 17:10 UTC; not re-read (R24-S35). ai 7.0.159 was published on 30 Oct 2026, 22:18 UTC (patch; newer version exists, not re-read; R25-S36). Last read at 7.0.140; Apache-2.0 (audited at 7.0.122)
AI SDK function name
experimental_decide since 7.0.128; experimental_evaluate is a deprecated alias, still exported at 7.0.140
First ai with experimental_evaluate
7.0.103 (16 Sep) by package contents; Vercel's guide says 7.0.105
AI SDK direct provider
@ai-sdk/typesafe-ai 3.0.26, 22 Oct 2026, 21:19 UTC (3.0.25 earlier the same day; R22-S41); 3.0.30 was released on 29 Oct 2026, 17:10 UTC (patch; newer version exists, not re-read; R24-S35); 3.0.31 was released on 30 Oct 2026, 15:39 UTC (patch; newer version exists, not re-read; R25-S36); image path read at 3.0.24 and 3.0.26 on 23 Oct 2026 (header L245–248; R22-S106, R22-S116). At 3.0.20 (npm package files read 16 Oct 2026, 05:25 UTC): model IDs include jev-1.13.0, jev-1.14.0, jev-latest; sends the images header automatically when a request carries PNG or JPEG image parts and the long-context header when longContext is set (src/typesafe-ai-decision-model.ts L34-36, L119-216, L229-233; R17-S39). Key and error path read at 3.0.18 (12 Oct 2026, 17:47 UTC); audited at 3.0.10
Provider base URL
https://api.typesafe.ai/v1 (env TYPESAFE_AI_BASE_URL; POST <base>/systemone)
Node
SDK ≥ 20; ai and @ai-sdk/typesafe-ai ≥ 22

Which path fits your project

If your project…UseBecause
Runs on Node 20 or 21@typesafe-ai/sdk or raw fetchai declares Node ≥ 22
Calls Jev through Vercel AI Gatewayexperimental_decide (formerly experimental_evaluate) with 'typesafe-ai/jev'The gateway string and AI_GATEWAY_API_KEY (or Vercel OIDC) are built in
Wants typed helpers and mapped error classes for TypeSafe direct@typesafe-ai/sdkchoice(), score(), noul() and one error class per status
Runs on Cloudflare Workersenv.AI.run('typesafe/jev', …)No package or TypeSafe key; the account binding authenticates
Uses another route, runtime or a gateway without an SDKRaw fetchStable HTTP contract; you write retry, timeout and parsing
Must not stop working after a minor upgradePin exact versionsThe AI SDK function is experimental and "may change in patch releases" (it was renamed in 7.0.128); the SDK is 0.x

Comparison at pinned versions

Documented SDK source at tag v0.6.0 (retry.ts, errors.ts, client.ts); AI SDK evaluate reference, evaluation guide and TypeSafe provider page; Cloudflare model page; all checked 29 Sep 2026. AI SDK column rechecked at ai 7.0.140 and @ai-sdk/typesafe-ai 3.0.18 on 14 Oct 2026 from the published packages (R16-S209 to R16-S216); Workers column not re-read.

Field@typesafe-ai/sdk (official)AI SDK experimental_decideRaw fetchCloudflare Workers binding
Installnpm install @typesafe-ai/sdknpm i ai, plus @ai-sdk/typesafe-ai for TypeSafe directNothingenv.AI binding in the wrangler config
RuntimeNode ≥ 20; ESM, CJS and types. Refuses to run in a browser unless dangerouslyAllowBrowser: trueNode ≥ 22Any runtime with fetchCloudflare Workers
RoutesTypeSafe direct; baseURL (TYPESAFE_BASE_URL) for compatible endpointsGateway string 'typesafe-ai/jev', or typeSafeAi.decisionModel('jev-latest') for TypeSafe direct (evaluationModel still works as an alias at 3.0.18)Any System One endpointCloudflare typesafe/jev
Key variableTYPESAFE_API_KEYGateway: AI_GATEWAY_API_KEY. Direct provider: TYPESAFE_AI_API_KEY; a missing key throws LoadAPIKeyError at the first call, not at provider creation (fail-closed unless the caller catches it)Your choiceAccount binding
Answer fieldsChoice choice, probabilities, confidence; Score score, legend, probabilities, confidence; Noul noul; usage.input_tokens, usage.output_tokens; modelChoice .choice; Score .score; Noul is called boolean and returns .probability; confidence at providerMetadata.typesafe.confidence[id]; usage.inputTokens; warnings; response.modelIdAs the API referenceNot re-read on 29 Sep (the page shows console.log(response) only)
Default retries2 retries on 408, 429, 5xx (including 529), connection errors and timeouts; backoff 0.5 s doubling to 5 s with up to 25% jitter; honours retry-after-ms and Retry-After up to 60 smaxRetries 2 in Core for transient failures (e.g. 429, 529), unchanged at 7.0.140; malformed answers are not retriedNoneNot documented on the page read
Default timeout10 s per attempt; no total budget found in the JS source (the Python SDK has a 30 s budget)None documented; the decide signature has no timeout at 7.0.140; pass abortSignalNoneNot documented on the page read
ErrorsBadRequestError 400, AuthenticationError 401, PermissionDeniedError 403, NotFoundError 404, UnprocessableEntityError 422, RateLimitError 429, InternalServerError ≥ 500, APIConnectionError, APITimeoutError, APIUserAbortError. A missing key throws at constructionAPICallError (provider failures incl. auth and validation), InvalidArgumentError, InvalidResponseDataError (malformed answers), Experimental_DecisionUnsupportedQuestionTypeError (the old Experimental_EvaluationUnsupportedQuestionTypeError is still exported), Experimental_DecisionRefusalError (from 7.0.130), NoSuchModelError; LoadAPIKeyError for a missing provider keyWhatever you mapWorkers AI error codes (see errors page)
Test facilityfetch option: "Custom HTTP fetch implementation for transport configuration or tests"Experimental_EvaluationMockModelV4 from ai/test, still exported at 7.0.140; Experimental_DecisionMockModelV4 is also exportedA local mock serverNot documented
Stability0.x; nine open issues (below)Experimental: "may change in patch releases"Stable HTTP contractRoute-owner page

Two things that differ between sources

  • First AI SDK version. experimental_evaluate is absent from the type declarations of ai 7.0.102 and present in 7.0.103 (published 16 Sep 2026, 18:36 UTC). Vercel's guide says "Install AI SDK 7.0.105 or later". This page uses 7.0.105 as the minimum and records the conflict. Documented package contents read, not installed; 29 Sep
  • Key variable name. The official SDK reads TYPESAFE_API_KEY. The AI SDK's direct provider reads TYPESAFE_AI_API_KEY. A key set under the wrong name is a "missing key" error, not a Jev error. Documented SDK env.ts; ai-sdk.dev provider page; 29 Sep

Minimal Choice call per path

Each example asks one Choice question about a support message. The code follows each owner's published example and has not been run by the pool, which has no API key. Model IDs differ by route; the current IDs are in the route matrix.

1. @typesafe-ai/sdk 0.6.0 Documented, not executed SDK README and docs JavaScript page

// npm install @typesafe-ai/sdk@0.6.0        (Node >= 20, server side only)
// export TYPESAFE_API_KEY=...
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();          // throws at once if the key is missing
const response = await client.systemOne({
  state: "I was charged twice for my subscription this month.",
  questions: {
    category: choice("What is this ticket about?", { billing: null, technical: null, other: null }),
  },
});

console.log(response.answers.category.choice, response.answers.category.confidence);
console.log(response.model);                  // log which versioned model answered

The documented example sets no model, so the SDK default alias jev-latest applies. What jev-latest points to, and which ID to pin on each route: Jev model IDs and aliases by route.

2. AI SDK experimental_evaluate (now experimental_decide) through Vercel AI Gateway Documented, not executed ai-sdk.dev evaluation guide and TypeSafe provider page. Kept at its audited pins (ai 7.0.122, @ai-sdk/typesafe-ai 3.0.10), where the old names apply; they still work at 7.0.140 as deprecated aliases. The full option shape of experimental_decide was not read, so the code is not moved to the new names.

// npm i ai@7.0.122                          (Node >= 22; 7.0.105 or later per Vercel)
// export AI_GATEWAY_API_KEY=...
import { experimental_evaluate } from "ai";

const result = await experimental_evaluate({
  model: "typesafe-ai/jev",
  state: "I was charged twice for my subscription this month.",
  questions: {
    department: {
      type: "choice",
      instructions: "Which team should handle this?",
      criteria: { billing: "Payments and invoices", technical: "Bugs and integrations", other: null },
    },
  },
});

console.log(result.answers.department.choice);
console.log(result.providerMetadata?.typesafe?.confidence?.department);  // confidence is not on the answer

For TypeSafe direct instead of the gateway, install @ai-sdk/typesafe-ai, set TYPESAFE_AI_API_KEY, and pass model: typeSafeAi.evaluationModel("jev-latest") (base URL https://api.typesafe.ai/v1). At 3.0.18 evaluationModel is an alias of decisionModel, and a missing key throws LoadAPIKeyError at the first call.

3. Raw fetch Documented, not executed request shape from the docs quickstart; the timeout line is the pool's addition

const res = await fetch("https://api.typesafe.ai/v1/systemone", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "jev-1.13.0",
    state: "I was charged twice for my subscription this month.",
    questions: {
      category: { type: "choice", instructions: "What is this ticket about?",
                  criteria: { billing: null, technical: null, other: null } },
    },
  }),
  signal: AbortSignal.timeout(10_000),        // raw fetch has no timeout unless you set one
});
if (!res.ok) throw new Error(`Jev ${res.status}: ${await res.text()}`);
const body = await res.json();
console.log(body.answers.category.choice, body.answers.category.confidence);

A retry loop for this path, tested offline against a local mock server, is the worked example on Testing without a key.

4. Cloudflare Workers binding Documented, not executed Cloudflare model page for typesafe/jev

export default {
  async fetch(request, env) {
    const response = await env.AI.run("typesafe/jev", {
      state: "I was charged twice for my subscription this month.",
      questions: {
        department: { type: "choice", instructions: "Which team should handle this?",
                      criteria: { billing: null, technical: null, other: null } },
      },
    });
    return Response.json(response);
  },
};

How long a call can take with default settings

With the official SDK's defaults and an endpoint that never answers, one call makes 3 attempts of 10 s each, with 0.5 s and 1 s waits between them. That adds up to about 31.5 s. The Claude Code plugins audited on Claude Code and MCP give a hook 10–15 s. Set a per-call timeout shorter than your caller's deadline.

One call to a hanging endpoint, 0–31.5 s

SDK defaults: 3 × 10 s attempts, 0.5 s and 1 s backoff (derived arithmetic)

Red line: a 15 s hook deadline. The caller gives up during the second attempt, while the SDK is still retrying.

Same retry pattern at 800 ms per attempt, Tested offline 3.9 s

The pool's offline test (T04) measured 3,908 ms for this case against a local mock server.

Blue: attempts; gray: backoff waits. The 31.5 s figure is derived from retry.ts defaults, not measured. Documented defaults, 29 Sep 2026.

TypeScript gotchas

Status codes and their meanings are on Errors and rate limits. This table lists only problems specific to the TypeScript paths.

#GotchaWhat to doSource and label
TS1Question type must be lowercase (choice, score, noul); capitalised types return 400Use the SDK helpers choice(), score(), noul()oh-my-claudecode #4091 Reported
TS2state: null returns 422, and the JS SDK does not stop it locallyValidate state before callingtypesafe-sdk-js #6 Reported
TS3The model ID differs by route: jev-1.13.0 or jev-latest direct; typesafe-ai/jev on Vercel; typesafe/jev-1.13 on OpenRouter; typesafe/jev on CloudflareKeep the ID in configuration per route; check the model IDs and aliases by routeRoute pages Documented 29 Sep
TS4Three key variables: TYPESAFE_API_KEY (official SDK), TYPESAFE_AI_API_KEY (AI SDK direct provider), AI_GATEWAY_API_KEY (gateway)Set the one your path reads. The official SDK throws at construction if it is missing; the AI SDK direct provider throws LoadAPIKeyError at the first call (3.0.18, read 14 Oct 2026)SDK env.ts L1–11; ai-sdk.dev; provider dist/index.js L156–163 (R16-S211, R16-S214) Documented
TS5The AI SDK calls a Noul boolean and returns .probability, not .noul; confidence sits in providerMetadata.typesafe.confidenceDo not port field names between pathsai-sdk.dev Documented
TS6Double retries: the SDK and the AI SDK each retry twice by default; a wrapper that retries on top multiplies calls and costSet maxRetries: 0 (AI SDK) or retry: { maxRetries: 0 } in the lower layer when you retry yourselfretry.ts; ai-sdk.dev Documented
TS7Worst case with SDK defaults and a hanging endpoint is about 31.5 s (see the figure)Pass a per-call timeout or abortSignal shorter than your caller's deadlineDerived from retry.ts; T04 shows the pattern at 800 ms
TS8Vercel's free tier returns 429 rate_limit_exceededHandle it separately from TypeSafe's own 429Vercel rate-limit docs Documented (28 Sep)
TS9The SDK throws in a browser unless dangerouslyAllowBrowser: true, and that setting would expose the keyCall Jev from a server routeclient.ts L60–65, L268 Documented
TS10Cancelling a call can terminate Node 20 and 22 (open issue #2); jkudish/jev-mcp routes around itAvoid aborting in-flight SDK calls on those Node versions, or use raw fetchtypesafe-sdk-js #2; jkudish README L757 Reported
TS11The AI SDK function "may change in patch releases": ai 7.0.128 renamed experimental_evaluate to experimental_decide. The old name is a deprecated alias at 7.0.140; per the 7.0.129 changelog it warns on use (the warning was not read in code)Pin the exact ai version; move to experimental_decide when you upgradeai-sdk.dev; ai 7.0.140 changelog and dist/index.js L13126–13127 (R16-S215) Documented
TS12Probabilities are rounded to 2 decimals and may not sum to 1Do not assert exact sums in testsai-sdk.dev provider page Documented
TS13From @ai-sdk/typesafe-ai 3.0.16 (and ai 7.0.133): "Arrays passed directly as state now contain decision state parts.""Wrap JSON arrays in an object or a json part."Provider 3.0.18 changelog (R16-S211), read 14 Oct 2026 Documented

Open issues in the official JS SDK

Open on GitHub on 29 Sep 2026. Each is the reporter's description, not rerun by the pool. Reported

  • #2: a handled cancellation can crash Node 20 and 22.
  • #6: noul() with no arguments, and state: null, build requests the API rejects.
  • #8: timeouts above Node's timer maximum fire after about 1 ms.
  • #9: a blank Retry-After header bypasses backoff.
  • #12: score() accepts a null level, which returns 422.
  • #13: 402 and 413 fall through to a generic APIError.
  • #14: the API key can be echoed into APIConnectionError, and an empty key is sent.
  • #15: Cloudflare HTML 403 when the state contains curl text.
  • #17: non-finite numbers serialise as null.

Issue list: typesafe-ai/typesafe-sdk-js issues.

Projects that use these paths

ProjectWhat its code doesLabel and date
Jevmail classify.tsCalls experimental_evaluate({ model: 'typesafe-ai/jev', …, maxRetries: 0 }), then runs its own 429 wait-and-retry-once and 5xx retry-once. This avoids stacking the AI SDK's 2 retries under its own (TS6).Documented 28 Sep audit, not re-audited
Vercel template jev-ai-sdk-form-routerCONFIDENCE_THRESHOLD = 0.95. The Jev call uses AbortSignal.timeout(12_000) and maxRetries: 1. If confidence is below 0.95 or missing, or Jev fails, it calls a fallback LLM (25 s, 1 retry). A missing confidence counts as a fallback, not a pass. package.json pins ai 7.0.107. The fallback model is openai/gpt-6-luna-fast in source but openai/gpt-5.6-luna-fast on the template page.Documented at 27ea469 (22 Sep), checked 29 Sep
MSFT-TKENDRICK/JEV-examplesThe author states the examples were never executed live. Not opened by the pool.Reported

Seen only: TanStack AI decide() with vercelGatewayDecider('typesafe-ai/jev') or cloudflareDecider('typesafe/jev'), described by Vercel. TanStack AI's direct package, @tanstack/ai-typesafe 1.0.0, was read at commit 5651e07 on 31 Oct 2026: it raises Jev errors to your code; see framework integrations. LangChain JS (@langchain/typesafe 0.0.2) and @effect/ai-typesafe 4.0.1 were read on 5 Oct 2026: see framework integrations. For TypeScript demo videos, see the TypeScript group on the videos page.

What was not verified

  • No example on this page was run. The official JS SDK was not installed, and the AI SDK was read from its published type declarations and docs.
  • The AI SDK's default timeout is undocumented. The changes in @ai-sdk/typesafe-ai 3.0.9 and 3.0.10 (both 28 Sep) were not compared.
  • The Cloudflare binding's response shape, retries and timeout were not re-read on 29 Sep.
  • The 31.5 s worst case is arithmetic from SDK defaults, not a measurement.
  • On 16 Oct 2026 @typesafe-ai/sdk 0.7.0 (README, default model) and @ai-sdk/typesafe-ai 3.0.20 (model IDs, opt-in headers) were read as files; nothing was installed or run. No image, Box or long-context request was sent. On 18 Oct 2026 the published 0.7.0 and 0.6.0 packages were compared file by file (dist/index.mjs, package.json, README; the .cjs build at its constants only); nothing was installed or run.
  • On 23 Oct 2026 @ai-sdk/typesafe-ai 3.0.24 and 3.0.26 and @typesafe-ai/sdk 0.7.0 were read as package files for their image path only; nothing was installed or run and no image was sent. The failure path of the AI SDK provider was not re-read.
  • On 14 Oct 2026 the packages were read as files; nothing was installed or run. Not read: the full option shape of experimental_decide, the deprecation warning text, and the Cloudflare Workers binding (audited 29 Sep 2026).

Search published pools, pages, reports, and evidence.