@vellumai/assistant 0.3.4 → 0.3.6

package/src/config/vellum-skills/sms-setup/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: "SMS Setup"
+description: "Set up and troubleshoot SMS messaging with guided Twilio configuration, compliance, and verification"
+user-invocable: true
+metadata: {"vellum": {"emoji": "\ud83d\udce8"}}
+---
+
+You are helping your user set up SMS messaging. This skill orchestrates Twilio setup, SMS-specific compliance, and end-to-end testing through a conversational flow.
+
+## Step 1: Check Channel Readiness
+
+First, check the current SMS channel readiness state by sending the `channel_readiness` IPC message:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "get",
+  "channel": "sms"
+}
+```
+
+Inspect the `channel_readiness_response`. The response contains `snapshots` with each channel's readiness state.
+
+- If the SMS channel shows `ready: true` and all `localChecks` pass, skip to Step 3.
+- If any local checks fail, proceed to Step 2 to fix the baseline.
+
+## Step 2: Establish Baseline (Twilio Setup)
+
+If SMS baseline is not ready (missing credentials, phone number, or ingress), load the `twilio-setup` skill to walk the user through the basics:
+
+```
+skill_load skill=twilio-setup
+```
+
+Tell the user: *"SMS needs Twilio configured first. I've loaded the Twilio setup guide — let's walk through it."*
+
+After twilio-setup completes, re-check readiness:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms"
+}
+```
+
+If baseline is still not ready, report the specific failures and ask the user to address them before continuing.
+
+## Step 3: Remote Compliance Check
+
+Once baseline is ready, run a full readiness check including remote (Twilio API) checks:
+
+```json
+{
+  "type": "channel_readiness",
+  "action": "refresh",
+  "channel": "sms",
+  "includeRemote": true
+}
+```
+
+Examine the remote check results:
+- If all remote checks pass, proceed to Step 4.
+- If compliance issues are found (e.g., toll-free verification needed), guide the user through the compliance flow.
+
+### Toll-Free Verification Submission
+
+When the remote check returns `toll_free_verification` as a failing check, the assistant must submit verification directly to the Twilio API. The daemon does not yet have an IPC action for this, so use the Twilio REST API directly.
+
+**Prerequisites:** The assistant needs the Account SID and Auth Token. These are stored in daemon secure storage and can be accessed by importing `getSecureKey` from the daemon's `security/secure-keys` module:
+
+```typescript
+import { getSecureKey } from "./src/security/secure-keys.js";
+const accountSid = getSecureKey("credential:twilio:account_sid");
+const authToken = getSecureKey("credential:twilio:auth_token");
+```
+
+**Step 3a: Look up the phone number SID.** The toll-free verification API requires the phone number's SID (format `PNxxxx`), not the E.164 number itself:
+
+```
+GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json?PhoneNumber={E.164 number}
+```
+
+Extract the `sid` field from the matching number in `incoming_phone_numbers`.
+
+**Step 3b: Check for existing verifications.** Before submitting, check if a verification already exists:
+
+```
+GET https://messaging.twilio.com/v1/Tollfree/Verifications
+```
+
+If a verification already exists for this number, report its status to the user and skip submission.
+
+**Step 3c: Check Trust Hub profile assignments.** Twilio auto-attaches toll-free numbers to their assigned Trust Hub Customer Profile. The verification API rejects submissions when the number is attached to a Primary Customer Profile (PCP). It requires either no profile, a Starter profile, or a Secondary Customer Profile (SCP).
+
+Check if the number is assigned to a profile:
+
+```
+GET https://trusthub.twilio.com/v1/CustomerProfiles?PageSize=50
+```
+
+For each profile, check `ChannelEndpointAssignments`:
+
+```
+GET https://trusthub.twilio.com/v1/CustomerProfiles/{ProfileSid}/ChannelEndpointAssignments?PageSize=50
+```
+
+If the number is assigned to a Primary profile:
+1. **Tell the user** the number is linked to a Primary Customer Profile, which blocks toll-free verification.
+2. **Offer two options:**
+   - **Option A:** Remove the number from the Primary profile (DELETE the ChannelEndpointAssignment), then resubmit. Warn that this may affect other services tied to that profile.
+   - **Option B:** Wait for the Starter profile to be approved (if one exists and is `in-review`), then link the number to that profile instead.
+3. **Do not silently retry.** The same error will recur until the profile assignment is resolved.
+
+**Step 3d: Collect user information.** Collect the following from the user (assume individual/sole proprietor by default):
+
+| Field | API Parameter | Notes |
+|---|---|---|
+| Name | `BusinessName` | Can be personal name |
+| Business type | `BusinessType` | Use `SOLE_PROPRIETOR` for individuals. Valid values: `PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `SOLE_PROPRIETOR`, `NON_PROFIT`, `GOVERNMENT` |
+| Website | `BusinessWebsite` | LinkedIn or personal site is fine |
+| Street address | `BusinessStreetAddress` | |
+| City | `BusinessCity` | |
+| State | `BusinessStateProvinceRegion` | |
+| Zip | `BusinessPostalCode` | |
+| Country | `BusinessCountry` | Two-letter ISO code, e.g. `US` |
+| Notification email | `NotificationEmail` | Where Twilio sends status updates |
+| Contact phone | `BusinessContactPhone` | E.164 format |
+| Contact first name | `BusinessContactFirstName` | |
+| Contact last name | `BusinessContactLastName` | |
+| Contact email | `BusinessContactEmail` | |
+| Use case category | `UseCaseCategories` | e.g. `ACCOUNT_NOTIFICATIONS` |
+| Use case summary | `UseCaseSummary` | Plain English description |
+| Message volume | `MessageVolume` | Estimated monthly messages, e.g. `100` |
+| Sample message | `ProductionMessageSample` | A realistic example message |
+| Opt-in type | `OptInType` | `VERBAL`, `WEB_FORM`, `PAPER_FORM`, `VIA_TEXT`, `MOBILE_QR_CODE` |
+| Opt-in image URL | `OptInImageUrls` | URL showing opt-in mechanism (can be website URL) |
+
+Do NOT ask for EIN, business registration number, or business registration authority. Explain that Twilio labels some fields as "business" fields even for individual submitters.
+
+**Step 3e: Submit verification:**
+
+```
+POST https://messaging.twilio.com/v1/Tollfree/Verifications
+Content-Type: application/x-www-form-urlencoded
+```
+
+With all fields as form-encoded parameters, including `TollfreePhoneNumberSid` (the PN SID from Step 3a).
+
+**Common errors:**
+- `"BusinessType must be one of [...]"` — Use exact enum values listed above
+- `"Customer profiles submitted with verifications must be either ISV Starters or Secondary Customer Profiles"` — The number is linked to a Primary profile. See Step 3c above.
+- `400` or `20001` errors — Check the `message` field for specifics and report to user
+
+**On success:** Tell the user the verification has been submitted and is now `PENDING_REVIEW`. Twilio typically reviews within 1-5 business days. They'll receive status updates at the notification email provided.
+
+**On failure:** Report the exact error message and guide the user through resolution.
+
+## Step 4: Test Send
+
+Run a test SMS to verify end-to-end delivery:
+
+Tell the user: *"Let's send a test SMS to verify everything works. What phone number should I send the test to?"*
+
+**Important:** If toll-free verification is pending (not yet approved), inform the user that test messages may be silently dropped by carriers even though Twilio accepts them. Offer to attempt the test anyway, but set expectations.
+
+**Trial account limitation:** On Twilio trial accounts, SMS can only be sent to verified phone numbers. If the send fails with a "not verified" error, tell the user to verify the recipient number in the Twilio Console under Verified Caller IDs, or upgrade their account.
+
+After the user provides a number, send a test message using the messaging tools:
+- Use `messaging_send` with `platform: "sms"`, `conversation_id: "<phone number>"`, and a test message like "Test SMS from your Vellum assistant."
+- Report the result honestly:
+  - If the send succeeds: *"The message was accepted by Twilio. Note: 'accepted' means Twilio received it for delivery, not that it reached the handset yet. Delivery can take a few seconds to a few minutes. If verification is still pending, carriers may silently drop the message."*
+  - If the send fails: report the error and suggest troubleshooting steps
+
+## Step 5: Final Status Report
+
+After completing (or skipping) the test, present a clear summary:
+
+**If everything passed:**
+*"SMS is ready! Here's your setup status:"*
+- Twilio credentials: configured
+- Phone number: {number}
+- Ingress: configured
+- Compliance: {status}
+- Test send: {result}
+
+**If there are blockers:**
+*"SMS setup is partially complete. Here's what still needs attention:"*
+- List each blocker with the specific next action
+
+## Troubleshooting
+
+If the user returns to this skill after initial setup:
+1. Always start with Step 1 (readiness check) to assess current state
+2. Skip steps that are already complete
+3. Focus on the specific issue the user is experiencing
+
+Common issues:
+- **"Messages not delivering"** — Check compliance status (toll-free verification), verify the number isn't flagged
+- **"Twilio error on send"** — Check credentials, phone number assignment, and ingress
+- **"Trial account limitations"** — Explain that trial accounts can only send to verified numbers
+- **"Customer profiles must be ISV Starters or Secondary"** — The toll-free number is linked to a Primary Customer Profile in Trust Hub. Must be unlinked or reassigned before verification can be submitted.
+
+## Accessing the Twilio API
+
+The skill references IPC messages (`channel_readiness`, `twilio_config`) that are sent via Unix socket to the daemon. The assistant does not have an HTTP endpoint for IPC. Use the following pattern to send IPC messages:
+
+```bash
+cd "$(git rev-parse --show-toplevel)/assistant" && bun -e '
+import { sendOneMessage } from "./src/cli/ipc-client.js";
+const res = await sendOneMessage({ type: "twilio_config", action: "get" });
+console.log(JSON.stringify(res, null, 2));
+'
+```
+
+For direct Twilio REST API calls (e.g., toll-free verification submission), use the same `bun -e` pattern with `getSecureKey` from `./src/security/secure-keys.js` to retrieve credentials, then use `fetch()`.

package/src/config/vellum-skills/twilio-setup/SKILL.md

@@ -18,6 +18,27 @@ This skill manages the full Twilio lifecycle:
 
 All operations go through the `twilio_config` IPC handler on the daemon, which validates inputs, stores credentials securely, and manages phone number state.
 
+### Multi-Assistant Setups
+
+In a multi-assistant environment (multiple assistants sharing the same daemon), some `twilio_config` actions are **assistant-scoped** while others are **global** (shared across all assistants):
+
+**Global actions** (ignore `assistantId` — credentials are shared across all assistants):
+- `set_credentials` — Stores Account SID and Auth Token in global secure storage (`credential:twilio:*` keys). All assistants share the same Twilio account credentials.
+- `clear_credentials` — Removes the globally stored Account SID and Auth Token. This affects all assistants.
+
+**Assistant-scoped actions** (use `assistantId` to scope phone number configuration per assistant):
+- `get` — Returns the phone number assigned to the specified assistant (falls back to the legacy global number if no per-assistant mapping exists).
+- `assign_number` — Assigns a phone number to a specific assistant via the per-assistant mapping.
+- `provision_number` — Provisions a new number and assigns it to the specified assistant.
+- `list_numbers` — Lists all phone numbers on the shared Twilio account (uses global credentials).
+
+Include `assistantId` in assistant-scoped actions whenever:
+- Multiple assistants share the same Twilio account but use different phone numbers
+- You want to ensure configuration changes only affect a specific assistant
+- The user has explicitly selected or referenced a particular assistant
+
+All IPC examples below include the optional `assistantId` field in assistant-scoped actions. Omit it in single-assistant setups. For global actions (`set_credentials`, `clear_credentials`), the `assistantId` field is accepted but ignored.
+
 ## Step 1: Check Current Configuration
 
 First, check whether Twilio is already configured by sending the `twilio_config` IPC message with `action: "get"`:
@@ -25,7 +46,8 @@ First, check whether Twilio is already configured by sending the `twilio_config`
 ```json
 {
   "type": "twilio_config",
-  "action": "get"
+  "action": "get",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -62,6 +84,8 @@ After both credentials are collected, retrieve them from secure storage and pass
 
 Both `accountSid` and `authToken` are required — the daemon validates the credentials against the Twilio API before storing them. If credentials are invalid, the daemon returns an error. Tell the user and ask them to re-enter via the secure prompt.
 
+**Note:** `set_credentials` is a global operation — credentials are stored once and shared across all assistants. The `assistantId` field is accepted but ignored.
+
 ## Step 3: Get a Phone Number
 
 The assistant needs a phone number to make calls and send SMS. There are two paths:
@@ -75,7 +99,8 @@ If the user wants to buy a new number through Twilio, send:
   "type": "twilio_config",
   "action": "provision_number",
   "areaCode": "415",
-  "country": "US"
+  "country": "US",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -100,7 +125,8 @@ If the user already has a Twilio phone number, first list available numbers:
 ```json
 {
   "type": "twilio_config",
-  "action": "list_numbers"
+  "action": "list_numbers",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -112,7 +138,8 @@ Then assign the chosen number:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -132,7 +159,8 @@ Then assign it through the IPC:
 {
   "type": "twilio_config",
   "action": "assign_number",
-  "phoneNumber": "+14155551234"
+  "phoneNumber": "+14155551234",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -181,7 +209,8 @@ Now link the user's phone number as the trusted SMS guardian for this assistant.
 {
   "type": "guardian_verification",
   "action": "create_challenge",
-  "channel": "sms"
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -195,7 +224,8 @@ Now link the user's phone number as the trusted SMS guardian for this assistant.
 {
   "type": "guardian_verification",
   "action": "status",
-  "channel": "sms"
+  "channel": "sms",
+  "assistantId": "<optional — omit for single-assistant setups>"
 }
 ```
 
@@ -232,7 +262,9 @@ If the user wants to disconnect Twilio, send:
 }
 ```
 
-This removes the stored Account SID and Auth Token. Your phone number assignment will be preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+This removes the stored Account SID and Auth Token. Phone number assignments are preserved. Voice calls and SMS will stop working until credentials are reconfigured.
+
+**Note:** `clear_credentials` is a global operation — it removes credentials for all assistants, not just the current one. The `assistantId` field is accepted but ignored. In multi-assistant setups, warn the user that clearing credentials will affect all assistants sharing this Twilio account.
 
 ## Troubleshooting
 

package/src/context/window-manager.ts

@@ -112,7 +112,7 @@ export class ContextWindowManager {
       };
     }
 
-    const summaryOffset = existingSummary !== null ? 1 : 0;
+    const summaryOffset = existingSummary != null ? 1 : 0;
     const userTurnStarts = collectUserTurnStartIndexes(messages);
     if (userTurnStarts.length === 0) {
       return {
@@ -186,14 +186,34 @@ export class ContextWindowManager {
     const projectedGainTokens = Math.max(0, previousEstimatedInputTokens - projectedInputTokens);
     const severePressure = previousEstimatedInputTokens >= Math.floor(this.config.maxInputTokens * SEVERE_PRESSURE_RATIO);
     const lastCompactedAt = options?.lastCompactedAt;
-    const withinCooldown = typeof lastCompactedAt === 'number'
-      && Date.now() - lastCompactedAt < COMPACTION_COOLDOWN_MS;
 
+    // Adaptive cooldown: conversations growing quickly (high projected gain) compact
+    // sooner. Scale the cooldown inversely with the growth-rate multiplier, capped at
+    // 1/4 of the base cooldown so we never check more than 4× as frequently.
+    const growthRateMultiplier = Math.max(1, projectedGainTokens / MIN_GAIN_TOKENS_DURING_COOLDOWN);
+    const adaptiveCooldownMs = Math.max(
+      COMPACTION_COOLDOWN_MS / 4,
+      COMPACTION_COOLDOWN_MS / growthRateMultiplier,
+    );
+    const withinCooldown = typeof lastCompactedAt === 'number'
+      && Date.now() - lastCompactedAt < adaptiveCooldownMs;
+
+    // The adaptive cooldown is already tuned to be shorter for fast-growing
+    // conversations (high projectedGainTokens → smaller adaptiveCooldownMs).
+    // Removing the redundant MIN_GAIN_TOKENS_DURING_COOLDOWN guard here lets
+    // that shorter cooldown actually gate compaction: high-growth conversations
+    // break out of the cooldown sooner and compact more frequently.
+    // force=true bypasses the cooldown so context-too-large recovery can always
+    // attempt a compaction even within the cooldown window.
     if (
       withinCooldown
-      && projectedGainTokens < MIN_GAIN_TOKENS_DURING_COOLDOWN
       && !severePressure
+      && !options?.force
     ) {
+      log.debug(
+        { projectedGainTokens, adaptiveCooldownMs, growthRateMultiplier, msSinceCompaction: typeof lastCompactedAt === 'number' ? Date.now() - lastCompactedAt : null },
+        'Compaction cooldown active',
+      );
       return {
         messages,
         compacted: false,
@@ -208,7 +228,7 @@ export class ContextWindowManager {
         summaryOutputTokens: 0,
         summaryModel: '',
         summaryText: existingSummary ?? '',
-        reason: 'compaction cooldown active with low projected gain',
+        reason: 'compaction cooldown active',
       };
     }
 
@@ -355,7 +375,7 @@ function collectUserTurnStartIndexes(messages: Message[]): number[] {
   for (let i = 0; i < messages.length; i++) {
     const message = messages[i];
     if (message.role !== 'user') continue;
-    if (getSummaryFromContextMessage(message) !== null) continue;
+    if (getSummaryFromContextMessage(message) !== undefined) continue;
     if (isToolResultOnly(message)) continue;
     starts.push(i);
   }
@@ -370,7 +390,7 @@ function collectUserTurnStartIndexes(messages: Message[]): number[] {
  */
 function countPersistedMessages(messages: Message[]): number {
   return messages.filter((message) => {
-    return getSummaryFromContextMessage(message) === null;
+    return getSummaryFromContextMessage(message) === undefined;
   }).length;
 }
 

package/src/daemon/approval-generators.ts

@@ -0,0 +1,186 @@
+import type { ApprovalCopyGenerator, ApprovalConversationGenerator, ApprovalConversationResult, ApprovalConversationDisposition } from '../runtime/http-types.js';
+import {
+  buildGenerationPrompt,
+  includesRequiredKeywords,
+  getFallbackMessage,
+  APPROVAL_COPY_TIMEOUT_MS,
+  APPROVAL_COPY_MAX_TOKENS,
+  APPROVAL_COPY_SYSTEM_PROMPT,
+} from '../runtime/approval-message-composer.js';
+import { loadConfig } from '../config/loader.js';
+import { getFailoverProvider, listProviders } from '../providers/registry.js';
+
+// ---------------------------------------------------------------------------
+// Approval conversation generator constants
+// ---------------------------------------------------------------------------
+
+const APPROVAL_CONVERSATION_TIMEOUT_MS = 8_000;
+const APPROVAL_CONVERSATION_MAX_TOKENS = 300;
+
+const APPROVAL_CONVERSATION_SYSTEM_PROMPT =
+  'You are an assistant helping a user manage a pending tool approval request. '
+  + 'Analyze the user\'s message to determine if they are making a decision '
+  + '(approve, reject, or cancel) or just asking a question / making conversation. '
+  + 'When uncertain, default to keep_pending — never approve or reject without clear intent. '
+  + 'For guardians: explain what tool is requesting approval and from whom. '
+  + 'Always provide a natural, helpful reply along with your decision.';
+
+const APPROVAL_CONVERSATION_TOOL_NAME = 'approval_decision';
+
+const APPROVAL_CONVERSATION_TOOL_SCHEMA = {
+  name: APPROVAL_CONVERSATION_TOOL_NAME,
+  description:
+    'Record the disposition of the approval conversation turn. '
+    + 'Call this tool with the determined disposition and a natural reply to the user.',
+  input_schema: {
+    type: 'object' as const,
+    properties: {
+      disposition: {
+        type: 'string',
+        enum: ['keep_pending', 'approve_once', 'approve_always', 'reject'],
+        description:
+          'The decision: keep_pending if the user is asking questions or unclear, '
+          + 'approve_once to approve this single request, approve_always to approve '
+          + 'this tool permanently, reject to deny the request.',
+      },
+      replyText: {
+        type: 'string',
+        description: 'A natural language reply to send back to the user.',
+      },
+      targetRunId: {
+        type: 'string',
+        description:
+          'The run ID of the specific pending approval being acted on. '
+          + 'Required when there are multiple pending approvals and the disposition is decision-bearing.',
+      },
+    },
+    required: ['disposition', 'replyText'],
+  },
+};
+
+const VALID_DISPOSITIONS: ReadonlySet<string> = new Set([
+  'keep_pending',
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+/**
+ * Create the daemon-owned approval copy generator that resolves providers
+ * and calls `provider.sendMessage` to generate approval copy text.
+ * This keeps all provider awareness in the daemon lifecycle, away from
+ * the runtime composer.
+ */
+export function createApprovalCopyGenerator(): ApprovalCopyGenerator {
+  return async (context, options = {}) => {
+    const config = loadConfig();
+    let provider;
+    try {
+      provider = getFailoverProvider(config.provider, config.providerOrder);
+    } catch {
+      return null;
+    }
+
+    const fallbackText = options.fallbackText?.trim() || getFallbackMessage(context);
+    const requiredKeywords = options.requiredKeywords?.map((kw) => kw.trim()).filter((kw) => kw.length > 0);
+    const prompt = buildGenerationPrompt(context, fallbackText, requiredKeywords);
+
+    const response = await provider.sendMessage(
+      [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+      [],
+      APPROVAL_COPY_SYSTEM_PROMPT,
+      {
+        config: {
+          max_tokens: options.maxTokens ?? APPROVAL_COPY_MAX_TOKENS,
+        },
+        signal: AbortSignal.timeout(options.timeoutMs ?? APPROVAL_COPY_TIMEOUT_MS),
+      },
+    );
+
+    const block = response.content.find((entry) => entry.type === 'text');
+    const text = block && 'text' in block ? block.text.trim() : '';
+    if (!text) return null;
+    const cleaned = text
+      .replace(/^["'`]+/, '')
+      .replace(/["'`]+$/, '')
+      .trim();
+    if (!cleaned) return null;
+    if (!includesRequiredKeywords(cleaned, requiredKeywords)) return null;
+    return cleaned;
+  };
+}
+
+/**
+ * Create the daemon-owned approval conversation generator that resolves
+ * providers and uses tool_use / function calling for structured output.
+ * Follows the same provider-aware pattern as createApprovalCopyGenerator().
+ */
+export function createApprovalConversationGenerator(): ApprovalConversationGenerator {
+  return async (context) => {
+    const config = loadConfig();
+    if (!listProviders().includes(config.provider)) {
+      throw new Error('No provider available for approval conversation');
+    }
+    const provider = getFailoverProvider(config.provider, config.providerOrder);
+
+    const pendingDescription = context.pendingApprovals
+      .map((p) => `- Run ${p.runId}: tool "${p.toolName}"`)
+      .join('\n');
+
+    const userPrompt = [
+      `Role: ${context.role}`,
+      `Tool requesting approval: "${context.toolName}"`,
+      `Allowed actions: ${context.allowedActions.join(', ')}`,
+      `Pending approvals:\n${pendingDescription}`,
+      `\nUser message: ${context.userMessage}`,
+    ].join('\n');
+
+    const response = await provider.sendMessage(
+      [{ role: 'user', content: [{ type: 'text', text: userPrompt }] }],
+      [APPROVAL_CONVERSATION_TOOL_SCHEMA],
+      APPROVAL_CONVERSATION_SYSTEM_PROMPT,
+      {
+        config: {
+          max_tokens: APPROVAL_CONVERSATION_MAX_TOKENS,
+        },
+        signal: AbortSignal.timeout(APPROVAL_CONVERSATION_TIMEOUT_MS),
+      },
+    );
+
+    // Extract the tool_use block from the response
+    const toolUseBlock = response.content.find(
+      (block) => block.type === 'tool_use' && block.name === APPROVAL_CONVERSATION_TOOL_NAME,
+    );
+
+    if (!toolUseBlock || toolUseBlock.type !== 'tool_use') {
+      throw new Error('Provider did not return a tool_use block for approval decision');
+    }
+
+    const input = toolUseBlock.input as Record<string, unknown>;
+
+    // Strict validation of the structured output
+    const disposition = input.disposition;
+    if (typeof disposition !== 'string' || !VALID_DISPOSITIONS.has(disposition)) {
+      throw new Error(`Invalid disposition: ${String(disposition)}`);
+    }
+
+    const replyText = input.replyText;
+    if (typeof replyText !== 'string' || replyText.trim().length === 0) {
+      throw new Error('Missing or empty replyText in tool_use response');
+    }
+
+    const targetRunId = input.targetRunId;
+    if (targetRunId !== undefined && typeof targetRunId !== 'string') {
+      throw new Error('Invalid targetRunId in tool_use response');
+    }
+
+    const result: ApprovalConversationResult = {
+      disposition: disposition as ApprovalConversationDisposition,
+      replyText: replyText.trim(),
+    };
+    if (typeof targetRunId === 'string' && targetRunId.length > 0) {
+      result.targetRunId = targetRunId;
+    }
+    return result;
+  };
+}