mobile-debug-mcp 0.26.0 → 0.26.2

package/docs/rfcs/006-runtime-action-instrumentation-and-binding-layer.md

@@ -0,0 +1,230 @@
+# RFC 006 — Runtime Action Instrumentation & Binding Layer
+
+## 1. Summary
+
+This RFC defines how the execution model in RFC 005 is mapped onto the current runtime behaviour of the system.
+
+It does not assume a new instrumentation system exists. Instead, it describes how lifecycle semantics are derived from existing execution flows, logs, module behaviour, and lightweight runtime metadata attached to action envelopes.
+
+It specifies:
+- how existing `action_type` values are interpreted under RFC 005 semantics
+- how lifecycle states are inferred from current runtime execution
+- how `src/server` and `src/interact` currently participate in execution
+- how legacy and platform actions are incorporated into the model
+
+This RFC is a runtime binding and normalisation layer over existing implementation behaviour.
+
+---
+
+## 2. Problem Statement
+
+RFC 005 defines a unified execution lifecycle:
+- Resolved
+- Dispatched
+- Pending Verification
+- Verified
+- Failed
+
+However, the current system already contains:
+- a concrete `action_type` execution model
+- execution logic split across `src/server` and `src/interact`
+- platform-specific actions (tap_element, type_text, press_back, start_app, restart_app, scroll_to_element)
+- distributed logging and partial instrumentation within modules
+
+There is no central instrumentation system and no explicit lifecycle emitter.
+Instead, lifecycle meaning is inferred from runtime behaviour and the `lifecycle_state` / `source_module` fields now attached to action envelopes.
+
+This results in:
+- implicit execution state transitions
+- distributed observability signals
+- non-uniform traceability across actions
+
+---
+
+## 3. Design Goals
+
+This layer MUST:
+
+- Map existing runtime behaviour to RFC 005 lifecycle semantics
+- Use existing `action_type` values as the authoritative execution taxonomy
+- Derive lifecycle states from observable runtime transitions
+- Reflect actual module responsibilities (not idealised separation)
+- Work with existing logging and execution hooks
+- Preserve compatibility with all current action implementations
+
+---
+
+## 4. Runtime Execution Flow (Observed)
+
+Current observed execution flow:
+
+UI Request
+→ src/server (routing + validation)
+→ src/interact (execution + platform dispatch)
+→ platform layer
+→ response handling + logs
+→ optional state verification (where available)
+
+Lifecycle states are derived from this flow rather than explicitly emitted.
+
+---
+
+## 5. Action Type Mapping (Current Runtime)
+
+This RFC maps existing `action_type` values to RFC 005 semantics.
+
+| action_type | RFC 005 Semantic Interpretation |
+|------------|---------------------------------|
+| tap | Selection |
+| tap_element | Selection |
+| type_text | Input |
+| press_back | Navigation |
+| start_app | System Action |
+| restart_app | System Action |
+| scroll_to_element | Navigation |
+
+This table reflects the current runtime contract.
+
+---
+
+## 6. Lifecycle State Derivation
+
+Lifecycle states are NOT explicitly emitted. They are inferred as follows:
+
+### 6.1 Resolved
+Inferred when:
+- src/server accepts request
+- action is validated and normalized
+- action_id is assigned (or equivalent identifier exists)
+
+---
+
+### 6.2 Dispatched
+Inferred when:
+- control passes from src/server to src/interact
+- execution call is issued to platform layer
+
+---
+
+### 6.3 Pending Verification
+Inferred when:
+- platform execution returns a result
+- before any UI/state evaluation occurs
+
+---
+
+### 6.4 Verified / Failed
+Inferred when:
+- post-execution evaluation is performed (if available)
+
+Rules:
+- Verified = expected outcome observed in UI/state/log signals
+- Failed = timeout, error, or mismatch in expected outcome
+
+Where no formal verification exists, outcome is derived from best available signals (logs, UI diff, or absence of error).
+
+---
+
+## 7. Instrumentation Reality
+
+There is no central instrumentation layer in the current system.
+
+Instead:
+- src/server emits partial logs during routing and validation
+- src/interact emits execution logs and platform responses
+- platform adapters may emit additional debugging information
+- action envelopes now carry lightweight lifecycle metadata for post-dispatch state and source ownership
+
+Lifecycle traceability is therefore assembled from distributed signals rather than a unified event system.
+
+---
+
+## 8. Module Responsibilities (Observed Behaviour)
+
+### src/server
+- receives action requests
+- performs validation and normalization
+- assigns identifiers where applicable
+- routes actions to src/interact
+- emits partial logs for request lifecycle
+
+---
+
+### src/interact
+- executes platform-specific actions
+- handles retries and fallback behaviours
+- emits execution logs
+- returns execution results
+- may perform lightweight post-processing
+
+---
+
+## 9. Verification Reality
+
+Verification is not a uniform system-wide layer.
+
+It may occur via:
+- UI state comparison (where available)
+- log-based confirmation
+- absence of error signals
+- platform feedback
+
+Verification outcomes are best-effort only where no formal verifier exists, and deterministic where reliable state signals or explicit evaluation paths are available.
+
+---
+
+## 10. Legacy and Special Actions
+
+Actions such as:
+- scroll_to_element
+- start_app
+- restart_app
+- press_back
+
+are fully supported in the runtime.
+
+These actions:
+- may bypass full lifecycle observability
+- may not have explicit verification paths
+- are interpreted using best-effort semantic mapping
+
+---
+
+## 11. Observability Model
+
+Observability is currently distributed across:
+- src/server logs
+- src/interact logs
+- platform debug output
+- action envelope metadata
+
+There is no unified event schema.
+
+Lifecycle reconstruction requires correlation of:
+- action_type
+- timestamps
+- execution boundaries
+- error signals
+
+---
+
+## 12. Relationship to RFC 005
+
+RFC 005 defines the ideal execution lifecycle semantics.
+
+RFC 006 defines how those semantics are interpreted from the existing runtime system.
+
+Together:
+- RFC 005 = conceptual correctness model
+- RFC 006 = runtime behavioural mapping layer
+
+---
+
+## 13. Summary
+
+This RFC ensures:
+- lifecycle semantics can be derived from current runtime behaviour
+- existing action_type contract is preserved as source of truth
+- no assumption of new instrumentation infrastructure is required
+- real module responsibilities are accurately represented
+- observability is understood as distributed rather than centralised

package/docs/specs/mcp-tooling-spec-v1.md

@@ -41,7 +41,7 @@ Outcome-specific guidance:
 - visible navigation expected -> `wait_for_screen_change` (optional) -> `expect_screen`
 - local UI change expected -> `wait_for_ui` (optional) -> `expect_element_visible`
 - readable element state expected -> `wait_for_ui` (optional) -> `expect_state`
-- backend/API activity expected without a visible UI change -> compare `get_screen_fingerprint` before/after, then call `get_network_activity` immediately after the action and `classify_action_outcome` with the observed requests
+- backend/API activity expected without a visible UI change -> compare `get_screen_fingerprint` before/after, then call `classify_action_outcome` with the runtime `action_type`; collect `get_network_activity` only if the result remains ambiguous
 
 For backend/API activity, `wait_for_screen_change` is not the right verification tool unless a visible transition is also expected.
 
@@ -69,6 +69,8 @@ MUST be returned in this structure:
   action_id: string,
   timestamp: string,
   action_type: string,
+  lifecycle_state?: 'pending_verification' | 'failed',
+  source_module?: 'server' | 'interact',
   target: {
     selector: object,
     resolved: object | null
@@ -87,6 +89,8 @@ Rules:
 
 - `success` is at the top level, not nested
 - `target` contains only selection and resolution context
+- `lifecycle_state` reflects the post-dispatch runtime state
+- `source_module` identifies where the envelope was produced
 - fingerprints represent observed pre/post UI state on a best-effort basis
 - `failure_code` is optional but MUST be used when a structured mapping exists
 
@@ -294,11 +298,11 @@ Tool: `classify_action_outcome`
 
 Rules:
 
-- MAY use UI, network, and log signals
+- MAY use UI, action, network, and log signals
 - MUST be deterministic
 - MUST NOT replace `expect_*` tools
 - MUST be treated as a supplementary signal only
-- SHOULD be used with `get_network_activity` when the expected outcome is backend/API activity without a visible UI change
+- SHOULD be used with `get_network_activity` only when the outcome is still ambiguous after routing by `action_type`
 
 It is not a verification mechanism.
 

package/docs/tools/interact.md

@@ -17,6 +17,7 @@ Important:
 
 - `wait_for_*` tools must not be used as the final verification of action success when an applicable `expect_*` tool exists.
 - action tools report execution success, not outcome correctness.
+- `classify_action_outcome` should receive the runtime `action_type` when you want routing to distinguish local-state and side-effect actions.
 
 ## tap / swipe / type_text / press_back
 
@@ -35,6 +36,8 @@ Example response:
   "action_id": "tap_1710000000000_1",
   "timestamp": "2026-04-23T08:00:00.000Z",
   "action_type": "tap",
+  "lifecycle_state": "pending_verification",
+  "source_module": "server",
   "target": { "selector": { "x": 100, "y": 200 }, "resolved": null },
   "success": true,
   "ui_fingerprint_before": "fp_before",
@@ -54,10 +57,10 @@ Preferred verification:
 - navigation outcome known -> `expect_screen`
 - local UI change known -> `expect_element_visible`
 - readable element state known -> `expect_state`
-- backend/API activity expected -> `classify_action_outcome` + `get_network_activity`
+- backend/API activity expected -> `classify_action_outcome` + optional `get_network_activity` if the UI signal remains ambiguous
 
-Use `wait_for_screen_change` only when a visible transition is the expected outcome. If a button should trigger an API request but the screen should stay the same, rely on network activity and classification instead.
-For backend-only actions, prefer comparing `get_screen_fingerprint` before/after and call `get_network_activity` immediately after the action; do not wait on `wait_for_screen_change` if no visible transition is expected.
+Use `wait_for_screen_change` only when a visible transition is the expected outcome. If a button should trigger an API request but the screen should stay the same, rely on `action_type` plus classification first.
+For backend-only actions, prefer comparing `get_screen_fingerprint` before/after and collect `get_network_activity` immediately after the action only if the result is still ambiguous; do not wait on `wait_for_screen_change` if no visible transition is expected.
 Use `wait_for_ui_change` when the screen stays in place but visible text or element state should change.
 
 ---
@@ -332,6 +335,8 @@ Success response:
   "action_id": "tap_element_1710000000000_1",
   "timestamp": "2026-04-23T08:00:00.000Z",
   "action_type": "tap_element",
+  "lifecycle_state": "pending_verification",
+  "source_module": "interact",
   "target": {
     "selector": { "elementId": "el_123" },
     "resolved": {
@@ -507,17 +512,18 @@ Notes:
 
 ## classify_action_outcome + get_network_activity
 
-Use this pair when the action is expected to trigger network/backend work and the screen may not visibly change.
+Use this pair when the action may trigger network/backend work and the screen may not visibly change.
 
 Pattern:
 
 1. perform the action
 2. call `classify_action_outcome` with `uiChanged` from `wait_for_screen_change` or a screen fingerprint comparison
-3. if the classifier asks for it, call `get_network_activity`
-4. call `classify_action_outcome` again with `networkRequests`
+3. pass the runtime `action_type` value as `actionType`
+4. collect `get_network_activity` only if the action is side-effect oriented and the UI signal remains ambiguous
+5. call `classify_action_outcome` again with `networkRequests` if you collected them
 
 Guidance:
 
 - `uiChanged=true` or `expectedElementVisible=true` means the action outcome is already verified
-- `nextAction="call_get_network_activity"` means the UI signal was inconclusive and the agent should inspect network activity
-- if network requests succeed but the UI stays unchanged, treat the outcome as a backend/API result rather than a screen transition
+- local-state actions should prefer refreshed snapshots, `expect_state`, or `expect_element_visible` over default network inspection
+- network activity is auxiliary evidence, not mandatory proof

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.26.0",
+  "version": "0.26.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/classify.ts

@@ -1,5 +1,6 @@
 export type ActionOutcome = 'success' | 'no_op' | 'backend_failure' | 'ui_failure' | 'unknown'
 export type NetworkRequestStatus = 'success' | 'failure' | 'retryable'
+export type ActionCategory = 'local_state' | 'side_effect'
 
 export interface NetworkRequest {
   endpoint: string
@@ -9,6 +10,8 @@ export interface NetworkRequest {
 export interface ClassifyActionOutcomeInput {
   uiChanged: boolean
   expectedElementVisible?: boolean | null
+  /** Concrete action_type from the runtime action result (for example: tap, type_text, start_app). */
+  actionType?: string | null
   /** null = get_network_activity has not been called yet */
   networkRequests?: NetworkRequest[] | null
   hasLogErrors?: boolean | null
@@ -17,8 +20,29 @@ export interface ClassifyActionOutcomeInput {
 export interface ClassifyActionOutcomeResult {
   outcome: ActionOutcome
   reasoning: string
-  /** Present when the caller must call get_network_activity before a final classification is possible */
-  nextAction?: 'call_get_network_activity'
+}
+
+const ACTION_CATEGORY_BY_TYPE: Record<string, ActionCategory> = {
+  tap: 'local_state',
+  tap_element: 'local_state',
+  swipe: 'local_state',
+  scroll_to_element: 'local_state',
+  type_text: 'local_state',
+  press_back: 'local_state',
+  start_app: 'side_effect',
+  restart_app: 'side_effect',
+  terminate_app: 'side_effect',
+  reset_app_data: 'side_effect',
+  install_app: 'side_effect',
+  build_app: 'side_effect',
+  build_and_install: 'side_effect'
+}
+
+function inferActionCategory(actionType?: string | null): ActionCategory | null {
+  if (typeof actionType !== 'string') return null
+  const normalized = actionType.trim().toLowerCase()
+  if (!normalized) return null
+  return ACTION_CATEGORY_BY_TYPE[normalized] ?? 'side_effect'
 }
 
 /**
@@ -26,39 +50,55 @@ export interface ClassifyActionOutcomeResult {
  * Same inputs always produce the same output.
  */
 export function classifyActionOutcome(input: ClassifyActionOutcomeInput): ClassifyActionOutcomeResult {
-  const { uiChanged, expectedElementVisible, networkRequests, hasLogErrors } = input
+  const { uiChanged, expectedElementVisible, actionType, networkRequests, hasLogErrors } = input
+  const actionCategory = inferActionCategory(actionType)
 
   // Step 1 — UI signal is positive
   if (uiChanged || expectedElementVisible === true) {
     return { outcome: 'success', reasoning: expectedElementVisible === true ? 'expected element is visible' : 'UI changed after action' }
   }
 
-  // Step 2 — UI did not change; network signal is required
-  if (networkRequests === null || networkRequests === undefined) {
+  // Step 2 — no action type means we cannot choose a safe routing path
+  if (actionCategory === null) {
     return {
       outcome: 'unknown',
-      reasoning: 'UI did not change; get_network_activity must be called before classification can proceed',
-      nextAction: 'call_get_network_activity'
+      reasoning: 'actionType was not supplied; pass the runtime action_type so the classifier can distinguish local-state and side-effect routing'
     }
   }
 
-  // Step 3 — any network failure
-  const failedRequest = networkRequests.find((r) => r.status === 'failure' || r.status === 'retryable')
+  const failedRequest = networkRequests?.find((r) => r.status === 'failure' || r.status === 'retryable')
   if (failedRequest) {
     return { outcome: 'backend_failure', reasoning: `network request ${failedRequest.endpoint} returned ${failedRequest.status}` }
   }
 
-  // Step 4 — no network requests at all
+  // Step 3 — local-state actions should be verified with state-specific signals first
+  if (actionCategory === 'local_state') {
+    const logNote = hasLogErrors ? ' (log errors present)' : ''
+    return {
+      outcome: 'no_op',
+      reasoning: `local-state action${logNote}; use expect_state, refreshed snapshot comparison, or expect_element_visible instead of defaulting to network inspection`
+    }
+  }
+
+  // Step 4 — side-effect actions may legitimately need network or log inspection
+  if (networkRequests === null || networkRequests === undefined) {
+    return {
+      outcome: 'unknown',
+      reasoning: 'side-effect action without network data; inspect network or log signals only if the outcome is still ambiguous'
+    }
+  }
+
+  // Step 5 — no network requests at all
   if (networkRequests.length === 0) {
     const logNote = hasLogErrors ? ' (log errors present)' : ''
-    return { outcome: 'no_op', reasoning: `no UI change and no network activity${logNote}` }
+    return { outcome: 'no_op', reasoning: `side-effect action and no network activity${logNote}` }
   }
 
-  // Step 5 — network requests exist and all succeeded
+  // Step 6 — network requests exist and all succeeded
   if (networkRequests.every((r) => r.status === 'success')) {
     return { outcome: 'ui_failure', reasoning: 'network requests succeeded but UI did not change' }
   }
 
-  // Step 6 — fallback
+  // Step 7 — fallback
   return { outcome: 'unknown', reasoning: 'signals are inconclusive' }
 }

package/src/interact/index.ts

@@ -6,7 +6,7 @@ export { AndroidInteract, iOSInteract };
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { ToolsObserve } from '../observe/index.js'
 import { computeSnapshotSignature } from '../observe/snapshot-metadata.js'
-import { nextActionId } from '../server/common.js'
+import { buildActionExecutionResult } from '../server/common.js'
 import type {
   ActionFailureCode,
   ActionTargetResolved,
@@ -291,27 +291,25 @@ export class ToolsInteract {
   }
 
   private static _actionFailure(
-    actionId: string,
-    timestamp: string,
     actionType: string,
     selector: Record<string, unknown> | null,
     resolved: ActionTargetResolved | null,
     failureCode: ActionFailureCode,
     retryable: boolean,
     uiFingerprintBefore: string | null,
-    uiFingerprintAfter?: string | null
+    uiFingerprintAfter?: string | null,
+    sourceModule: 'server' | 'interact' = 'interact'
   ): TapElementResponse {
-    return {
-      action_id: actionId,
-      timestamp,
-      action_type: actionType,
-      target: { selector, resolved },
+    return buildActionExecutionResult({
+      actionType,
+      selector,
+      resolved,
       success: false,
-      failure_code: failureCode,
-      retryable,
-      ui_fingerprint_before: uiFingerprintBefore,
-      ui_fingerprint_after: uiFingerprintAfter
-    }
+      uiFingerprintBefore,
+      uiFingerprintAfter: uiFingerprintAfter ?? null,
+      failure: { failureCode, retryable },
+      sourceModule
+    })
   }
 
   static _resetResolvedUiElementsForTests() {
@@ -472,14 +470,11 @@ export class ToolsInteract {
   }
 
   static async tapElementHandler({ elementId }: { elementId: string }): Promise<TapElementResponse> {
-    const timestampMs = Date.now()
-    const timestamp = new Date(timestampMs).toISOString()
     const actionType = 'tap_element'
-    const actionId = nextActionId(actionType, timestampMs)
     const selector = { elementId }
     const resolved = ToolsInteract._resolvedUiElements.get(elementId)
     if (!resolved) {
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, null)
+      return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null)
     }
 
     const fingerprintBefore = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId)
@@ -491,22 +486,22 @@ export class ToolsInteract {
     const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved)
 
     if (!currentMatch) {
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore)
+      return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore)
     }
 
     const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index)
 
     if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
+      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
     }
 
     if (currentMatch.el.enabled === false) {
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
+      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
     }
 
     const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds
     if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
+      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore)
     }
 
     const x = Math.floor((bounds[0] + bounds[2]) / 2)
@@ -515,23 +510,20 @@ export class ToolsInteract {
 
     if (!tapResult.success) {
       const fingerprintAfterFailure = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId)
-      return ToolsInteract._actionFailure(actionId, timestamp, actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure)
+      return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'UNKNOWN', false, fingerprintBefore, fingerprintAfterFailure)
     }
 
     const fingerprintAfter = await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId)
-    return {
-      action_id: actionId,
-      timestamp,
-      action_type: actionType,
-      ...(tree?.device ? { device: tree.device } : {}),
-      target: {
-        selector,
-        resolved: resolvedTarget
-      },
+    return buildActionExecutionResult({
+      actionType,
+      device: tree?.device,
+      selector,
+      resolved: resolvedTarget,
       success: true,
-      ui_fingerprint_before: fingerprintBefore,
-      ui_fingerprint_after: fingerprintAfter
-    }
+      uiFingerprintBefore: fingerprintBefore,
+      uiFingerprintAfter: fingerprintAfter,
+      sourceModule: 'interact'
+    })
   }
 
   static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {

package/src/server/common.ts

@@ -112,6 +112,23 @@ export function inferScrollFailure(message: string | undefined): { failureCode:
   return { failureCode: 'UNKNOWN', retryable: false }
 }
 
+const ACTION_LIFECYCLE_STATE_BY_OUTCOME = {
+  success: 'pending_verification',
+  failure: 'failed'
+} as const
+
+export function determineActionLifecycleState({
+  success,
+  failure
+}: {
+  success: boolean
+  failure?: { failureCode: ActionFailureCode; retryable: boolean }
+}): NonNullable<ActionExecutionResult['lifecycle_state']> {
+  if (failure) return ACTION_LIFECYCLE_STATE_BY_OUTCOME.failure
+  if (success) return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
+  return ACTION_LIFECYCLE_STATE_BY_OUTCOME.success
+}
+
 export function buildActionExecutionResult({
   actionType,
   device,
@@ -121,7 +138,8 @@ export function buildActionExecutionResult({
   uiFingerprintBefore,
   uiFingerprintAfter,
   failure,
-  details
+  details,
+  sourceModule
 }: {
   actionType: string
   device?: ActionExecutionResult['device']
@@ -132,6 +150,7 @@ export function buildActionExecutionResult({
   uiFingerprintAfter: string | null
   failure?: { failureCode: ActionFailureCode; retryable: boolean }
   details?: Record<string, unknown>
+  sourceModule: 'server' | 'interact'
 }): ActionExecutionResult {
   const timestampMs = Date.now()
   const timestamp = new Date(timestampMs).toISOString()
@@ -139,6 +158,8 @@ export function buildActionExecutionResult({
     action_id: nextActionId(actionType, timestampMs),
     timestamp,
     action_type: actionType,
+    lifecycle_state: determineActionLifecycleState({ success, failure }),
+    source_module: sourceModule,
     ...(device ? { device } : {}),
     target: {
       selector,