tapline-host 1.4.0 → 1.5.0

package/dist/tools.d.ts

@@ -2,8 +2,12 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ControlQueue } from "./control.js";
 import type { InputOutcome, OverlayRead, PersonInput, QualityPreset, ViewerAction } from "./viewer.js";
+import { Journey, type JourneyState } from "./journey.js";
+import { type Runner } from "./journeyexport.js";
 import { Confirmations } from "./confirm.js";
 import { type PolicyFile } from "./policy.js";
+import { type UxJourneyHook, type UxRules } from "./uxcheck.js";
+import { MediaState } from "./media.js";
 import { type TaplineHost } from "./server.js";
 export declare const targetSchema: z.ZodObject<{
     ref: z.ZodOptional<z.ZodString>;
@@ -29,6 +33,7 @@ export declare const toolShapes: {
         readonly labels: z.ZodOptional<z.ZodBoolean>;
     };
     readonly check_layout: {};
+    readonly ux_check: {};
     readonly audit: {
         readonly types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
             contrast: "contrast";
@@ -270,9 +275,89 @@ export declare const toolShapes: {
         readonly seconds: z.ZodNumber;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
+    readonly media: {
+        add: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        confirm: z.ZodOptional<z.ZodBoolean>;
+        remove: z.ZodOptional<z.ZodBoolean>;
+        picker: z.ZodOptional<z.ZodBoolean>;
+    };
     readonly session_report: {
         readonly since: z.ZodOptional<z.ZodNumber>;
     };
+    readonly journey: {
+        readonly start: z.ZodOptional<z.ZodBoolean>;
+        readonly goal: z.ZodOptional<z.ZodString>;
+        readonly persona: z.ZodOptional<z.ZodString>;
+        readonly conditions: z.ZodOptional<z.ZodObject<{
+            language: z.ZodOptional<z.ZodString>;
+            region: z.ZodOptional<z.ZodString>;
+            text_size: z.ZodOptional<z.ZodEnum<{
+                s: "s";
+                m: "m";
+                xs: "xs";
+                l: "l";
+                xl: "xl";
+                xxl: "xxl";
+                xxxl: "xxxl";
+                ax1: "ax1";
+                ax2: "ax2";
+                ax3: "ax3";
+                ax4: "ax4";
+                ax5: "ax5";
+                system: "system";
+            }>>;
+            network: z.ZodOptional<z.ZodEnum<{
+                offline: "offline";
+                "3g": "3g";
+                lossy: "lossy";
+            }>>;
+        }, z.core.$strict>>;
+        readonly allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        readonly eyes: z.ZodOptional<z.ZodEnum<{
+            agent: "agent";
+            user: "user";
+        }>>;
+        readonly stop: z.ZodOptional<z.ZodBoolean>;
+        readonly reached: z.ZodOptional<z.ZodBoolean>;
+        readonly why: z.ZodOptional<z.ZodString>;
+        readonly export: z.ZodOptional<z.ZodObject<{
+            to: z.ZodEnum<{
+                pr: "pr";
+                issue: "issue";
+            }>;
+            repo: z.ZodString;
+            pr: z.ZodOptional<z.ZodNumber>;
+            confirm: z.ZodOptional<z.ZodBoolean>;
+            public: z.ZodOptional<z.ZodBoolean>;
+            fork: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        readonly stress: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                network: "network";
+                background: "background";
+                double_tap: "double_tap";
+                rotate: "rotate";
+                relaunch: "relaunch";
+            }>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                offline: "offline";
+                "3g": "3g";
+                lossy: "lossy";
+                normal: "normal";
+            }>>;
+            target: z.ZodOptional<z.ZodObject<{
+                ref: z.ZodOptional<z.ZodString>;
+                text: z.ZodOptional<z.ZodString>;
+                x: z.ZodOptional<z.ZodNumber>;
+                y: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        readonly survives: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            goal_step: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        readonly done: z.ZodOptional<z.ZodBoolean>;
+    };
     readonly run: {
         readonly steps: z.ZodArray<z.ZodObject<{
             tool: z.ZodString;
@@ -323,6 +408,8 @@ export interface ToolsOptions {
     clientId?: () => string | undefined;
     /** The safety policy (AGENT-TOOLS 1.8 §11). Default: the built-in words; --no-policy passes empty lists. */
     policy?: PolicyFile;
+    /** The user's UX house rules (`--ux-rules FILE`, AGENT-TOOLS 1.12 §17.3). Default: none. */
+    uxRules?: UxRules;
     /** Where a person's OK is asked for and given (the live viewer listens). Default: a fresh one. */
     confirmations?: Confirmations;
     /** False when nobody can answer a request (--viewer off). Default true. */
@@ -375,6 +462,22 @@ export interface ToolsOptions {
         on: boolean;
         quality: QualityPreset;
     };
+    /** The clock a journey measures with, in ms (tests pass their own). Default: Date.now. */
+    clock?: () => number;
+    /**
+     * Called when a journey stops (AGENT-TOOLS 1.12 §17.5), with its state: the report writer's hook. The lines it
+     * returns follow the summary in the answer (`Findings: …`, `Report: <folder>`).
+     */
+    onJourneyStop?: (state: JourneyState) => string[] | Promise<string[]>;
+    /**
+     * Where journeys keep their report folders (e.g. ~/.tapline/journeys): each journey gets
+     * `<yyyy-mm-dd-hhmm>-<slug>/` with its frames, and `stop` writes the report there. Unset: no frames, no report.
+     */
+    journeysDir?: string;
+    /** Runs `gh` and `git` for `export` (AGENT-TOOLS 1.12 §17.5). Unset: export answers that it can't run. Tests pass a fake. */
+    exportRunner?: Runner;
+    /** Cap for the journey GIF in bytes (tests lower it; default 3 MB). */
+    gifMaxBytes?: number;
 }
 /**
  * The app's `feed` params. For measuring only, TAPLINE_FEED_GAP_MS (30–2000) replaces the app's
@@ -423,6 +526,12 @@ export declare class TaplineTools {
     private scrollBase;
     readonly confirmations: Confirmations;
     private readonly policy;
+    private readonly uxRules;
+    /**
+     * Hook for the journey (AGENT-TOOLS 1.12 §17): gives `ux_check` the action labels of earlier screens, and is told
+     * what each `ux_check` found. Null while no journey runs (naming is then not checked, and the answer says so).
+     */
+    uxJourney: UxJourneyHook | null;
     private readonly reloadSettleMs;
     private readonly stillGapMs;
     private readonly stillCapMs;
@@ -463,7 +572,62 @@ export declare class TaplineTools {
     private readonly crashBaseline;
     /** Set inside a tool call (and everything it awaits), so a call within a call (`run`'s steps) adds no notes. */
     private readonly noteScope;
+    /** The journey this agent has running (AGENT-TOOLS 1.12 §17.1); one at a time. */
+    private journeyRun;
+    /** The app the running journey started on (its identity and name): its clean-up goes to that app only. */
+    private journeyApp;
+    /** The journey's own app if it is connected (the current one first), else undefined: never another app (Codex review of 1.5.0). */
+    private journeySession;
+    /** Why a journey's clean-up didn't reach its app. */
+    private journeyAppGone;
+    /** The state of the journey that stopped last, for the report writer and the stress moments. */
+    private journeyDone;
+    /** Inside `run`: "run" for the batch's own checks (not counted), "step" for a step (counted like a call of its own). */
+    private readonly journeyScope;
+    /** The running journey's frames and report pictures (AGENT-TOOLS 1.12 §17.5); undefined without a `journeysDir`. */
+    private recorder;
+    /** The hook this journey gave `ux_check`, to take back at the stop. */
+    private journeyHook;
+    private pickerOff;
+    /** Where the last touch of the call in flight was, for the frame's tap ring. */
+    private lastTouch;
+    /** Stress moments that wait for a person (§17.4), by kind: what must survive. */
+    private readonly stressWaiting;
+    /** When the app last left the front or its link dropped, and when an app last connected (real time, for stress done). */
+    private readonly appLeftAt;
+    private readonly appConnectedAt;
+    /** Which app's picker event is being counted right now (set around the media state's own count). */
+    private pickerFrom;
+    /** "starting" until a journey's set-up is done, "stopping" until its clean-up is done: no other start meanwhile. */
+    private journeyBusy;
+    private readonly clock;
     constructor(host: TaplineHost, options: ToolsOptions);
+    /** The journey running now, for the stress moments and the report writer (AGENT-TOOLS 1.12 §17). */
+    currentJourney(): Journey | undefined;
+    /** The state of the journey that stopped last. */
+    finishedJourney(): JourneyState | undefined;
+    /** Whether the agent sees the app as a user does: a journey is running and its eyes are the user's. */
+    private userEyes;
+    /**
+     * Measures one call of a running journey and shows its answer as a user would see it. Calls inside `run` count
+     * as steps (the batch itself and its expectation checks do not); a dry run counts as nothing.
+     */
+    private journeyCall;
+    /** When a password field was last typed into, and whether that was within the second iOS still shows its last character. */
+    private secureTypedAt;
+    private secureWindow;
+    /** In a user's eyes no id reaches the agent, not even inside an error the app composed. */
+    private shownToUser;
+    /** `id` and `label` answer `bad_params` in a journey's user's eyes (§17.1). */
+    private hiddenTarget;
+    /** Whether the journey's `allow` lets this shortcut through (always, outside a user's eyes). */
+    private shortcutAllowed;
+    private shortcutWords;
+    /** A shortcut in a user's eyes: refused unless `allow` names it, and noted for the report when it goes through. */
+    private shortcutRefusal;
+    private static readonly SCROLL_TO_TARGET_OFF;
+    /** What a journey's user's eyes refuse in a step of `run`, before anything runs (a step number first); null when it is fine. */
+    private journeyStepRefusal;
     /** The agent's client id for the call log; the MCP server passes the client's name once it is known. */
     setClientId(read: () => string | undefined): void;
     /** A call refused before it reached its tool (an unknown argument): numbered and logged like any other, so the report counts it. */
@@ -526,6 +690,7 @@ export declare class TaplineTools {
     private dryRunBatch;
     /** One step of `run`, as its own tool call without a list. */
     private runStep;
+    private runStepNow;
     /** The screen's route names now (one cheap read), or null when the app has no router or didn't answer. */
     private currentRoute;
     /** Null when the expectation holds within its time; else how it failed. */
@@ -533,6 +698,12 @@ export declare class TaplineTools {
     private textExpectMissed;
     inspect(args: Shape<"inspect">): Promise<CallToolResult>;
     audit(args?: Shape<"audit">): Promise<CallToolResult>;
+    /** The house rule `max_taps_to_goal`, for the journey to check at stop; undefined when the user set none. */
+    get maxTapsToGoal(): number | undefined;
+    uxCheck(_args?: Shape<"ux_check">): Promise<CallToolResult>;
+    /** What `media` remembers per app: the asset ids it added, and the picker skips a journey report reads. */
+    readonly mediaState: MediaState;
+    media(args?: Shape<"media">): Promise<CallToolResult>;
     checkLayout(_args?: Shape<"check_layout">): Promise<CallToolResult>;
     /** Saves a file-mode screenshot (0600, newest `screenshotKeep` kept) and returns its path. */
     private saveShot;
@@ -542,6 +713,8 @@ export declare class TaplineTools {
     private takePersonNote;
     /** An action answered with no list and no changes: the call log can't say what is in the list any more. */
     private markListUnseen;
+    /** Remembers where a touch landed (points, and the touched element's frame) for the journey's frame and GIF. */
+    private noteTouch;
     /** Runs a request, then (unless disabled) appends the fresh element list and how long the app took to settle. */
     private act;
     /**
@@ -670,6 +843,8 @@ export declare class TaplineTools {
     scroll(args: Shape<"scroll">): Promise<CallToolResult>;
     toggle(args: Shape<"toggle">): Promise<CallToolResult>;
     appCommand(args: Shape<"app_command">): Promise<CallToolResult>;
+    /** AGENT-TOOLS 1.11 §16.4: a policy whose block list holds `network` refuses a condition; `normal` always goes. */
+    private networkRefusal;
     waitFor(args: Shape<"wait_for">): Promise<CallToolResult>;
     /** A drag through React Native's touch system (AGENT-TOOLS 5.2): what a pan view or a swipe-to-close sheet handles. */
     swipe(args: Shape<"swipe">): Promise<CallToolResult>;
@@ -687,6 +862,44 @@ export declare class TaplineTools {
     /** One measuring window in the app: start, (the tap,) wait out `seconds`, stop. */
     private measureWindow;
     performance(args?: Shape<"performance">): Promise<CallToolResult>;
+    journey(args?: Shape<"journey">): Promise<CallToolResult>;
+    private journeyStart;
+    private journeyStarted;
+    /** Opens the report folder for a journey that has somewhere to keep one, and hands `ux_check` the hook that feeds it. */
+    private startRecorder;
+    /** The recorder's eyes: a read that touches nothing, and a small picture. */
+    private frameSource;
+    private journeyStop;
+    private journeyStopped;
+    /** `export` of `stop`: the report to GitHub through the user's own gh and git; the report stays local when it fails. */
+    private exportReport;
+    private journeyStress;
+    private waitForPerson;
+    /** The screen's size in points from a read that touches nothing; null when the app doesn't answer. */
+    private freshScreenSize;
+    /**
+     * Why a person's stress moment can't be taken as done, or null when the app shows it happened: background left the
+     * front (or the link dropped) since it was asked; relaunch connected anew; rotate flipped the screen's size.
+     */
+    private stressUnseen;
+    /** Waits for an app after a reload or a person leaving it (a new session comes up), a few seconds at most. */
+    private reconnected;
+    private stressNetwork;
+    /** The same touch twice, 80 ms apart, each through the usual checks and the policy. */
+    private stressDoubleTap;
+    /** Records the moment and answers it: `Stress: <kind>; it survived: …` or `…; it didn't survive: …`. */
+    private stressDone;
+    /** Whether what had to survive is still there, from a read that touches nothing. */
+    private survivalOf;
+    /** `goal_step`: a step number (the screen that step ended on) or a screen's name (part of its route). */
+    private goalStepHolds;
+    /** The command and arguments that set one of a journey's conditions. */
+    private conditionCall;
+    /** Runs one condition command straight on the app (a journey's own, not the agent's shortcut); the app's answer may say what it was before. */
+    private runCondition;
+    private applyCondition;
+    /** At the stop: network goes back to normal, text size to the phone's own, language and region to what the app said they were. */
+    private undoConditions;
     wait(args: Shape<"wait">): Promise<CallToolResult>;
 }
 export {};