Implement planned topic: 0038-vercel-ai-sdk

[skill-temporal-developer-updater]

Skill Validation Report — 0038-vercel-ai-sdk

Skill: Vercel AI SDK (TypeScript integration)
Skill root: .
Branch: draft/0038-vercel-ai-sdk
Files under review (uncommitted on this draft branch):

• references/typescript/integrations/vercel-ai-sdk.md (new, 200 lines)
• references/integrations.md (one row added)

Primary docs source: ../documentation/docs/develop/typescript/integrations/ai-sdk.mdx (275 lines)

This is a third-party integration topic with a catalog convention in place, so Check 5 applies. The topic ships a per-language API only (TypeScript), so Check 7 does not apply.

---

Go/no-go

Check	Verdict
1. Citation audit	PASS
2. Reverse-grep audit	PASS
3. Regression on known bugs	PASS
4. Independent re-verification (sample)	PASS (10/10)
5. Integration-layout audit	PASS
6. Tone and scope audit	PASS
7. Cross-language structure audit	N/A (single-language integration)

Overall verdict: GO. All applicable checks pass their thresholds. No findings warrant a re-authoring pass or spot-fix.

---

Check 1 findings — citation audit

Mechanically resolved every <!-- docs/… --> inline comment in references/typescript/integrations/vercel-ai-sdk.md. All citations point to docs/develop/typescript/integrations/ai-sdk.mdx, which exists (275 lines).

Authored line	Cited range	Cited text supports claim?
L5 (overview)	17–24	Yes — plugin auto-wraps generateText() as Activities; tools/MCP framing reinforced by 152–158 / 209–215 elsewhere in same file.
L9 (Public Preview note)	30–35	Yes — :::info block marks Public Preview.
L15 (TS SDK prerequisites)	44–46	Yes — docs point at the local-setup guide; the package list is a normal expansion.
L16 (AI SDK familiarity)	39–40	Yes — verbatim guidance.
L17 (credentials)	98–107	Yes — Worker-only credentials supported by both the prose and the :::tip block.
L24 (npm install)	56–60	Yes — exact command.
L28 (Worker plugin setup)	62–89	Yes — covers Worker.create + plugin + modelProvider + same Task Queue/Namespace.
L49 (worker code block)	64–85	Yes — code matches verbatim except for import * as activities from './activities' which is the expected expansion of the docs’ omitted-imports comment.
L51 (TQ/NS alignment)	87–89	Yes — verbatim.
L55 (use the AI SDK in workflow)	131–147	Yes — language-model proxy + Activity behavior supported by adjacent 149–150.
L70 (haiku code)	135–147	Yes — code block matches.
L72 (Durable Execution benefits)	149–150	Yes — phrasing tightened but substantively identical.
L76 (tool/Activity delegation)	152–158	Yes — proxyActivities is the canonical mechanism shown in the code block below at 180.
L91 (Activity code)	163–173	Yes — code matches.
L125 (workflow with tool)	179–207	Yes — code matches.
L129 (MCP intro)	209–215	Yes — "stateless MCP client … inside Workflows" is verbatim.
L133 (mcpClientFactories)	218–251	Yes — covers factory map, factory builder, plugin registration, multi-server registration.
L159 (MCP factory code)	221–251	Yes — matches the docs code block.
L161 (Stdio startup behavior)	236–238	Yes — verbatim.
L165 (TemporalMCPClient + tools())	254–274	Yes — matches the docs code + commentary.
L184 (MCP agent code)	256–271	Yes — matches.
L188 (import-source common mistake)	65–66, 136–137, 181–182, 222, 257	Yes — each cited line shows the import from the named package.
L189 (no direct I/O in tool execute)	154–207	Yes — docs explicitly state tool functions follow Workflow rules and delegate to Activities.
L190 (only two AiSdkPlugin options)	73–75, 243–249	Yes — these are the only options shown in the canonical examples. The "only two are documented" claim is a documentation-absence assertion that is accurate.
L191 (object-form constructor)	260	Yes — new TemporalMCPClient({ name: 'testServer' }).
L192 (TQ/NS mismatch)	87–89	Yes — restated negative form of the docs guidance.
L193 (no provider creds on client)	102–106	Yes — verbatim concept.
L198 (provider list link)	99–100	Yes — ai-sdk.dev/providers/ai-sdk-providers is the link surfaced in the docs.

Pass criterion (≥ 98%): 28/28 = 100% resolve cleanly.

Hyperlink check. User-facing links at the bottom of the file:

• L197 https://docs.temporal.io/develop/typescript/integrations/ai-sdk — full URL ✓
• L198 https://ai-sdk.dev/ and https://ai-sdk.dev/providers/ai-sdk-providers — both full URLs ✓

No root-relative /develop/... paths found.

---

Check 2 findings — reverse-grep audit

Token classes extracted from vercel-ai-sdk.md and grepped against docs/develop/typescript/integrations/ai-sdk.mdx:

Token class	Status
Packages (@temporalio/ai-sdk, @ai-sdk/openai, @ai-sdk/mcp, @modelcontextprotocol/sdk/client/stdio.js)	All present in docs
Public symbols (AiSdkPlugin, temporalProvider, temporalProvider.languageModel, TemporalMCPClient, experimental_createMCPClient, createMCPClient, StdioClientTransport, proxyActivities, generateText, tool)	All present in docs
Plugin options (modelProvider, mcpClientFactories)	Both present in docs
Worker.create options (plugins, connection, namespace, taskQueue, workflowsPath, activities)	All present in docs
AI SDK fields (model, prompt, system, tools, description, inputSchema, execute, stopWhen, stepCountIs)	All present in docs
Hardcoded examples ('gpt-4o-mini', 'ai-sdk', 'default', 'testServer', '14-20C', 'Sunny with wind.', 'You only respond in haikus.')	All present in docs

Pass criterion (zero unexplained grep-misses): zero misses. PASS.

---

Check 3 findings — regression on known bugs

Scanned for all universal regression patterns:

Pattern	Status
--profile as a flag in temporal	Not present (skill is TS-only, no CLI surface)
TEMPORAL_TLS_CLIENT_CERT_PATH / _KEY_PATH / _SERVER_CA_CERT_PATH	Not present
tcld service-account	Not present
--output text / --output jsonl	Not present
saas-api.tmprl.cloud:7233	Not present

No topic-specific regressions exist for this file. PASS.

---

Check 4 findings — independent re-verification

Sampled 10 claims; for each, opened the cited docs region independently and compared the authored phrasing.

#	Claim	Cited	Match?
1	"automatically wrapped in Temporal Activities" (overview)	mdx:17–24	Yes
2	Public Preview admonition uses exact standard phrasing	mdx:30–35	Yes — verbatim
3	"Most AI SDK providers read credentials from environment variables; the client process does not need provider credentials."	mdx:98–107	Yes
4	"Register AiSdkPlugin on Worker.create and pass a modelProvider"	mdx:62–89	Yes
5	"the string is forwarded to the configured modelProvider to construct the model"	mdx:131–147	Yes
6	"any tool that performs I/O must delegate to an Activity" via proxyActivities	mdx:152–158	Yes
7	"stateless MCP client" + "listing tools, invoking them" run as Activities	mdx:209–215 (+273–274)	Yes
8	mcpClientFactories is a map keyed by server name; multiple servers register by adding factory entries	mdx:218–251	Yes
9	StdioClientTransport: Worker starts MCP server process on demand per Task	mdx:236–238	Yes
10	TemporalMCPClient object-form constructor; await mcpClient.tools() returns tools to pass to generateText	mdx:254–274	Yes

Prerequisite/minimum-version spot-check: L15 only cites the standard TS SDK setup (CLI + the four @temporalio/* packages) — no version pins. The docs make no version requirement either. Acceptable absence.

Defaults check: the only knob with a documented value the authored file mentions is startToCloseTimeout: '1 minute' inside the code block; this is the docs' example value, not a default. AI SDK options like stopWhen: stepCountIs(5) mirror the docs example exactly.

Pass criterion (≥ 95%): 10/10 = 100%. PASS.

---

Check 5 findings — integration-layout audit

Sub-check	Result
1. File location at references/typescript/integrations/vercel-ai-sdk.md	PASS
2. Exactly one new row in references/integrations.md	PASS — single appended row, all five columns present
3. Catalog description is a single terse clause	PASS — one sentence; comparable length and shape to the existing OpenAI Agents SDK / Google ADK rows in the same table
4. No SKILL.md edit	PASS — git diff shows no change to SKILL.md
5. No per-language entry-point bullet added to references/typescript/typescript.md	PASS — git diff shows no change to references/typescript/typescript.md
6. Inline cross-link cap (≤ one line in topical references)	PASS by absence — no cross-link added to references/typescript/ai-patterns.md (file does not exist) or references/core/ai-patterns.md

All six sub-checks pass.

---

Check 6 findings — tone and scope audit

Walked the file bullet-by-bullet against the 15 finding patterns.

Pattern 1 (workaround / escape-hatch disclosure): none found. The "Common mistakes" section names hard constraints (delegate I/O to Activities, use object-form constructor, match TQ/NS, keep credentials Worker-side) without disclosing escape hatches.

Pattern 2–4 (in-the-weeds rationale, implementation-internals speculation, multi-sentence noise bullets): none. Bullets are short and actionable.

Pattern 5 (Public Preview admonition): present at L7–9 with exact standard phrasing. PASS.

Pattern 6–7 (duplicated / post-admonition release-stage chatter): only one Public Preview note; nothing else restates preview status.

Pattern 8 (speculative common mistakes): the six "Common mistakes" bullets each map to a specific docs claim — no random typo speculation.

Pattern 9 (duplicated hard-constraint lists): the no-fetch-in-tools constraint appears only once.

Pattern 10 (Resources pointing at raw source trees): "Additional Resources" cites the canonical Temporal docs page, the upstream Vercel AI SDK docs, and two sibling reference files — no raw source-tree links.

Pattern 11 (external links duplicating local coverage): N/A — the upstream AI SDK docs are the authoritative API source, and no equivalent local file exists.

Pattern 12 (DIY rebuilds of supported integrations): N/A — file teaches the supported @temporalio/ai-sdk integration end-to-end.

Pattern 13 (repo slang / internal jargon): none.

Pattern 14 (inline imports in examples): all imports sit at module scope in every code block.

Pattern 15 (ambiguous "context" references): none.

PASS.

---

Statistics

• Authored files validated: 2 (references/typescript/integrations/vercel-ai-sdk.md, references/integrations.md)
• Citation comments resolved: 28
• Citation hit rate: 28/28 = 100%
• Reverse-grep misses: 0
• Regression-pattern hits: 0
• Check 4 sample size: 10 claims
• Check 4 match rate: 10/10 = 100%
• Check 5 sub-checks passed: 6/6
• Check 6 findings: 0
• Check 7: N/A (single-language integration)

---

Verdict

GO. Skill is grounded in the cited docs, free of regression patterns, structurally compliant with the integration catalog convention, and free of workaround-disclosure or scope-creep findings. Safe to merge.