mobile-debug-mcp 0.24.6 → 0.24.8

package/src/interact/index.ts

@@ -36,6 +36,7 @@ interface UiElement {
   parentId?: number | string | null
   _index?: number
   _interactable?: boolean
+  _sliderLike?: boolean
 }
 
 interface ResolvedUiElementContext {
@@ -46,9 +47,22 @@ interface ResolvedUiElementContext {
   index: number
 }
 
+interface UiResolution {
+  width?: number
+  height?: number
+}
+
 
 export class ToolsInteract {
   private static readonly _maxResolvedUiElements = 256
+  private static readonly _sliderSearchLookahead = 8
+  private static readonly _sliderNegativeGapTolerancePx = 32
+  private static readonly _sliderPositiveGapLimitPx = 640
+  private static readonly _sliderTrackMinLengthPx = 220
+  private static readonly _sliderTrackMaxThicknessPx = 180
+  private static readonly _sliderTrackLengthRatio = 0.18
+  private static readonly _sliderTrackThicknessRatio = 0.08
+  private static readonly _sliderLabelWidthRatio = 1.5
   private static _resolvedUiElements = new Map<string, ResolvedUiElementContext>()
 
   private static _normalize(s: any): string {
@@ -240,6 +254,78 @@ export class ToolsInteract {
     return best
   }
 
+  private static _resolveNearbyActionableControl(
+    elements: UiElement[],
+    chosen: { el: UiElement, idx: number } | null,
+    screen?: UiResolution | null
+  ): { el: UiElement, idx: number, sliderLike?: boolean } | null {
+    if (!chosen) return null
+
+    const labelBounds = ToolsInteract._normalizeBounds(chosen.el.bounds)
+    if (!labelBounds) return null
+
+    const [labelLeft, labelTop, labelRight, labelBottom] = labelBounds
+    const labelWidth = labelRight - labelLeft
+    const labelHeight = labelBottom - labelTop
+    const screenWidth = Number(screen?.width) > 0 ? Number(screen?.width) : 0
+    const screenHeight = Number(screen?.height) > 0 ? Number(screen?.height) : 0
+    const minTrackLengthPx = Math.max(
+      ToolsInteract._sliderTrackMinLengthPx,
+      screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackLengthRatio) : 0,
+      screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackLengthRatio) : 0
+    )
+    const maxTrackThicknessPx = Math.max(
+      ToolsInteract._sliderTrackMaxThicknessPx,
+      screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackThicknessRatio) : 0,
+      screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackThicknessRatio) : 0
+    )
+
+    let best: { el: UiElement, idx: number, sliderLike?: boolean } | null = null
+    let bestScore = Infinity
+
+    for (let i = chosen.idx + 1; i < Math.min(elements.length, chosen.idx + ToolsInteract._sliderSearchLookahead); i++) {
+      const candidate = elements[i]
+      if (!candidate || !(candidate.clickable || candidate.focusable) || candidate.visible === false) continue
+
+      const candidateBounds = ToolsInteract._normalizeBounds(candidate.bounds)
+      if (!candidateBounds) continue
+
+      const [left, top, right] = candidateBounds
+      const width = right - left
+      const height = candidateBounds[3] - top
+      const verticalGap = top - labelBottom
+      if (verticalGap < -ToolsInteract._sliderNegativeGapTolerancePx || verticalGap > ToolsInteract._sliderPositiveGapLimitPx) continue
+
+      const horizontalOverlap = Math.min(labelRight, right) - Math.max(labelLeft, left)
+      if (horizontalOverlap < -ToolsInteract._sliderNegativeGapTolerancePx) continue
+
+      const candidateText = ToolsInteract._normalize(candidate.text ?? candidate.label ?? candidate.value ?? '')
+      const candidateContent = ToolsInteract._normalize(candidate.contentDescription ?? candidate.contentDesc ?? candidate.accessibilityLabel ?? '')
+      const candidateClass = ToolsInteract._normalize(candidate.type ?? candidate.class ?? '')
+
+      let score = verticalGap
+      const horizontalTrackLike =
+        width >= Math.max(minTrackLengthPx, Math.floor(labelWidth * ToolsInteract._sliderLabelWidthRatio)) &&
+        height <= maxTrackThicknessPx
+      const verticalTrackLike =
+        height >= Math.max(minTrackLengthPx, Math.floor(labelHeight * ToolsInteract._sliderLabelWidthRatio)) &&
+        width <= maxTrackThicknessPx
+      const trackLike = /slider|seek|range/i.test(candidateClass) || horizontalTrackLike || verticalTrackLike
+      if (!candidateText && !candidateContent) score -= 18
+      if (trackLike) score -= 30
+      if (/view|layout|group|frame/i.test(candidateClass)) score -= 10
+      if (width > labelWidth * ToolsInteract._sliderLabelWidthRatio) score -= 8
+      if (candidateText || candidateContent) score += 20
+
+      if (score < bestScore) {
+        bestScore = score
+        best = { el: candidate, idx: i, sliderLike: trackLike }
+      }
+    }
+
+    return best
+  }
+
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
     const effectivePlatform = platform || 'android'
@@ -347,6 +433,7 @@ export class ToolsInteract {
 
     let best: UiElement | null = null
     let bestScore = 0
+    let lastTree: any = null
 
     const scoreElement = (el: UiElement | null) => {
       if (!el || !el.visible) return 0
@@ -380,7 +467,8 @@ export class ToolsInteract {
 
     while (Date.now() <= deadline) {
       try {
-        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+      lastTree = tree
         if (tree && Array.isArray((tree as any).elements)) {
           const elements = ((tree as any).elements as UiElement[])
           for (let i = 0; i < elements.length; i++) {
@@ -407,8 +495,8 @@ export class ToolsInteract {
 
     // If the best match is not interactable, try to resolve an actionable ancestor.
     try {
-      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
-      const elements = (tree && Array.isArray(tree.elements)) ? (tree.elements as UiElement[]) : []
+      const elements = (lastTree && Array.isArray(lastTree.elements)) ? (lastTree.elements as UiElement[]) : []
+      const screen = lastTree?.resolution && typeof lastTree.resolution === 'object' ? lastTree.resolution as UiResolution : null
       let chosen = best as any
       const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null
 
@@ -465,6 +553,16 @@ export class ToolsInteract {
         // small score bump to reflect actionability
         bestScore = Math.min(1, bestScore + 0.02)
       }
+
+      if (best && !(best.clickable || best.focusable)) {
+        const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best, idx: best._index ?? elements.indexOf(best) }, screen)
+        if (nearbyActionable) {
+          best = nearbyActionable.el
+          best._index = nearbyActionable.idx
+          best._interactable = true
+          best._sliderLike = nearbyActionable.sliderLike
+        }
+      }
     } catch (e) { console.error('Error resolving ancestor:', e) }
 
     if (!best) return { found: false, error: 'Element not found' }
@@ -483,8 +581,18 @@ export class ToolsInteract {
       tapCoordinates,
       telemetry: {
         matchedIndex: best?._index ?? null,
-        matchedInteractable: !!best?._interactable
+        matchedInteractable: !!best?._interactable,
+        sliderLike: !!best?._sliderLike
+      }
+    }
+    if (best?._sliderLike) {
+      const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left)
+      const interactionHint = {
+        kind: 'slider',
+        axis: isVertical ? 'vertical' : 'horizontal',
+        trackBounds: boundsObj
       }
+      ;(outEl as any).interactionHint = interactionHint
     }
     const scoreVal = Math.min(1, Number(bestScore.toFixed(3)))
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }

package/src/manage/android.ts

@@ -2,22 +2,33 @@ import { promises as fs } from 'fs'
 import { spawn } from 'child_process'
 import path from 'path'
 import { existsSync } from 'fs'
-import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js'
+import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk, prepareGradle } from '../utils/android/utils.js'
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js'
 import { detectJavaHome } from '../utils/java.js'
 import { AndroidObserve } from '../observe/android.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
+type BuildEnv = Record<string, string | undefined>
+
+export interface AndroidBuildOptions {
+  variant?: string
+  env?: BuildEnv
+}
+
 export class AndroidManage {
   private isTestOnlyInstallFailure(output: string | undefined): boolean {
     return typeof output === 'string' && output.includes('INSTALL_FAILED_TEST_ONLY')
   }
 
-  async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
-    void _variant
+  async build(projectPath: string, optionsOrVariant?: string | AndroidBuildOptions): Promise<{ artifactPath: string, output?: string } | { error: string }> {
+    const options: AndroidBuildOptions = typeof optionsOrVariant === 'string' ? { variant: optionsOrVariant } : (optionsOrVariant || {})
     try {
+      const env = {
+        ...(options.env || {}),
+        ...(options.variant ? { MCP_GRADLE_TASK: options.variant } : {})
+      }
       // Always use the shared prepareGradle utility for consistent env/setup
-      const { execCmd, gradleArgs, spawnOpts } = await (await import('../utils/android/utils.js')).prepareGradle(projectPath)
+      const { execCmd, gradleArgs, spawnOpts } = await prepareGradle(projectPath, env)
       await new Promise<void>((resolve, reject) => {
         const proc = spawn(execCmd, gradleArgs, spawnOpts)
         let stderr = ''
@@ -43,13 +54,13 @@ export class AndroidManage {
 
     let apkToInstall: string = apkPath
     try {
-      const stat = await fs.stat(apkPath).catch(() => null)
-      if (stat && stat.isDirectory()) {
-        const detectedJavaHome = await detectJavaHome().catch(() => undefined)
-        const env = Object.assign({}, process.env)
-        if (detectedJavaHome) {
-          if (env.JAVA_HOME !== detectedJavaHome) {
-            env.JAVA_HOME = detectedJavaHome
+        const stat = await fs.stat(apkPath).catch(() => null)
+        if (stat && stat.isDirectory()) {
+          const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+          const env = { ...process.env }
+          if (detectedJavaHome) {
+            if (env.JAVA_HOME !== detectedJavaHome) {
+              env.JAVA_HOME = detectedJavaHome
             env.PATH = `${path.join(detectedJavaHome, 'bin')}${path.delimiter}${env.PATH || ''}`
             console.debug('[android-run] Overriding JAVA_HOME with detected path:', detectedJavaHome)
           }

package/src/manage/index.ts

@@ -60,25 +60,37 @@ export async function detectProjectPlatform(projectPath: string): Promise<'ios'|
   }
 }
 
+type BuildEnv = Record<string, string | undefined>
+
+function mergeDefinedEnv(...parts: Array<BuildEnv | undefined>): BuildEnv {
+  const merged: BuildEnv = {}
+  for (const part of parts) {
+    if (!part) continue
+    for (const [key, value] of Object.entries(part)) {
+      if (typeof value === 'undefined') continue
+      merged[key] = value
+    }
+  }
+  return merged
+}
+
 export class ToolsManage {
   static async build_android({ projectPath, gradleTask, maxWorkers, gradleCache, forceClean }: { projectPath: string, gradleTask?: string, maxWorkers?: number, gradleCache?: boolean, forceClean?: boolean }) {
     const android = new AndroidManage()
-    // prepare gradle options via environment hints
-    if (typeof maxWorkers === 'number') process.env.MCP_GRADLE_WORKERS = String(maxWorkers)
-    if (typeof gradleCache === 'boolean') process.env.MCP_GRADLE_CACHE = gradleCache ? '1' : '0'
-    if (forceClean) process.env.MCP_FORCE_CLEAN_ANDROID = '1'
     const task = gradleTask || 'assembleDebug'
-    const artifact = await (android as any).build(projectPath, task)
-    return artifact
+    return await (android as any).build(projectPath, {
+      variant: task,
+      env: mergeDefinedEnv({
+        MCP_GRADLE_TASK: task,
+        MCP_GRADLE_WORKERS: typeof maxWorkers === 'number' ? String(maxWorkers) : undefined,
+        MCP_GRADLE_CACHE: typeof gradleCache === 'boolean' ? (gradleCache ? '1' : '0') : undefined,
+        MCP_FORCE_CLEAN_ANDROID: forceClean ? '1' : undefined
+      })
+    })
   }
 
   static async build_ios({ projectPath, workspace: _workspace, project: _project, scheme: _scheme, destinationUDID, derivedDataPath, buildJobs, forceClean }: { projectPath: string, workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, buildJobs?: number, forceClean?: boolean }) {
     const ios = new iOSManage()
-    // Use provided options rather than env-only; still set env fallbacks for downstream tools
-    if (derivedDataPath) process.env.MCP_DERIVED_DATA = derivedDataPath
-    if (typeof buildJobs === 'number') process.env.MCP_BUILD_JOBS = String(buildJobs)
-    if (forceClean) process.env.MCP_FORCE_CLEAN_IOS = '1'
-    if (destinationUDID) process.env.MCP_XCODE_DESTINATION_UDID = destinationUDID
 
     const opts: any = {}
     if (_workspace) opts.workspace = _workspace
@@ -86,12 +98,21 @@ export class ToolsManage {
     if (_scheme) opts.scheme = _scheme
     if (destinationUDID) opts.destinationUDID = destinationUDID
     if (derivedDataPath) opts.derivedDataPath = derivedDataPath
-    if (forceClean) opts.forceClean = forceClean
+    if (typeof buildJobs === 'number') opts.buildJobs = buildJobs
+    if (typeof forceClean === 'boolean') opts.forceClean = forceClean
     // prefer explicit xcodebuild path from env
     if (process.env.XCODEBUILD_PATH) opts.xcodeCmd = process.env.XCODEBUILD_PATH
 
-    const artifact = await (ios as any).build(projectPath, opts)
-    return artifact
+    return await (ios as any).build(projectPath, {
+      ...opts,
+      env: mergeDefinedEnv({
+        MCP_DERIVED_DATA: derivedDataPath,
+        MCP_XCODE_JOBS: typeof buildJobs === 'number' ? String(buildJobs) : undefined,
+        MCP_FORCE_CLEAN: typeof forceClean === 'boolean' ? (forceClean ? '1' : '0') : undefined,
+        MCP_XCODE_DESTINATION_UDID: destinationUDID,
+        XCODEBUILD_PATH: process.env.XCODEBUILD_PATH
+      })
+    })
   }
 
   static async build_flutter({ projectPath, platform, buildMode, maxWorkers: _maxWorkers, forceClean: _forceClean }: { projectPath: string, platform?: 'android'|'ios', buildMode?: 'debug'|'release'|'profile', maxWorkers?: number, forceClean?: boolean }) {
@@ -178,11 +199,11 @@ export class ToolsManage {
     const chosen = platform || 'android'
     if (chosen === 'android') {
       const android = new AndroidManage()
-      const artifact = await (android as any).build(projectPath, variant)
+      const artifact = await (android as any).build(projectPath, { variant })
       return artifact
     } else {
       const ios = new iOSManage()
-      const artifact = await (ios as any).build(projectPath, variant)
+      const artifact = await (ios as any).build(projectPath, { variant })
       return artifact
     }
   }

package/src/manage/ios.ts

@@ -5,12 +5,25 @@ import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validate
 import { iOSObserve } from "../observe/ios.js"
 import path from "path"
 
+type BuildEnv = Record<string, string | undefined>
+
+export interface IOSBuildOptions {
+  workspace?: string
+  project?: string
+  scheme?: string
+  destinationUDID?: string
+  derivedDataPath?: string
+  buildJobs?: number
+  forceClean?: boolean
+  xcodeCmd?: string
+  env?: BuildEnv
+}
+
 export class iOSManage {
-  async build(projectPath: string, optsOrVariant?: string | { workspace?: string, project?: string, scheme?: string, destinationUDID?: string, derivedDataPath?: string, forceClean?: boolean, xcodeCmd?: string }): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
+  async build(projectPath: string, optsOrVariant?: string | IOSBuildOptions): Promise<{ artifactPath: string, output?: string } | { error: string, diagnostics?: any }> {
     // Support legacy variant string as second arg
-    let opts: any = {}
-    if (typeof optsOrVariant === 'string') opts.variant = optsOrVariant
-    else opts = optsOrVariant || {}
+    const opts: IOSBuildOptions = typeof optsOrVariant === 'string' ? {} : (optsOrVariant || {})
+    const env = { ...process.env, ...(opts.env || {}) }
 
     try {
       // Look for an Xcode workspace or project at the provided path. If not present, scan subdirectories (limited depth)
@@ -65,7 +78,7 @@ export class iOSManage {
       }
 
       // Determine destination: prefer explicit option, then env var, otherwise use booted simulator UDID
-      let destinationUDID = opts.destinationUDID || process.env.MCP_XCODE_DESTINATION_UDID || process.env.MCP_XCODE_DESTINATION || ''
+      let destinationUDID = opts.destinationUDID || env.MCP_XCODE_DESTINATION_UDID || env.MCP_XCODE_DESTINATION || ''
       if (!destinationUDID) {
         try {
           const meta = await getIOSDeviceMetadata('booted')
@@ -74,7 +87,7 @@ export class iOSManage {
       }
 
       // Determine xcode command early so it can be used when detecting schemes
-      const xcodeCmd = opts.xcodeCmd || process.env.XCODEBUILD_PATH || 'xcodebuild'
+      const xcodeCmd = opts.xcodeCmd || env.XCODEBUILD_PATH || 'xcodebuild'
 
       // Determine available schemes by querying xcodebuild -list rather than guessing
       async function detectScheme(xcodeCmdInner: string, workspacePath?: string, projectPathFull?: string, cwd?: string): Promise<string | null> {
@@ -98,11 +111,11 @@ export class iOSManage {
       let chosenScheme: string | null = opts.scheme || null
 
       // Derived data and result bundle (agent-configurable)
-      const derivedDataPath = opts.derivedDataPath || process.env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
+      const derivedDataPath = opts.derivedDataPath || env.MCP_DERIVED_DATA || path.join(projectRootDir, 'build', 'DerivedData')
       // Use unique result bundle path by default to avoid collisions
-      const resultBundlePath = process.env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`)
-      const xcodeJobs = parseInt(process.env.MCP_XCODE_JOBS || '', 10) || 4
-      const forceClean = opts.forceClean || process.env.MCP_FORCE_CLEAN === '1'
+      const resultBundlePath = env.MCP_XCODE_RESULTBUNDLE_PATH || path.join(projectRootDir, 'build', 'xcresults', `ResultBundle-${Date.now()}-${Math.random().toString(36).slice(2)}.xcresult`)
+      const xcodeJobs = typeof opts.buildJobs === 'number' ? opts.buildJobs : (parseInt(env.MCP_XCODE_JOBS || '', 10) || 4)
+      const forceClean = typeof opts.forceClean === 'boolean' ? opts.forceClean : env.MCP_FORCE_CLEAN === '1'
 
       // ensure result dirs exist
       await fs.mkdir(path.dirname(resultBundlePath), { recursive: true }).catch(() => {})
@@ -147,8 +160,8 @@ export class iOSManage {
       await fs.mkdir(resultsDir, { recursive: true }).catch(() => {})
 
 
-      const XCODEBUILD_TIMEOUT = parseInt(process.env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
-      const MAX_RETRIES = parseInt(process.env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
+      const XCODEBUILD_TIMEOUT = parseInt(env.MCP_XCODEBUILD_TIMEOUT || '', 10) || 180000 // default 3 minutes
+      const MAX_RETRIES = parseInt(env.MCP_XCODEBUILD_RETRIES || '', 10) || 1
 
       const tries = MAX_RETRIES + 1
       let lastStdout = ''
@@ -157,8 +170,8 @@ export class iOSManage {
 
       for (let attempt = 1; attempt <= tries; attempt++) {
         // Run xcodebuild with a watchdog
-        const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
-          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir })
+          const res = await new Promise<{ code: number | null, stdout: string, stderr: string, killedByWatchdog?: boolean }>((resolve) => {
+          const proc = spawn(xcodeCmd, buildArgs, { cwd: projectRootDir, env })
           let stdout = ''
           let stderr = ''
 
@@ -215,7 +228,7 @@ export class iOSManage {
       if (lastErr) {
         // Include diagnostics and result bundle path when available; provide structured info useful for agents
         const invokedCommand = `${xcodeCmd} ${buildArgs.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`
-        const envSnapshot = { PATH: process.env.PATH }
+          const envSnapshot = { PATH: env.PATH }
         return { error: `xcodebuild failed: ${lastErr.message}. See build-results for logs.`, output: `stdout:\n${lastStdout}\nstderr:\n${lastStderr}`, diagnostics: { exitCode: (lastErr as any).code || null, invokedCommand, cwd: projectRootDir, envSnapshot } }
       }
 

package/src/server/common.ts

@@ -20,6 +20,56 @@ export type ToolCallResult = Awaited<ReturnType<typeof wrapResponse>> | {
 }
 export type ToolHandler = (args: ToolCallArgs) => Promise<ToolCallResult>
 
+export function getStringArg(args: ToolCallArgs, key: string): string | undefined {
+  const value = args[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+export function requireStringArg(args: ToolCallArgs, key: string): string {
+  const value = getStringArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid string argument: ${key}`)
+  return value
+}
+
+export function getNumberArg(args: ToolCallArgs, key: string): number | undefined {
+  const value = args[key]
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+export function requireNumberArg(args: ToolCallArgs, key: string): number {
+  const value = getNumberArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid number argument: ${key}`)
+  return value
+}
+
+export function getBooleanArg(args: ToolCallArgs, key: string): boolean | undefined {
+  const value = args[key]
+  return typeof value === 'boolean' ? value : undefined
+}
+
+export function requireBooleanArg(args: ToolCallArgs, key: string): boolean {
+  const value = getBooleanArg(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid boolean argument: ${key}`)
+  return value
+}
+
+export function getObjectArg<T extends Record<string, unknown>>(args: ToolCallArgs, key: string): T | undefined {
+  const value = args[key]
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  return value as T
+}
+
+export function requireObjectArg<T extends Record<string, unknown>>(args: ToolCallArgs, key: string): T {
+  const value = getObjectArg<T>(args, key)
+  if (value === undefined) throw new Error(`Missing or invalid object argument: ${key}`)
+  return value
+}
+
+export function getArrayArg<T>(args: ToolCallArgs, key: string): T[] | undefined {
+  const value = args[key]
+  return Array.isArray(value) ? value as T[] : undefined
+}
+
 let actionSequence = 0
 
 export function nextActionId(actionType: string, timestamp: number) {