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

package/dist/ports/anchor-resolver.d.ts

@@ -0,0 +1,30 @@
+import type { DisplayViewport } from "../domain/geometry.js";
+import type { LayoutElement } from "../domain/layout.js";
+import type { AnchorCandidateKind } from "../domain/knowledge.js";
+export interface AnchorResolution {
+    status: "found" | "notFound" | "ambiguous" | "visualOnly";
+    point?: {
+        x: number;
+        y: number;
+    };
+    bounds?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    element?: LayoutElement;
+    message?: string;
+    resolvedBy?: {
+        kind: AnchorCandidateKind;
+        confidence: "primary" | "fallback";
+    };
+}
+export interface AnchorResolverPort {
+    resolve: (input: {
+        anchorId: string;
+        layout: readonly LayoutElement[];
+        viewport?: DisplayViewport | undefined;
+        signal?: AbortSignal | undefined;
+    }) => Promise<AnchorResolution>;
+}

package/dist/ports/anchor-resolver.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/annotated-screen-resolver.d.ts

@@ -0,0 +1,4 @@
+import type { Point } from "../domain/geometry.js";
+export interface AnnotatedScreenResolverPort {
+    resolve: (screenshotPath: string, label: string, signal?: AbortSignal) => Promise<Point>;
+}

package/dist/ports/annotated-screen-resolver.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/camera-probe.d.ts

@@ -0,0 +1,23 @@
+import type { FailureCode } from "../domain/failure.js";
+export type CameraProbeFailureCode = Extract<FailureCode, `ALIGN_CAMERA_${string}` | `ALIGN_SHUTTER_${string}` | `ALIGN_CONFIRM_${string}`>;
+export declare class CameraProbeError extends Error {
+    readonly code: CameraProbeFailureCode;
+    readonly name = "CameraProbeError";
+    constructor(code: CameraProbeFailureCode, message: string);
+}
+export interface CameraProbeResult {
+    packageName: string;
+    activityName: string;
+    shutterResourceId: string;
+    shutterContentDescription?: string | undefined;
+    confirmResourceId?: string | undefined;
+    confirmContentDescription?: string | undefined;
+    confirmActivityName?: string | undefined;
+}
+export interface CameraProbeInput {
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+}
+export interface CameraProbePort {
+    probe: (input: CameraProbeInput) => Promise<CameraProbeResult>;
+}

package/dist/ports/camera-probe.js

@@ -0,0 +1,8 @@
+export class CameraProbeError extends Error {
+    code;
+    name = "CameraProbeError";
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}

package/dist/ports/context-document-writer.d.ts

@@ -0,0 +1,24 @@
+export type ContextDocumentWrite = {
+    status: "written";
+    sha256: string;
+} | {
+    status: "escape";
+} | {
+    status: "unwritable";
+    message: string;
+};
+export interface ContextDocumentBatchEntry {
+    readonly relativePath: string;
+    readonly document: unknown;
+}
+export interface ContextDocumentWriter {
+    writeContextDocument: (input: {
+        projectRoot: string;
+        relativePath: string;
+        document: unknown;
+    }) => Promise<ContextDocumentWrite>;
+    writeContextDocumentBatch?: (input: {
+        projectRoot: string;
+        documents: readonly ContextDocumentBatchEntry[];
+    }) => Promise<readonly ContextDocumentWrite[]>;
+}

package/dist/ports/context-document-writer.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/detached-process-launcher.d.ts

@@ -0,0 +1,12 @@
+export interface DetachedProcessInput {
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    stdoutPath: string;
+    stderrPath: string;
+}
+export interface DetachedProcessLauncher {
+    launch: (input: DetachedProcessInput) => Promise<{
+        pid: number;
+    }>;
+}

package/dist/ports/detached-process-launcher.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/diagnostics.d.ts

@@ -0,0 +1,15 @@
+import type { CommandEvent } from "../domain/diagnostics.js";
+import type { UiBackendId } from "../domain/ui-backend.js";
+/** Receives UI backend timing facts; never error text. */
+export interface UiCaptureObserver {
+    captured: (backend: UiBackendId, durationMs: number, error?: unknown) => void;
+    sessionRecovered: (backend: UiBackendId, succeeded: boolean) => void;
+}
+/** The local, Git-ignored diagnostics journal of one host project. */
+export interface DiagnosticsJournal {
+    append: (projectRoot: string, event: CommandEvent) => Promise<void>;
+    /** Raw journal lines, oldest first, including the rotated file. */
+    readLines: (projectRoot: string) => Promise<readonly string[]>;
+    /** A per-project random salt that never leaves the host. */
+    salt: (projectRoot: string) => Promise<Buffer>;
+}

package/dist/ports/diagnostics.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/external-flow-registry.d.ts

@@ -0,0 +1,37 @@
+import type { ExternalFlow } from "../domain/external-flow.js";
+export interface ExternalFlowRecord {
+    bytes: Buffer;
+    flow: ExternalFlow;
+    source: "builtin" | "project";
+    path: string;
+}
+export interface ExternalFlowCatalogEntry {
+    name: string;
+    source: "builtin" | "project";
+    path: string;
+    status: "valid" | "invalid";
+    escapedPackageName?: string | undefined;
+    stepCount?: number | undefined;
+    failure?: {
+        code: string;
+        message: string;
+    } | undefined;
+}
+export interface WriteExternalFlowInput {
+    projectRoot: string;
+    name: string;
+    flow: ExternalFlow;
+    force?: boolean | undefined;
+}
+export interface WriteExternalFlowResult {
+    path: string;
+    overwritten: boolean;
+}
+export interface ExternalFlowRegistry {
+    read: (input: {
+        projectRoot: string;
+        name: string;
+    }) => Promise<ExternalFlowRecord>;
+    list: (projectRoot: string) => Promise<readonly ExternalFlowCatalogEntry[]>;
+    write: (input: WriteExternalFlowInput) => Promise<WriteExternalFlowResult>;
+}

package/dist/ports/external-flow-registry.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/generation-prompt.d.ts

@@ -2,8 +2,9 @@ import type { PendingConfirmation } from "../domain/generation.js";
 import type { Expectation } from "../domain/journey.js";
 import type { LayoutElement } from "../domain/layout.js";
 import type { ProposalBinding, ProposedStep } from "../domain/proposed-step.js";
+export type ManualAction = Exclude<ProposedStep["action"], "bridge">;
 export interface ManualProposalInput {
-    action: ProposedStep["action"];
+    action: ManualAction;
     binding: ProposalBinding;
     before: string;
     expect?: Expectation | undefined;

package/dist/ports/generation-session-store.d.ts

@@ -1,4 +1,4 @@
-import type { GenerationInFlight, GenerationSession, PendingConfirmation } from "../domain/generation.js";
+import type { GenerationInFlight, GenerationSession, PendingConfirmation, VerificationPhase } from "../domain/generation.js";
 export declare const GENERATION_SESSION_STORE_ERROR_CODES: readonly ["INVALID_ID", "INVALID_SESSION", "INVALID_REVISION", "SESSION_ALREADY_EXISTS", "SESSION_NOT_FOUND", "SESSION_PUBLISHED", "REVISION_CONFLICT", "INVALID_TRANSITION", "LOCK_TIMEOUT", "INVALID_EVIDENCE_PATH", "INVALID_EVIDENCE", "EVIDENCE_NOT_FOUND", "EVIDENCE_ALREADY_EXISTS", "SESSION_NOT_PUBLISHABLE", "PUBLISH_DESTINATION_EXISTS", "IO_ERROR"];
 export type GenerationSessionStoreErrorCode = typeof GENERATION_SESSION_STORE_ERROR_CODES[number];
 export declare class GenerationSessionStoreError extends Error {
@@ -19,14 +19,24 @@ export interface GenerationSessionStore {
     beginStep: (id: string, expectedRevision: number, inFlight: GenerationInFlight, approvedConfirmation?: PendingConfirmation) => Promise<GenerationSession>;
     completeStep: (id: string, expectedRevision: number, expectedInFlight: GenerationInFlight, next: GenerationSession) => Promise<void>;
     recover: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
-    beginVerification: (id: string, expectedRevision: number, attemptId: string) => Promise<GenerationSession>;
+    beginVerification: (id: string, expectedRevision: number, attemptId: string, owner?: {
+        pid: number;
+        startedAt: string;
+    }) => Promise<GenerationSession>;
+    updateVerificationPhase: (id: string, attemptId: string, phase: VerificationPhase) => Promise<void>;
+    abortVerification: (id: string, expectedRevision: number) => Promise<GenerationSession>;
     completeVerification: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
     failVerification: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
+    recoverVerification: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
+    reopenVerification: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
+    archive: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
+    list: () => Promise<readonly GenerationSession[]>;
     markBundlePublishable: (id: string, expectedRevision: number, next: GenerationSession) => Promise<void>;
     writeEvidence: (id: string, relativePath: string, value: unknown) => Promise<void>;
     writeTextEvidence: (id: string, relativePath: string, value: string) => Promise<void>;
     produceEvidence: (id: string, relativePath: string, produce: (temporaryPath: string) => Promise<void>) => Promise<void>;
     readEvidence: (id: string, relativePath: string) => Promise<Buffer>;
+    evidenceReference: (id: string, relativePath: string) => Promise<string>;
     listEvidence: (id: string) => Promise<readonly GenerationEvidenceFile[]>;
     publish: (id: string) => Promise<string>;
 }

package/dist/ports/git-diff.d.ts

@@ -0,0 +1,9 @@
+import type { ChangeSet } from "../domain/impact.js";
+export interface GitDiffPort {
+    diff: (input: {
+        projectRoot: string;
+        base: string;
+        head: string;
+        signal?: AbortSignal | undefined;
+    }) => Promise<ChangeSet>;
+}

package/dist/ports/git-diff.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/journey-composition-store.d.ts

@@ -0,0 +1,17 @@
+export interface JourneyCompositionStore {
+    read: (input: {
+        projectRoot: string;
+        relativePath: string;
+    }) => Promise<Buffer>;
+    listFlowPaths: (projectRoot: string) => Promise<readonly string[]>;
+    listJourneyPaths: (projectRoot: string) => Promise<readonly string[]>;
+    readJourneyMeta: (input: {
+        projectRoot: string;
+        journeyPath: string;
+    }) => Promise<Buffer | null>;
+    writeText: (input: {
+        projectRoot: string;
+        relativePath: string;
+        content: string;
+    }) => Promise<void>;
+}

package/dist/ports/journey-composition-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/knowledge-registry.d.ts

@@ -0,0 +1,20 @@
+import type { AnchorDefinition, KnowledgeBundleIndex, ScreenDefinition } from "../domain/knowledge.js";
+export interface LoadedKnowledgeBundle {
+    index: KnowledgeBundleIndex;
+    indexSha256: string;
+    knowledgeHash: string;
+    anchors: AnchorDefinition[];
+    screens: ScreenDefinition[];
+}
+export interface KnowledgeRehashResult {
+    indexPath: string;
+    knowledgeHash: string;
+    revision: number;
+    changed: boolean;
+    anchors: number;
+    screens: number;
+}
+export interface KnowledgeRegistryPort {
+    load: (projectRoot: string) => Promise<LoadedKnowledgeBundle>;
+    rehash: (projectRoot: string, packageName: string) => Promise<KnowledgeRehashResult>;
+}

package/dist/ports/knowledge-registry.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/process-runner.d.ts

@@ -14,11 +14,18 @@ export interface CommandResult {
     durationMs: number;
     timedOut: boolean;
     cancelled: boolean;
+    terminationRequested?: boolean | undefined;
     spawnError?: string | undefined;
 }
 export interface StreamHandlers {
     onStdoutLine?(line: string): void;
     onStderrLine?(line: string): void;
+    /**
+     * Long-lived streams may disable aggregate capture while still consuming
+     * complete lines through the callbacks above.
+     */
+    captureStdout?: boolean | undefined;
+    captureStderr?: boolean | undefined;
 }
 export interface RunningCommand {
     /** Resolves undefined once the stream remains alive through startup. */

package/dist/ports/project-file-inspector.d.ts

@@ -23,6 +23,7 @@ export type ProjectFileInspection = {
     status: "inspected";
     resolvedRelativePath: string;
     sha256: string;
+    bytes?: Buffer;
 };
 export interface ProjectFileInspector {
     inspectProjectFile: (input: {

package/dist/ports/project-identity-inspector.d.ts

@@ -0,0 +1,24 @@
+export type ProjectIdentityInspection = {
+    readonly status: "inspected";
+    readonly packageName: string;
+    readonly launchActivity: string;
+} | {
+    readonly status: "rootNotFound";
+} | {
+    readonly status: "rootNotDirectory";
+} | {
+    readonly status: "moduleNotFound";
+} | {
+    readonly status: "manifestNotFound";
+} | {
+    readonly status: "manifestUnreadable";
+} | {
+    readonly status: "identityNotFound";
+    readonly message: string;
+};
+export interface ProjectIdentityInspector {
+    inspectIdentity: (input: {
+        readonly projectRoot: string;
+        readonly moduleDir: string;
+    }) => Promise<ProjectIdentityInspection>;
+}

package/dist/ports/project-identity-inspector.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/project-inventory-inspector.d.ts

@@ -0,0 +1,21 @@
+export type ProjectInventoryCategory = "manifests" | "sources" | "layouts" | "navigation";
+export type ProjectInventoryInspection = {
+    status: "rootNotFound";
+} | {
+    status: "rootUnreadable";
+} | {
+    status: "rootNotDirectory";
+} | {
+    status: "escape";
+} | {
+    status: "inspected";
+    paths: string[];
+    pathSetSha256: string;
+};
+export interface ProjectInventoryInspector {
+    inspectProjectInventory: (input: {
+        projectRoot: string;
+        projectDir: string;
+        categories: ProjectInventoryCategory[];
+    }) => Promise<ProjectInventoryInspection>;
+}

package/dist/ports/project-inventory-inspector.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/project-module-discoverer.d.ts

@@ -0,0 +1,26 @@
+export interface DiscoveredModule {
+    readonly id: string;
+    readonly projectDir: string;
+    readonly kind: "application" | "feature" | "library";
+    readonly dependsOn: readonly string[];
+}
+export type ProjectModuleDiscovery = {
+    readonly status: "discovered";
+    readonly modules: readonly DiscoveredModule[];
+} | {
+    readonly status: "rootNotFound";
+} | {
+    readonly status: "rootNotDirectory";
+} | {
+    readonly status: "noSettingsFile";
+} | {
+    readonly status: "noApplicationModule";
+} | {
+    readonly status: "discoveryFailed";
+    readonly message: string;
+};
+export interface ProjectModuleDiscoverer {
+    discoverModules: (input: {
+        readonly projectRoot: string;
+    }) => Promise<ProjectModuleDiscovery>;
+}

package/dist/ports/project-module-discoverer.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/recorder-prompt.d.ts

@@ -1,4 +1,6 @@
-export type RecorderAction = "click" | "longClick" | "inputText" | "swipe" | "scrollTo" | "back" | "wait" | "finish" | "cancel";
+import type { BridgeScenario } from "../domain/journey.js";
+export type RecorderAction = "click" | "longClick" | "inputText" | "swipe" | "scrollTo" | "back" | "wait" | "bridgeTrigger" | "finish" | "cancel";
+export type ExternalStepAction = "click" | "longClick" | "inputText" | "swipe" | "scrollTo" | "back" | "wait" | "finishExternal";
 export type ScrollDecision = {
     kind: "select";
     id: string;
@@ -26,4 +28,11 @@ export interface RecorderPromptPort {
     notifyFailure: (message: string) => Promise<void>;
     selectScrollContainer: (choices: readonly RecorderTargetChoice[]) => Promise<string>;
     scrollTargetDecision: (choices: readonly RecorderTargetChoice[]) => Promise<ScrollDecision>;
+    selectBridgeScenario: () => Promise<BridgeScenario>;
+    inputBridgeDescription: (scenario: BridgeScenario) => Promise<string>;
+    inputBridgeReturnTimeoutMs: () => Promise<number>;
+    selectExternalStepAction: () => Promise<ExternalStepAction>;
+    notifyExternalEscape: (escapedPackageName: string) => Promise<void>;
+    notifyExternalReturn: () => Promise<void>;
+    notifyBridgeNoEscape: () => Promise<void>;
 }

package/dist/ports/runtime-backend.d.ts

@@ -0,0 +1,89 @@
+import type { ForegroundComponent } from "../domain/activity.js";
+import type { AppProcess } from "../domain/app-process.js";
+import type { Point } from "../domain/geometry.js";
+import type { DeviceInfo, RuntimeBackendDescriptor, RuntimeCapabilities } from "../domain/runtime.js";
+import type { WindowTopology } from "../domain/window-hierarchy.js";
+import type { UiBackendSelection } from "../domain/ui-backend.js";
+import type { DeviceIdentity } from "./adb.js";
+import type { AnnotatedScreenResolverPort } from "./annotated-screen-resolver.js";
+import type { CommandResult, RunningCommand } from "./process-runner.js";
+import type { UiSnapshotProvider } from "./ui-snapshot.js";
+import type { UiStabilityProbe } from "./ui-stability.js";
+export interface OpenRuntimeSessionOptions {
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+}
+export interface OpenRuntimeUiSnapshotsOptions {
+    timeoutMs?: number | undefined;
+    backend?: UiBackendSelection | undefined;
+    cacheEnabled?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface RuntimeAppQuery {
+    packageName: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface RuntimeLaunchOptions extends RuntimeAppQuery {
+    activity: string;
+}
+export interface RuntimeLogcatStreamOptions {
+    onStdoutLine: (line: string) => void;
+    onStderrLine?: ((line: string) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface RuntimeDumpLogcatOptions {
+    maxLines: number;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface RuntimeScreenshotOptions {
+    outputPath: string;
+    annotate?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface RuntimeIntentOptions {
+    action: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface RuntimeSession {
+    readonly descriptor: RuntimeBackendDescriptor;
+    readonly deviceSerial: string;
+    openUiSnapshots(options?: OpenRuntimeUiSnapshotsOptions): Promise<UiSnapshotProvider>;
+    isInstalled(app: RuntimeAppQuery): Promise<boolean>;
+    launchApp(options: RuntimeLaunchOptions): Promise<CommandResult>;
+    forceStop(app: RuntimeAppQuery): Promise<CommandResult>;
+    readonly currentActivity: ((app: RuntimeAppQuery) => Promise<string>) | undefined;
+    readonly deviceIdentity: ((app: RuntimeAppQuery) => Promise<DeviceIdentity>) | undefined;
+    readonly foregroundComponent: ((app: RuntimeAppQuery) => Promise<ForegroundComponent>) | undefined;
+    readonly appProcesses: ((app: RuntimeAppQuery) => Promise<readonly AppProcess[]>) | undefined;
+    readonly windowTopology: ((app: RuntimeAppQuery) => Promise<WindowTopology>) | undefined;
+    tap(point: Point, signal?: AbortSignal): Promise<CommandResult>;
+    longClick(point: Point, durationMs: number, signal?: AbortSignal): Promise<CommandResult>;
+    swipe(from: Point, to: Point, durationMs: number, signal?: AbortSignal): Promise<CommandResult>;
+    back(signal?: AbortSignal): Promise<CommandResult>;
+    inputText(text: string, signal?: AbortSignal): Promise<CommandResult>;
+    readonly startLogcat: ((options: RuntimeLogcatStreamOptions) => RunningCommand) | undefined;
+    readonly dumpLogcat: ((options: RuntimeDumpLogcatOptions) => Promise<CommandResult>) | undefined;
+    captureScreenshot(options: RuntimeScreenshotOptions): Promise<CommandResult>;
+    readonly annotatedScreens: AnnotatedScreenResolverPort | undefined;
+    readonly uiStability: UiStabilityProbe;
+    readonly startActivityByIntent: ((options: RuntimeIntentOptions) => Promise<CommandResult>) | undefined;
+    close(): Promise<void>;
+}
+export interface RuntimeBackend {
+    readonly descriptor: RuntimeBackendDescriptor;
+    readonly capabilities: RuntimeCapabilities;
+    listDevices(signal?: AbortSignal): Promise<readonly DeviceInfo[]>;
+    openSession(options: OpenRuntimeSessionOptions): Promise<RuntimeSession>;
+}
+/**
+ * The session-opening slice of `RuntimeBackend`. Application services that
+ * borrow a `RuntimeSession` per run depend on this type so backends can be
+ * shared or replaced without exposing the full backend interface.
+ */
+export type RuntimeSessionOpener = Pick<RuntimeBackend, "openSession">;
+/** Borrows one session for `use` and always closes it. */
+export declare function withRuntimeSession<T>(sessions: RuntimeSessionOpener, deviceSerial: string, signal: AbortSignal | undefined, use: (session: RuntimeSession) => Promise<T>): Promise<T>;

package/dist/ports/runtime-backend.js

@@ -0,0 +1,13 @@
+/** Borrows one session for `use` and always closes it. */
+export async function withRuntimeSession(sessions, deviceSerial, signal, use) {
+    const session = await sessions.openSession({
+        deviceSerial,
+        ...(signal === undefined ? {} : { signal })
+    });
+    try {
+        return await use(session);
+    }
+    finally {
+        await session.close();
+    }
+}

package/dist/ports/runtime-capability.d.ts

@@ -0,0 +1,12 @@
+import type { FailureCode } from "../domain/failure.js";
+export interface RuntimeCapabilityError extends Error {
+    code: FailureCode;
+}
+export declare function isRuntimeCapabilityError(error: unknown): error is RuntimeCapabilityError;
+/**
+ * Fail-closed rejection for capability-gated RuntimeSession members. The
+ * error carries `RUNTIME_CAPABILITY_MISSING` so CLI consumers surface the
+ * coded failure instead of a generic internal error, and the message names
+ * the escape hatches that select a capable backend.
+ */
+export declare function runtimeCapabilityMissing(backendId: string, member: string): RuntimeCapabilityError;

package/dist/ports/runtime-capability.js

@@ -0,0 +1,20 @@
+export function isRuntimeCapabilityError(error) {
+    return (error !== null
+        && typeof error === "object"
+        && "code" in error
+        && error.code === "RUNTIME_CAPABILITY_MISSING");
+}
+/**
+ * Fail-closed rejection for capability-gated RuntimeSession members. The
+ * error carries `RUNTIME_CAPABILITY_MISSING` so CLI consumers surface the
+ * coded failure instead of a generic internal error, and the message names
+ * the escape hatches that select a capable backend.
+ */
+export function runtimeCapabilityMissing(backendId, member) {
+    const error = new Error(`Runtime backend "${backendId}" does not support ${member}. `
+        + "Select a backend with this capability through runtime.backend in "
+        + ".taphound/config.json or the TAPHOUND_RUNTIME_BACKEND environment "
+        + 'variable (for example "adb").');
+    error.code = "RUNTIME_CAPABILITY_MISSING";
+    return error;
+}

package/dist/ports/runtime-session-ports.d.ts

@@ -0,0 +1,25 @@
+import type { AdbPort } from "./adb.js";
+import type { AnnotatedScreenResolverPort } from "./annotated-screen-resolver.js";
+import type { RuntimeSession } from "./runtime-backend.js";
+import type { ScreenshotPort } from "./screenshot.js";
+import type { UiStabilityProbe } from "./ui-stability.js";
+/**
+ * Legacy port views over one borrowed `RuntimeSession`.
+ *
+ * Level 1 session-first orchestrators borrow one session per run and feed
+ * their unchanged `AdbPort`-shaped helpers through these views so the whole
+ * run flows through a single session. Level 2 retypes the helpers onto
+ * `Pick<RuntimeSession, ...>` and deletes the views.
+ */
+export interface RuntimeSessionPortViews {
+    adb: AdbPort;
+    screenshots: ScreenshotPort;
+    annotatedScreens: AnnotatedScreenResolverPort;
+    uiStability: UiStabilityProbe;
+}
+/**
+ * Builds the legacy port views for one borrowed session. Implementations
+ * live in the runtime adapters; application services depend on this factory
+ * type only.
+ */
+export type RuntimeSessionPortViewsFactory = (session: RuntimeSession) => RuntimeSessionPortViews;

package/dist/ports/runtime-session-ports.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/screenshot.d.ts

@@ -0,0 +1,11 @@
+import type { CommandResult } from "./process-runner.js";
+export interface ScreenshotOptions {
+    deviceSerial: string;
+    outputPath: string;
+    annotate?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface ScreenshotPort {
+    capture: (options: ScreenshotOptions) => Promise<CommandResult>;
+}

package/dist/ports/screenshot.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/skill-installer.d.ts

@@ -3,6 +3,6 @@ export interface SkillInstallResult {
     readonly skipped: boolean;
 }
 export interface SkillInstallerPort {
-    findPayload: () => Promise<string>;
-    installTo: (targetDir: string) => Promise<SkillInstallResult>;
+    listSkillNames: () => Promise<readonly string[]>;
+    installTo: (skillName: string, targetDir: string) => Promise<SkillInstallResult>;
 }