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

package/dist/cli/commands/generation/shared.js

@@ -0,0 +1,291 @@
+// Options, output, failure mapping, and configuration shared by the `generation` subcommands.
+import { resolve } from "node:path";
+import { z } from "zod";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../../domain/failure.js";
+import { GenerationFinalizationError } from "../../../application/generation/generation-finalizer.js";
+import { GenerationOperationError } from "../../../application/generation/generation-starter.js";
+import { ContextLoadError } from "../../../application/context/context-loader.js";
+import { TapHoundConfigSchema } from "../../../domain/config.js";
+import { verificationPhaseLabel } from "../../../domain/generation.js";
+import { ProposedStepSchema } from "../../../domain/proposed-step.js";
+import { RuntimeSnapshotSchema } from "../../../domain/runtime-snapshot.js";
+import { assertArtifactDirectory, CONFIG_PATH } from "../../../domain/workspace.js";
+import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
+import { GenerationPromptCancelledError } from "../../../ports/generation-prompt.js";
+import { contextLoadHint, errorMessage, writeJson, writeLine } from "../../output.js";
+import { prepareWorkspace } from "../../workspace-guard.js";
+import { canonicalProjectRoot } from "../../project-root.js";
+import { idlePolicyText } from "./session-commands.js";
+export const PlannerEnvelopeSchema = z.union([
+    z.strictObject({
+        version: z.literal(1),
+        proposal: ProposedStepSchema,
+        snapshot: RuntimeSnapshotSchema
+    }),
+    z.strictObject({
+        version: z.literal(1),
+        proposal: ProposedStepSchema,
+        snapshotRef: z.string().min(1)
+    })
+]);
+export const ManualActionSchema = z.enum([
+    "click",
+    "longClick",
+    "inputText",
+    "swipe",
+    "scrollTo",
+    "back",
+    "wait"
+]);
+export function writeFailure(dependencies, options, exitCode, code, error, outputOptions = {}) {
+    const output = {
+        status: outputOptions.status ?? "error",
+        exitCode,
+        ...(outputOptions.generationId === undefined
+            ? {}
+            : { generationId: outputOptions.generationId }),
+        ...(outputOptions.timing === undefined
+            ? {}
+            : { timing: outputOptions.timing }),
+        failure: {
+            code,
+            message: errorMessage(error),
+            ...(outputOptions.details !== undefined
+                ? { details: outputOptions.details }
+                : error instanceof GenerationFinalizationError
+                    && error.details !== undefined
+                    ? { details: error.details }
+                    : error instanceof GenerationOperationError
+                        && error.details !== undefined
+                        ? { details: error.details }
+                        : {}),
+            ...(outputOptions.hint === undefined ? {} : { hint: outputOptions.hint })
+        }
+    };
+    if (options.json === true) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stderr, output.failure.message);
+    }
+    dependencies.setExitCode(exitCode);
+}
+export async function loadConfig(dependencies, options) {
+    try {
+        const config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config)));
+        assertArtifactDirectory(options.project, config.artifactsDir);
+        await prepareWorkspace(dependencies, options.project);
+        return config;
+    }
+    catch (error) {
+        throw new GenerationOperationError("CONFIG_INVALID", errorMessage(error));
+    }
+}
+export async function generationConfig(dependencies, options) {
+    const projectRoot = await canonicalProjectRoot(dependencies.cwd(), options.project);
+    return {
+        projectRoot,
+        config: await loadConfig(dependencies, {
+            project: projectRoot,
+            config: options.config
+        })
+    };
+}
+export function tools(checks) {
+    return Object.fromEntries(checks.flatMap((check) => (check.status === "passed" && check.version !== undefined
+        ? [[check.name, check.version]]
+        : [])));
+}
+export function writeSuccess(dependencies, options, output, message) {
+    if (options.json === true) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stdout, message);
+    }
+    dependencies.setExitCode(0);
+}
+export function compactOutput(options) {
+    return "compact" in options && options.compact === true;
+}
+export function envelopeHint(options) {
+    if ("input" in options && options.input !== undefined) {
+        return "Planner envelope must be a strict object with exactly three top-level fields: version (1), proposal (object), and either snapshot (the full RuntimeSnapshot object) or snapshotRef (the snapshotRef string from the preceding observe output). Unknown or missing fields are rejected. See docs/agent-integration.md and assets/skills/taphound-journey-generator/schemas/proposed-step-envelope.json.";
+    }
+    return "TapHound rejected the JSON input. See docs/agent-integration.md for the command contract.";
+}
+export function generationStatusText(status) {
+    const verificationAttempt = status.verification.status === "running"
+        || status.verification.status === "passed"
+        || status.verification.status === "failed"
+        ? ("attemptId" in status.verification
+            ? status.verification.attemptId
+            : "none")
+        : "none";
+    const owner = status.verification.status === "running"
+        && status.verification.ownerPid !== undefined
+        ? `${String(status.verification.ownerPid)} (${status.recovery.ownerAlive === null
+            ? "unknown"
+            : status.recovery.ownerAlive ? "alive" : "not alive"})`
+        : "none";
+    const phase = status.verification.status === "running"
+        && status.verification.phase !== undefined
+        ? verificationPhaseLabel(status.verification.phase)
+        : null;
+    const inFlight = status.inFlight === null
+        ? "none"
+        : `step ${String(status.inFlight.stepIndex)}, attempt ${status.inFlight.attemptId}`;
+    const confirmation = status.pendingConfirmation === null
+        ? "none"
+        : `${status.pendingConfirmation.challengeId} (${status.pendingConfirmation.expired
+            ? "expired"
+            : status.pendingConfirmation.status}, expires ${status.pendingConfirmation.expiresAt})`;
+    const recovery = status.recovery.available
+        ? `${status.recovery.kind ?? "unknown"}; decision=${status.recovery.requiredDecision ?? "none"}; outcome=${status.recovery.attemptOutcome ?? "unknown"}`
+        : "unavailable";
+    return [
+        `Generation: ${status.generationId}`,
+        `State: ${status.state}`,
+        `Revision: ${String(status.revision)}`,
+        `Candidate steps: ${String(status.candidateStepCount)}`,
+        ...(status.idlePolicy === undefined
+            ? []
+            : [`Idle policy: ${idlePolicyText(status.idlePolicy)}`]),
+        `In flight: ${inFlight}`,
+        `Pending confirmation: ${confirmation}`,
+        `Verification: ${status.verification.status} (attempt ${verificationAttempt})`,
+        `Verification owner: ${owner}`,
+        ...(phase === null ? [] : [`Verification phase: ${phase}`]),
+        `Publication: ${status.publication.status}`,
+        `Recovery: ${recovery}`,
+        `Action may have executed: ${status.recovery.actionMayHaveExecuted ? "yes" : "no"}`
+    ].join("\n");
+}
+export function mappedFailure(dependencies, options, error) {
+    if (error instanceof z.ZodError || error instanceof SyntaxError) {
+        writeFailure(dependencies, options, 2, "CONTEXT_INVALID", error, {
+            hint: envelopeHint(options)
+        });
+        return;
+    }
+    if (error instanceof ContextLoadError) {
+        const hint = contextLoadHint(error);
+        writeFailure(dependencies, options, error.code === "CONTEXT_STALE" ? 1 : 2, error.code, error, hint === undefined ? {} : { hint });
+        return;
+    }
+    if (dependencies.signal?.aborted === true) {
+        writeFailure(dependencies, options, 1, "RECOVERY_REQUIRED", "Generation command was cancelled");
+        return;
+    }
+    if (error instanceof GenerationFinalizationError) {
+        writeFailure(dependencies, options, 1, error.code, error);
+        return;
+    }
+    if (error instanceof GenerationOperationError) {
+        const exitCode = error.code === "CONFIG_INVALID"
+            || error.code === "CONTEXT_INVALID"
+            || error.code === "BRIEF_INVALID"
+            || error.code === "FLOW_INVALID"
+            || error.code === "EXTERNAL_FLOW_NOT_FOUND"
+            || error.code === "EXTERNAL_FLOW_STALE"
+            || error.code === "EXTERNAL_LOCATOR_STRICTNESS"
+            ? 2
+            : error.code === "EXTERNAL_PACKAGE_MISMATCH"
+                || error.code === "EXTERNAL_ACTIVITY_MISMATCH"
+                || error.code === "EXTERNAL_STEP_FAILED"
+                ? 1
+                : 1;
+        writeFailure(dependencies, options, exitCode, error.code, error);
+        return;
+    }
+    if (error instanceof GenerationSessionStoreError) {
+        const exitCode = error.code === "INVALID_ID"
+            || error.code === "INVALID_SESSION"
+            || error.code === "INVALID_REVISION"
+            ? 2
+            : error.code === "IO_ERROR" || error.code === "LOCK_TIMEOUT"
+                ? 4
+                : 1;
+        writeFailure(dependencies, options, exitCode, error.code, error);
+        return;
+    }
+    if (error instanceof GenerationPromptCancelledError) {
+        writeFailure(dependencies, options, 1, "RECOVERY_REQUIRED", error);
+        return;
+    }
+    if (error instanceof Error
+        && error.message.includes("requires local TTY")) {
+        writeFailure(dependencies, options, 1, "RISK_CONFIRMATION_REQUIRED", error);
+        return;
+    }
+    const failureCode = failureCodeFromUnknown(error);
+    if (failureCode !== undefined) {
+        writeFailure(dependencies, options, exitCodeForFailure(failureCode), failureCode, error);
+        return;
+    }
+    writeFailure(dependencies, options, 4, "INTERNAL_ERROR", error);
+}
+export async function executeApproved(dependencies, options, runtime, input) {
+    const result = await runtime.executor.execute({
+        ...input,
+        ...(dependencies.signal === undefined
+            ? {}
+            : { signal: dependencies.signal })
+    });
+    if (result.status !== "succeeded") {
+        writeFailure(dependencies, options, 1, result.failure.code, result.failure.message, {
+            status: "recoveryRequired",
+            generationId: input.generationId,
+            ...(result.timing === undefined ? {} : { timing: result.timing }),
+            ...(result.failure.details === undefined
+                ? {}
+                : { details: result.failure.details })
+        });
+        return;
+    }
+    const session = await runtime.readSession(input.generationId);
+    writeSuccess(dependencies, options, {
+        status: "succeeded",
+        exitCode: 0,
+        generationId: input.generationId,
+        revision: session.revision,
+        stepIndex: session.candidateSteps.length - 1,
+        step: result.step,
+        source: input.source,
+        ...(result.timing === undefined ? {} : { timing: result.timing }),
+        ...(result.nextObservation === undefined
+            ? {}
+            : compactOutput(options)
+                ? {
+                    nextBinding: result.nextObservation.binding,
+                    nextSnapshotRef: result.nextObservation.snapshotRef
+                }
+                : {
+                    nextBinding: result.nextObservation.binding,
+                    nextSnapshot: result.nextObservation.snapshot,
+                    nextSnapshotRef: result.nextObservation.snapshotRef
+                }),
+        ...(result.nextObservationFailure === undefined
+            ? {}
+            : { nextObservationFailure: result.nextObservationFailure })
+    }, `Generation step ${String(session.candidateSteps.length - 1)} succeeded`);
+}
+export function requireRuntime(dependencies, projectRoot, config) {
+    if (dependencies.generationRuntime === undefined) {
+        throw new Error("Generation command runtime is unavailable");
+    }
+    return dependencies.generationRuntime({
+        projectRoot,
+        config
+    });
+}
+export async function assertRuntimeConfig(runtime, generationId) {
+    await runtime.assertConfigIdentity(generationId);
+}
+export function addCommonOptions(command, dependencies) {
+    return command
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .requiredOption("--session <id>", "Generation session id")
+        .option("--json", "Emit one machine-readable JSON value");
+}

package/dist/cli/commands/generation/step-commands.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+import { type BridgeScenario } from "../../../domain/journey.js";
+import type { CliDependencies } from "../../dependencies.js";
+export declare function createStepCommand(dependencies: CliDependencies): Command;
+export declare function createConfirmCommand(dependencies: CliDependencies): Command;
+export declare function createManualCommand(dependencies: CliDependencies): Command;
+export declare function resolveBridgeDescription(scenario: BridgeScenario, description: string | undefined): string;
+export declare function createBridgeCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/generation/step-commands.js

@@ -0,0 +1,315 @@
+// `generation` subcommands that bind and execute steps: step, confirm, manual, and bridge.
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { z } from "zod";
+import { GenerationOperationError } from "../../../application/generation/generation-starter.js";
+import { GenerationSessionIdSchema } from "../../../domain/generation.js";
+import { BridgeScenarioSchema } from "../../../domain/journey.js";
+import { LocatorSchema } from "../../../domain/layout.js";
+import { ManualActionSchema, PlannerEnvelopeSchema, addCommonOptions, assertRuntimeConfig, executeApproved, generationConfig, mappedFailure, requireRuntime, tools, writeFailure, writeSuccess } from "./shared.js";
+export function createStepCommand(dependencies) {
+    return addCommonOptions(new Command("step")
+        .description("Accept and execute one strict planner proposal")
+        .option("--compact", "Return authoritative nextSnapshotRef instead of the full next snapshot")
+        .option("--input <path>", "Strict proposal envelope path")
+        .option("--replace <index>", "Truncate candidate steps at <index>, replay the stored prefix, and bind a fresh snapshot"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            if (options.replace !== undefined) {
+                if (options.input !== undefined) {
+                    throw new GenerationOperationError("CONFIG_INVALID", "generation step accepts either --input or --replace, not both");
+                }
+                const stepIndex = z.coerce.number().int().nonnegative().parse(options.replace);
+                const session = await runtime.readSession(generationId);
+                const doctor = await dependencies.doctor.run({
+                    packageName: config.run.packageName,
+                    skipPermissionProbe: true,
+                    requestedDevice: session.target.deviceSerial,
+                    ...(config.ui?.backend === undefined
+                        ? {}
+                        : { requestedUiBackend: config.ui.backend }),
+                    ...(dependencies.signal === undefined
+                        ? {}
+                        : { signal: dependencies.signal })
+                });
+                if (doctor.status === "failed") {
+                    writeFailure(dependencies, options, 3, doctor.failureCode ?? "ENVIRONMENT_MISSING_TOOL", doctor.checks.find((check) => check.status === "failed")?.message
+                        ?? "TapHound environment preflight failed");
+                    return;
+                }
+                const result = await runtime.replace({
+                    generationId,
+                    stepIndex,
+                    projectRoot: projectRoot,
+                    config,
+                    toolVersions: tools(doctor.checks),
+                    manualReplay: process.stdin.isTTY,
+                    ...(dependencies.signal === undefined
+                        ? {}
+                        : { signal: dependencies.signal })
+                });
+                writeSuccess(dependencies, options, {
+                    status: "replaced",
+                    exitCode: 0,
+                    stepIndex: result.stepIndex,
+                    remainingStepCount: result.remainingStepCount,
+                    truncatedStepCount: result.truncatedStepCount,
+                    ...result.observation.binding,
+                    snapshotRef: result.observation.snapshotRef,
+                    ...(options.compact === true
+                        ? {}
+                        : { snapshot: result.observation.snapshot })
+                }, `Generation truncated to ${String(result.remainingStepCount)} step(s) at index ${String(result.stepIndex)} and re-observed`);
+                return;
+            }
+            if (options.input === undefined) {
+                throw new GenerationOperationError("CONFIG_INVALID", "generation step requires either --input <envelope> or --replace <index>");
+            }
+            const envelope = PlannerEnvelopeSchema.parse(await dependencies.readJson(resolve(projectRoot, options.input)));
+            const confirmation = await runtime.confirmation.request({
+                generationId,
+                proposal: envelope.proposal,
+                ...("snapshot" in envelope
+                    ? { snapshot: envelope.snapshot }
+                    : { snapshotRef: envelope.snapshotRef }),
+                source: "planner"
+            });
+            if (confirmation.status === "confirmationRequired") {
+                writeSuccess(dependencies, options, {
+                    status: "confirmationRequired",
+                    exitCode: 0,
+                    generationId,
+                    revision: confirmation.revision,
+                    challenge: confirmation.challenge
+                }, `Confirmation required: ${confirmation.challenge.challengeId}`);
+                return;
+            }
+            await executeApproved(dependencies, options, runtime, {
+                generationId,
+                proposal: confirmation.proposal,
+                snapshot: confirmation.snapshot,
+                source: "planner"
+            });
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}
+export function createConfirmCommand(dependencies) {
+    return addCommonOptions(new Command("confirm")
+        .description("Approve and execute Core-owned challenge evidence")
+        .option("--compact", "Return authoritative nextSnapshotRef instead of the full next snapshot")
+        .option("--decision <decision>", "Delegated non-TTY decision after explicit human review: approve or decline")
+        .requiredOption("--challenge <id>", "Core confirmation challenge id"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const challengeId = GenerationSessionIdSchema.parse(options.challenge);
+            if (options.decision !== undefined
+                && options.decision !== "approve"
+                && options.decision !== "decline") {
+                throw new GenerationOperationError("CONFIG_INVALID", "generation confirm --decision must be approve or decline");
+            }
+            const decision = options.decision;
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const approved = await runtime.confirmation.confirmStored({
+                generationId,
+                challengeId,
+                ...(decision === undefined ? {} : { decision }),
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            if (approved.status === "declined") {
+                writeSuccess(dependencies, options, {
+                    status: "declined",
+                    exitCode: 0,
+                    generationId,
+                    challengeId
+                }, `Generation confirmation declined: ${challengeId}`);
+                return;
+            }
+            await executeApproved(dependencies, options, runtime, {
+                generationId,
+                proposal: approved.proposal,
+                snapshot: approved.snapshot,
+                source: approved.source
+            });
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}
+export function createManualCommand(dependencies) {
+    return addCommonOptions(new Command("manual")
+        .description("Interactively build, execute, and record one manual Journey step")
+        .option("--compact", "Return authoritative nextSnapshotRef instead of the full next snapshot")
+        .requiredOption("--action <action>", "Journey action to execute through deterministic Core controls"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const action = ManualActionSchema.parse(options.action);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const existing = await runtime.confirmation.findPendingManual({
+                generationId,
+                action
+            });
+            if (existing !== null) {
+                writeSuccess(dependencies, options, {
+                    status: "confirmationRequired",
+                    exitCode: 0,
+                    generationId,
+                    revision: existing.revision,
+                    challenge: existing.challenge
+                }, `Confirmation required: ${existing.challenge.challengeId}`);
+                return;
+            }
+            const observation = await runtime.observer.observe({
+                generationId,
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            const confirmation = await runtime.confirmation.requestManual({
+                generationId,
+                snapshot: observation.snapshot,
+                manual: {
+                    action,
+                    binding: observation.binding,
+                    before: observation.snapshot.activity,
+                    layout: observation.snapshot.layout
+                },
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            if (confirmation.status === "confirmationRequired") {
+                writeSuccess(dependencies, options, {
+                    status: "confirmationRequired",
+                    exitCode: 0,
+                    generationId,
+                    revision: confirmation.revision,
+                    challenge: confirmation.challenge
+                }, `Confirmation required: ${confirmation.challenge.challengeId}`);
+                return;
+            }
+            await executeApproved(dependencies, options, runtime, {
+                generationId,
+                proposal: confirmation.proposal,
+                snapshot: observation.snapshot,
+                source: "manualOverride"
+            });
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}
+export function resolveBridgeDescription(scenario, description) {
+    if (description !== undefined) {
+        return z.string().trim().min(1).parse(description);
+    }
+    switch (scenario) {
+        case "photoCapture":
+            return "Capture photo via system camera";
+        case "pickImage":
+            return "Pick image via system picker";
+        case "pickFile":
+            return "Pick file via system picker";
+        case "custom":
+            throw new GenerationOperationError("CONTEXT_INVALID", "Bridge scenario 'custom' requires --description");
+    }
+}
+export function createBridgeCommand(dependencies) {
+    return addCommonOptions(new Command("bridge")
+        .description("Execute a cross-application bridge step through Core controls")
+        .option("--compact", "Return authoritative nextSnapshotRef instead of the full next snapshot")
+        .requiredOption("--scenario <scenario>", "Bridge scenario: photoCapture, pickImage, pickFile, or custom")
+        .requiredOption("--trigger-locator <json>", "JSON locator for the trigger element")
+        .option("--description <text>", "Bridge description (required for custom scenario)")
+        .option("--return-timeout-ms <ms>", "Maximum time to wait for return to the target app in milliseconds", "60000")
+        .option("--flow <name>", "External flow name for deterministic bridge replay (requires --external-flow at session start)")
+        .option("--escape-timeout-ms <ms>", "Maximum time to wait for package escape after trigger click in milliseconds"), dependencies).action(async (options) => {
+        try {
+            const generationId = GenerationSessionIdSchema.parse(options.session);
+            const scenario = BridgeScenarioSchema.parse(options.scenario);
+            const triggerLocator = LocatorSchema.parse(JSON.parse(options.triggerLocator));
+            const returnTimeoutMs = z.number().int().positive().parse(Number(options.returnTimeoutMs));
+            const escapeTimeoutMs = options.escapeTimeoutMs === undefined
+                ? undefined
+                : z.number().int().positive().parse(Number(options.escapeTimeoutMs));
+            const description = resolveBridgeDescription(scenario, options.description);
+            const { projectRoot, config } = await generationConfig(dependencies, options);
+            const runtime = requireRuntime(dependencies, projectRoot, config);
+            await assertRuntimeConfig(runtime, generationId);
+            const session = await runtime.readSession(generationId);
+            if (session.pendingConfirmation?.status === "pending") {
+                writeSuccess(dependencies, options, {
+                    status: "confirmationRequired",
+                    exitCode: 0,
+                    generationId,
+                    revision: session.revision,
+                    challenge: session.pendingConfirmation
+                }, `Confirmation required: ${session.pendingConfirmation.challengeId}`);
+                return;
+            }
+            let flowName;
+            if (options.flow !== undefined) {
+                flowName = z.string().trim().min(1).parse(options.flow);
+                const binding = session.externalFlows.find((entry) => entry.name === flowName);
+                if (binding === undefined) {
+                    throw new GenerationOperationError("EXTERNAL_FLOW_NOT_FOUND", `External Flow "${flowName}" is not bound to generation session ${generationId}`);
+                }
+            }
+            const observation = await runtime.observer.observe({
+                generationId,
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            const proposal = {
+                action: "bridge",
+                scenario,
+                description,
+                triggerLocator,
+                returnTimeoutMs,
+                ...(flowName === undefined ? {} : { flow: flowName }),
+                ...(escapeTimeoutMs === undefined ? {} : { escapeTimeoutMs }),
+                binding: observation.binding,
+                activity: { before: observation.snapshot.activity }
+            };
+            const confirmation = await runtime.confirmation.request({
+                generationId,
+                proposal,
+                snapshot: observation.snapshot,
+                source: "manualOverride"
+            });
+            if (confirmation.status === "confirmationRequired") {
+                writeSuccess(dependencies, options, {
+                    status: "confirmationRequired",
+                    exitCode: 0,
+                    generationId,
+                    revision: confirmation.revision,
+                    challenge: confirmation.challenge
+                }, `Confirmation required: ${confirmation.challenge.challengeId}`);
+                return;
+            }
+            await executeApproved(dependencies, options, runtime, {
+                generationId,
+                proposal: confirmation.proposal,
+                snapshot: observation.snapshot,
+                source: "manualOverride"
+            });
+        }
+        catch (error) {
+            mappedFailure(dependencies, options, error);
+        }
+    });
+}