appium-mcp 1.82.2 → 1.83.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.83.0](https://github.com/appium/appium-mcp/compare/v1.82.2...v1.83.0) (2026-06-08)
+
+### Features
+
+* emit structured action evidence records ([#386](https://github.com/appium/appium-mcp/issues/386)) ([d42593e](https://github.com/appium/appium-mcp/commit/d42593e86c0bb6535b4e1c3e855c6d7e307e9611))
+
 ## [1.82.2](https://github.com/appium/appium-mcp/compare/v1.82.1...v1.82.2) (2026-06-08)
 
 ### Miscellaneous Chores

package/README.md

@@ -154,6 +154,7 @@ This will automatically configure the MCP server for use with Claude Code. Make
 | `AI_VISION_IMAGE_QUALITY`                 | Optional                               | JPEG quality 1–100 for compressed screenshots sent to the vision API (default: `80`)                                                                                                                                                                                                                                                               |
 | `SENTENCE_TRANSFORMERS_MODEL`             | Optional                               | Hugging Face model used for semantic search in Appium documentation queries (default: `Xenova/all-MiniLM-L6-v2`)                                                                                                                                                                                                                                   |
 | `APPIUM_MCP_PERSIST_REMOTE_SESSIONS_PATH` | Optional                               | Absolute file path to persist attached remote session info across server restarts (JSON format)                                                                                                                                                                                                                                                    |
+| `APPIUM_MCP_EVIDENCE`                     | Optional                               | Set to `true` or `1` to attach a structured **action evidence record** (locator, resolved element id, context, timing, normalized error code) to `appium_find_element` and `appium_gesture` responses as an `application/vnd.appium.evidence+json` resource block, for CI/debugging. Disabled by default; responses are unchanged when unset.        |
 
 ### Capabilities
 

package/dist/tests/tools/evidence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evidence.test.d.ts.map

package/dist/tests/tools/evidence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.test.d.ts","sourceRoot":"","sources":["../../../src/tests/tools/evidence.test.ts"],"names":[],"mappings":""}

package/dist/tests/tools/evidence.test.js

@@ -0,0 +1,158 @@
+import { describe, test, expect, jest, beforeEach, afterEach, } from '@jest/globals';
+// Mock the session store to avoid pulling in the native drivers it imports.
+jest.unstable_mockModule('../../session-store', () => ({
+    getSessionInfo: jest.fn(() => null),
+}));
+const { classifyError, isEvidenceEnabled, withEvidence } = await import('../../tools/evidence.js');
+const ENV_KEY = 'APPIUM_MCP_EVIDENCE';
+function enableEvidence(value = '1') {
+    process.env[ENV_KEY] = value;
+}
+const textResult = (text) => ({
+    content: [{ type: 'text', text }],
+});
+const errorResult = (text) => ({
+    content: [{ type: 'text', text }],
+    isError: true,
+});
+function readRecord(result) {
+    const block = result.content.find((c) => c.type === 'resource');
+    const text = block?.type === 'resource' && 'text' in block.resource
+        ? block.resource.text
+        : undefined;
+    if (typeof text !== 'string') {
+        throw new Error('no evidence resource block found');
+    }
+    return JSON.parse(text);
+}
+describe('classifyError', () => {
+    test.each([
+        ['An element could not be located on the page', 'ELEMENT_NOT_FOUND'],
+        ['no such element: unable to find', 'ELEMENT_NOT_FOUND'],
+        ['stale element reference', 'STALE_ELEMENT'],
+        ['The operation timed out after 10000ms', 'TIMEOUT'],
+        ['no such context WEBVIEW_x', 'CONTEXT_NOT_AVAILABLE'],
+        ['invalid selector: //[', 'INVALID_SELECTOR'],
+        ['something unexpected exploded', 'ACTION_FAILED'],
+    ])('maps %j -> %s', (message, code) => {
+        expect(classifyError(new Error(message))).toBe(code);
+    });
+    test('accepts non-Error values', () => {
+        expect(classifyError('plain timeout string')).toBe('TIMEOUT');
+        expect(classifyError(undefined)).toBe('ACTION_FAILED');
+    });
+});
+describe('isEvidenceEnabled', () => {
+    const original = process.env[ENV_KEY];
+    afterEach(() => {
+        if (original === undefined) {
+            delete process.env[ENV_KEY];
+        }
+        else {
+            process.env[ENV_KEY] = original;
+        }
+    });
+    test.each(['1', 'true', 'TRUE'])('enabled for %j', (value) => {
+        process.env[ENV_KEY] = value;
+        expect(isEvidenceEnabled()).toBe(true);
+    });
+    test.each(['0', 'false', '', undefined])('disabled for %j', (value) => {
+        if (value === undefined) {
+            delete process.env[ENV_KEY];
+        }
+        else {
+            process.env[ENV_KEY] = value;
+        }
+        expect(isEvidenceEnabled()).toBe(false);
+    });
+});
+describe('withEvidence', () => {
+    const original = process.env[ENV_KEY];
+    beforeEach(() => {
+        delete process.env[ENV_KEY];
+    });
+    afterEach(() => {
+        if (original === undefined) {
+            delete process.env[ENV_KEY];
+        }
+        else {
+            process.env[ENV_KEY] = original;
+        }
+    });
+    test('is a no-op when disabled', () => {
+        const result = textResult('ok');
+        const out = withEvidence(result, {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt: Date.now(),
+        });
+        expect(out).toBe(result);
+        expect(out.content).toHaveLength(1);
+    });
+    test('appends a resource block without mutating the text', () => {
+        enableEvidence();
+        const out = withEvidence(textResult("elementId 'abc'\nfound"), {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt: Date.now(),
+            locator: { strategy: 'accessibility id', selector: 'login' },
+            element: { webdriverId: 'abc' },
+        });
+        expect(out.content[0]).toEqual({
+            type: 'text',
+            text: "elementId 'abc'\nfound",
+        });
+        const block = out.content[1];
+        expect(block.type).toBe('resource');
+        if (block.type === 'resource') {
+            expect(block.resource.uri).toMatch(/^evidence:\/\//);
+            expect(block.resource.mimeType).toBe('application/vnd.appium.evidence+json');
+        }
+    });
+    test('builds a success record', () => {
+        enableEvidence();
+        const startedAt = Date.now();
+        const record = readRecord(withEvidence(textResult('found'), {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt,
+            locator: { strategy: 'id', selector: 'btn' },
+            element: { webdriverId: 'el-1' },
+        }));
+        expect(record.schemaVersion).toBe(1);
+        expect(record.producer.name).toBe('appium-mcp');
+        expect(record.evidenceId).toEqual(expect.any(String));
+        expect(record.status).toBe('success');
+        expect(record.action.name).toBe('appium_find_element');
+        expect(record.action.stage).toBe('locate');
+        expect(record.action.locator).toEqual({ strategy: 'id', selector: 'btn' });
+        expect(record.action.element).toEqual({ webdriverId: 'el-1' });
+        expect(record.error).toBeUndefined();
+        expect(record.timing.durationMs).toBeGreaterThanOrEqual(0);
+        expect(record.timing.startedAt).toBe(new Date(startedAt).toISOString());
+    });
+    test('classifies error from the passed error object', () => {
+        enableEvidence();
+        const record = readRecord(withEvidence(errorResult('Failed to find element. Error: stale'), {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt: Date.now(),
+            error: new Error('stale element reference'),
+        }));
+        expect(record.status).toBe('error');
+        expect(record.error?.code).toBe('STALE_ELEMENT');
+        expect(record.error?.message).toBe('stale element reference');
+    });
+    test('falls back to result text when no error object is supplied', () => {
+        enableEvidence();
+        const record = readRecord(withEvidence(errorResult('The operation timed out'), {
+            name: 'appium_gesture',
+            stage: 'interact',
+            startedAt: Date.now(),
+        }));
+        expect(record.status).toBe('error');
+        expect(record.error?.code).toBe('TIMEOUT');
+        expect(record.error?.message).toBe('The operation timed out');
+    });
+});
+//# sourceMappingURL=evidence.test.js.map

package/dist/tests/tools/evidence.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.test.js","sourceRoot":"","sources":["../../../src/tests/tools/evidence.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/evidence.d.ts

@@ -0,0 +1,82 @@
+import type { ContentResult } from 'fastmcp';
+/**
+ * Structured, machine-readable trace of a single tool action, so CI and agents
+ *  can diagnose failures without parsing prose.
+ *
+ * This is an *action* record. A future run-level bundle may reference many of
+ * these plus heavier artifacts (screenshots, page source).
+ */
+export interface ActionEvidenceRecord {
+    schemaVersion: 1;
+    producer: {
+        name: 'appium-mcp';
+        version: string;
+    };
+    evidenceId: string;
+    status: 'success' | 'error';
+    /**
+     * Action-specific details. `stage`/`locator`/`element` are optional because
+     * they only apply to tools that resolve or interact with elements (find,
+     * gesture); tools like screenshot carry just `name`.
+     */
+    action: {
+        name: string;
+        stage?: EvidenceStage;
+        locator?: {
+            strategy: string;
+            selector: string;
+        };
+        element?: {
+            webdriverId: string;
+        };
+    };
+    context?: {
+        platform?: string;
+        contextName?: string;
+    };
+    timing: {
+        startedAt: string;
+        finishedAt: string;
+        durationMs: number;
+    };
+    error?: {
+        code: EvidenceErrorCode;
+        message: string;
+    };
+}
+export type EvidenceStage = 'locate' | 'interact' | 'capture';
+export type EvidenceErrorCode = 'ELEMENT_NOT_FOUND' | 'TIMEOUT' | 'STALE_ELEMENT' | 'CONTEXT_NOT_AVAILABLE' | 'INVALID_SELECTOR' | 'ACTION_FAILED';
+/** Inputs a handler supplies to describe the action it performed. */
+export interface EvidenceInput {
+    name: string;
+    startedAt: number;
+    stage?: EvidenceStage;
+    locator?: ActionEvidenceRecord['action']['locator'];
+    element?: ActionEvidenceRecord['action']['element'];
+    context?: ActionEvidenceRecord['context'];
+    error?: unknown;
+}
+/**
+ * When disabled, evidence is never built or attached and tool
+ * responses are byte-for-byte unchanged.
+ */
+export declare function isEvidenceEnabled(): boolean;
+/**
+ * Attach an evidence record to an existing tool result as a `resource` content
+ * block, leaving the original text untouched. No-op when evidence is disabled.
+ */
+export declare function withEvidence(result: ContentResult, input: EvidenceInput): ContentResult;
+/**
+ * Snapshot the active session's platform and current context for the evidence
+ * record. Returns undefined when there is no session to read, so the field is
+ * simply omitted. The session-store import is deferred until evidence is
+ * enabled so the disabled path pulls in no driver dependencies.
+ */
+export declare function evidenceContext(sessionId?: string): Promise<ActionEvidenceRecord['context'] | undefined>;
+/**
+ * Map a raw Appium/WebDriver error to a stable, normalized code. The codes are
+ * also the foundation for failure-reason hypotheses. Inspects the error name
+ * first, then the message, falling back to ACTION_FAILED.
+ */
+export declare function classifyError(err: unknown): EvidenceErrorCode;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/tools/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/tools/evidence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B;;;;OAIG;IACH,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,aAAa,CAAC;QACtB,OAAO,CAAC,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC;QACjD,OAAO,CAAC,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;KACnC,CAAC;IACF,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,SAAS,GACT,eAAe,GACf,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,CAAC;AAIpB,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAG3C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,aAAa,GACnB,aAAa,CAmBf;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,CAatD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAqB7D"}

package/dist/tools/evidence.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import pkg from '../../package.json' with { type: 'json' };
+const EVIDENCE_MIME_TYPE = 'application/vnd.appium.evidence+json';
+/**
+ * When disabled, evidence is never built or attached and tool
+ * responses are byte-for-byte unchanged.
+ */
+export function isEvidenceEnabled() {
+    const raw = process.env.APPIUM_MCP_EVIDENCE?.trim().toLowerCase();
+    return raw === '1' || raw === 'true';
+}
+/**
+ * Attach an evidence record to an existing tool result as a `resource` content
+ * block, leaving the original text untouched. No-op when evidence is disabled.
+ */
+export function withEvidence(result, input) {
+    if (!isEvidenceEnabled()) {
+        return result;
+    }
+    const record = buildRecord(result, input);
+    return {
+        ...result,
+        content: [
+            ...result.content,
+            {
+                type: 'resource',
+                resource: {
+                    uri: `evidence://${record.evidenceId}`,
+                    mimeType: EVIDENCE_MIME_TYPE,
+                    text: JSON.stringify(record),
+                },
+            },
+        ],
+    };
+}
+/**
+ * Snapshot the active session's platform and current context for the evidence
+ * record. Returns undefined when there is no session to read, so the field is
+ * simply omitted. The session-store import is deferred until evidence is
+ * enabled so the disabled path pulls in no driver dependencies.
+ */
+export async function evidenceContext(sessionId) {
+    if (!isEvidenceEnabled()) {
+        return undefined;
+    }
+    const { getSessionInfo } = await import('../session-store.js');
+    const info = getSessionInfo(sessionId);
+    if (!info) {
+        return undefined;
+    }
+    return {
+        ...(info.metadata.platform ? { platform: info.metadata.platform } : {}),
+        ...(info.currentContext ? { contextName: info.currentContext } : {}),
+    };
+}
+/**
+ * Map a raw Appium/WebDriver error to a stable, normalized code. The codes are
+ * also the foundation for failure-reason hypotheses. Inspects the error name
+ * first, then the message, falling back to ACTION_FAILED.
+ */
+export function classifyError(err) {
+    const name = err instanceof Error ? err.name : '';
+    const message = (err instanceof Error ? err.message : String(err)) ?? '';
+    const haystack = `${name} ${message}`.toLowerCase();
+    if (/no such element|could not be located|element not found/.test(haystack)) {
+        return 'ELEMENT_NOT_FOUND';
+    }
+    if (/stale element/.test(haystack)) {
+        return 'STALE_ELEMENT';
+    }
+    if (/timed? ?out|timeout/.test(haystack)) {
+        return 'TIMEOUT';
+    }
+    if (/no such context|context.*not.*(found|available)/.test(haystack)) {
+        return 'CONTEXT_NOT_AVAILABLE';
+    }
+    if (/invalid selector|invalid.*(locator|xpath)/.test(haystack)) {
+        return 'INVALID_SELECTOR';
+    }
+    return 'ACTION_FAILED';
+}
+function buildRecord(result, input) {
+    const finished = Date.now();
+    const status = result.isError || input.error !== undefined ? 'error' : 'success';
+    return {
+        schemaVersion: 1,
+        producer: { name: 'appium-mcp', version: pkg.version },
+        evidenceId: randomUUID(),
+        status,
+        action: {
+            name: input.name,
+            ...(input.stage ? { stage: input.stage } : {}),
+            ...(input.locator ? { locator: input.locator } : {}),
+            ...(input.element ? { element: input.element } : {}),
+        },
+        ...(input.context ? { context: input.context } : {}),
+        timing: {
+            startedAt: new Date(input.startedAt).toISOString(),
+            finishedAt: new Date(finished).toISOString(),
+            durationMs: finished - input.startedAt,
+        },
+        ...(status === 'error' ? { error: buildError(input.error, result) } : {}),
+    };
+}
+/**
+ * Resolve the error message, then classify from the same source so the code
+ * and message always agree — handlers that swallow errors only expose the
+ * result text, so fall back to that when no error object is passed.
+ */
+function buildError(err, result) {
+    const message = errorMessage(err, result);
+    return { code: classifyError(err ?? message), message };
+}
+function errorMessage(err, result) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (err !== undefined) {
+        return String(err);
+    }
+    const text = result.content.find((c) => c.type === 'text');
+    return text && 'text' in text ? text.text : 'Unknown error';
+}
+//# sourceMappingURL=evidence.js.map

package/dist/tools/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/tools/evidence.ts"],"names":[],"mappings":"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"}

package/dist/tools/gestures/gesture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gesture.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/gesture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AActD,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAkDrD"}
+{"version":3,"file":"gesture.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/gesture.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AA0BtD,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAwCrD"}

package/dist/tools/gestures/gesture.js

@@ -1,10 +1,12 @@
 import { errorResult, resolveDriver, textResult, toolErrorMessage, } from '../tool-response.js';
-import { GESTURE_ACTIONS, gestureSchema } from './schema.js';
+import { GESTURE_ACTIONS, gestureSchema, } from './schema.js';
 import { handleTap, handleDoubleTap, handleLongPress } from './handlers/tap.js';
 import { handleScroll, handleSwipe } from './handlers/swipe-scroll.js';
 import { handlePinchZoom } from './handlers/pinch.js';
 import { handleScrollToElement } from './handlers/scroll-to-element.js';
 import { back } from '../../command.js';
+import { withEvidence, evidenceContext, } from '../evidence.js';
+import { isAiElementUUID } from './handlers/ai-element.js';
 export default function gesture(server) {
     server.addTool({
         name: 'appium_gesture',
@@ -23,31 +25,51 @@ export default function gesture(server) {
                 return resolved.result;
             }
             const { driver } = resolved;
-            switch (args.action) {
-                case 'back':
-                    try {
-                        await back(driver);
-                        return textResult('Successfully performed back action.');
-                    }
-                    catch (err) {
-                        return errorResult(`Failed to perform back action. ${toolErrorMessage(err)}`);
-                    }
-                case 'tap':
-                    return handleTap(driver, args);
-                case 'double_tap':
-                    return handleDoubleTap(driver, args);
-                case 'long_press':
-                    return handleLongPress(driver, args);
-                case 'scroll':
-                    return handleScroll(driver, args);
-                case 'swipe':
-                    return handleSwipe(driver, args);
-                case 'pinch_zoom':
-                    return handlePinchZoom(driver, args);
-                case 'scroll_to_element':
-                    return handleScrollToElement(driver, args);
-            }
+            const startedAt = Date.now();
+            const context = await evidenceContext(args.sessionId);
+            const result = await dispatchGesture(driver, args);
+            return withEvidence(result, {
+                name: 'appium_gesture',
+                stage: gestureStage(args.action),
+                startedAt,
+                context,
+                ...(args.strategy && args.selector
+                    ? { locator: { strategy: args.strategy, selector: args.selector } }
+                    : {}),
+                ...(args.elementUUID && !isAiElementUUID(args.elementUUID)
+                    ? { element: { webdriverId: args.elementUUID } }
+                    : {}),
+            });
         },
     });
 }
+async function dispatchGesture(driver, args) {
+    switch (args.action) {
+        case 'back':
+            try {
+                await back(driver);
+                return textResult('Successfully performed back action.');
+            }
+            catch (err) {
+                return errorResult(`Failed to perform back action. ${toolErrorMessage(err)}`);
+            }
+        case 'tap':
+            return handleTap(driver, args);
+        case 'double_tap':
+            return handleDoubleTap(driver, args);
+        case 'long_press':
+            return handleLongPress(driver, args);
+        case 'scroll':
+            return handleScroll(driver, args);
+        case 'swipe':
+            return handleSwipe(driver, args);
+        case 'pinch_zoom':
+            return handlePinchZoom(driver, args);
+        case 'scroll_to_element':
+            return handleScrollToElement(driver, args);
+    }
+}
+function gestureStage(action) {
+    return action === 'scroll_to_element' ? 'locate' : 'interact';
+}
 //# sourceMappingURL=gesture.js.map

package/dist/tools/gestures/gesture.js.map

@@ -1 +1 @@
-{"version":3,"file":"gesture.js","sourceRoot":"","sources":["../../../src/tools/gestures/gesture.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,MAAe;IAC7C,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,oDAAoD,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAClF,gFAAgF;YAChF,yFAAyF;YACzF,gGAAgG;QAClG,UAAU,EAAE,aAAa;QACzB,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,IAAiB,EACjB,QAA6C,EACrB,EAAE;YAC1B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACrD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;YAE5B,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;gBACpB,KAAK,MAAM;oBACT,IAAI,CAAC;wBACH,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;wBACnB,OAAO,UAAU,CAAC,qCAAqC,CAAC,CAAC;oBAC3D,CAAC;oBAAC,OAAO,GAAY,EAAE,CAAC;wBACtB,OAAO,WAAW,CAChB,kCAAkC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAC1D,CAAC;oBACJ,CAAC;gBACH,KAAK,KAAK;oBACR,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACjC,KAAK,YAAY;oBACf,OAAO,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACvC,KAAK,YAAY;oBACf,OAAO,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACvC,KAAK,QAAQ;oBACX,OAAO,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACpC,KAAK,OAAO;oBACV,OAAO,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACnC,KAAK,YAAY;oBACf,OAAO,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACvC,KAAK,mBAAmB;oBACtB,OAAO,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"gesture.js","sourceRoot":"","sources":["../../../src/tools/gestures/gesture.ts"],"names":[],"mappings":"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"}

package/dist/tools/interactions/find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAqC5B,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA2CzD"}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAqC5B,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA4EzD"}

package/dist/tools/interactions/find.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { resolveDriver, textResultWithPrimaryElementId, errorResult, toolErrorMessage, readWebElementId, } from '../tool-response.js';
+import { withEvidence, evidenceContext } from '../evidence.js';
 export const findElementSchema = z.object({
     strategy: z
         .enum([
@@ -57,17 +58,39 @@ export default function findElement(server) {
                 return resolved.result;
             }
             const { driver } = resolved;
+            const startedAt = Date.now();
+            const locator = { strategy: args.strategy, selector: args.selector };
+            const context = await evidenceContext(args.sessionId);
             try {
                 const element = await driver.findElement(args.strategy, args.selector);
                 const elementId = readWebElementId(element);
                 if (!elementId) {
-                    return errorResult('Element was returned without a valid element ID');
+                    return withEvidence(errorResult('Element was returned without a valid element ID'), {
+                        name: 'appium_find_element',
+                        stage: 'locate',
+                        startedAt,
+                        locator,
+                        context,
+                    });
                 }
-                return textResultWithPrimaryElementId(elementId, `Successfully found element ${args.selector} with strategy ${args.strategy}.`);
+                return withEvidence(textResultWithPrimaryElementId(elementId, `Successfully found element ${args.selector} with strategy ${args.strategy}.`), {
+                    name: 'appium_find_element',
+                    stage: 'locate',
+                    startedAt,
+                    locator,
+                    element: { webdriverId: elementId },
+                    context,
+                });
             }
             catch (err) {
-                const errorMessage = toolErrorMessage(err);
-                return errorResult(`Failed to find element. Error: ${errorMessage}`);
+                return withEvidence(errorResult(`Failed to find element. Error: ${toolErrorMessage(err)}`), {
+                    name: 'appium_find_element',
+                    stage: 'locate',
+                    startedAt,
+                    locator,
+                    context,
+                    error: err,
+                });
             }
         },
     });

package/dist/tools/interactions/find.js.map

@@ -1 +1 @@
-{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,aAAa,EACb,8BAA8B,EAC9B,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC;QACJ,kBAAkB;QAClB,IAAI;QACJ,uBAAuB;QACvB,kBAAkB;QAClB,sBAAsB;QACtB,OAAO;QACP,MAAM;QACN,YAAY;QACZ,cAAc;KACf,CAAC;SACD,QAAQ,CACP,2CAA2C;QACzC,+DAA+D;QAC/D,8DAA8D;QAC9D,gDAAgD;QAChD,wDAAwD;QACxD,oEAAoE;QACpE,6EAA6E;QAC7E,2CAA2C;QAC3C,qDAAqD;QACrD,mDAAmD;QACnD,yFAAyF;QACzF,uGAAuG,CAC1G;IACH,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,CACP,2CAA2C;QACzC,6GAA6G,CAChH;IACH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4DAA4D,CAAC;CAC1E,CAAC,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAe;IACjD,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE;;;;;;;;mGAQkF;QAC/F,UAAU,EAAE,iBAAiB;QAC7B,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,IAAuC,EACvC,QAA6C,EACrB,EAAE;YAC1B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACrD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;YAE5B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvE,MAAM,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;gBAC5C,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,OAAO,WAAW,CAAC,iDAAiD,CAAC,CAAC;gBACxE,CAAC;gBACD,OAAO,8BAA8B,CACnC,SAAS,EACT,8BAA8B,IAAI,CAAC,QAAQ,kBAAkB,IAAI,CAAC,QAAQ,GAAG,CAC9E,CAAC;YACJ,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;gBAC3C,OAAO,WAAW,CAAC,kCAAkC,YAAY,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../src/tools/interactions/find.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.82.2",
+  "version": "1.83.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.82.2",
+  "version": "1.83.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.82.2",
+      "version": "1.83.0",
       "transport": {
         "type": "stdio"
       }

package/src/tools/evidence.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from 'node:crypto';
+import type { ContentResult } from 'fastmcp';
+import pkg from '../../package.json' with { type: 'json' };
+
+/**
+ * Structured, machine-readable trace of a single tool action, so CI and agents
+ *  can diagnose failures without parsing prose.
+ *
+ * This is an *action* record. A future run-level bundle may reference many of
+ * these plus heavier artifacts (screenshots, page source).
+ */
+export interface ActionEvidenceRecord {
+  schemaVersion: 1;
+  producer: { name: 'appium-mcp'; version: string };
+  evidenceId: string;
+  status: 'success' | 'error';
+  /**
+   * Action-specific details. `stage`/`locator`/`element` are optional because
+   * they only apply to tools that resolve or interact with elements (find,
+   * gesture); tools like screenshot carry just `name`.
+   */
+  action: {
+    name: string;
+    stage?: EvidenceStage;
+    locator?: { strategy: string; selector: string };
+    element?: { webdriverId: string };
+  };
+  context?: {
+    platform?: string;
+    contextName?: string;
+  };
+  timing: { startedAt: string; finishedAt: string; durationMs: number };
+  error?: { code: EvidenceErrorCode; message: string };
+}
+
+export type EvidenceStage = 'locate' | 'interact' | 'capture';
+
+export type EvidenceErrorCode =
+  | 'ELEMENT_NOT_FOUND'
+  | 'TIMEOUT'
+  | 'STALE_ELEMENT'
+  | 'CONTEXT_NOT_AVAILABLE'
+  | 'INVALID_SELECTOR'
+  | 'ACTION_FAILED';
+
+const EVIDENCE_MIME_TYPE = 'application/vnd.appium.evidence+json';
+
+/** Inputs a handler supplies to describe the action it performed. */
+export interface EvidenceInput {
+  name: string;
+  startedAt: number;
+  stage?: EvidenceStage;
+  locator?: ActionEvidenceRecord['action']['locator'];
+  element?: ActionEvidenceRecord['action']['element'];
+  context?: ActionEvidenceRecord['context'];
+  error?: unknown;
+}
+
+/**
+ * When disabled, evidence is never built or attached and tool
+ * responses are byte-for-byte unchanged.
+ */
+export function isEvidenceEnabled(): boolean {
+  const raw = process.env.APPIUM_MCP_EVIDENCE?.trim().toLowerCase();
+  return raw === '1' || raw === 'true';
+}
+
+/**
+ * Attach an evidence record to an existing tool result as a `resource` content
+ * block, leaving the original text untouched. No-op when evidence is disabled.
+ */
+export function withEvidence(
+  result: ContentResult,
+  input: EvidenceInput
+): ContentResult {
+  if (!isEvidenceEnabled()) {
+    return result;
+  }
+  const record = buildRecord(result, input);
+  return {
+    ...result,
+    content: [
+      ...result.content,
+      {
+        type: 'resource',
+        resource: {
+          uri: `evidence://${record.evidenceId}`,
+          mimeType: EVIDENCE_MIME_TYPE,
+          text: JSON.stringify(record),
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Snapshot the active session's platform and current context for the evidence
+ * record. Returns undefined when there is no session to read, so the field is
+ * simply omitted. The session-store import is deferred until evidence is
+ * enabled so the disabled path pulls in no driver dependencies.
+ */
+export async function evidenceContext(
+  sessionId?: string
+): Promise<ActionEvidenceRecord['context'] | undefined> {
+  if (!isEvidenceEnabled()) {
+    return undefined;
+  }
+  const { getSessionInfo } = await import('../session-store.js');
+  const info = getSessionInfo(sessionId);
+  if (!info) {
+    return undefined;
+  }
+  return {
+    ...(info.metadata.platform ? { platform: info.metadata.platform } : {}),
+    ...(info.currentContext ? { contextName: info.currentContext } : {}),
+  };
+}
+
+/**
+ * Map a raw Appium/WebDriver error to a stable, normalized code. The codes are
+ * also the foundation for failure-reason hypotheses. Inspects the error name
+ * first, then the message, falling back to ACTION_FAILED.
+ */
+export function classifyError(err: unknown): EvidenceErrorCode {
+  const name = err instanceof Error ? err.name : '';
+  const message = (err instanceof Error ? err.message : String(err)) ?? '';
+  const haystack = `${name} ${message}`.toLowerCase();
+
+  if (/no such element|could not be located|element not found/.test(haystack)) {
+    return 'ELEMENT_NOT_FOUND';
+  }
+  if (/stale element/.test(haystack)) {
+    return 'STALE_ELEMENT';
+  }
+  if (/timed? ?out|timeout/.test(haystack)) {
+    return 'TIMEOUT';
+  }
+  if (/no such context|context.*not.*(found|available)/.test(haystack)) {
+    return 'CONTEXT_NOT_AVAILABLE';
+  }
+  if (/invalid selector|invalid.*(locator|xpath)/.test(haystack)) {
+    return 'INVALID_SELECTOR';
+  }
+  return 'ACTION_FAILED';
+}
+
+function buildRecord(
+  result: ContentResult,
+  input: EvidenceInput
+): ActionEvidenceRecord {
+  const finished = Date.now();
+  const status: ActionEvidenceRecord['status'] =
+    result.isError || input.error !== undefined ? 'error' : 'success';
+
+  return {
+    schemaVersion: 1,
+    producer: { name: 'appium-mcp', version: pkg.version },
+    evidenceId: randomUUID(),
+    status,
+    action: {
+      name: input.name,
+      ...(input.stage ? { stage: input.stage } : {}),
+      ...(input.locator ? { locator: input.locator } : {}),
+      ...(input.element ? { element: input.element } : {}),
+    },
+    ...(input.context ? { context: input.context } : {}),
+    timing: {
+      startedAt: new Date(input.startedAt).toISOString(),
+      finishedAt: new Date(finished).toISOString(),
+      durationMs: finished - input.startedAt,
+    },
+    ...(status === 'error' ? { error: buildError(input.error, result) } : {}),
+  };
+}
+
+/**
+ * Resolve the error message, then classify from the same source so the code
+ * and message always agree — handlers that swallow errors only expose the
+ * result text, so fall back to that when no error object is passed.
+ */
+function buildError(
+  err: unknown,
+  result: ContentResult
+): NonNullable<ActionEvidenceRecord['error']> {
+  const message = errorMessage(err, result);
+  return { code: classifyError(err ?? message), message };
+}
+
+function errorMessage(err: unknown, result: ContentResult): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (err !== undefined) {
+    return String(err);
+  }
+  const text = result.content.find((c) => c.type === 'text');
+  return text && 'text' in text ? text.text : 'Unknown error';
+}

package/src/tools/gestures/gesture.ts

@@ -1,16 +1,28 @@
 import type { ContentResult, FastMCP } from 'fastmcp';
+import type { DriverInstance } from '../../session-store.js';
 import {
   errorResult,
   resolveDriver,
   textResult,
   toolErrorMessage,
 } from '../tool-response.js';
-import { GESTURE_ACTIONS, gestureSchema, type GestureArgs } from './schema.js';
+import {
+  GESTURE_ACTIONS,
+  gestureSchema,
+  type GestureAction,
+  type GestureArgs,
+} from './schema.js';
 import { handleTap, handleDoubleTap, handleLongPress } from './handlers/tap.js';
 import { handleScroll, handleSwipe } from './handlers/swipe-scroll.js';
 import { handlePinchZoom } from './handlers/pinch.js';
 import { handleScrollToElement } from './handlers/scroll-to-element.js';
 import { back } from '../../command.js';
+import {
+  withEvidence,
+  evidenceContext,
+  type EvidenceStage,
+} from '../evidence.js';
+import { isAiElementUUID } from './handlers/ai-element.js';
 
 export default function gesture(server: FastMCP): void {
   server.addTool({
@@ -35,31 +47,56 @@ export default function gesture(server: FastMCP): void {
       }
       const { driver } = resolved;
 
-      switch (args.action) {
-        case 'back':
-          try {
-            await back(driver);
-            return textResult('Successfully performed back action.');
-          } catch (err: unknown) {
-            return errorResult(
-              `Failed to perform back action. ${toolErrorMessage(err)}`
-            );
-          }
-        case 'tap':
-          return handleTap(driver, args);
-        case 'double_tap':
-          return handleDoubleTap(driver, args);
-        case 'long_press':
-          return handleLongPress(driver, args);
-        case 'scroll':
-          return handleScroll(driver, args);
-        case 'swipe':
-          return handleSwipe(driver, args);
-        case 'pinch_zoom':
-          return handlePinchZoom(driver, args);
-        case 'scroll_to_element':
-          return handleScrollToElement(driver, args);
-      }
+      const startedAt = Date.now();
+      const context = await evidenceContext(args.sessionId);
+      const result = await dispatchGesture(driver, args);
+      return withEvidence(result, {
+        name: 'appium_gesture',
+        stage: gestureStage(args.action),
+        startedAt,
+        context,
+        ...(args.strategy && args.selector
+          ? { locator: { strategy: args.strategy, selector: args.selector } }
+          : {}),
+        ...(args.elementUUID && !isAiElementUUID(args.elementUUID)
+          ? { element: { webdriverId: args.elementUUID } }
+          : {}),
+      });
     },
   });
 }
+
+async function dispatchGesture(
+  driver: DriverInstance,
+  args: GestureArgs
+): Promise<ContentResult> {
+  switch (args.action) {
+    case 'back':
+      try {
+        await back(driver);
+        return textResult('Successfully performed back action.');
+      } catch (err: unknown) {
+        return errorResult(
+          `Failed to perform back action. ${toolErrorMessage(err)}`
+        );
+      }
+    case 'tap':
+      return handleTap(driver, args);
+    case 'double_tap':
+      return handleDoubleTap(driver, args);
+    case 'long_press':
+      return handleLongPress(driver, args);
+    case 'scroll':
+      return handleScroll(driver, args);
+    case 'swipe':
+      return handleSwipe(driver, args);
+    case 'pinch_zoom':
+      return handlePinchZoom(driver, args);
+    case 'scroll_to_element':
+      return handleScrollToElement(driver, args);
+  }
+}
+
+function gestureStage(action: GestureAction): EvidenceStage {
+  return action === 'scroll_to_element' ? 'locate' : 'interact';
+}

package/src/tools/interactions/find.ts

@@ -7,6 +7,7 @@ import {
   toolErrorMessage,
   readWebElementId,
 } from '../tool-response.js';
+import { withEvidence, evidenceContext } from '../evidence.js';
 
 export const findElementSchema = z.object({
   strategy: z
@@ -74,19 +75,52 @@ export default function findElement(server: FastMCP): void {
       }
       const { driver } = resolved;
 
+      const startedAt = Date.now();
+      const locator = { strategy: args.strategy, selector: args.selector };
+      const context = await evidenceContext(args.sessionId);
       try {
         const element = await driver.findElement(args.strategy, args.selector);
         const elementId = readWebElementId(element);
         if (!elementId) {
-          return errorResult('Element was returned without a valid element ID');
+          return withEvidence(
+            errorResult('Element was returned without a valid element ID'),
+            {
+              name: 'appium_find_element',
+              stage: 'locate',
+              startedAt,
+              locator,
+              context,
+            }
+          );
         }
-        return textResultWithPrimaryElementId(
-          elementId,
-          `Successfully found element ${args.selector} with strategy ${args.strategy}.`
+        return withEvidence(
+          textResultWithPrimaryElementId(
+            elementId,
+            `Successfully found element ${args.selector} with strategy ${args.strategy}.`
+          ),
+          {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt,
+            locator,
+            element: { webdriverId: elementId },
+            context,
+          }
         );
       } catch (err: unknown) {
-        const errorMessage = toolErrorMessage(err);
-        return errorResult(`Failed to find element. Error: ${errorMessage}`);
+        return withEvidence(
+          errorResult(
+            `Failed to find element. Error: ${toolErrorMessage(err)}`
+          ),
+          {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt,
+            locator,
+            context,
+            error: err,
+          }
+        );
       }
     },
   });