taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/application/devices/resolve-device-assignments.js

@@ -0,0 +1,60 @@
+function failure(code, message, missingRoles) {
+    return {
+        ok: false,
+        code,
+        message,
+        ...(missingRoles === undefined ? {} : { missingRoles })
+    };
+}
+export function resolveDeviceAssignments(input) {
+    const { declaredRoles, explicit, onlineSerials } = input;
+    const duplicateRole = explicit.find((mapping, index) => explicit.some((other, otherIndex) => otherIndex > index && other.role === mapping.role));
+    if (duplicateRole !== undefined) {
+        return failure("CONFIG_INVALID", `Duplicate --device mapping for role: ${duplicateRole.role}`);
+    }
+    const unknownRole = explicit.find((mapping) => !declaredRoles.includes(mapping.role));
+    if (unknownRole !== undefined) {
+        return failure("CONFIG_INVALID", `Device role is not declared by the journey: ${unknownRole.role}`);
+    }
+    const reusedSerial = explicit.find((mapping, index) => explicit.some((other, otherIndex) => otherIndex > index
+        && other.deviceSerial === mapping.deviceSerial));
+    if (reusedSerial !== undefined) {
+        return failure("CONFIG_INVALID", `Device serial is mapped to multiple roles: ${reusedSerial.deviceSerial}`);
+    }
+    const online = new Set(onlineSerials);
+    const offlineSerial = explicit.find((mapping) => !online.has(mapping.deviceSerial));
+    if (offlineSerial !== undefined) {
+        return failure("DEVICE_UNAVAILABLE", `Requested device is not online: ${offlineSerial.deviceSerial}`);
+    }
+    if (explicit.length === 0) {
+        if (declaredRoles.length > 1) {
+            return failure("DEVICE_ROLE_UNMAPPED", `Journey declares multiple devices; map each role with --device <role>=<serial> for: ${declaredRoles.join(", ")}`, [...declaredRoles]);
+        }
+        if (onlineSerials.length !== 1) {
+            return failure("DEVICE_UNAVAILABLE", `Expected exactly one online device, found ${String(onlineSerials.length)}`);
+        }
+        const autoSerial = onlineSerials[0];
+        const autoRole = declaredRoles[0];
+        if (autoSerial === undefined || autoRole === undefined) {
+            return failure("DEVICE_UNAVAILABLE", "Expected exactly one online device, found 1");
+        }
+        return {
+            ok: true,
+            assignments: [{ role: autoRole, deviceSerial: autoSerial }]
+        };
+    }
+    const explicitRoles = new Set(explicit.map((mapping) => mapping.role));
+    const missingRoles = declaredRoles.filter((role) => !explicitRoles.has(role));
+    if (missingRoles.length > 0) {
+        return failure("DEVICE_ROLE_UNMAPPED", `No device mapping for journey role(s): ${missingRoles.join(", ")}`, missingRoles);
+    }
+    return {
+        ok: true,
+        assignments: declaredRoles.flatMap((role) => {
+            const mapping = explicit.find((entry) => entry.role === role);
+            return mapping === undefined
+                ? []
+                : [{ role, deviceSerial: mapping.deviceSerial }];
+        })
+    };
+}

package/dist/application/diagnosis/failure-classifier.d.ts

@@ -0,0 +1,23 @@
+import { type FailureClassification } from "../../domain/failure-classification.js";
+import type { TapHoundReport } from "../../domain/report.js";
+export interface FailureClassifierInput {
+    report: TapHoundReport;
+    classificationId?: string | undefined;
+}
+export interface FailureClassifierDependencies {
+    now: () => Date;
+}
+/**
+ * Deterministic Failure Classifier (architecture doc §20, P1.5).
+ *
+ * Maps a completed run report into a concise, structured failure contract for
+ * a Coding Agent: type, likely stage, expected vs actual, step index, locator,
+ * and evidence refs. No model call, no log dump; raw evidence stays on disk
+ * and is referenced by path. Classification is pure derivation from the
+ * published report.
+ */
+export declare class FailureClassifier {
+    private readonly dependencies;
+    constructor(dependencies: FailureClassifierDependencies);
+    readonly classify: (input: FailureClassifierInput) => FailureClassification;
+}

package/dist/application/diagnosis/failure-classifier.js

@@ -0,0 +1,179 @@
+import { FAILURE_CODE_TYPES, FAILURE_TYPE_STAGES, FailureClassificationSchema } from "../../domain/failure-classification.js";
+function expectedActualFor(type, report) {
+    const primary = report.primaryFailure;
+    if (primary === undefined) {
+        return {};
+    }
+    if (type === "activity_mismatch") {
+        const step = report.steps.find((candidate) => (candidate.status === "failed"));
+        const check = step?.activity?.after.status === "failed"
+            ? step.activity.after
+            : step?.activity?.before.status === "failed"
+                ? step.activity.before
+                : undefined;
+        if (check !== undefined) {
+            return {
+                expected: check.expected,
+                actual: check.actual ?? "missing"
+            };
+        }
+    }
+    if (type === "expect_failed") {
+        const step = report.steps.find((candidate) => (candidate.expectation?.status === "failed"));
+        const expectation = step?.expectation;
+        if (expectation !== undefined) {
+            return {
+                expected: expectation.type,
+                actual: expectation.message ?? "missing"
+            };
+        }
+    }
+    if (type === "target_not_found"
+        || type === "target_ambiguous"
+        || type === "target_unresolved") {
+        const step = report.steps.find((candidate) => (candidate.status === "failed"));
+        const locator = step?.locator;
+        if (locator !== undefined) {
+            const source = locator.anchorId ?? locator.message ?? locator.matchedBy;
+            if (source === undefined) {
+                return {};
+            }
+            return {
+                expected: locator.status === "found"
+                    ? `found ${source}`
+                    : source,
+                actual: locator.status === "failed"
+                    ? "not found in layout"
+                    : locator.status
+            };
+        }
+    }
+    if (type === "app_crash") {
+        return {
+            expected: "process alive",
+            actual: "process exited"
+        };
+    }
+    if (type === "contract_invalid" || type === "evidence_failed") {
+        return {
+            expected: "binding satisfied",
+            actual: primary.message
+        };
+    }
+    return {};
+}
+function evidenceRefsFor(report) {
+    const refs = [];
+    for (const screenshot of report.artifacts.screenshots) {
+        refs.push(screenshot.path);
+    }
+    for (const logcat of report.artifacts.logcats) {
+        refs.push(logcat.path);
+    }
+    for (const stepLog of report.artifacts.stepLogs) {
+        refs.push(stepLog);
+    }
+    const failedStepLog = report.steps.find((step) => (step.status === "failed" && step.logcatPath !== undefined));
+    if (failedStepLog?.logcatPath !== undefined) {
+        refs.push(failedStepLog.logcatPath);
+    }
+    return refs;
+}
+function requestOutcomeFor(report) {
+    const failedIndex = report.primaryFailure?.stepIndex;
+    const events = report.steps.filter((step) => (step.expectation?.type === "logcatEvent"
+        && step.expectation.status === "passed"
+        && step.expectation.logcatEvent?.matchedCount === 1
+        && step.expectation.logcatEvent.matchedLineSha256 !== undefined
+        && (failedIndex === undefined || step.index <= failedIndex)));
+    if (events.length === 0) {
+        return { errorClass: "unknown", evidenceRefs: [] };
+    }
+    const classes = new Set(events.map((step) => step.expectation?.logcatEvent?.requestErrorClass));
+    const errorClass = classes.size === 1
+        ? [...classes][0] ?? "unknown"
+        : "unknown";
+    const refs = new Set([report.artifacts.report]);
+    for (const step of events) {
+        if (step.logcatPath !== undefined)
+            refs.add(step.logcatPath);
+    }
+    return { errorClass, evidenceRefs: [...refs] };
+}
+function locatorFor(type, report) {
+    if (type !== "target_not_found"
+        && type !== "target_ambiguous"
+        && type !== "target_unresolved") {
+        return undefined;
+    }
+    const locator = report.steps.find((step) => step.status === "failed")?.locator;
+    if (locator === undefined) {
+        return undefined;
+    }
+    // Rebuild a canonical Locator from a report locator: report locators carry
+    // runtime status fields the domain Locator does not accept.
+    if (locator.anchorId !== undefined) {
+        return { resourceId: `anchor:${locator.anchorId}` };
+    }
+    if (locator.matchedBy === "resourceId") {
+        return { resourceId: locator.message ?? "resourceId" };
+    }
+    if (locator.matchedBy === "text") {
+        return { text: locator.message ?? "text" };
+    }
+    if (locator.matchedBy === "contentDescription") {
+        return { contentDescription: locator.message ?? "contentDescription" };
+    }
+    return { resourceId: "unknown" };
+}
+/**
+ * Deterministic Failure Classifier (architecture doc §20, P1.5).
+ *
+ * Maps a completed run report into a concise, structured failure contract for
+ * a Coding Agent: type, likely stage, expected vs actual, step index, locator,
+ * and evidence refs. No model call, no log dump; raw evidence stays on disk
+ * and is referenced by path. Classification is pure derivation from the
+ * published report.
+ */
+export class FailureClassifier {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    classify = (input) => {
+        const { report } = input;
+        const primary = report.primaryFailure;
+        if (primary === undefined) {
+            throw new Error(`Cannot classify run ${report.runId}: the report has no primary failure`);
+        }
+        const type = FAILURE_CODE_TYPES[primary.code] ?? "internal_error";
+        const stage = FAILURE_TYPE_STAGES[type];
+        const expectedActual = expectedActualFor(type, report);
+        const locator = locatorFor(type, report);
+        const classificationId = input.classificationId
+            ?? `${report.runId}:${primary.code}:${String(primary.stepIndex ?? "-")}`;
+        const classification = FailureClassificationSchema.parse({
+            version: 1,
+            runId: report.runId,
+            classificationId,
+            type,
+            stage,
+            code: primary.code,
+            message: primary.message,
+            ...(primary.stepIndex === undefined
+                ? {}
+                : { stepIndex: primary.stepIndex }),
+            ...(expectedActual.expected === undefined
+                ? {}
+                : { expected: expectedActual.expected }),
+            ...(expectedActual.actual === undefined
+                ? {}
+                : { actual: expectedActual.actual }),
+            ...(locator === undefined ? {} : { locator }),
+            evidenceRefs: evidenceRefsFor(report),
+            requestOutcome: requestOutcomeFor(report),
+            sourceReportPath: report.artifacts.report
+        });
+        return classification;
+    };
+}

package/dist/application/doctor/doctor-service.d.ts

@@ -1,35 +1,68 @@
 import type { FailureCode } from "../../domain/failure.js";
+import type { RuntimeBackendId } from "../../domain/runtime.js";
+import type { UiBackendSelection } from "../../domain/ui-backend.js";
 import type { AdbPort } from "../../ports/adb.js";
 import type { ProcessRunner } from "../../ports/process-runner.js";
-export type DoctorCheckName = "node" | "adb" | "android" | "app" | "permissions" | "device";
+import type { DeviceAssignment } from "../devices/resolve-device-assignments.js";
+export type DoctorCheckName = "node" | "adb" | "android" | "app" | "permissions" | "device" | "appium" | "mobile-mcp";
+export type DoctorCheckStatus = "passed" | "failed" | "notRun";
 export interface DoctorCheck {
     name: DoctorCheckName;
-    status: "passed" | "failed" | "notRun";
+    status: DoctorCheckStatus;
     version?: string | undefined;
     message?: string | undefined;
 }
+export interface DoctorDeviceCheck {
+    role: string;
+    deviceSerial: string;
+    online: boolean;
+    app: DoctorCheckStatus;
+    permissions: DoctorCheckStatus;
+    message?: string | undefined;
+}
 export interface DoctorReport {
     status: "passed" | "failed";
+    runtimeBackend: RuntimeBackendId;
     checks: DoctorCheck[];
     deviceSerial?: string | undefined;
+    devices?: readonly DoctorDeviceCheck[] | undefined;
     failureCode?: Extract<FailureCode, "ENVIRONMENT_MISSING_TOOL" | "DEVICE_UNAVAILABLE" | "APP_NOT_INSTALLED"> | undefined;
 }
 export interface DoctorRunInput {
     packageName?: string | undefined;
     requestedDevice?: string | undefined;
+    requestedDevices?: readonly DeviceAssignment[] | undefined;
     signal?: AbortSignal | undefined;
+    skipPermissionProbe?: boolean | undefined;
+    requestedUiBackend?: UiBackendSelection | undefined;
 }
 export interface DoctorDependencies {
     runner: ProcessRunner;
-    adb: AdbPort;
+    /** Device listing and the install probe; each probe borrows a session. */
+    adb: Pick<AdbPort, "devices" | "isInstalled">;
     nodeVersion: string;
+    runtimeBackendId: RuntimeBackendId;
     checkAndroidPermissions: (deviceSerial: string, signal?: AbortSignal) => Promise<{
         status: "passed" | "failed";
         message?: string | undefined;
     }>;
+    checkAppiumUiAutomator2?: (signal?: AbortSignal) => Promise<{
+        status: "passed" | "failed";
+        version?: string | undefined;
+        message?: string | undefined;
+    }>;
+    checkMobileMcpServer?: (signal?: AbortSignal) => Promise<{
+        status: "passed" | "failed";
+        version?: string | undefined;
+        message?: string | undefined;
+    }>;
 }
 export declare class DoctorService {
     private readonly dependencies;
     constructor(dependencies: DoctorDependencies);
     run(input?: DoctorRunInput): Promise<DoctorReport>;
+    private environmentChecks;
+    private conclude;
+    private runSingleDevice;
+    private runForAssignments;
 }

package/dist/application/doctor/doctor-service.js

@@ -19,7 +19,14 @@ export class DoctorService {
         this.dependencies = dependencies;
     }
     async run(input = {}) {
-        const { packageName, requestedDevice, signal } = input;
+        const assignments = input.requestedDevices;
+        if (assignments !== undefined && assignments.length > 0) {
+            return this.runForAssignments(input, assignments);
+        }
+        return this.runSingleDevice(input);
+    }
+    async environmentChecks(input) {
+        const { signal } = input;
         const checks = [nodeCheck(this.dependencies.nodeVersion)];
         const tool = async (name, executable, args) => {
             try {
@@ -54,7 +61,106 @@ export class DoctorService {
                 };
             }
         };
-        checks.push(await tool("adb", "adb", ["version"]), await tool("android", "android", ["--version"]));
+        checks.push(await tool("adb", "adb", ["version"]));
+        if (this.dependencies.runtimeBackendId === "mobile-mcp") {
+            checks.push({
+                name: "android",
+                status: "notRun",
+                message: "Android CLI probe requires the adb runtime backend"
+            });
+            try {
+                const mobileMcp = await this.dependencies.checkMobileMcpServer?.(signal);
+                checks.push(mobileMcp === undefined ? {
+                    name: "mobile-mcp",
+                    status: "failed",
+                    message: "Mobile MCP server check is not configured"
+                } : {
+                    name: "mobile-mcp",
+                    status: mobileMcp.status,
+                    ...(mobileMcp.version === undefined ? {} : { version: mobileMcp.version }),
+                    ...(mobileMcp.message === undefined ? {} : { message: mobileMcp.message })
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "mobile-mcp",
+                    status: "failed",
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        else {
+            checks.push(await tool("android", "android", ["--version"]));
+            checks.push({
+                name: "mobile-mcp",
+                status: "notRun",
+                message: "Mobile MCP server probe requires the mobile-mcp runtime backend"
+            });
+        }
+        if (input.requestedUiBackend === "appium-uiautomator2") {
+            if (this.dependencies.runtimeBackendId === "mobile-mcp") {
+                checks.push({
+                    name: "appium",
+                    status: "failed",
+                    message: "ui.backend=appium-uiautomator2 is not supported by the mobile-mcp runtime backend"
+                });
+            }
+            else {
+                try {
+                    const appium = await this.dependencies.checkAppiumUiAutomator2?.(signal);
+                    checks.push(appium === undefined ? {
+                        name: "appium",
+                        status: "failed",
+                        message: "Appium UiAutomator2 check is not configured"
+                    } : {
+                        name: "appium",
+                        status: appium.status,
+                        ...(appium.version === undefined ? {} : { version: appium.version }),
+                        ...(appium.message === undefined ? {} : { message: appium.message })
+                    });
+                }
+                catch (error) {
+                    checks.push({
+                        name: "appium",
+                        status: "failed",
+                        message: error instanceof Error ? error.message : String(error)
+                    });
+                }
+            }
+        }
+        else {
+            checks.push({
+                name: "appium",
+                status: "notRun",
+                message: "Appium probe requires ui.backend=appium-uiautomator2"
+            });
+        }
+        return checks;
+    }
+    conclude(checks, identity) {
+        const failedCheck = (name) => checks.some((check) => check.name === name && check.status === "failed");
+        const environmentFailed = ["node", "adb", "android", "appium", "mobile-mcp", "permissions"].some(failedCheck);
+        const failureCode = environmentFailed
+            ? "ENVIRONMENT_MISSING_TOOL"
+            : failedCheck("device")
+                ? "DEVICE_UNAVAILABLE"
+                : failedCheck("app")
+                    ? "APP_NOT_INSTALLED"
+                    : undefined;
+        return {
+            status: failureCode === undefined ? "passed" : "failed",
+            runtimeBackend: this.dependencies.runtimeBackendId,
+            checks,
+            ...(identity.deviceSerial === undefined
+                ? {}
+                : { deviceSerial: identity.deviceSerial }),
+            ...(identity.devices === undefined ? {} : { devices: identity.devices }),
+            ...(failureCode === undefined ? {} : { failureCode })
+        };
+    }
+    async runSingleDevice(input) {
+        const { packageName, requestedDevice, signal } = input;
+        const checks = await this.environmentChecks(input);
         let deviceSerial;
         let deviceCheck;
         try {
@@ -124,7 +230,14 @@ export class DoctorService {
                 });
             }
         }
-        if (deviceSerial === undefined) {
+        if (input.skipPermissionProbe === true) {
+            checks.push({
+                name: "permissions",
+                status: "notRun",
+                message: "Permission probe deferred to verification"
+            });
+        }
+        else if (deviceSerial === undefined) {
             checks.push({
                 name: "permissions",
                 status: "notRun",
@@ -151,28 +264,145 @@ export class DoctorService {
             }
         }
         checks.push(deviceCheck);
-        const failedCheck = (name) => checks.some((check) => check.name === name && check.status === "failed");
-        const environmentFailed = ["node", "adb", "android", "permissions"]
-            .some(failedCheck);
-        const failureCode = environmentFailed
-            ? "ENVIRONMENT_MISSING_TOOL"
-            : failedCheck("device")
-                ? "DEVICE_UNAVAILABLE"
-                : failedCheck("app")
-                    ? "APP_NOT_INSTALLED"
-                    : undefined;
-        if (failureCode !== undefined) {
-            return {
-                status: "failed",
-                checks,
-                ...(deviceSerial === undefined ? {} : { deviceSerial }),
-                failureCode
-            };
-        }
-        return {
-            status: "passed",
-            checks,
+        return this.conclude(checks, {
             ...(deviceSerial === undefined ? {} : { deviceSerial })
-        };
+        });
+    }
+    async runForAssignments(input, assignments) {
+        const { packageName, signal } = input;
+        const checks = await this.environmentChecks(input);
+        let onlineSerials;
+        let listingError;
+        try {
+            const devices = await this.dependencies.adb.devices(signal);
+            onlineSerials = new Set(devices
+                .filter((device) => device.status === "device")
+                .map((device) => device.serial));
+        }
+        catch (error) {
+            onlineSerials = new Set();
+            listingError = error instanceof Error ? error.message : String(error);
+        }
+        const deviceChecks = [];
+        const appFailures = [];
+        const permissionFailures = [];
+        for (const assignment of assignments) {
+            const online = onlineSerials.has(assignment.deviceSerial);
+            const problems = [];
+            if (!online) {
+                problems.push(listingError !== undefined
+                    ? `Device listing failed: ${listingError}`
+                    : `Requested device is not online: ${assignment.deviceSerial}`);
+            }
+            let app = "notRun";
+            if (online && packageName !== undefined) {
+                try {
+                    const installed = await this.dependencies.adb.isInstalled({
+                        packageName,
+                        deviceSerial: assignment.deviceSerial,
+                        ...(signal === undefined ? {} : { signal })
+                    });
+                    app = installed ? "passed" : "failed";
+                    if (!installed) {
+                        const message = `Package ${packageName} is not installed on ${assignment.deviceSerial}`;
+                        appFailures.push(message);
+                        problems.push(message);
+                    }
+                }
+                catch (error) {
+                    app = "failed";
+                    const message = error instanceof Error
+                        ? error.message
+                        : String(error);
+                    appFailures.push(message);
+                    problems.push(message);
+                }
+            }
+            let permissions = "notRun";
+            if (online && input.skipPermissionProbe !== true) {
+                try {
+                    const permission = await this.dependencies.checkAndroidPermissions(assignment.deviceSerial, signal);
+                    permissions = permission.status;
+                    if (permission.status === "failed") {
+                        if (permission.message !== undefined) {
+                            permissionFailures.push(permission.message);
+                            problems.push(permission.message);
+                        }
+                        else {
+                            permissionFailures.push(`Permission probe failed on ${assignment.deviceSerial}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    permissions = "failed";
+                    const message = error instanceof Error
+                        ? error.message
+                        : String(error);
+                    permissionFailures.push(message);
+                    problems.push(message);
+                }
+            }
+            deviceChecks.push({
+                role: assignment.role,
+                deviceSerial: assignment.deviceSerial,
+                online,
+                app,
+                permissions,
+                ...(problems.length === 0 ? {} : { message: problems.join("; ") })
+            });
+        }
+        const offlineDevices = deviceChecks.filter((device) => !device.online);
+        const appRan = deviceChecks.some((device) => device.app !== "notRun");
+        const permissionsRan = deviceChecks.some((device) => device.permissions !== "notRun");
+        const appStatus = appFailures.length > 0
+            ? "failed"
+            : appRan
+                ? "passed"
+                : "notRun";
+        checks.push({
+            name: "app",
+            status: appStatus,
+            ...(appStatus === "failed"
+                ? { message: appFailures.join("; ") }
+                : appStatus === "passed"
+                    ? { message: packageName }
+                    : {
+                        message: packageName === undefined
+                            ? "Installed application probe requires a configured package"
+                            : "Installed application probe requires an online selected device"
+                    })
+        });
+        const permissionStatus = permissionFailures.length > 0
+            ? "failed"
+            : permissionsRan
+                ? "passed"
+                : "notRun";
+        checks.push({
+            name: "permissions",
+            status: permissionStatus,
+            ...(permissionStatus === "failed"
+                ? { message: permissionFailures.join("; ") }
+                : permissionStatus === "notRun"
+                    ? {
+                        message: input.skipPermissionProbe === true
+                            ? "Permission probe deferred to verification"
+                            : "Permission probe requires an online selected device"
+                    }
+                    : {})
+        });
+        checks.push({
+            name: "device",
+            status: offlineDevices.length === 0 ? "passed" : "failed",
+            ...(offlineDevices.length === 0
+                ? {
+                    message: deviceChecks
+                        .map((device) => `${device.role}=${device.deviceSerial}`)
+                        .join(", ")
+                }
+                : {
+                    message: `Requested devices are not online: ${offlineDevices.map((device) => device.deviceSerial).join(", ")}`
+                })
+        });
+        return this.conclude(checks, { devices: deviceChecks });
     }
 }

package/dist/application/generation/generation-app-preparer.d.ts

@@ -0,0 +1,20 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import type { Clock } from "../../ports/clock.js";
+import { type RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { RuntimeSessionPortViewsFactory } from "../../ports/runtime-session-ports.js";
+export interface GenerationAppPreparationInput {
+    config: TapHoundConfig;
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+}
+export interface GenerationAppPreparerDependencies {
+    sessions: RuntimeSessionOpener;
+    sessionPorts: RuntimeSessionPortViewsFactory;
+    clock: Clock;
+}
+export declare class GenerationAppPreparer {
+    private readonly dependencies;
+    constructor(dependencies: GenerationAppPreparerDependencies);
+    prepare(input: GenerationAppPreparationInput): Promise<void>;
+    private coldLaunch;
+}