mobile-debug-mcp 0.33.0 → 0.35.0

package/src/server/tool-definitions.ts

@@ -1,1146 +1,73 @@
-import { journeyStepsJson } from './journey-schema.js'
-import { conditionalTools, expectedStateJson } from './condition-schema.js'
-import { readinessPropertiesJson } from './readiness-schema.js'
-
-export const toolDefinitions: any[] = [
-  ...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
+import { verificationModeJson, responseModeJson } from '../contracts/execution-controls.js'
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+import { manageTools } from './definitions/manage.js'
+import { observeTools } from './definitions/observe.js'
+import { diagnosticTools } from './definitions/diagnostic.js'
+import { waitTools } from './definitions/wait.js'
+import { assertTools } from './definitions/assert.js'
+import { targetTools } from './definitions/target.js'
+import { inputTools } from './definitions/input.js'
+import { debuggerTools } from './schemas/debugger-schema.js'
+import { systemTraceTools } from './schemas/system-trace-schema.js'
+import { journeyStepsJson } from './schemas/journey-schema.js'
+import { conditionalTools, expectedStateJson } from './schemas/condition-schema.js'
+import { readinessPropertiesJson } from './schemas/readiness-schema.js'
+
+const baseTools = new Map([...manageTools, ...observeTools, ...diagnosticTools, ...waitTools, ...assertTools, ...targetTools, ...inputTools].map(tool => [tool.name, tool]))
+const baseOrder = [
+  "start_app",
+  "terminate_app",
+  "restart_app",
+  "reset_app_data",
+  "install_app",
+  "build_app",
+  "get_logs",
+  "list_devices",
+  "get_system_status",
+  "capture_screenshot",
+  "capture_debug_snapshot",
+  "start_log_stream",
+  "read_log_stream",
+  "stop_log_stream",
+  "get_ui_tree",
+  "get_current_screen",
+  "get_screen_fingerprint",
+  "wait_for_screen_change",
+  "wait_for_ui_change",
+  "expect_screen",
+  "expect_element_visible",
+  "expect_state",
+  "adjust_control",
+  "wait_for_ui",
+  "find_element",
+  "tap",
+  "tap_element",
+  "swipe",
+  "scroll_to_element",
+  "type_text",
+  "press_back",
+  "classify_action_outcome",
+  "run_journey",
+  "get_network_activity"
+]
+export const toolDefinitions: Tool[] = [
+...debuggerTools,
+...systemTraceTools,
+...['get_app_readiness', 'wait_for_app_ready'].map(name => ({
     name,
-    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Unresponsive/debugger-paused detection is unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
-    inputSchema: { type: 'object', additionalProperties: false, required: ['platform'], properties: {
+    description: `${name === 'get_app_readiness' ? 'Observe readiness with at most two fresh UI-tree samples.' : 'Wait within a single bounded budget for settled UI evidence.'} Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.`,
+    inputSchema: { type: 'object' as const, additionalProperties: false, required: ['platform'], properties: {
       ...readinessPropertiesJson,
       timeoutMs: { ...readinessPropertiesJson.timeoutMs, default: name === 'get_app_readiness' ? 15000 : 30000 },
       ...(name === 'wait_for_app_ready' ? { pollIntervalMs: { type: 'integer', minimum: 100, maximum: 1000, default: 500 } } : {})
     } }
   })),
-  {
-    name: 'start_app',
-    description: `Purpose:
-Launch a mobile app on Android or iOS.
-
-Inputs:
-- platform
-- appId
-- deviceId (optional)
-
-Output Structure:
- - action_id, timestamp (ISO 8601), action_type
- - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
- - source_module: runtime source of the action envelope
- - target.selector = { appId }
-- success = true when launch was dispatched successfully
-- failure_code/retryable when launch dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Define the expected landing screen when it is known
-2. Call start_app
-3. If needed, wait for transition using wait_for_*
-4. Verify with expect_screen
-5. If verification fails, retry once or capture a snapshot
-
-Verification Guidance:
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- expect_screen is the authoritative verification step when the landing screen is known
-- Do not treat timing or screen change alone as final verification
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → inspect snapshot/logs before retrying`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        appId: {
-          type: 'string',
-          description: 'Android package name or iOS bundle id'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        },
-        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
-        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
-        actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
-        verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
-      },
-      required: ['platform', 'appId']
-    }
-  },
-  {
-    name: 'terminate_app',
-    description: 'Terminate a mobile app on Android or iOS simulator',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        appId: {
-          type: 'string',
-          description: 'Android package name or iOS bundle id'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        }
-      },
-      required: ['platform', 'appId']
-    }
-  },
-  {
-    name: 'restart_app',
-    description: `Purpose:
-Restart a mobile app on Android or iOS.
-
-Inputs:
-- platform
-- appId
-- deviceId (optional)
-
-Output Structure:
- - action_id, timestamp (ISO 8601), action_type
- - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
- - source_module: runtime source of the action envelope
- - target.selector = { appId }
-- success = true when the restart command completed
-- failure_code/retryable when restart dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Define the expected landing screen when it is known
-2. Call restart_app
-3. If needed, wait for transition using wait_for_*
-4. Verify with expect_screen
-5. If verification fails, retry once or capture a snapshot
-
-Verification Guidance:
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- expect_screen is the authoritative verification step when the reopened screen is known
-- Do not treat timing or screen change alone as final verification
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → inspect snapshot/logs before retrying`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        appId: {
-          type: 'string',
-          description: 'Android package name or iOS bundle id'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        }
-      },
-      required: ['platform', 'appId']
-    }
-  },
-  {
-    name: 'reset_app_data',
-    description: 'Reset app data (clear storage) for a mobile app on Android or iOS simulator',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        appId: {
-          type: 'string',
-          description: 'Android package name or iOS bundle id'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        }
-      },
-      required: ['platform', 'appId']
-    }
-  },
-  {
-    name: 'install_app',
-    description: 'Install an app on Android or iOS. Accepts a built binary (apk/.ipa/.app) or a project directory to build then install. platform and projectType are required.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to install to (required).' },
-        projectType: { type: 'string', enum: ['native', 'kmp', 'react-native', 'flutter'], description: 'Project type to guide build/install tool selection (required).' },
-        appPath: { type: 'string', description: 'Path to APK, .app, .ipa, or project directory' },
-        deviceId: { type: 'string', description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.' }
-      },
-      required: ['platform', 'projectType', 'appPath']
-    }
-  },
-  {
-    name: 'build_app',
-    description: 'Build a project for Android or iOS and return the built artifact path. Does not install. platform and projectType are required.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to build for (required).' },
-        projectType: { type: 'string', enum: ['native', 'kmp', 'react-native', 'flutter'], description: 'Project type to guide build tool selection (required).' },
-        projectPath: { type: 'string', description: 'Path to project directory (contains gradlew or xcodeproj/xcworkspace)' },
-        variant: { type: 'string', description: 'Optional build variant (e.g., Debug/Release)' }
-      },
-      required: ['platform', 'projectType', 'projectPath']
-    }
-  },
-  {
-    name: 'get_logs',
-    description: 'Get recent logs from Android or iOS simulator. Returns device metadata and structured logs suitable for AI consumption.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        appId: {
-          type: 'string',
-          description: 'Filter by Android package name or iOS bundle id'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        },
-        pid: { type: 'number', description: 'Filter by process id' },
-        tag: { type: 'string', description: 'Filter by tag (Android) or subsystem/category (iOS)' },
-        level: { type: 'string', description: 'Log level filter (VERBOSE, DEBUG, INFO, WARN, ERROR)' },
-        contains: { type: 'string', description: 'Substring to match in log message' },
-        since_seconds: { type: 'number', description: 'Only return logs from the last N seconds' },
-        limit: { type: 'number', description: 'Override default number of returned lines' },
-        lines: {
-          type: 'number',
-          description: 'Legacy - number of log lines (android only)'
-        }
-      },
-      required: ['platform']
-    }
-  },
-  {
-    name: 'list_devices',
-    description: 'List connected devices and their metadata (android + ios).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'] }
-      }
-    }
-  },
-  {
-    name: 'get_system_status',
-    description: 'Quick healthcheck of local mobile debugging environment (adb, devices, logs, env, iOS).',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'capture_screenshot',
-    description: 'Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios']
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        }
-      },
-      required: ['platform']
-    }
-  },
-  {
-    name: 'capture_debug_snapshot',
-    description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        reason: { type: 'string', description: 'Optional reason for snapshot' },
-        includeLogs: { type: 'boolean', description: 'Whether to include logs', default: true },
-        includeScreenshot: { type: 'boolean', description: 'Whether to collect screenshot bytes', default: true },
-        logLines: { type: 'number', description: 'Maximum number of log lines to include', default: 200 },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        appId: { type: 'string', description: 'Optional appId to scope logs (package/bundle id)' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' },
-        sessionId: { type: 'string', description: 'Optional log stream session id to prefer' }
-      }
-    }
-  },
-  {
-    name: 'start_log_stream',
-    description: 'Start streaming logs for a target application on Android or iOS. For Android this uses adb logcat --pid=<pid>; for iOS it streams `xcrun simctl spawn <device> log stream` with a predicate.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], default: 'android' },
-        packageName: { type: 'string', description: 'Android package name or iOS bundle id' },
-        level: { type: 'string', enum: ['error', 'warn', 'info', 'debug'], default: 'error' },
-        deviceId: { type: 'string', description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.' },
-        sessionId: { type: 'string', description: 'Session identifier for the log stream' }
-      },
-      required: ['packageName']
-    }
-  },
-  {
-    name: 'read_log_stream',
-    description: 'Read accumulated log stream entries for the active session.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        sessionId: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'stop_log_stream',
-    description: 'Stop an active log stream for the session.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        sessionId: { type: 'string' }
-      }
-    }
-  },
-  {
-    name: 'get_ui_tree',
-    description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata and incremental delta signals when available.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios'],
-          description: 'Platform to get UI tree for'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.'
-        },
-        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
-        sinceSnapshotRevision: { type: 'number', minimum: 1 }
-      },
-      required: ['platform']
-    }
-  },
-  {
-    name: 'get_current_screen',
-    description: 'Get the currently visible activity on an Android device. Returns package and activity name.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial (Android). Defaults to connected/booted device.'
-        }
-      }
-    }
-  },
-  {
-    name: 'get_screen_fingerprint',
-    description: 'Generate a stable fingerprint representing the current visible screen (activity + visible UI elements).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
-        deviceId: { type: 'string', description: 'Optional device id/udid to target' }
-      }
-    }
-  },
-  {
-    name: 'wait_for_screen_change',
-    description: `Purpose:
-Detect that a screen transition has occurred by waiting for the current fingerprint to differ from a previous fingerprint.
-
-Capabilities:
-- Synchronization for uncertain navigation timing
-- Detection that something changed on screen
-
-Constraints:
-- Does not verify correctness of the resulting state
-- Must not be used alone to confirm action success when an applicable expect_* tool exists
-- For backend/API activity without a visible UI change, pass the runtime action_type into classify_action_outcome and collect network evidence only if the result remains ambiguous
-
-Recommended Usage:
-1. Capture or define the expected outcome
-2. Call an action tool
-3. Use wait_for_screen_change when transition timing is uncertain
-4. Follow with expect_screen when the expected destination is known`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
-        previousFingerprint: { type: 'string', description: 'The fingerprint to compare against (required)' },
-        timeoutMs: { type: 'number', description: 'Timeout in ms to wait for change (default 5000)', default: 5000 },
-        pollIntervalMs: { type: 'number', description: 'Polling interval in ms (default 300)', default: 300 },
-        deviceId: { type: 'string', description: 'Optional device id/udid to target' }
-      },
-      required: ['previousFingerprint']
-    }
-  },
-  {
-    name: 'wait_for_ui_change',
-    description: `Purpose:
-Wait for a non-navigation UI mutation or in-place update to become stable.
-
-Inputs:
-- expected_change (optional): hierarchy_diff, text_change, or state_change
-- timeout_ms (optional)
-- stability_window_ms (optional)
-- scope (optional): screen or subtree
-- target (optional): element_id when scope=subtree
-
-Guidance:
-- Prefer wait_for_screen_change for navigation transitions.
-- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
-- Use the returned snapshot_revision as the observed synchronization point when available.
-- Scoped waits return scope-aware stability metadata and a lightweight change summary.
-
-Failure Handling:
-- TIMEOUT means the UI did not change in a stable way within the allotted time.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
-        deviceId: { type: 'string', description: 'Optional device id/udid to target' },
-        expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
-        scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
-        target: { type: 'string', description: 'Target element_id when scope is subtree' },
-        timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
-        stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
-      }
-    }
-  },
-  {
-    name: 'expect_screen',
-    description: `Purpose:
-Deterministically verify that the intended navigation outcome of an action has occurred.
-
-Inputs:
-- fingerprint: preferred exact-match screen fingerprint
-- screen: exact semantic screen identifier when a fingerprint is not available
-
-Output Structure:
-- success: true when the expected screen matches the observed screen
-- observed_screen: current fingerprint and screen identifier
-- expected_screen: the expected fingerprint and/or screen identifier
-- confidence: 1 for an exact match, otherwise 0
-
-Recommended Usage:
-1. Define the expected screen before executing the action
-2. Resolve the target element or screen state
-3. Call an action tool such as tap_element
-4. If needed, wait for transition using wait_for_*
-5. Call expect_screen as the final verification step
-6. If success=false, treat the outcome as unverified and follow the action tool retry guidance
-
-Verification Guidance:
-- Primary and authoritative verification tool for navigation outcomes
-- Prefer fingerprint whenever you have one
-- Use screen only as a fallback exact match against known identifiers
-- Works best when the expected screen identifier is known ahead of time
-- If the expected screen is not already known, capture or define it before executing the action
-
-Constraints:
-- Returns structured binary success/failure only
-- Must not rely on natural-language interpretation or reasoning
-
-Failure Handling:
-- success=false means the expected screen was not reached; retry or recover using the action tool's failure strategy`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
-        fingerprint: { type: 'string', description: 'Expected screen fingerprint. Preferred verification mechanism.' },
-        screen: { type: 'string', description: 'Expected exact screen identifier when no fingerprint is available.' },
-        deviceId: { type: 'string', description: 'Optional device id/udid to target' }
-      }
-    }
-  },
-  {
-    name: 'expect_element_visible',
-    description: `Purpose:
-Deterministically verify that the intended UI outcome of an action has occurred by confirming a target element is visible.
-
-Inputs:
-- selector: required selector used to resolve the target element
-- element_id: optional previously resolved element identifier used only as context
-
-Output Structure:
-- success: true when the element is visible
-- selector: selector used for verification
-- element_id: resolved element identifier when available
-- element: minimal resolved element info when visible
-- failure_code: TIMEOUT or UNKNOWN when verification fails
-- retryable: true when failure_code=TIMEOUT
-
-Recommended Usage:
-1. Define the expected element state before executing the action
-2. Resolve the target element or triggering control
-3. Call an action tool such as tap_element
-4. If needed, wait for UI availability using wait_for_*
-5. Call expect_element_visible as the final verification step
-6. If success=false, follow the action tool retry guidance
-
-Verification Guidance:
-- Primary and authoritative verification tool for expected element appearance or visibility
-- Use this when the screen should stay the same but the UI should reveal or update a specific element
-- selector is the primary input; element_id is an optional optimization only
-- The tool resolves the selector internally when needed
-
-Constraints:
-- Returns structured binary success/failure only
-- Must not rely on natural-language interpretation or reasoning
-
-Failure Handling:
-- TIMEOUT → retry verification once or retry the action after re-resolving
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        selector: {
-          type: 'object',
-          properties: {
-            text: { type: 'string' },
-            resource_id: { type: 'string' },
-            accessibility_id: { type: 'string' },
-            contains: { type: 'boolean', default: false }
-          }
-        },
-        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
-        timeout_ms: { type: 'number', default: 5000 },
-        poll_interval_ms: { type: 'number', default: 300 },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' }
-      },
-      required: ['selector']
-    }
-  },
-  {
-    name: 'expect_state',
-    description: `Purpose:
-Verify a readable UI state property on the currently visible element.
-
-Inputs:
-- selector or element_id
-- property
-- expected
-- platform/deviceId (optional)
-
-Supported properties:
-- checked, selected, focused, expanded, enabled, text_value, value, raw_value
-
-Verification Guidance:
-- Use this when the UI element is visible but its state must also be confirmed
-- Prefer the canonical property names above
-- The tool compares the normalized readable state and returns the observed value when available
-
-Constraints:
-- Returns structured success/failure only
-- Does not infer a state when the property is unavailable
-
-Failure Handling:
-- ELEMENT_NOT_FOUND → re-resolve the element or wait for UI stabilization
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        selector: {
-          type: 'object',
-          properties: {
-            text: { type: 'string' },
-            resource_id: { type: 'string' },
-            accessibility_id: { type: 'string' },
-            contains: { type: 'boolean', default: false }
-          }
-        },
-        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
-        property: { type: 'string', description: 'Readable state property to verify.' },
-        expected: {
-          description: 'Expected normalized state value.',
-          oneOf: [
-            { type: 'boolean' },
-            { type: 'number' },
-            { type: 'string' },
-            { type: 'object' }
-          ]
-        },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' }
-      },
-      required: ['property', 'expected']
-    }
-  },
-  {
-    name: 'adjust_control',
-    description: `Purpose:
-Adjust a numeric control value with verification.
-
-This is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.
-
-Inputs:
-- exactly one of selector or element_id
-- property (defaults to "value")
-- targetValue
-- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)
-- maxAttempts (optional; defaults to 5)
-- platform/deviceId (optional)
-
-Output Structure:
-- action_id, timestamp (ISO 8601), action_type
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode
-- target.selector = original selector or element handle
-- success = true when the control converges within tolerance
-
-Verification Guidance:
-- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode
-- Use expect_state for the control value readback
-- Do not use derived semantic metadata as proof of success
-
-Failure Handling:
-- ELEMENT_NOT_FOUND → re-resolve the control
-- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime
-- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        selector: {
-          type: 'object',
-          properties: {
-            text: { type: 'string' },
-            resource_id: { type: 'string' },
-            accessibility_id: { type: 'string' },
-            contains: { type: 'boolean', default: false }
-          }
-        },
-        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
-        property: { type: 'string', description: 'Readable numeric state property to adjust.', default: 'value' },
-        targetValue: { type: 'number', description: 'Target numeric value.' },
-        tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value. Defaults are derived from the readable control domain.' },
-        maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 5 },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' }
-      },
-      required: ['targetValue'],
-      oneOf: [
-        { required: ['selector'] },
-        { required: ['element_id'] }
-      ]
-    }
-  },
-  {
-    name: 'wait_for_ui',
-    description: `Purpose:
-Resolve elements and/or detect that a UI transition or availability condition has occurred.
-
-Capabilities:
-- Deterministic element resolution
-- Synchronization when element timing or availability is uncertain
-
-Constraints:
-- Does not verify correctness of the resulting state
-- Must not be used alone to confirm action success when an applicable expect_* tool exists
-
-Recommended Usage:
-1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness
-2. Call the action tool
-3. If the expected outcome is known, follow with expect_* as final verification`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        selector: {
-          type: 'object',
-          properties: {
-            text: { type: 'string' },
-            resource_id: { type: 'string' },
-            accessibility_id: { type: 'string' },
-            contains: { type: 'boolean', description: 'When true, perform substring matching', default: false }
-          }
-        },
-        condition: { type: 'string', enum: ['exists', 'not_exists', 'visible', 'clickable'], default: 'exists' },
-        timeout_ms: { type: 'number', default: 60000 },
-        poll_interval_ms: { type: 'number', default: 300 },
-        match: { type: 'object', properties: { index: { type: 'number' } } },
-        retry: { type: 'object', properties: { max_attempts: { type: 'number', default: 1 }, backoff_ms: { type: 'number', default: 0 } } },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' }
-      }
-    }
-  },
-  {
-    name: 'find_element',
-    description: `Find a UI element by semantic query (text, content-desc, resource-id, class).
-
-Returns the best match plus resolution metadata when available, including confidence, selection reason, and fallback alternates.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: { type: 'string', description: 'Search query (text or label)' },
-        exact: { type: 'boolean', description: 'Require exact match (true/false)', default: false },
-        timeoutMs: { type: 'number', description: 'Timeout in ms to keep searching', default: 3000 },
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
-        deviceId: { type: 'string', description: 'Optional device serial/udid' }
-      },
-      required: ['query']
-    }
-  },
-  {
-    name: 'tap',
-    description: `Purpose:
-Dispatch a tap at specific screen coordinates.
-
-Inputs:
-- x, y coordinates
-- platform (optional)
-- deviceId (optional)
-
-Output Structure:
- - action_id, timestamp (ISO 8601), action_type
- - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
- - source_module: runtime source of the action envelope
- - target.selector = { x, y }
-- success = true when the tap was dispatched
-- failure_code/retryable when dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Resolve coordinates deterministically
-2. Call tap
-3. If needed, wait for transition using wait_for_*
-4. Verify with expect_screen or expect_element_visible depending on the intended outcome
-
-Verification Guidance:
-- Prefer tap_element over tap when an element can be resolved
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Use expect_screen for navigation and expect_element_visible for local UI changes
-- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios'],
-          description: 'Platform to tap on'
-        },
-        x: {
-          type: 'number',
-          description: 'X coordinate'
-        },
-        y: {
-          type: 'number',
-          description: 'Y coordinate'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial/UDID. Defaults to connected/booted device.'
-        },
-        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
-        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
-        actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
-        verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
-      },
-      required: ['x', 'y']
-    }
-  },
-  {
-    name: 'tap_element',
-    description: `Purpose:
-Tap a previously resolved UI element using its elementId.
-
-Inputs:
-- elementId: a resolved UI element identifier returned by wait_for_ui
-
-Output Structure:
-- action_id: unique timestamp-based action identifier
-- timestamp: ISO 8601 timestamp for the action attempt
-- action_type: "tap_element"
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target.selector: original target handle ({ elementId })
-- target.resolved: minimal resolved element info used for the tap
-- success: true when the tap was dispatched
-- failure_code: present when success=false
-- retryable: present when failure_code exists
-- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action
-
-Recommended Usage:
-1. Resolve the target with wait_for_ui or another deterministic resolver
-2. Call tap_element
-3. If needed, wait for transition using wait_for_*
-4. Verify outcome using expect_*
-   - use expect_screen when navigation is expected
-   - use expect_element_visible when the UI change is local
-5. If verification fails, inspect failure_code and follow the retry strategy below
-
-Verification Guidance:
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Prefer expect_screen for navigation or modal transitions
-- Prefer expect_element_visible when the tap should reveal or update a specific element
-- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists
-- Do not treat tap_element.success as outcome success; it only means the tap was executed
-
-Failure Handling:
-- STALE_REFERENCE → re-resolve the element, then retry
-- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry
-- UNKNOWN → capture a snapshot and stop
-
-This tool reports execution success only. Verification must be done with a separate expect_* tool.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        elementId: {
-          type: 'string',
-          description: 'A unique element identifier returned by wait_for_ui'
-        },
-        selector: { type: 'object', properties: { text: { type: 'string' }, resource_id: { type: 'string' }, accessibility_id: { type: 'string' }, contains: { type: 'boolean' } } },
-        waitFor: { type: 'object', properties: { condition: { type: 'string', enum: ['exists', 'visible', 'clickable'] }, timeoutMs: { type: 'number', minimum: 100, maximum: 10000 }, pollIntervalMs: { type: 'number', minimum: 50, maximum: 1000 }, match: { type: 'object', properties: { index: { type: 'number' } } } } },
-        platform: { type: 'string', enum: ['android', 'ios'] },
-        deviceId: { type: 'string' },
-        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
-        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }
-      }
-    }
-  },
-  {
-    name: 'swipe',
-    description: `Purpose:
-Dispatch a swipe gesture on Android or iOS.
-
-Inputs:
-- start and end coordinates
-- duration
-- platform/deviceId (optional)
-
-Output Structure:
-- action_id, timestamp (ISO 8601), action_type
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target.selector = { x1, y1, x2, y2, duration }
-- success = true when the swipe was dispatched
-- failure_code/retryable when dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Determine swipe coordinates
-2. Call swipe
-3. If needed, wait for transition using wait_for_*
-4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected
-
-Verification Guidance:
-- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios'],
-          description: 'Platform to swipe on (android or ios)'
-        },
-        x1: { type: 'number', description: 'Start X coordinate' },
-        y1: { type: 'number', description: 'Start Y coordinate' },
-        x2: { type: 'number', description: 'End X coordinate' },
-        y2: { type: 'number', description: 'End Y coordinate' },
-        duration: { type: 'number', description: 'Duration in ms' },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial/UDID. Defaults to connected/booted device.'
-        }
-      },
-      required: ['x1', 'y1', 'x2', 'y2', 'duration']
-    }
-  },
-  {
-    name: 'scroll_to_element',
-    description: `Purpose:
-Scroll until a target element becomes visible.
-
-Inputs:
-- platform
-- selector
-- direction, maxScrolls, scrollAmount, deviceId (optional)
-
-Output Structure:
-- action_id, timestamp (ISO 8601), action_type
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target.selector = original selector
-- target.resolved = minimal resolved element info when found
-- success = true when scrolling produced a visible target element
-- failure_code/retryable when the target was not reached
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Resolve the target selector
-2. Call scroll_to_element
-3. If needed, wait for UI stabilization using wait_for_*
-4. Verify with expect_element_visible when the expected element visibility is known
-5. If success=false, follow failure handling before retrying
-
-Verification Guidance:
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Use expect_element_visible when you need an explicit post-scroll confirmation
-- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
-
-Failure Handling:
-- NAVIGATION_NO_CHANGE → adjust scroll direction or stop
-- TIMEOUT → retry with refined selector or larger scroll budget
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to operate on (required)' },
-        selector: {
-          type: 'object',
-          properties: {
-            text: { type: 'string' },
-            resourceId: { type: 'string' },
-            contentDesc: { type: 'string' },
-            className: { type: 'string' }
-          }
-        },
-        direction: { type: 'string', enum: ['down', 'up'], default: 'down' },
-        maxScrolls: { type: 'number', default: 10 },
-        scrollAmount: { type: 'number', default: 0.7 },
-        deviceId: { type: 'string', description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.' }
-      },
-      required: ['platform', 'selector']
-    }
-  },
-  {
-    name: 'type_text',
-    description: `Purpose:
-Type text into the currently focused Android input field.
-
-Inputs:
-- text
-- platform/deviceId (optional)
-
-Output Structure:
-- action_id, timestamp (ISO 8601), action_type
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target.selector = { text }
-- success = true when text input was dispatched
-- failure_code/retryable when dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Resolve or focus the target input first
-2. Call type_text
-3. If needed, wait for UI stabilization using wait_for_*
-4. Verify with expect_element_visible or expect_screen, depending on the intended outcome
-
-Verification Guidance:
-- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → re-focus the input or capture a snapshot`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android'],
-          description: 'Platform to type on (currently only android supported)'
-        },
-        text: {
-          type: 'string',
-          description: 'The text to type'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial/UDID. Defaults to connected/booted device.'
-        }
-      },
-      required: ['text']
-    }
-  },
-  {
-    name: 'press_back',
-    description: `Purpose:
-Dispatch the Android Back action.
-
-Inputs:
-- platform/deviceId (optional)
-
-Output Structure:
-- action_id, timestamp (ISO 8601), action_type
-- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
-- source_module: runtime source of the action envelope
-- target.selector = { key: "back" }
-- success = true when the back action was dispatched
-- failure_code/retryable when dispatch fails
-- ui_fingerprint_before/ui_fingerprint_after when available
-
-Recommended Usage:
-1. Call press_back
-2. If needed, wait for transition using wait_for_*
-3. Verify with expect_screen when a known destination is expected
-4. If verification fails, retry once or recover explicitly
-
-Verification Guidance:
-- Back outcomes can vary by screen, so verify against the intended destination when possible
-- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
-- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
-
-Failure Handling:
-- TIMEOUT → retry once
-- UNKNOWN → capture a snapshot and stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android'],
-          description: 'Platform (currently only android supported)'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial/UDID. Defaults to connected/booted device.'
-        }
-      }
-    }
-  },
-  {
-    name: 'classify_action_outcome',
-    description: `Classify the outcome of the most recent action into exactly one of: success, no_op, backend_failure, ui_failure, unknown.
-
-Use the runtime action result's \`action_type\` as \`actionType\` so the classifier can distinguish local-state actions from side-effect actions.
-Use this when the intended outcome is not already fully verified by the UI signal alone.
-For backend/API activity, compare get_screen_fingerprint before and after the action and call get_network_activity immediately after the action if the outcome is still ambiguous.
-
-HOW TO GATHER INPUTS before calling:
-1. Call wait_for_screen_change or compare get_screen_fingerprint before/after — set uiChanged accordingly.
-2. If you checked for a specific element with wait_for_ui, set expectedElementVisible.
-3. Pass actionType from the action response when available.
-4. Only provide networkRequests if you already collected them or want to classify a side-effect action with backend evidence.
-
-RULES (applied in order — stop at first match):
-1. If uiChanged=true OR expectedElementVisible=true → outcome=success
-2. If actionType is missing → outcome=unknown
-3. If any request has status=failure or retryable → outcome=backend_failure
-4. If actionType maps to a local-state action → outcome=no_op; prefer state-based verification and avoid default network fallback
-5. If actionType maps to a side-effect action and no networkRequests were supplied → outcome=unknown
-6. If no requests returned → outcome=no_op
-7. If all requests succeeded → outcome=ui_failure
-8. Otherwise → outcome=unknown
-
-BEHAVIOUR after outcome:
-- success → continue
-- no_op → retry with richer state verification or re-resolve the element
-- backend_failure → stop and report the failing endpoint
-- ui_failure → stop and report failure
-- unknown → take one recovery step (e.g. capture_debug_snapshot), then stop`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        uiChanged: {
-          type: 'boolean',
-          description: 'true if the screen fingerprint or activity changed after the action. Use wait_for_screen_change or compare get_screen_fingerprint before and after.'
-        },
-        expectedElementVisible: {
-          type: 'boolean',
-          description: 'true if the element you expected to appear is now visible (from wait_for_ui). Omit if you did not check for a specific element.'
-        },
-        actionType: {
-          type: 'string',
-          description: 'The runtime action_type from the action response (for example tap, tap_element, swipe, type_text, press_back, start_app).'
-        },
-        networkRequests: {
-          type: 'array',
-          description: 'Optional network evidence collected after the action. Use it when the expected outcome is backend/API activity or when the UI signal is ambiguous.',
-          items: {
-            type: 'object',
-            properties: {
-              endpoint: { type: 'string', description: 'Request endpoint or full URL' },
-              status: { type: 'string', enum: ['success', 'failure', 'retryable'], description: 'Outcome of the request' }
-            },
-            required: ['endpoint', 'status']
-          }
-        },
-        hasLogErrors: {
-          type: 'boolean',
-          description: 'true if structured log errors were observed (e.g. from read_log_stream). Optional — include if you have already read logs.'
-        }
-      },
-      required: ['uiChanged']
-    }
-  },
-  {
-    name: 'run_journey',
-    description: 'Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: { type: 'string', enum: ['android', 'ios'] },
-        deviceId: { type: 'string' },
-        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'compact' },
-        steps: { type: 'array', minItems: 1, maxItems: 50, items: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string', enum: ['start_app', 'tap', 'wait', 'assert'] } }, required: ['id', 'type'] } }
-      },
-      required: ['platform', 'steps']
-    }
-  },
-  {
-    name: 'get_network_activity',
-    description: `Returns structured network events captured from platform logs since the last action.
-
-Call this immediately after an action when you want backend evidence for a side-effect flow, only if the result is still ambiguous.
-Do not call more than once per action.
-
-Events are filtered to significant (non-background) requests only.
-Each event includes endpoint, method, statusCode, networkError, status, and durationMs.
-
-status values:
-- success: HTTP 2xx or request detected with no error signal
-- failure: HTTP 4xx
-- retryable: HTTP 5xx, network error (timeout, dns_error, tls_error, etc.)
-
-Returns { requests: [], count: 0 } when no credible network signals are found.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        platform: {
-          type: 'string',
-          enum: ['android', 'ios'],
-          description: 'Platform to read network logs from'
-        },
-        deviceId: {
-          type: 'string',
-          description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.'
-        }
-      },
-      required: ['platform']
-    }
-  }
+...baseOrder.map(name => baseTools.get(name)!)
 ]
 
 // Keep the additive execution controls consistent across all action tools.
 for (const tool of toolDefinitions) {
+  tool.inputSchema.properties ??= {}
   if (['wait_for_ui', 'wait_for_ui_change'].includes(tool.name)) {
     tool.inputSchema.properties.requireReady = { type: 'boolean', default: false }
     tool.description += '\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.'
@@ -1150,7 +77,7 @@ for (const tool of toolDefinitions) {
   if (conditionalTools.has(tool.name)) {
     tool.inputSchema.properties.expectedState = expectedStateJson
     tool.inputSchema.properties.platform ??= { type: 'string', enum: ['android'] }
-    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), {
+    tool.inputSchema.allOf = [...(Array.isArray(tool.inputSchema.allOf) ? tool.inputSchema.allOf : []), {
       if: { required: ['expectedState'] },
       then: { required: ['platform', 'deviceId'], properties: {
         platform: { enum: ['type_text', 'press_back'].includes(tool.name) ? ['android'] : ['android', 'ios'] },
@@ -1159,12 +86,12 @@ for (const tool of toolDefinitions) {
     }]
     tool.description += '\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.'
   } else {
-    tool.inputSchema.allOf = [...(tool.inputSchema.allOf ?? []), { not: { required: ['expectedState'] } }]
+    tool.inputSchema.allOf = [...(Array.isArray(tool.inputSchema.allOf) ? tool.inputSchema.allOf : []), { not: { required: ['expectedState'] } }]
   }
   if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
     Object.assign(tool.inputSchema.properties, {
-      verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
-      responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+      verificationMode: { ...verificationModeJson, default: 'full' },
+      responseMode: { ...responseModeJson, default: 'debug' },
       actionTimeoutMs: { type: 'integer', description: 'Dispatch budget in milliseconds, clamped to 100–30000.' },
       verificationTimeoutMs: { type: 'integer', description: 'Light observation budget in milliseconds, clamped to 100–60000.' }
     })
@@ -1172,9 +99,10 @@ for (const tool of toolDefinitions) {
   if (tool.name === 'tap_element') Object.assign(tool.inputSchema, { oneOf: [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }] })
   if (tool.name === 'run_journey') Object.assign(tool.inputSchema.properties, {
     steps: journeyStepsJson,
+    systemTraceId: { type: 'string', format: 'uuid', description: 'Explicit active same-device system trace. Invalid references prevent all journey input. Capture lifetime is controlled separately.' },
     captureOnFailure: { type: 'boolean', default: false },
-    defaults: { type: 'object', additionalProperties: false, properties: {
-      verificationMode: { type: 'string', enum: ['none', 'light', 'full'] },
+    defaults: { type: 'object' as const, additionalProperties: false, properties: {
+      verificationMode: verificationModeJson,
       actionTimeoutMs: { type: 'integer' }, verificationTimeoutMs: { type: 'integer' }
     } }
   })
@@ -1182,9 +110,10 @@ for (const tool of toolDefinitions) {
 
 // Correlation is explicit; an omitted reference creates an independent observation.
 for (const tool of toolDefinitions) {
+  tool.inputSchema.properties ??= {}
   if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream'].includes(tool.name)) {
     Object.assign(tool.inputSchema.properties, { actionRef: {
-      type: 'object', additionalProperties: false, required: ['sessionId', 'actionId'], properties: {
+      type: 'object' as const, additionalProperties: false, required: ['sessionId', 'actionId'], properties: {
         sessionId: { type: 'string', minLength: 1, maxLength: 128 },
         actionId: { type: 'string', minLength: 1, maxLength: 128 }
       }