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

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

@@ -1,26 +1,34 @@
 import { GenerationSessionSchema } from "../../domain/generation.js";
 import { ProposedStepSchema } from "../../domain/proposed-step.js";
 import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { locatorEvidenceForElement } from "../../domain/locator-evidence.js";
+import { resolveActionTarget } from "../interaction/action-target.js";
 import { resolveLocator } from "../locator/locator-resolver.js";
+import { hasExactlyOneEnabledFocusedElement } from "./focused-input.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);
+/**
+ * Report the same Locator verdict Replay would: an unknown or ambiguous
+ * target is a Locator failure, not an unsupported action.
+ */
+function rejectResolution(resolution) {
+    if (resolution.code === "LOCATOR_NOT_FOUND"
+        || resolution.code === "LOCATOR_AMBIGUOUS") {
+        throw new GenerationOperationError(resolution.code, resolution.message);
     }
-    if (!capability(resolution.element)) {
-        rejectCapability(`Layout target lacks required ${capabilityName} capability`);
+    rejectCapability(resolution.message);
+}
+/**
+ * Reject a proposal whose target Replay could not act on, using the action
+ * capability rules both engines share.
+ */
+function requireActionTarget(snapshot, action, locator) {
+    const resolved = resolveActionTarget(snapshot.layout, action, locator, undefined);
+    if (resolved.status !== "found") {
+        rejectResolution(resolved);
     }
-    return resolution.element;
 }
 function validateBinding(session, snapshot, proposal) {
     const binding = proposal.binding;
@@ -47,33 +55,90 @@ function validateBinding(session, snapshot, proposal) {
     }
 }
 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");
+    if (proposal.action === "click"
+        || proposal.action === "longClick"
+        || proposal.action === "swipe") {
+        requireActionTarget(snapshot, proposal.action, proposal.locator);
         return;
     }
     if (proposal.action === "scrollTo") {
-        requireUniqueTarget(snapshot, proposal.container, (element) => element.scrollable === true
-            && element.bounds !== undefined, "scrollable container bounds");
+        requireActionTarget(snapshot, "swipe", proposal.container);
         const target = resolveLocator(snapshot.layout, proposal.locator, { requireEnabled: false });
         if (target.status === "failed" && target.code === "LOCATOR_AMBIGUOUS") {
-            rejectCapability(`scrollTo target is ambiguous: ${target.message}`);
+            throw new GenerationOperationError("LOCATOR_AMBIGUOUS", `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) {
+        if (!hasExactlyOneEnabledFocusedElement(snapshot.layout)) {
             rejectCapability("inputText requires exactly one enabled focused visible Layout element");
         }
+        return;
+    }
+    if (proposal.action === "bridge") {
+        requireActionTarget(snapshot, "click", proposal.triggerLocator);
+        return;
+    }
+}
+function bindLocatorEvidence(layout, locator) {
+    if (locator.index === undefined) {
+        return locator;
+    }
+    const resolution = resolveLocator(layout, locator, {
+        requireEnabled: false
+    });
+    // Evidence binds the identity-matched entry before capability promotion.
+    return resolution.status === "found"
+        ? {
+            ...locator,
+            evidence: locatorEvidenceForElement(resolution.element)
+        }
+        : locator;
+}
+function bindProposalEvidence(snapshot, proposal) {
+    const expect = proposal.expect?.type === "element"
+        ? {
+            ...proposal.expect,
+            locator: bindLocatorEvidence(snapshot.layout, proposal.expect.locator)
+        }
+        : proposal.expect;
+    const common = expect === undefined ? {} : { expect };
+    switch (proposal.action) {
+        case "click":
+        case "longClick":
+        case "swipe":
+            return ProposedStepSchema.parse({
+                ...proposal,
+                ...common,
+                locator: bindLocatorEvidence(snapshot.layout, proposal.locator)
+            });
+        case "scrollTo":
+            return ProposedStepSchema.parse({
+                ...proposal,
+                ...common,
+                locator: bindLocatorEvidence(snapshot.layout, proposal.locator),
+                container: bindLocatorEvidence(snapshot.layout, proposal.container)
+            });
+        case "inputText":
+        case "back":
+        case "wait":
+            return ProposedStepSchema.parse({ ...proposal, ...common });
+        case "bridge":
+            return ProposedStepSchema.parse({
+                ...proposal,
+                ...common,
+                triggerLocator: bindLocatorEvidence(snapshot.layout, proposal.triggerLocator)
+            });
+    }
+}
+function validateWindowHierarchy(snapshot) {
+    if (snapshot.windowHierarchy?.status === "incomplete") {
+        throw new GenerationOperationError("WINDOW_HIERARCHY_INCOMPLETE", snapshot.windowHierarchy.diagnostics
+            .map((diagnostic) => diagnostic.message)
+            .join("; "), {
+            diagnostics: snapshot.windowHierarchy.diagnostics,
+            recovery: snapshot.windowHierarchy.recovery
+        });
     }
 }
 export class ProposedStepValidator {
@@ -82,7 +147,8 @@ export class ProposedStepValidator {
         const snapshot = RuntimeSnapshotSchema.parse(input.snapshot);
         const proposal = ProposedStepSchema.parse(input.proposal);
         validateBinding(session, snapshot, proposal);
+        validateWindowHierarchy(snapshot);
         validateAction(snapshot, proposal);
-        return proposal;
+        return bindProposalEvidence(snapshot, proposal);
     }
 }

package/dist/application/generation/replay-policy-loader.d.ts

@@ -0,0 +1,16 @@
+import type { IdlePolicy } from "../../domain/config.js";
+import type { Journey } from "../../domain/journey.js";
+export interface PublishedReplayPolicy {
+    generatedReplayPolicy: boolean;
+    requireFocusedInput: boolean;
+    idle: IdlePolicy;
+}
+export declare class ReplayPolicyUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare function loadPublishedReplayPolicy(input: {
+    readJson: (path: string) => Promise<unknown>;
+    projectRoot: string;
+    journeyPath: string;
+    journey: Journey;
+}): Promise<PublishedReplayPolicy>;

package/dist/application/generation/replay-policy-loader.js

@@ -0,0 +1,29 @@
+import { resolve } from "node:path";
+import { GenerationMetaSchema } from "../../domain/generation.js";
+import { hashJourney } from "../../domain/report.js";
+import { generationMetaOutputPath } from "./generation-publisher.js";
+export class ReplayPolicyUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReplayPolicyUnavailableError";
+    }
+}
+export async function loadPublishedReplayPolicy(input) {
+    const metaPath = generationMetaOutputPath(input.journeyPath);
+    try {
+        const meta = GenerationMetaSchema.parse(await input.readJson(metaPath));
+        if (resolve(input.projectRoot, meta.journeyPath) !== resolve(input.journeyPath)
+            || meta.journeySha256 !== hashJourney(input.journey)
+            || !meta.replayPolicy.generatedReplayPolicy
+            || !meta.replayPolicy.requireFocusedInput) {
+            throw new ReplayPolicyUnavailableError("Generation meta does not bind this Journey and its strict Replay policy");
+        }
+        return meta.replayPolicy;
+    }
+    catch (error) {
+        if (error instanceof ReplayPolicyUnavailableError) {
+            throw error;
+        }
+        throw new ReplayPolicyUnavailableError(`Cannot load a valid strict Replay policy from ${metaPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

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

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

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

@@ -1,14 +1,129 @@
+import { ConfirmationReasonSchema } from "../../domain/generation.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+const SEMANTIC_TERMS = {
+    destructive: [
+        "delete", "remove", "erase", "clear", "unsubscribe", "unfollow",
+        "leave", "block", "report"
+    ],
+    // hardCommit: irreversible or financial actions that still require
+    // confirmation even when the action is otherwise allowed.
+    hardCommit: [
+        "send", "pay", "purchase", "buy", "order", "transfer", "donate",
+        "book", "reserve", "subscribe", "submit", "confirm"
+    ],
+    // softCommit: reversible content or navigation actions (e.g. Create Group
+    // is navigation, Save Draft is reversible). These default to safe so that
+    // common UI flows are not blocked by semantic keyword matches. A project
+    // can still force confirmation via confirmationRequiredActions.
+    softCommit: [
+        "forward", "share", "publish", "post", "upload", "invite",
+        "save", "create"
+    ],
+    account: [
+        "login", "logout", "signin", "signout", "register"
+    ]
+};
+const NON_COMMIT_CONTEXT = new Set(["search", "filter", "query"]);
+function tokens(value) {
+    return value
+        .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((token) => token.length > 0);
+}
+function semanticStrings(proposal, snapshot) {
+    if (proposal.action !== "click"
+        && proposal.action !== "longClick") {
+        return [];
+    }
+    const locator = proposal.locator;
+    const locatorValues = [
+        locator.resourceId,
+        locator.text,
+        locator.contentDescription
+    ].filter((value) => value !== undefined);
+    const resolution = resolveLocator(snapshot.layout, locator, {
+        requireEnabled: false
+    });
+    const element = resolution.status === "found"
+        ? resolution.element
+        : undefined;
+    return [
+        ...locatorValues,
+        ...(element === undefined
+            ? []
+            : [
+                element.resourceId,
+                element.text,
+                element.contentDescription
+            ].filter((value) => value !== undefined))
+    ];
+}
+function semanticReason(category, matchedTerm, action) {
+    return ConfirmationReasonSchema.parse({
+        rule: "semanticSideEffect",
+        category,
+        matchedTerm,
+        message: `${action} targets a ${category} control (matched term "${matchedTerm}")`
+    });
+}
+function semanticSideEffect(proposal, snapshot) {
+    const allTokens = semanticStrings(proposal, snapshot).flatMap(tokens);
+    for (const category of ["destructive", "account"]) {
+        const terms = SEMANTIC_TERMS[category];
+        const matchedTerm = terms.find((term) => allTokens.includes(term));
+        if (matchedTerm !== undefined) {
+            return semanticReason(category, matchedTerm, proposal.action);
+        }
+    }
+    const matchedTerm = SEMANTIC_TERMS.hardCommit.find((term) => allTokens.includes(term));
+    if (matchedTerm === "submit"
+        && allTokens.some((token) => NON_COMMIT_CONTEXT.has(token))) {
+        return undefined;
+    }
+    if (matchedTerm !== undefined) {
+        return semanticReason("hardCommit", matchedTerm, proposal.action);
+    }
+    return undefined;
+}
 export class RiskEvaluator {
-    evaluate(action, policy) {
+    evaluate(actionOrProposal, policy, snapshot) {
+        const action = typeof actionOrProposal === "string"
+            ? actionOrProposal
+            : actionOrProposal.action;
+        if (action === "bridge") {
+            return { effectiveRisk: "safe" };
+        }
         if (policy.forbiddenActions.includes(action)) {
             return { effectiveRisk: "forbidden" };
         }
         if (policy.confirmationRequiredActions.includes(action)) {
-            return { effectiveRisk: "confirmationRequired" };
+            return {
+                effectiveRisk: "confirmationRequired",
+                reason: ConfirmationReasonSchema.parse({
+                    rule: "policyActionRequiresConfirmation",
+                    message: `${action} is listed in confirmationRequiredActions`
+                })
+            };
         }
         if (policy.allowedActions.includes(action)) {
+            if (typeof actionOrProposal !== "string" && snapshot !== undefined) {
+                const semantic = semanticSideEffect(actionOrProposal, snapshot);
+                if (semantic !== undefined) {
+                    return {
+                        effectiveRisk: "confirmationRequired",
+                        reason: semantic
+                    };
+                }
+            }
             return { effectiveRisk: "safe" };
         }
-        return { effectiveRisk: "confirmationRequired" };
+        return {
+            effectiveRisk: "confirmationRequired",
+            reason: ConfirmationReasonSchema.parse({
+                rule: "actionNotAllowlisted",
+                message: `${action} is not listed in allowedActions`
+            })
+        };
     }
 }

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

@@ -1,39 +1,71 @@
+import { z } from "zod";
 import { type PendingConfirmation } from "../../domain/generation.js";
+import { LayoutElementSchema } from "../../domain/layout.js";
 import { type ProposalBinding } from "../../domain/proposed-step.js";
 import { type RuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { assessWindowHierarchy } from "../../domain/window-hierarchy.js";
 import type { AdbPort } from "../../ports/adb.js";
-import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { RuntimeSessionPortViewsFactory } from "../../ports/runtime-session-ports.js";
+import type { UiSnapshot, UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { UiStabilityProbe } from "../../ports/ui-stability.js";
+import type { IdleConfig, IdleResult } from "../wait/idle-waiter.js";
 import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
 export type RuntimeObservationBinding = ProposalBinding;
 export interface RuntimeObservation {
     binding: RuntimeObservationBinding;
     snapshot: RuntimeSnapshot;
     snapshotHash: string;
+    snapshotRef: string;
 }
 export interface RuntimeObserveInput {
     generationId: string;
+    idle?: IdleConfig | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface CollectedRuntimeState {
+    foregroundPackageName: string;
+    activity: string;
+    pid: number | null;
+    layout: readonly z.infer<typeof LayoutElementSchema>[];
+    windowHierarchy: ReturnType<typeof assessWindowHierarchy>;
+    uiSnapshot: Pick<UiSnapshot, "observationId" | "capturedAt" | "durationMs" | "backend" | "viewport">;
+}
+export interface CollectedRuntimeObserveInput {
+    generationId: string;
+    runtime: CollectedRuntimeState;
     signal?: AbortSignal | undefined;
 }
 export interface RuntimeObserverDependencies {
-    store: Pick<GenerationSessionStore, "read" | "writeEvidence" | "produceEvidence" | "commitSnapshot">;
-    adb: Pick<AdbPort, "foregroundComponent" | "appProcesses">;
-    androidCli: Pick<AndroidCliPort, "layout" | "captureScreen">;
+    store: Pick<GenerationSessionStore, "read" | "writeEvidence" | "produceEvidence" | "commitSnapshot" | "evidenceReference">;
+    sessions: RuntimeSessionOpener;
+    sessionPorts: RuntimeSessionPortViewsFactory;
+    waitUntilIdle?: (deviceSerial: string, config: IdleConfig, signal: AbortSignal | undefined, packageName: string, stability: UiStabilityProbe, 
+    /** The observed session's device, for idle device profiles. */
+    device: Pick<AdbPort, "deviceIdentity">) => Promise<IdleResult>;
     now: () => Date;
     createAttemptId: () => string;
+    uiCacheEnabled?: boolean | undefined;
+    uiSnapshotTimeoutMs?: number | undefined;
 }
 export interface SnapshotReobservationGuardDependencies {
     store: Pick<GenerationSessionStore, "read">;
-    adb: Pick<AdbPort, "foregroundComponent" | "appProcesses">;
-    androidCli: Pick<AndroidCliPort, "layout">;
+    adb: Pick<AdbPort, "foregroundComponent" | "appProcesses" | "windowTopology">;
+    uiSnapshotProvider: UiSnapshotProvider;
     now: () => Date;
+    uiSnapshotTimeoutMs?: number | undefined;
 }
 export declare class RuntimeObserver {
     private readonly dependencies;
     constructor(dependencies: RuntimeObserverDependencies);
     readonly observe: (input: RuntimeObserveInput) => Promise<RuntimeObservation>;
+    readonly observeCollected: (input: CollectedRuntimeObserveInput) => Promise<RuntimeObservation>;
+    private commit;
 }
 export declare class SnapshotReobservationGuard {
     private readonly dependencies;
     constructor(dependencies: SnapshotReobservationGuardDependencies);
-    readonly assertFresh: (input: ProposalBinding, signal?: AbortSignal, approvedConfirmation?: PendingConfirmation) => Promise<RuntimeSnapshot>;
+    readonly assertFresh: (input: ProposalBinding, signal?: AbortSignal, approvedConfirmation?: PendingConfirmation, tolerance?: {
+        layoutChangeFrom?: RuntimeSnapshot | undefined;
+    }) => Promise<RuntimeSnapshot>;
 }