taphound 0.2.0-dev.1 → 0.2.0-dev.12

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;
+}

package/dist/application/generation/generation-app-preparer.js

@@ -0,0 +1,28 @@
+import { normalizeActivity } from "../../domain/activity.js";
+import { withRuntimeSession } from "../../ports/runtime-backend.js";
+import { coldLaunchApp } from "../runtime/cold-launch.js";
+export class GenerationAppPreparer {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    prepare(input) {
+        return withRuntimeSession(this.dependencies.sessions, input.deviceSerial, input.signal, (session) => this.coldLaunch(this.dependencies.sessionPorts(session).adb, input));
+    }
+    async coldLaunch(adb, input) {
+        const launched = await coldLaunchApp(adb, this.dependencies.clock, {
+            packageName: input.config.run.packageName,
+            activity: normalizeActivity(input.config.run.packageName, input.config.run.activity),
+            deviceSerial: input.deviceSerial,
+            pollIntervalMs: input.config.idle.pollIntervalMs,
+            timeoutMs: input.config.idle.timeoutMs,
+            signal: input.signal
+        });
+        if (launched.status === "cancelled") {
+            throw new Error("App launch was cancelled");
+        }
+        if (launched.status === "failed") {
+            throw new Error(launched.message);
+        }
+    }
+}

package/dist/application/generation/generation-config-service.d.ts

@@ -0,0 +1,21 @@
+import { type GenerationSession } from "../../domain/generation.js";
+import { type TapHoundConfig } from "../../domain/config.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+export interface GenerationIdlePolicyPatch {
+    strategy?: TapHoundConfig["idle"]["strategy"] | undefined;
+    pollIntervalMs?: number | undefined;
+    stablePolls?: number | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface GenerationConfigServiceDependencies {
+    store: Pick<GenerationSessionStore, "read" | "update">;
+}
+export declare class GenerationConfigService {
+    private readonly dependencies;
+    constructor(dependencies: GenerationConfigServiceDependencies);
+    readonly updateIdlePolicy: (input: {
+        generationId: string;
+        config: TapHoundConfig;
+        patch: GenerationIdlePolicyPatch;
+    }) => Promise<GenerationSession>;
+}

package/dist/application/generation/generation-config-service.js

@@ -0,0 +1,53 @@
+import { GenerationSessionSchema } from "../../domain/generation.js";
+import { IdlePolicySchema } from "../../domain/config.js";
+import { GenerationOperationError } from "./generation-starter.js";
+function hasPatch(patch) {
+    return patch.strategy !== undefined
+        || patch.pollIntervalMs !== undefined
+        || patch.stablePolls !== undefined
+        || patch.timeoutMs !== undefined;
+}
+function assertUpdatable(session) {
+    if (session.state !== "active") {
+        throw new GenerationOperationError("CONFIG_INVALID", `Generation idle policy can only be updated on an active session (state: ${session.state})`);
+    }
+    if (session.inFlight !== null) {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation idle policy cannot change while a step is in flight");
+    }
+    if (session.pendingConfirmation !== null) {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation idle policy cannot change while a confirmation is pending");
+    }
+    if (session.verification.status !== "notRun") {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation idle policy cannot change once verification has started");
+    }
+    if (session.publication.status !== "notRun") {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation idle policy cannot change after publication");
+    }
+}
+export class GenerationConfigService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    updateIdlePolicy = async (input) => {
+        if (!hasPatch(input.patch)) {
+            throw new GenerationOperationError("CONFIG_INVALID", "Generation idle policy update requires at least one setting");
+        }
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        assertUpdatable(session);
+        const base = session.idlePolicy ?? input.config.idle;
+        const idlePolicy = IdlePolicySchema.parse({
+            strategy: input.patch.strategy ?? base.strategy,
+            pollIntervalMs: input.patch.pollIntervalMs ?? base.pollIntervalMs,
+            stablePolls: input.patch.stablePolls ?? base.stablePolls,
+            timeoutMs: input.patch.timeoutMs ?? base.timeoutMs
+        });
+        const next = {
+            ...session,
+            revision: session.revision + 1,
+            idlePolicy
+        };
+        await this.dependencies.store.update(input.generationId, session.revision, next);
+        return next;
+    };
+}

package/dist/application/generation/generation-confirmation-service.d.ts

@@ -13,18 +13,22 @@ export interface GenerationConfirmationDependencies {
 export interface ConfirmationRequestInput {
     generationId: string;
     proposal: ProposedStep;
-    snapshot: RuntimeSnapshot;
+    snapshot?: RuntimeSnapshot | undefined;
+    snapshotRef?: string | undefined;
     source?: "planner" | "manualOverride" | undefined;
 }
 export interface ConfirmationApproveInput extends ConfirmationRequestInput {
     challengeId: string;
+    decision?: ConfirmationDecision | undefined;
     signal?: AbortSignal | undefined;
 }
 export interface StoredConfirmationApproveInput {
     generationId: string;
     challengeId: string;
+    decision?: ConfirmationDecision | undefined;
     signal?: AbortSignal | undefined;
 }
+export type ConfirmationDecision = "approve" | "decline";
 export interface ManualConfirmationRequestInput {
     generationId: string;
     snapshot: RuntimeSnapshot;
@@ -37,18 +41,22 @@ export interface PendingManualConfirmationInput {
 }
 export interface ConfirmationRequiredResult {
     status: "confirmationRequired";
+    revision: number;
     challenge: PendingConfirmation;
 }
 export type ConfirmationRequestResult = {
     status: "approved";
     proposal: ProposedStep;
+    snapshot: RuntimeSnapshot;
 } | ConfirmationRequiredResult;
-export interface StoredConfirmationApproveResult {
+export type StoredConfirmationApproveResult = {
     status: "approved";
     proposal: ProposedStep;
     snapshot: RuntimeSnapshot;
     source: "planner" | "manualOverride";
-}
+} | {
+    status: "declined";
+};
 export declare function summarizeProposedStep(step: ProposedStep): string;
 export declare function confirmationEvidencePath(challengeId: string): string;
 export declare class GenerationConfirmationService {
@@ -63,6 +71,8 @@ export declare class GenerationConfirmationService {
     readonly confirm: (input: ConfirmationApproveInput) => Promise<{
         status: "approved";
         proposal: ProposedStep;
+    } | {
+        status: "declined";
     }>;
     readonly clearApproved: (input: {
         generationId: string;
@@ -73,4 +83,5 @@ export declare class GenerationConfirmationService {
     private requireExactPendingChallenge;
     private updateConfirmationReconciled;
     private readStoredEvidence;
+    private resolveSnapshot;
 }