@elevasis/sdk 1.24.0 → 1.26.0

package/reference/platform-tools/index.mdx

@@ -1,217 +1,216 @@
----
-title: Platform Tools
-description: Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters, credential security model, and working code examples
-loadWhen: "Connecting to external services"
----
-
-Your SDK workflows have access to 70+ tools -- Gmail, Stripe, Google Sheets, PDF generation, human-in-the-loop approvals, storage, scheduling, and more. Credentials are managed server-side and never appear in your code.
-
-**Typed adapters** are the recommended way to call tools. They provide full TypeScript autocomplete, compile-time method checking, and eliminate boilerplate. Use `platform.call()` only for tools that don't have an adapter yet.
-
-## Usage
-
-**Preferred: Typed adapters** (available for all integration tools + key platform services)
-
-```typescript
-import { createResendAdapter, scheduler, llm } from '@elevasis/sdk/worker'
-
-// Integration tools: factory pattern (credential bound once)
-const resend = createResendAdapter('my-resend')
-await resend.sendEmail({ from: 'hi@app.com', to: 'user@example.com', subject: '...' })
-
-// Platform services: singleton (no credential needed)
-await scheduler.createSchedule({ ... })
-const result = await llm.generate({ messages: [...] })
-```
-
-**Fallback: `platform.call()`** (for tools without typed adapters)
-
-```typescript
-import { platform } from '@elevasis/sdk/worker'
-
-const result = await platform.call({
-  tool: 'acqDb',            // tool name
-  method: 'upsertDeal',     // method exposed by that tool
-  params: { ... },          // method-specific parameters
-})
-```
-
-Both patterns return a Promise that resolves with the tool result or rejects with a `PlatformToolError` containing a message, error code, and a `retryable` flag.
-
-## Integration Adapters
-
-Ten integration adapters give you access to 50+ tool methods covering third-party APIs. Pass the credential name once at adapter creation. Supabase is listed separately under [Database Access](#database-access) below.
-
-| Adapter       | Tools                         | Credential Shape         |
-| ------------- | ----------------------------- | ------------------------ |
-| Attio         | 12 (CRUD + schema + notes)    | `{ apiKey }`             |
-| Google Sheets | 13 (read/write/filter/upsert) | OAuth2 / service account |
-| Stripe        | 6 (payment links + checkout)  | `{ secretKey }`          |
-| Instantly     | 5 (email campaigns)           | `{ apiKey }`             |
-| SignatureAPI  | 4 (envelopes)                 | `{ apiKey }`             |
-| Tomba         | 3 (email discovery)           | `api-key-secret`         |
-| Gmail         | 2 (send email)                | OAuth2 / service account |
-| Resend        | 2 (send/get email)            | `{ apiKey }`             |
-| Dropbox       | 2 (upload/folder)             | `{ accessToken }`        |
-| Apify         | 1 (run actor)                 | `{ token }`              |
-
-## Credential Security
-
-Integration credentials are never stored in `.env` and never available via `process.env` inside worker threads. Credentials live in the platform credential system and are accessed through three controlled channels.
-
-### Layer 1: Platform Tools (Default)
-
-All platform tools resolve credentials server-side. The credential value never crosses the postMessage boundary into the worker.
-
-```typescript
-// Credential 'my-gmail' is resolved server-side -- value never enters worker memory
-const result = await platform.call({
-  tool: 'gmail',
-  method: 'sendEmail',
-  credential: 'my-gmail',
-  params: { to: '...', subject: '...', body: '...' },
-})
-```
-
-### Layer 2: HTTP Platform Tool
-
-For APIs without a dedicated adapter, use the `http` platform tool. Credentials are injected server-side before the outgoing request.
-
-```typescript
-const result = await platform.call({
-  tool: 'http',
-  method: 'request',
-  credential: 'my-custom-api',
-  params: {
-    url: 'https://api.example.com/v1/data',
-    method: 'GET',
-    headers: { 'Content-Type': 'application/json' },
-  },
-})
-```
-
-**Supported injection patterns:**
-
-| Pattern         | Credential Config                                                | How Injected                             |
-| --------------- | ---------------------------------------------------------------- | ---------------------------------------- |
-| Bearer token    | `{ type: 'bearer', token: 'sk_...' }`                            | `Authorization: Bearer sk_...` header    |
-| API key header  | `{ type: 'api-key-header', header: 'X-API-Key', key: 'ak_...' }` | Custom header                            |
-| Basic auth      | `{ type: 'basic', username: '...', password: '...' }`            | `Authorization: Basic base64(user:pass)` |
-| Query parameter | `{ type: 'query-param', param: 'api_key', value: 'ak_...' }`     | Appended to URL                          |
-| Body field      | `{ type: 'body-field', field: 'apiKey', value: 'ak_...' }`       | Merged into JSON body                    |
-| Custom header   | `{ type: 'custom-header', header: 'X-Custom', value: '...' }`    | Arbitrary header                         |
-
-### Layer 3: getCredential() (Explicit Opt-In)
-
-For third-party SDKs that require a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This explicitly causes the credential value to enter worker memory.
-
-```typescript
-import { platform } from '@elevasis/sdk/worker'
-
-const cred = await platform.getCredential('my-stripe-key')
-const stripe = new Stripe(cred.credentials.secretKey)
-```
-
-All `getCredential()` calls are logged. Use `platform.call()` with the `http` tool when possible.
-
-### Credential Setup
-
-Credentials are created in the command center UI: navigate to Credentials -> Add Credential -> select type -> enter values -> save. The name you give the credential is what you pass as `credential: 'my-cred-name'` in `platform.call()`. Credential names are case-sensitive -- a mismatch causes `PlatformToolError: credential not found`.
-
-### Choosing a Pattern
-
-| Situation                                              | Pattern                                 |
-| ------------------------------------------------------ | --------------------------------------- |
-| Using a supported adapter (Gmail, Attio, Stripe, etc.) | `platform.call()` with the adapter tool |
-| Calling an API not in the catalog                      | `platform.call()` with `tool: 'http'`   |
-| Third-party SDK that requires a raw key                | `platform.getCredential()`              |
-
-`.env` contains only `ELEVASIS_PLATFORM_KEY` for CLI authentication -- never integration credentials.
-
----
-
-## Platform Services
-
-Nine built-in platform services are available without a `credential` field. All have typed singleton adapters imported from `@elevasis/sdk/worker`.
-
-| Tool Key       | Methods                                                                                                                                                                                     | Purpose                                         |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| `acqDb`        | 35 methods (CRUD + sync)                                                                                                                                                                    | Acquisition database -- `acqDb` adapter         |
-| `email`        | `send`                                                                                                                                                                                      | Send email to org members -- `email` adapter    |
-| `storage`      | `upload`, `download`, `createSignedUrl`, `delete`, `list`                                                                                                                                   | File storage -- `storage` adapter               |
-| `pdf`          | `render`, `renderToBuffer`                                                                                                                                                                  | PDF rendering -- `pdf` adapter                  |
-| `notification` | `create`                                                                                                                                                                                    | In-app notifications -- `notifications` adapter |
-| `approval`     | `create`, `deleteByMetadata`                                                                                                                                                                | HITL approval gates -- `approval` adapter       |
-| `scheduler`    | `createSchedule`, `updateAnchor`, `deleteSchedule`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`, `listSchedules`, `getSchedule`, `cancelSchedule`, `cancelSchedulesByMetadata` | Task scheduling -- `scheduler` adapter          |
-| `llm`          | `generate`                                                                                                                                                                                  | LLM inference -- `llm` adapter                  |
-| `execution`    | `trigger`                                                                                                                                                                                   | Nested child execution -- `execution` adapter   |
-
-## LLM Tool
-
-Call any supported LLM from your workflow with no API keys required. Keys are resolved server-side from environment variables.
-
-**Supported models:**
-
-| Provider     | Models                                                                                                         |
-| ------------ | -------------------------------------------------------------------------------------------------------------- |
-| `google`     | `gemini-3-flash-preview`                                                                                       |
-| `openai`     | `gpt-5`, `gpt-5-mini`                                                                                          |
-| `anthropic`  | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`                                                     |
-| `openrouter` | `openrouter/anthropic/claude-sonnet-4.5`, `openrouter/deepseek/deepseek-v3.2`, `openrouter/x-ai/grok-4.1-fast` |
-
-**Key params:** `provider`, `model`, `messages` (`{ role, content }[]`), `responseSchema` (optional JSON Schema), `temperature` (optional).
-
-See [Platform Adapters](adapters-platform.mdx#llm-adapter) for full typed usage with structured output.
-
-## Execution Tool
-
-Trigger another resource as a nested child of the current execution. The child runs synchronously and its result is returned. Maximum depth: 5 levels. The invoked resource must belong to the same organization.
-
-See [Platform Adapters](adapters-platform.mdx#execution-adapter) for usage.
-
-## Database Access
-
-Supabase is a first-class integration adapter for persistent storage. Pass the `credential` field with your stored Supabase credential name.
-
-**Methods:** `insert`, `select`, `update`, `delete`, `upsert`, `rpc`, `count`
-
-```typescript
-const qualified = await platform.call({
-  tool: 'supabase',
-  credential: 'my-database',
-  method: 'select',
-  params: {
-    table: 'leads',
-    filter: { status: 'eq.qualified', score: 'gte.80' },
-    order: { column: 'score', ascending: false },
-    limit: 50,
-  },
-})
-```
-
-**Filter syntax** uses PostgREST format (`operator.value`):
-
-| Filter                   | Example                            | Meaning       |
-| ------------------------ | ---------------------------------- | ------------- |
-| `eq`                     | `{ status: 'eq.qualified' }`       | Equals        |
-| `neq`                    | `{ status: 'neq.lost' }`           | Not equals    |
-| `gt`, `gte`, `lt`, `lte` | `{ score: 'gte.80' }`              | Comparisons   |
-| `like`, `ilike`          | `{ name: 'ilike.%jane%' }`         | Pattern match |
-| `in`                     | `{ status: 'in.(new,contacted)' }` | In set        |
-| `is`                     | `{ deleted_at: 'is.null' }`        | Null check    |
-
-**Credential setup:** Create a credential with provider `supabase` -- config fields are `url` and `serviceRoleKey`. Workflows always use the service role key (server-side, no RLS).
-
-**`/database init`:** Guided setup that stores your Supabase credential, generates `data/schema.ts`, and creates `docs/database.mdx`.
-
----
-
-## Documentation
-
-- [Integration Adapters](adapters-integration.mdx) - All 10 integration adapters with method tables and code examples
-- [Platform Adapters](adapters-platform.mdx) - All 9 platform service adapters with method tables and code examples
-- [Adapter Type Safety](type-safety.mdx) - Required fields, discriminated unions, and intentionally loose adapter types
-
----
-
-**Last Updated:** 2026-03-06
+---
+title: Platform Tools
+description: Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters, credential security model, and working code examples
+---
+
+Your SDK workflows have access to 70+ tools -- Gmail, Stripe, Google Sheets, PDF generation, human-in-the-loop approvals, storage, scheduling, and more. Credentials are managed server-side and never appear in your code.
+
+**Typed adapters** are the recommended way to call tools. They provide full TypeScript autocomplete, compile-time method checking, and eliminate boilerplate. Use `platform.call()` only for tools that don't have an adapter yet.
+
+## Usage
+
+**Preferred: Typed adapters** (available for all integration tools + key platform services)
+
+```typescript
+import { createResendAdapter, scheduler, llm } from '@elevasis/sdk/worker'
+
+// Integration tools: factory pattern (credential bound once)
+const resend = createResendAdapter('my-resend')
+await resend.sendEmail({ from: 'hi@app.com', to: 'user@example.com', subject: '...' })
+
+// Platform services: singleton (no credential needed)
+await scheduler.createSchedule({ ... })
+const result = await llm.generate({ messages: [...] })
+```
+
+**Fallback: `platform.call()`** (for tools without typed adapters)
+
+```typescript
+import { platform } from '@elevasis/sdk/worker'
+
+const result = await platform.call({
+  tool: 'acqDb',            // tool name
+  method: 'upsertDeal',     // method exposed by that tool
+  params: { ... },          // method-specific parameters
+})
+```
+
+Both patterns return a Promise that resolves with the tool result or rejects with a `PlatformToolError` containing a message, error code, and a `retryable` flag.
+
+## Integration Adapters
+
+Ten integration adapters give you access to 50+ tool methods covering third-party APIs. Pass the credential name once at adapter creation. Supabase is listed separately under [Database Access](#database-access) below.
+
+| Adapter       | Tools                         | Credential Shape         |
+| ------------- | ----------------------------- | ------------------------ |
+| Attio         | 12 (CRUD + schema + notes)    | `{ apiKey }`             |
+| Google Sheets | 13 (read/write/filter/upsert) | OAuth2 / service account |
+| Stripe        | 6 (payment links + checkout)  | `{ secretKey }`          |
+| Instantly     | 5 (email campaigns)           | `{ apiKey }`             |
+| SignatureAPI  | 4 (envelopes)                 | `{ apiKey }`             |
+| Tomba         | 3 (email discovery)           | `api-key-secret`         |
+| Gmail         | 2 (send email)                | OAuth2 / service account |
+| Resend        | 2 (send/get email)            | `{ apiKey }`             |
+| Dropbox       | 2 (upload/folder)             | `{ accessToken }`        |
+| Apify         | 1 (run actor)                 | `{ token }`              |
+
+## Credential Security
+
+Integration credentials are never stored in `.env` and never available via `process.env` inside worker threads. Credentials live in the platform credential system and are accessed through three controlled channels.
+
+### Layer 1: Platform Tools (Default)
+
+All platform tools resolve credentials server-side. The credential value never crosses the postMessage boundary into the worker.
+
+```typescript
+// Credential 'my-gmail' is resolved server-side -- value never enters worker memory
+const result = await platform.call({
+  tool: 'gmail',
+  method: 'sendEmail',
+  credential: 'my-gmail',
+  params: { to: '...', subject: '...', body: '...' },
+})
+```
+
+### Layer 2: HTTP Platform Tool
+
+For APIs without a dedicated adapter, use the `http` platform tool. Credentials are injected server-side before the outgoing request.
+
+```typescript
+const result = await platform.call({
+  tool: 'http',
+  method: 'request',
+  credential: 'my-custom-api',
+  params: {
+    url: 'https://api.example.com/v1/data',
+    method: 'GET',
+    headers: { 'Content-Type': 'application/json' },
+  },
+})
+```
+
+**Supported injection patterns:**
+
+| Pattern         | Credential Config                                                | How Injected                             |
+| --------------- | ---------------------------------------------------------------- | ---------------------------------------- |
+| Bearer token    | `{ type: 'bearer', token: 'sk_...' }`                            | `Authorization: Bearer sk_...` header    |
+| API key header  | `{ type: 'api-key-header', header: 'X-API-Key', key: 'ak_...' }` | Custom header                            |
+| Basic auth      | `{ type: 'basic', username: '...', password: '...' }`            | `Authorization: Basic base64(user:pass)` |
+| Query parameter | `{ type: 'query-param', param: 'api_key', value: 'ak_...' }`     | Appended to URL                          |
+| Body field      | `{ type: 'body-field', field: 'apiKey', value: 'ak_...' }`       | Merged into JSON body                    |
+| Custom header   | `{ type: 'custom-header', header: 'X-Custom', value: '...' }`    | Arbitrary header                         |
+
+### Layer 3: getCredential() (Explicit Opt-In)
+
+For third-party SDKs that require a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This explicitly causes the credential value to enter worker memory.
+
+```typescript
+import { platform } from '@elevasis/sdk/worker'
+
+const cred = await platform.getCredential('my-stripe-key')
+const stripe = new Stripe(cred.credentials.secretKey)
+```
+
+All `getCredential()` calls are logged. Use `platform.call()` with the `http` tool when possible.
+
+### Credential Setup
+
+Credentials are created in the command center UI: navigate to Credentials -> Add Credential -> select type -> enter values -> save. The name you give the credential is what you pass as `credential: 'my-cred-name'` in `platform.call()`. Credential names are case-sensitive -- a mismatch causes `PlatformToolError: credential not found`.
+
+### Choosing a Pattern
+
+| Situation                                              | Pattern                                 |
+| ------------------------------------------------------ | --------------------------------------- |
+| Using a supported adapter (Gmail, Attio, Stripe, etc.) | `platform.call()` with the adapter tool |
+| Calling an API not in the catalog                      | `platform.call()` with `tool: 'http'`   |
+| Third-party SDK that requires a raw key                | `platform.getCredential()`              |
+
+`.env` contains only `ELEVASIS_PLATFORM_KEY` for CLI authentication -- never integration credentials.
+
+---
+
+## Platform Services
+
+Nine built-in platform services are available without a `credential` field. All have typed singleton adapters imported from `@elevasis/sdk/worker`.
+
+| Tool Key       | Methods                                                                                                                                                                                     | Purpose                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `acqDb`        | 35 methods (CRUD + sync)                                                                                                                                                                    | Acquisition database -- `acqDb` adapter         |
+| `email`        | `send`                                                                                                                                                                                      | Send email to org members -- `email` adapter    |
+| `storage`      | `upload`, `download`, `createSignedUrl`, `delete`, `list`                                                                                                                                   | File storage -- `storage` adapter               |
+| `pdf`          | `render`, `renderToBuffer`                                                                                                                                                                  | PDF rendering -- `pdf` adapter                  |
+| `notification` | `create`                                                                                                                                                                                    | In-app notifications -- `notifications` adapter |
+| `approval`     | `create`, `deleteByMetadata`                                                                                                                                                                | HITL approval gates -- `approval` adapter       |
+| `scheduler`    | `createSchedule`, `updateAnchor`, `deleteSchedule`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`, `listSchedules`, `getSchedule`, `cancelSchedule`, `cancelSchedulesByMetadata` | Task scheduling -- `scheduler` adapter          |
+| `llm`          | `generate`                                                                                                                                                                                  | LLM inference -- `llm` adapter                  |
+| `execution`    | `trigger`                                                                                                                                                                                   | Nested child execution -- `execution` adapter   |
+
+## LLM Tool
+
+Call any supported LLM from your workflow with no API keys required. Keys are resolved server-side from environment variables.
+
+**Supported models:**
+
+| Provider     | Models                                                                                                         |
+| ------------ | -------------------------------------------------------------------------------------------------------------- |
+| `google`     | `gemini-3-flash-preview`                                                                                       |
+| `openai`     | `gpt-5`, `gpt-5-mini`                                                                                          |
+| `anthropic`  | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`                                                     |
+| `openrouter` | `openrouter/anthropic/claude-sonnet-4.5`, `openrouter/deepseek/deepseek-v3.2`, `openrouter/x-ai/grok-4.1-fast` |
+
+**Key params:** `provider`, `model`, `messages` (`{ role, content }[]`), `responseSchema` (optional JSON Schema), `temperature` (optional).
+
+See [Platform Adapters](adapters-platform.mdx#llm-adapter) for full typed usage with structured output.
+
+## Execution Tool
+
+Trigger another resource as a nested child of the current execution. The child runs synchronously and its result is returned. Maximum depth: 5 levels. The invoked resource must belong to the same organization.
+
+See [Platform Adapters](adapters-platform.mdx#execution-adapter) for usage.
+
+## Database Access
+
+Supabase is a first-class integration adapter for persistent storage. Pass the `credential` field with your stored Supabase credential name.
+
+**Methods:** `insert`, `select`, `update`, `delete`, `upsert`, `rpc`, `count`
+
+```typescript
+const qualified = await platform.call({
+  tool: 'supabase',
+  credential: 'my-database',
+  method: 'select',
+  params: {
+    table: 'leads',
+    filter: { status: 'eq.qualified', score: 'gte.80' },
+    order: { column: 'score', ascending: false },
+    limit: 50,
+  },
+})
+```
+
+**Filter syntax** uses PostgREST format (`operator.value`):
+
+| Filter                   | Example                            | Meaning       |
+| ------------------------ | ---------------------------------- | ------------- |
+| `eq`                     | `{ status: 'eq.qualified' }`       | Equals        |
+| `neq`                    | `{ status: 'neq.lost' }`           | Not equals    |
+| `gt`, `gte`, `lt`, `lte` | `{ score: 'gte.80' }`              | Comparisons   |
+| `like`, `ilike`          | `{ name: 'ilike.%jane%' }`         | Pattern match |
+| `in`                     | `{ status: 'in.(new,contacted)' }` | In set        |
+| `is`                     | `{ deleted_at: 'is.null' }`        | Null check    |
+
+**Credential setup:** Create a credential with provider `supabase` -- config fields are `url` and `serviceRoleKey`. Workflows always use the service role key (server-side, no RLS).
+
+**`/database init`:** Guided setup that stores your Supabase credential, generates `data/schema.ts`, and creates `docs/database.mdx`.
+
+---
+
+## Documentation
+
+- [Integration Adapters](adapters-integration.mdx) - All 10 integration adapters with method tables and code examples
+- [Platform Adapters](adapters-platform.mdx) - All 9 platform service adapters with method tables and code examples
+- [Adapter Type Safety](type-safety.mdx) - Required fields, discriminated unions, and intentionally loose adapter types
+
+---
+
+**Last Updated:** 2026-03-06

package/reference/platform-tools/type-safety.mdx

@@ -1,82 +1,82 @@
----
-title: Adapter Type Safety
-description: SDK worker adapter type safety patterns - required fields, discriminated unions, and intentionally loose types
----
-
-SDK worker adapters enforce correctness at compile time via TypeScript, not at deploy time. Misconfigured adapters fail in the IDE before a file is even saved — no runtime surprises, no silent failures in production.
-
-The approach: tighten types where misconfiguration is a realistic foot-gun, and leave types intentionally loose where flexibility is a design requirement.
-
----
-
-## Required Field Enforcement
-
-### LLM Adapter — `provider` and `model`
-
-`provider` and `model` are required on `SDKLLMGenerateParams` in `packages/sdk/src/worker/adapters/llm.ts`. They were previously optional because the server-side `modelConfig` fallback in `tool-dispatcher.ts` would fill them in — but that fallback is a foot-gun, not a feature. Omitting them silently selects a default model that may not be appropriate for the call site.
-
-```typescript
-// Required — both fields must be specified inline
-await llm.generate({
-  provider: 'anthropic',
-  model: 'claude-sonnet-4-5',
-  messages: [...],
-  responseSchema: {...},
-})
-```
-
-### Tomba Adapter — `domain` and `email`
-
-`domain` is required on `TombaDomainSearchParams` and `TombaEmailFinderParams`. `email` is required on `TombaEmailVerifierParams`. Previously all params were optional, allowing calls to compile but fail at runtime. The type change enforces the fields that are always necessary for email discovery and verification.
-
----
-
-## Discriminated Unions
-
-### Email Targeting — mutually exclusive modes
-
-`EmailToolMap.send.params` uses a discriminated union with `never` to enforce that exactly one targeting mode is provided. You cannot pass zero modes or combine multiple modes.
-
-```typescript
-type EmailTargeting =
-  | { userIds: string[]; targetRole?: never; targetAll?: never }
-  | { targetRole: string; userIds?: never; targetAll?: never }
-  | { targetAll: true; userIds?: never; targetRole?: never }
-```
-
-The `never` pattern on sibling fields causes TypeScript to error if you pass two targeting fields simultaneously. Passing none also fails because none of the union members match.
-
----
-
-## Strict Object Types
-
-### Approval Adapter — typed context
-
-`ApprovalToolMap.create.params` uses `context: Record<string, unknown>` instead of `context: unknown`. This prevents passing primitives (strings, numbers) as context — approval tasks always expect a structured key-value object.
-
-```typescript
-// Correct
-await approval.create({
-  context: { dealId: 'deal-123', proposalUrl: 'https://...' },
-  ...
-})
-
-// TypeScript error — primitives not assignable to Record<string, unknown>
-await approval.create({ context: 'deal-123', ... })
-```
-
----
-
-## Intentionally Loose Types
-
-Some adapters were audited and deliberately left with flexible types. Do not tighten these — the looseness is a design requirement.
-
-| Adapter | Field      | Type                        | Reason                                                                                                         |
-| ------- | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Attio   | `object`   | `string`                    | Supports custom user-defined object slugs; a union would be too restrictive for orgs with custom Attio objects |
-| Attio   | `values`   | `Record<string, unknown>` | Dynamic per-object schemas vary by org configuration                                                           |
-| PDF     | `document` | `Record<string, unknown>` | Renderer accepts flexible document structures by design; schema is enforced server-side                        |
-
----
-
-**Source:** `packages/sdk/src/worker/adapters/llm.ts`, `packages/core/src/execution/engine/tools/tool-maps.ts`
+---
+title: Adapter Type Safety
+description: SDK worker adapter type safety patterns - required fields, discriminated unions, and intentionally loose types
+---
+
+SDK worker adapters enforce correctness at compile time via TypeScript, not at deploy time. Misconfigured adapters fail in the IDE before a file is even saved -- no runtime surprises, no silent failures in production.
+
+The approach: tighten types where misconfiguration is a realistic foot-gun, and leave types intentionally loose where flexibility is a design requirement.
+
+---
+
+## Required Field Enforcement
+
+### LLM Adapter -- `provider` and `model`
+
+`provider` and `model` are required on `SDKLLMGenerateParams` in `packages/sdk/src/worker/adapters/llm.ts`. They were previously optional because the server-side `modelConfig` fallback in `tool-dispatcher.ts` would fill them in -- but that fallback is a foot-gun, not a feature. Omitting them silently selects a default model that may not be appropriate for the call site.
+
+```typescript
+// Required -- both fields must be specified inline
+await llm.generate({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+  messages: [...],
+  responseSchema: {...},
+})
+```
+
+### Tomba Adapter -- `domain` and `email`
+
+`domain` is required on `TombaDomainSearchParams` and `TombaEmailFinderParams`. `email` is required on `TombaEmailVerifierParams`. Previously all params were optional, allowing calls to compile but fail at runtime. The type change enforces the fields that are always necessary for email discovery and verification.
+
+---
+
+## Discriminated Unions
+
+### Email Targeting -- mutually exclusive modes
+
+`EmailToolMap.send.params` uses a discriminated union with `never` to enforce that exactly one targeting mode is provided. You cannot pass zero modes or combine multiple modes.
+
+```typescript
+type EmailTargeting =
+  | { userIds: string[]; targetRole?: never; targetAll?: never }
+  | { targetRole: string; userIds?: never; targetAll?: never }
+  | { targetAll: true; userIds?: never; targetRole?: never }
+```
+
+The `never` pattern on sibling fields causes TypeScript to error if you pass two targeting fields simultaneously. Passing none also fails because none of the union members match.
+
+---
+
+## Strict Object Types
+
+### Approval Adapter -- typed context
+
+`ApprovalToolMap.create.params` uses `context: Record<string, unknown>` instead of `context: unknown`. This prevents passing primitives (strings, numbers) as context -- approval tasks always expect a structured key-value object.
+
+```typescript
+// Correct
+await approval.create({
+  context: { dealId: 'deal-123', proposalUrl: 'https://...' },
+  ...
+})
+
+// TypeScript error -- primitives not assignable to Record<string, unknown>
+await approval.create({ context: 'deal-123', ... })
+```
+
+---
+
+## Intentionally Loose Types
+
+Some adapters were audited and deliberately left with flexible types. Do not tighten these -- the looseness is a design requirement.
+
+| Adapter | Field      | Type                        | Reason                                                                                                         |
+| ------- | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Attio   | `object`   | `string`                    | Supports custom user-defined object slugs; a union would be too restrictive for orgs with custom Attio objects |
+| Attio   | `values`   | `Record<string, unknown>` | Dynamic per-object schemas vary by org configuration                                                           |
+| PDF     | `document` | `Record<string, unknown>` | Renderer accepts flexible document structures by design; schema is enforced server-side                        |
+
+---
+
+**Source:** `packages/sdk/src/worker/adapters/llm.ts`, `packages/core/src/execution/engine/tools/tool-maps.ts`