taphound 0.2.0-dev.1

package/dist/application/generation/proposed-step-validator.js

@@ -0,0 +1,88 @@
+import { GenerationSessionSchema } from "../../domain/generation.js";
+import { ProposedStepSchema } from "../../domain/proposed-step.js";
+import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+import { GenerationOperationError } from "./generation-starter.js";
+function flatten(elements) {
+    return elements.flatMap((element) => [
+        element,
+        ...flatten(element.children)
+    ]);
+}
+function rejectCapability(message) {
+    throw new GenerationOperationError("ACTION_UNSUPPORTED", message);
+}
+function requireUniqueTarget(snapshot, locator, capability, capabilityName) {
+    const resolution = resolveLocator(snapshot.layout, locator);
+    if (resolution.status !== "found") {
+        rejectCapability(resolution.message);
+    }
+    if (!capability(resolution.element)) {
+        rejectCapability(`Layout target lacks required ${capabilityName} capability`);
+    }
+    return resolution.element;
+}
+function validateBinding(session, snapshot, proposal) {
+    const binding = proposal.binding;
+    if (session.state !== "active"
+        || session.inFlight !== null
+        || session.pendingConfirmation !== null
+        || session.verification.status !== "notRun"
+        || session.publication.status !== "notRun"
+        || binding.generationId !== session.id
+        || binding.baseRevision !== session.revision
+        || binding.snapshotHash !== session.bindings.snapshotHash
+        || snapshot.generationId !== session.id
+        || snapshot.baseRevision !== session.revision
+        || snapshot.deviceSerial !== session.target.deviceSerial
+        || hashRuntimeSnapshot(snapshot) !== binding.snapshotHash) {
+        throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal is not bound to the authoritative generation snapshot");
+    }
+    if (snapshot.expectedPackageName !== session.target.packageName
+        || snapshot.foregroundPackageName !== session.target.packageName) {
+        throw new GenerationOperationError("PACKAGE_ESCAPE", "Foreground package escaped the generation target");
+    }
+    if (snapshot.activity !== proposal.activity.before) {
+        throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal before Activity does not match the current snapshot");
+    }
+}
+function validateAction(snapshot, proposal) {
+    if (proposal.action === "click") {
+        requireUniqueTarget(snapshot, proposal.locator, (element) => element.clickable === true, "clickable");
+        return;
+    }
+    if (proposal.action === "longClick") {
+        requireUniqueTarget(snapshot, proposal.locator, (element) => element.longClickable === true, "longClickable");
+        return;
+    }
+    if (proposal.action === "swipe") {
+        requireUniqueTarget(snapshot, proposal.locator, (element) => element.scrollable === true
+            && element.bounds !== undefined, "scrollable bounds");
+        return;
+    }
+    if (proposal.action === "scrollTo") {
+        requireUniqueTarget(snapshot, proposal.container, (element) => element.scrollable === true
+            && element.bounds !== undefined, "scrollable container bounds");
+        const target = resolveLocator(snapshot.layout, proposal.locator, { requireEnabled: false });
+        if (target.status === "failed" && target.code === "LOCATOR_AMBIGUOUS") {
+            rejectCapability(`scrollTo target is ambiguous: ${target.message}`);
+        }
+        return;
+    }
+    if (proposal.action === "inputText") {
+        const focused = flatten(snapshot.layout).filter((element) => element.enabled && element.focused === true);
+        if (focused.length !== 1) {
+            rejectCapability("inputText requires exactly one enabled focused visible Layout element");
+        }
+    }
+}
+export class ProposedStepValidator {
+    validate(input) {
+        const session = GenerationSessionSchema.parse(input.session);
+        const snapshot = RuntimeSnapshotSchema.parse(input.snapshot);
+        const proposal = ProposedStepSchema.parse(input.proposal);
+        validateBinding(session, snapshot, proposal);
+        validateAction(snapshot, proposal);
+        return proposal;
+    }
+}

package/dist/application/generation/risk-evaluator.d.ts

@@ -0,0 +1,9 @@
+import type { ProposedStep } from "../../domain/proposed-step.js";
+import type { InteractionPolicy } from "../../domain/project-context.js";
+export type EffectiveRisk = "safe" | "confirmationRequired" | "forbidden";
+export interface RiskEvaluation {
+    effectiveRisk: EffectiveRisk;
+}
+export declare class RiskEvaluator {
+    evaluate(action: ProposedStep["action"], policy: InteractionPolicy): RiskEvaluation;
+}

package/dist/application/generation/risk-evaluator.js

@@ -0,0 +1,14 @@
+export class RiskEvaluator {
+    evaluate(action, policy) {
+        if (policy.forbiddenActions.includes(action)) {
+            return { effectiveRisk: "forbidden" };
+        }
+        if (policy.confirmationRequiredActions.includes(action)) {
+            return { effectiveRisk: "confirmationRequired" };
+        }
+        if (policy.allowedActions.includes(action)) {
+            return { effectiveRisk: "safe" };
+        }
+        return { effectiveRisk: "confirmationRequired" };
+    }
+}

package/dist/application/generation/runtime-observer.d.ts

@@ -0,0 +1,39 @@
+import { type PendingConfirmation } from "../../domain/generation.js";
+import { type ProposalBinding } from "../../domain/proposed-step.js";
+import { type RuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+export type RuntimeObservationBinding = ProposalBinding;
+export interface RuntimeObservation {
+    binding: RuntimeObservationBinding;
+    snapshot: RuntimeSnapshot;
+    snapshotHash: string;
+}
+export interface RuntimeObserveInput {
+    generationId: string;
+    signal?: AbortSignal | undefined;
+}
+export interface RuntimeObserverDependencies {
+    store: Pick<GenerationSessionStore, "read" | "writeEvidence" | "produceEvidence" | "commitSnapshot">;
+    adb: Pick<AdbPort, "foregroundComponent" | "appProcesses">;
+    androidCli: Pick<AndroidCliPort, "layout" | "captureScreen">;
+    now: () => Date;
+    createAttemptId: () => string;
+}
+export interface SnapshotReobservationGuardDependencies {
+    store: Pick<GenerationSessionStore, "read">;
+    adb: Pick<AdbPort, "foregroundComponent" | "appProcesses">;
+    androidCli: Pick<AndroidCliPort, "layout">;
+    now: () => Date;
+}
+export declare class RuntimeObserver {
+    private readonly dependencies;
+    constructor(dependencies: RuntimeObserverDependencies);
+    readonly observe: (input: RuntimeObserveInput) => Promise<RuntimeObservation>;
+}
+export declare class SnapshotReobservationGuard {
+    private readonly dependencies;
+    constructor(dependencies: SnapshotReobservationGuardDependencies);
+    readonly assertFresh: (input: ProposalBinding, signal?: AbortSignal, approvedConfirmation?: PendingConfirmation) => Promise<RuntimeSnapshot>;
+}

package/dist/application/generation/runtime-observer.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { primaryAppPid } from "../../domain/app-process.js";
+import { GenerationSessionIdSchema, GenerationSessionSchema } from "../../domain/generation.js";
+import { LayoutElementSchema } from "../../domain/layout.js";
+import { ProposalBindingSchema } from "../../domain/proposed-step.js";
+import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { GenerationOperationError } from "./generation-starter.js";
+function failedCapture(result) {
+    return result.exitCode !== 0
+        || result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined;
+}
+function revisionPath(revision) {
+    return `evidence/snapshots/revision-${String(revision).padStart(6, "0")}`;
+}
+function assertObservable(session) {
+    if (session.state !== "active"
+        || session.inFlight !== null
+        || session.pendingConfirmation !== null) {
+        throw new Error("Generation session must be active and idle to observe");
+    }
+    if (session.revision === Number.MAX_SAFE_INTEGER) {
+        throw new Error("Generation session revision cannot be incremented");
+    }
+}
+async function collectRuntime(dependencies, session, signal) {
+    const identity = {
+        packageName: session.target.packageName,
+        deviceSerial: session.target.deviceSerial,
+        ...(signal === undefined ? {} : { signal })
+    };
+    const foreground = await dependencies.adb.foregroundComponent(identity);
+    const pid = primaryAppPid(await dependencies.adb.appProcesses(identity), session.target.packageName);
+    const layout = z.array(LayoutElementSchema).parse(await dependencies.androidCli.layout({
+        deviceSerial: session.target.deviceSerial,
+        ...(signal === undefined ? {} : { signal })
+    }));
+    return {
+        foregroundPackageName: foreground.packageName,
+        activity: foreground.activity,
+        pid,
+        layout
+    };
+}
+export class RuntimeObserver {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    observe = async (input) => {
+        const current = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        assertObservable(current);
+        const runtime = await collectRuntime(this.dependencies, current, input.signal);
+        const baseRevision = current.revision + 1;
+        const attemptId = GenerationSessionIdSchema.parse(this.dependencies.createAttemptId());
+        const evidenceDirectory = `${revisionPath(baseRevision)}/${attemptId}`;
+        const screenshotPath = `${evidenceDirectory}/screen.png`;
+        await this.dependencies.store.produceEvidence(current.id, screenshotPath, async (temporaryPath) => {
+            const capture = await this.dependencies.androidCli.captureScreen({
+                outputPath: temporaryPath,
+                deviceSerial: current.target.deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            if (failedCapture(capture)) {
+                throw new Error(capture.stderr.trim()
+                    || capture.spawnError
+                    || "Runtime screenshot capture failed");
+            }
+        });
+        const snapshot = RuntimeSnapshotSchema.parse({
+            version: 1,
+            generationId: current.id,
+            baseRevision,
+            deviceSerial: current.target.deviceSerial,
+            expectedPackageName: current.target.packageName,
+            foregroundPackageName: runtime.foregroundPackageName,
+            activity: runtime.activity,
+            pid: runtime.pid,
+            capturedAt: this.dependencies.now().toISOString(),
+            screenshotPath,
+            layout: runtime.layout
+        });
+        const snapshotHash = hashRuntimeSnapshot(snapshot);
+        await this.dependencies.store.writeEvidence(current.id, `${evidenceDirectory}/snapshot.json`, snapshot);
+        const next = GenerationSessionSchema.parse({
+            ...current,
+            revision: baseRevision,
+            bindings: {
+                ...current.bindings,
+                snapshotHash
+            }
+        });
+        await this.dependencies.store.commitSnapshot(current.id, current.revision, next);
+        return {
+            binding: {
+                generationId: current.id,
+                baseRevision: next.revision,
+                snapshotHash
+            },
+            snapshot,
+            snapshotHash
+        };
+    };
+}
+export class SnapshotReobservationGuard {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    assertFresh = async (input, signal, approvedConfirmation) => {
+        try {
+            const binding = ProposalBindingSchema.parse(input);
+            const session = GenerationSessionSchema.parse(await this.dependencies.store.read(binding.generationId));
+            if (session.id !== binding.generationId
+                || session.state !== "active"
+                || session.bindings.snapshotHash !== binding.snapshotHash
+                || session.inFlight !== null
+                || session.verification.status !== "notRun"
+                || session.publication.status !== "notRun"
+                || (approvedConfirmation === undefined
+                    ? (session.revision !== binding.baseRevision
+                        || session.pendingConfirmation !== null)
+                    : (approvedConfirmation.status !== "approved"
+                        || session.revision !== binding.baseRevision + 2
+                        || JSON.stringify(session.pendingConfirmation)
+                            !== JSON.stringify(approvedConfirmation)))) {
+                throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal snapshot binding is no longer authoritative");
+            }
+            const runtime = await collectRuntime(this.dependencies, session, signal);
+            const snapshot = RuntimeSnapshotSchema.parse({
+                version: 1,
+                generationId: session.id,
+                baseRevision: binding.baseRevision,
+                deviceSerial: session.target.deviceSerial,
+                expectedPackageName: session.target.packageName,
+                foregroundPackageName: runtime.foregroundPackageName,
+                activity: runtime.activity,
+                pid: runtime.pid,
+                capturedAt: this.dependencies.now().toISOString(),
+                screenshotPath: "non-authoritative://runtime-reobservation",
+                layout: runtime.layout
+            });
+            if (hashRuntimeSnapshot(snapshot) !== binding.snapshotHash) {
+                throw new GenerationOperationError("SNAPSHOT_STALE", "Runtime snapshot changed after proposal");
+            }
+            return snapshot;
+        }
+        catch (error) {
+            if (error instanceof GenerationOperationError
+                && error.code === "SNAPSHOT_STALE") {
+                throw error;
+            }
+            throw new GenerationOperationError("SNAPSHOT_STALE", "Runtime snapshot could not be re-observed");
+        }
+    };
+}

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

@@ -0,0 +1,17 @@
+import { type AgentId, type InitResult } from "../../domain/init.js";
+import type { SkillInstallerPort } from "../../ports/skill-installer.js";
+export interface InitServiceDeps {
+    installer: SkillInstallerPort;
+    cwd: string;
+    homedir: string;
+}
+export interface InitInput {
+    agents: readonly AgentId[];
+    global: boolean;
+}
+export declare class InitService {
+    private readonly deps;
+    constructor(deps: InitServiceDeps);
+    install(input: InitInput): Promise<InitResult>;
+}
+export declare function defaultHomedir(): string;

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

@@ -0,0 +1,44 @@
+import { homedir } from "node:os";
+import { NoAgentsSelectedError, resolveTargetPaths } from "../../domain/init.js";
+export class InitService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async install(input) {
+        if (input.agents.length === 0) {
+            throw new NoAgentsSelectedError();
+        }
+        const targets = resolveTargetPaths(input.agents, input.global, this.deps.cwd, this.deps.homedir);
+        const installedPaths = [];
+        const skippedPaths = [];
+        const allAgents = [];
+        for (const target of targets) {
+            const result = await this.deps.installer.installTo(target.absolutePath);
+            if (result.skipped) {
+                skippedPaths.push(target.relativePath);
+            }
+            else {
+                installedPaths.push(target.relativePath);
+            }
+            for (const agent of target.agents) {
+                if (!allAgents.includes(agent)) {
+                    allAgents.push(agent);
+                }
+            }
+        }
+        const result = {
+            status: "installed",
+            exitCode: 0,
+            agents: allAgents,
+            paths: installedPaths
+        };
+        if (skippedPaths.length > 0) {
+            return { ...result, skipped: skippedPaths };
+        }
+        return result;
+    }
+}
+export function defaultHomedir() {
+    return homedir();
+}

package/dist/application/interaction/action-executor.d.ts

@@ -0,0 +1,25 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { JourneyStep } from "../../domain/journey.js";
+import type { Bounds } from "../../domain/layout.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { Point } from "../../ports/android-cli.js";
+export interface ActionTarget {
+    point: Point;
+    bounds?: Bounds | undefined;
+}
+export type ActionExecutionResult = {
+    status: "succeeded";
+} | {
+    status: "failed";
+    code: Extract<FailureCode, "ACTION_FAILED">;
+    message: string;
+};
+export declare class ActionExecutor {
+    private readonly adb;
+    private readonly deviceSerial;
+    constructor(adb: AdbPort, deviceSerial: string);
+    execute(step: JourneyStep, target?: ActionTarget, signal?: AbortSignal): Promise<ActionExecutionResult>;
+    swipeBounds(bounds: Bounds, direction: Extract<JourneyStep, {
+        action: "swipe";
+    }>["direction"], distancePercent: number, durationMs: number, signal?: AbortSignal): Promise<ActionExecutionResult>;
+}

package/dist/application/interaction/action-executor.js

@@ -0,0 +1,103 @@
+function failed(message) {
+    return {
+        status: "failed",
+        code: "ACTION_FAILED",
+        message
+    };
+}
+function commandResult(result) {
+    if (result.exitCode !== 0
+        || result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined) {
+        return failed(result.stderr.trim() || "ADB Action failed");
+    }
+    return { status: "succeeded" };
+}
+function swipePoints(bounds, direction, distancePercent) {
+    const centerX = (bounds.left + bounds.right) / 2;
+    const centerY = (bounds.top + bounds.bottom) / 2;
+    const horizontalDistance = (bounds.right - bounds.left) * distancePercent;
+    const verticalDistance = (bounds.bottom - bounds.top) * distancePercent;
+    const points = {
+        up: {
+            from: { x: centerX, y: centerY + verticalDistance / 2 },
+            to: { x: centerX, y: centerY - verticalDistance / 2 }
+        },
+        down: {
+            from: { x: centerX, y: centerY - verticalDistance / 2 },
+            to: { x: centerX, y: centerY + verticalDistance / 2 }
+        },
+        left: {
+            from: { x: centerX + horizontalDistance / 2, y: centerY },
+            to: { x: centerX - horizontalDistance / 2, y: centerY }
+        },
+        right: {
+            from: { x: centerX - horizontalDistance / 2, y: centerY },
+            to: { x: centerX + horizontalDistance / 2, y: centerY }
+        }
+    };
+    const selected = points[direction];
+    return {
+        from: {
+            x: Math.round(selected.from.x),
+            y: Math.round(selected.from.y)
+        },
+        to: {
+            x: Math.round(selected.to.x),
+            y: Math.round(selected.to.y)
+        }
+    };
+}
+export class ActionExecutor {
+    adb;
+    deviceSerial;
+    constructor(adb, deviceSerial) {
+        this.adb = adb;
+        this.deviceSerial = deviceSerial;
+    }
+    async execute(step, target, signal) {
+        let result;
+        switch (step.action) {
+            case "click":
+                if (target === undefined) {
+                    return failed("click requires a resolved target");
+                }
+                result = await this.adb.tap(target.point, this.deviceSerial, signal);
+                break;
+            case "longClick":
+                if (target === undefined) {
+                    return failed("longClick requires a resolved target");
+                }
+                result = await this.adb.longClick(target.point, step.durationMs, this.deviceSerial, signal);
+                break;
+            case "inputText":
+                result = await this.adb.inputText(step.text, this.deviceSerial, signal);
+                break;
+            case "swipe": {
+                if (target === undefined) {
+                    return failed("swipe requires a resolved target");
+                }
+                if (target.bounds === undefined) {
+                    return failed("swipe requires target bounds from a scrollable element");
+                }
+                const points = swipePoints(target.bounds, step.direction, step.distancePercent);
+                result = await this.adb.swipe(points.from, points.to, step.durationMs, this.deviceSerial, signal);
+                break;
+            }
+            case "scrollTo":
+                return failed("scrollTo is not executed via ActionExecutor");
+            case "back":
+                result = await this.adb.back(this.deviceSerial, signal);
+                break;
+            case "wait":
+                return { status: "succeeded" };
+        }
+        return commandResult(result);
+    }
+    async swipeBounds(bounds, direction, distancePercent, durationMs, signal) {
+        const points = swipePoints(bounds, direction, distancePercent);
+        const result = await this.adb.swipe(points.from, points.to, durationMs, this.deviceSerial, signal);
+        return commandResult(result);
+    }
+}

package/dist/application/interaction/fallback-resolver.d.ts

@@ -0,0 +1,24 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { JourneyStep } from "../../domain/journey.js";
+import type { AndroidCliPort, Point } from "../../ports/android-cli.js";
+export type FallbackResolution = {
+    status: "unavailable";
+} | {
+    status: "found";
+    point: Point;
+    source: "annotatedLabel";
+    label: string;
+    annotatedScreenshotPath: string;
+} | {
+    status: "failed";
+    code: Extract<FailureCode, "LOCATOR_NOT_FOUND">;
+    message: string;
+    label?: string | undefined;
+    annotatedScreenshotPath?: string | undefined;
+};
+export declare class FallbackResolver {
+    private readonly androidCli;
+    private readonly deviceSerial;
+    constructor(androidCli: AndroidCliPort, deviceSerial: string);
+    resolve(step: JourneyStep, annotatedScreenshotPath: string, signal?: AbortSignal): Promise<FallbackResolution>;
+}

package/dist/application/interaction/fallback-resolver.js

@@ -0,0 +1,48 @@
+export class FallbackResolver {
+    androidCli;
+    deviceSerial;
+    constructor(androidCli, deviceSerial) {
+        this.androidCli = androidCli;
+        this.deviceSerial = deviceSerial;
+    }
+    async resolve(step, annotatedScreenshotPath, signal) {
+        if ((step.action !== "click" && step.action !== "longClick")
+            || step.fallback === undefined) {
+            return { status: "unavailable" };
+        }
+        const capture = await this.androidCli.captureScreen({
+            outputPath: annotatedScreenshotPath,
+            annotate: true,
+            deviceSerial: this.deviceSerial,
+            ...(signal === undefined ? {} : { signal })
+        });
+        if (capture.exitCode !== 0) {
+            return {
+                status: "failed",
+                code: "LOCATOR_NOT_FOUND",
+                message: capture.stderr.trim() || "Annotated screen capture failed"
+            };
+        }
+        try {
+            const point = await this.androidCli.resolveScreen(annotatedScreenshotPath, step.fallback.label, signal);
+            return {
+                status: "found",
+                point,
+                source: "annotatedLabel",
+                label: step.fallback.label,
+                annotatedScreenshotPath
+            };
+        }
+        catch (error) {
+            return {
+                status: "failed",
+                code: "LOCATOR_NOT_FOUND",
+                message: error instanceof Error
+                    ? error.message
+                    : "Annotated label resolution failed",
+                label: step.fallback.label,
+                annotatedScreenshotPath
+            };
+        }
+    }
+}

package/dist/application/interaction/scroll-to-executor.d.ts

@@ -0,0 +1,40 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { JourneyStep } from "../../domain/journey.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { IdleConfig, IdleWaiter } from "../wait/idle-waiter.js";
+import type { ActionExecutor } from "./action-executor.js";
+export type ScrollToExecutionResult = {
+    status: "found";
+    swipesUsed: number;
+} | {
+    status: "failed";
+    code: FailureCode;
+    message: string;
+    swipesUsed: number;
+    idle?: {
+        polls: number;
+        lastDiff: readonly unknown[];
+    };
+} | {
+    status: "cancelled";
+    swipesUsed: number;
+};
+export interface ScrollToExecutorOptions {
+    androidCli: Pick<AndroidCliPort, "layout">;
+    actionExecutor: Pick<ActionExecutor, "swipeBounds">;
+    idleWaiter: Pick<IdleWaiter, "waitUntilIdle">;
+    deviceSerial: string;
+    idle: IdleConfig;
+    readLayout?: (() => Promise<readonly LayoutElement[]>) | undefined;
+    beforeSwipe?: (() => Promise<readonly LayoutElement[]>) | undefined;
+    beforeMutation?: (() => Promise<void>) | undefined;
+    requireLiveContainerCapability?: boolean | undefined;
+}
+export declare class ScrollToExecutor {
+    private readonly options;
+    constructor(options: ScrollToExecutorOptions);
+    execute(step: Extract<JourneyStep, {
+        action: "scrollTo";
+    }>, signal?: AbortSignal, initialLayout?: readonly LayoutElement[]): Promise<ScrollToExecutionResult>;
+}