execbro 1.10.16 → 1.10.18

package/build/pro/flowpointTools.js

@@ -0,0 +1,266 @@
+import { z } from "zod";
+import { registerToolWithTelemetry } from "../core/register.js";
+import { getConnectedAppByDevice, getFirstConnectedApp, executeInApp } from "../core/index.js";
+import { UserInputError } from "../core/errors.js";
+import { allStoredFlowpoints, clearFlowpointStores, drainFlowpoints, filterFlowpoints, formatFlowpoints, formatMeta, getFlowpointStore, matchesPoint, buildClearExpression, verifyFlow, resolveLastRuns, } from "./flowpoints.js";
+const NO_FLOWPOINTS_HINT = "No flowpoints captured. Instrument the flow under test (execbro-sdk required):\n\n" +
+    "  import { flowpoint } from 'execbro-sdk'\n" +
+    "  flowpoint({ name: 'my-flow', step: 'start', begin: true })\n" +
+    "  flowpoint({ name: 'my-flow', step: 'done', meta: { anything: true } })\n\n" +
+    "Then reload the app, drive the flow, and query again. " +
+    'See get_usage_guide(topic="flowpoints").';
+export function resolveTargetDeviceName(device) {
+    if (device) {
+        const app = getConnectedAppByDevice(device);
+        if (!app)
+            throw new UserInputError(`No connected device matches "${device}"`);
+        return app.deviceInfo.deviceName || app.deviceInfo.title || "unknown";
+    }
+    const first = getFirstConnectedApp();
+    if (!first)
+        throw new UserInputError("No connected app. Run scan_metro first.");
+    return first.deviceInfo.deviceName || first.deviceInfo.title || "unknown";
+}
+const deviceParam = z
+    .string()
+    .optional()
+    .describe("Target device name (substring match). Omit for all devices. Run get_apps to see connected devices.");
+export function registerFlowpointTools(server) {
+    registerToolWithTelemetry(server, "get_flowpoints", {
+        description: "Read flowpoint breadcrumbs — structured, timestamped points emitted by flowpoint() calls " +
+            "(execbro-sdk) — grouped by flow and run, with inter-point timing deltas.\n" +
+            "PURPOSE: verify what actually happened inside a flow (steps, order, timing, failures) " +
+            "instead of inferring it from console logs.\n" +
+            "WHEN TO USE: after driving an instrumented flow; or with level: 'error' to ask " +
+            '"did any flow fail?" across all flows at once.\n' +
+            "WORKFLOW: instrument with flowpoint() -> reload -> drive the flow -> " +
+            "wait_for_flowpoint (sync) -> verify_flow (assert) -> get_flowpoints (inspect details).\n" +
+            "LIMITATIONS: requires execbro-sdk init() and flowpoint() instrumentation in app code.\n" +
+            "GOOD: get_flowpoints({ name: 'add-to-cart', run: 'last' }) after a retry.\n" +
+            "BAD: polling get_flowpoints in a loop — use wait_for_flowpoint instead.\n" +
+            'SEE ALSO: call get_usage_guide(topic="flowpoints") for the full playbook.',
+        inputSchema: {
+            name: z.string().optional().describe("Filter to one flow name. Omit for all flows."),
+            step: z.string().optional().describe("Filter to one step label (exact match)."),
+            run: z
+                .string()
+                .optional()
+                .describe("Filter to one run id, or 'last' for the most recent run per flow."),
+            level: z.enum(["info", "warn", "error"]).optional().describe("Filter by severity."),
+            metaIncludes: z
+                .string()
+                .optional()
+                .describe("Case-insensitive substring match against the stringified meta payload."),
+            since: z.number().optional().describe("Epoch-ms lower bound on the point timestamp (exclusive)."),
+            limit: z.number().optional().default(200).describe("Max points returned, newest kept (default 200)."),
+            device: deviceParam,
+        },
+    }, async ({ name, step, run, level, metaIncludes, since, limit, device }) => {
+        const deviceName = resolveTargetDeviceName(device);
+        const drained = await drainFlowpoints(deviceName, device);
+        if (!drained.ok) {
+            return { isError: true, content: [{ type: "text", text: drained.error }] };
+        }
+        const sourceEntries = device ? getFlowpointStore(deviceName).entries : allStoredFlowpoints();
+        const entries = filterFlowpoints(sourceEntries, {
+            name,
+            step,
+            run,
+            level,
+            metaIncludes,
+            since,
+            limit,
+        });
+        if (entries.length === 0) {
+            if (sourceEntries.length === 0) {
+                return { content: [{ type: "text", text: NO_FLOWPOINTS_HINT }] };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${sourceEntries.length} flowpoints stored, but 0 matched your filters. ` +
+                            "Loosen or drop filters (name/step/run/level/metaIncludes/since) to see them.",
+                    },
+                ],
+            };
+        }
+        const flows = new Set(entries.map((e) => e.name)).size;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Flowpoints (${entries.length} points, ${flows} flow${flows === 1 ? "" : "s"}):\n\n${formatFlowpoints(entries)}`,
+                },
+            ],
+        };
+    }, (result) => !!result?.content?.[0]?.text?.startsWith("No flowpoints captured"));
+    registerToolWithTelemetry(server, "clear_flowpoints", {
+        description: "Clear stored flowpoints.\n" +
+            "PURPOSE: reset flowpoint history between test sessions.\n" +
+            "WHEN TO USE: rarely — prefer begin: true + run: 'last' filtering between attempts. " +
+            "With name: clears one flow from the server store only (cleared entries never re-drain). " +
+            "Without name: clears everything server-side AND the in-app buffer.",
+        inputSchema: {
+            name: z.string().optional().describe("Clear only this flow (server-side). Omit to clear all."),
+            device: z
+                .string()
+                .optional()
+                .describe("Target device (substring match). Scopes both the server-store clear and the in-app " +
+                "buffer clear. Omit for all devices."),
+        },
+    }, async ({ name, device }) => {
+        const deviceName = device ? resolveTargetDeviceName(device) : undefined;
+        let cleared = clearFlowpointStores(name, deviceName);
+        let caveat = "";
+        if (!name) {
+            const result = await executeInApp(buildClearExpression(), false, { timeoutMs: 3000, originatingToolName: "clear_flowpoints" }, device);
+            if (result.success) {
+                const inApp = parseInt(result.result || "0", 10);
+                if (!isNaN(inApp))
+                    cleared = Math.max(cleared, inApp);
+            }
+            else {
+                caveat = " (in-app buffer clear failed — still-buffered points may re-drain after the next app event)";
+            }
+        }
+        const scope = name ? ` for flow "${name}"` : "";
+        return { content: [{ type: "text", text: `Cleared ${cleared} flowpoints${scope}.${caveat}` }] };
+    });
+    registerToolWithTelemetry(server, "wait_for_flowpoint", {
+        description: "Block until a flowpoint matching the criteria arrives, or timeout.\n" +
+            "PURPOSE: deterministic synchronization for drive-then-verify — act first, then block on the flow's " +
+            "terminal step instead of sleeping and re-polling.\n" +
+            "WHEN TO USE: after tapping/driving an instrumented flow, with the flow's terminal step.\n" +
+            "Points emitted after your action but before this call still match (only points already " +
+            "seen by a previous flowpoint tool call are excluded).\n" +
+            "On timeout, returns whatever points DID arrive for the flow — that partial trail is the " +
+            "diagnostic for what stalled.\n" +
+            'SEE ALSO: get_usage_guide(topic="flowpoints").',
+        inputSchema: {
+            name: z.string().describe("Flow name to watch."),
+            step: z.string().optional().describe("Step label to wait for (exact match). Omit to match any step."),
+            level: z.enum(["info", "warn", "error"]).optional().describe("Only match this severity."),
+            metaIncludes: z
+                .string()
+                .optional()
+                .describe("Case-insensitive substring the stringified meta must contain."),
+            timeoutMs: z.number().optional().default(5000).describe("Max wait in ms (default 5000, cap 30000)."),
+            device: deviceParam,
+        },
+    }, async ({ name, step, level, metaIncludes, timeoutMs, device }) => {
+        const effectiveTimeout = Math.min(timeoutMs, 30000);
+        const deviceName = resolveTargetDeviceName(device);
+        const store = getFlowpointStore(deviceName);
+        const baselineEntry = store.entries.length > 0 ? store.entries[store.entries.length - 1] : null;
+        const start = Date.now();
+        const deadline = start + effectiveTimeout;
+        const freshEntries = () => {
+            const startIdx = baselineEntry ? store.entries.indexOf(baselineEntry) + 1 : 0;
+            return store.entries.slice(startIdx).filter((e) => e.name === name);
+        };
+        for (;;) {
+            const remaining = deadline - Date.now();
+            if (remaining > 0) {
+                const drained = await Promise.race([
+                    drainFlowpoints(deviceName, device),
+                    new Promise((resolve) => setTimeout(() => resolve(null), remaining)),
+                ]);
+                if (drained && !drained.ok) {
+                    return { isError: true, content: [{ type: "text", text: drained.error }] };
+                }
+            }
+            const fresh = freshEntries();
+            const match = fresh.find((e) => matchesPoint(e, { step, level, metaIncludes }));
+            if (match) {
+                const meta = match.meta !== undefined ? `\nmeta: ${formatMeta(match.meta)}` : "";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Matched after ${Date.now() - start}ms: flow "${match.name}" ` +
+                                `run ${match.run} step "${match.step}" [${match.level}]${meta}`,
+                        },
+                    ],
+                };
+            }
+            if (Date.now() >= deadline) {
+                const trail = fresh.length
+                    ? `Points that DID arrive for "${name}" during the wait:\n\n${formatFlowpoints(fresh)}`
+                    : `No new points arrived for flow "${name}" during the wait.`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Timeout after ${effectiveTimeout}ms waiting for flow "${name}"${step ? ` step "${step}"` : ""}.\n${trail}`,
+                        },
+                    ],
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(1, deadline - Date.now()))));
+        }
+    });
+    registerToolWithTelemetry(server, "verify_flow", {
+        description: "Assert a flow behaved as expected: compare the actual flowpoint trail of one run " +
+            "against an expected step sequence and get a factual PASS/FAIL diff.\n" +
+            "PURPOSE: factual PASS/FAIL assertion of a flow run against an expected step sequence.\n" +
+            "WHEN TO USE: after wait_for_flowpoint confirms the flow finished; or write the expectation first " +
+            "(runtime TDD) and iterate until PASS.\n" +
+            "Matching is subsequence: expected steps must appear in order; extra points in between " +
+            "are fine. Any unexpected error-level point fails the run unless allowErrors is true or " +
+            "that step is explicitly expected.\n" +
+            "WORKFLOW: write the expected sequence (even before implementing — runtime TDD), drive " +
+            "the flow, wait_for_flowpoint on the terminal step, then verify_flow.\n" +
+            'SEE ALSO: get_usage_guide(topic="flowpoints").',
+        inputSchema: {
+            name: z.string().describe("Flow name to verify."),
+            expect: z
+                .array(z.union([
+                z.string(),
+                z.object({
+                    step: z.string(),
+                    level: z.enum(["info", "warn", "error"]).optional(),
+                    metaIncludes: z.string().optional(),
+                }),
+            ]))
+                .describe("Expected step sequence, in order. Strings are shorthand for { step }."),
+            run: z.string().optional().default("last").describe("Run id to check, or 'last' (default)."),
+            allowErrors: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Tolerate unexpected error-level points (default false)."),
+            device: deviceParam,
+        },
+    }, async ({ name, expect: expected, run, allowErrors, device }) => {
+        const deviceName = resolveTargetDeviceName(device);
+        const drained = await drainFlowpoints(deviceName, device);
+        if (!drained.ok) {
+            return { isError: true, content: [{ type: "text", text: drained.error }] };
+        }
+        const sourceEntries = device ? getFlowpointStore(deviceName).entries : allStoredFlowpoints();
+        const flowEntries = sourceEntries.filter((e) => e.name === name);
+        if (flowEntries.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No flowpoints recorded for flow "${name}".\n\n${NO_FLOWPOINTS_HINT}`,
+                    },
+                ],
+            };
+        }
+        const runId = run === "last" || run === undefined ? resolveLastRuns(flowEntries).get(name) : run;
+        const runEntries = flowEntries.filter((e) => e.run === runId);
+        if (runEntries.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `No entries for flow "${name}" run "${runId}".` }],
+            };
+        }
+        const result = verifyFlow(name, runId, runEntries, expected, allowErrors ?? false);
+        // A FAIL verdict is a successful verification, not a tool error — never set isError for it.
+        return { content: [{ type: "text", text: result.text }] };
+    });
+}
+//# sourceMappingURL=flowpointTools.js.map

package/build/pro/flowpointTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowpointTools.js","sourceRoot":"","sources":["../../src/pro/flowpointTools.ts"],"names":[],"mappings":"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"}

package/build/pro/flowpoints.d.ts

@@ -0,0 +1,86 @@
+export type FlowpointLevel = "info" | "warn" | "error";
+export interface FlowpointEntry {
+    seq: number;
+    t: number;
+    name: string;
+    step: string;
+    run: string;
+    level: FlowpointLevel;
+    meta?: unknown;
+}
+export interface FlowpointSnapshot {
+    contextId: string;
+    entries: FlowpointEntry[];
+}
+export declare const FLOWPOINT_STORE_CAP = 2000;
+export interface FlowpointStoreState {
+    entries: FlowpointEntry[];
+    cursor: number;
+    contextId: string | null;
+}
+export declare function createFlowpointStore(): FlowpointStoreState;
+/** Pure drain reducer: diff a full in-app snapshot against the store. Returns entries appended. */
+export declare function applyDrain(store: FlowpointStoreState, snapshot: FlowpointSnapshot): number;
+export declare function buildDrainExpression(): string;
+export declare function buildClearExpression(): string;
+export type FlowpointMissingReason = "uninitialized" | "outdated";
+export declare function parseDrainResult(raw: string): FlowpointSnapshot | {
+    missing: true;
+    reason: FlowpointMissingReason;
+} | null;
+export interface FlowpointFilters {
+    name?: string;
+    step?: string;
+    run?: string;
+    level?: FlowpointLevel;
+    metaIncludes?: string;
+    since?: number;
+    limit?: number;
+}
+export declare function formatMeta(meta: unknown): string;
+export interface PointMatch {
+    step?: string;
+    level?: FlowpointLevel;
+    metaIncludes?: string;
+}
+export declare function matchesPoint(entry: FlowpointEntry, match: PointMatch): boolean;
+/** Per flow name, the run id of the chronologically last entry. Assumes entries sorted by t. */
+export declare function resolveLastRuns(entries: FlowpointEntry[]): Map<string, string>;
+export declare function filterFlowpoints(entries: FlowpointEntry[], filters: FlowpointFilters): FlowpointEntry[];
+/** Compact grouped text: flow → run → points with inter-point deltas. Assumes entries sorted by t. */
+export declare function formatFlowpoints(entries: FlowpointEntry[]): string;
+export declare function getFlowpointStore(deviceName: string): FlowpointStoreState;
+/** All stored entries across devices, sorted chronologically. */
+export declare function allStoredFlowpoints(): FlowpointEntry[];
+/**
+ * Remove entries from the server stores. Cursors/contextIds are kept so cleared
+ * entries never re-drain. When deviceName is given, only that device's store is
+ * touched; otherwise all stores are.
+ */
+export declare function clearFlowpointStores(name?: string, deviceName?: string): number;
+export declare const SDK_FLOWPOINTS_MISSING: string;
+export declare const SDK_FLOWPOINTS_OUTDATED: string;
+export type DrainOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    sdkMissing?: boolean;
+};
+export declare function drainFlowpoints(deviceName: string, device?: string): Promise<DrainOutcome>;
+export type ExpectStep = string | {
+    step: string;
+    level?: FlowpointLevel;
+    metaIncludes?: string;
+};
+export interface VerifyOutcome {
+    pass: boolean;
+    text: string;
+}
+/**
+ * Subsequence assertion: expected steps must appear in order within the run; extra
+ * points in between are allowed. Unexpected error-level points fail the verification
+ * unless allowErrors is true or the error point matched an expected step.
+ */
+export declare function verifyFlow(name: string, runId: string, runEntries: FlowpointEntry[], expect: ExpectStep[], allowErrors: boolean): VerifyOutcome;
+//# sourceMappingURL=flowpoints.d.ts.map

package/build/pro/flowpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowpoints.d.ts","sourceRoot":"","sources":["../../src/pro/flowpoints.ts"],"names":[],"mappings":"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"}

package/build/pro/flowpoints.js

@@ -0,0 +1,283 @@
+import { executeInApp } from "../core/executor.js";
+import { pushLogBox } from "../core/logbox.js";
+export const FLOWPOINT_STORE_CAP = 2000;
+export function createFlowpointStore() {
+    return { entries: [], cursor: 0, contextId: null };
+}
+/** Pure drain reducer: diff a full in-app snapshot against the store. Returns entries appended. */
+export function applyDrain(store, snapshot) {
+    const reset = store.contextId !== snapshot.contextId;
+    const fresh = reset ? snapshot.entries : snapshot.entries.filter((e) => e.seq > store.cursor);
+    store.entries.push(...fresh);
+    if (store.entries.length > FLOWPOINT_STORE_CAP) {
+        store.entries.splice(0, store.entries.length - FLOWPOINT_STORE_CAP);
+    }
+    const maxSeq = snapshot.entries.reduce((m, e) => Math.max(m, e.seq), 0);
+    store.cursor = reset ? maxSeq : Math.max(store.cursor, maxSeq);
+    store.contextId = snapshot.contextId;
+    return fresh.length;
+}
+export function buildDrainExpression() {
+    return `(() => {
+        const g = globalThis.__EXECBRO__ ?? globalThis.__RN_AI_DEVTOOLS__;
+        if (!g || typeof g.getFlowpointSnapshot !== "function") {
+            const reason = g ? "outdated" : "uninitialized";
+            if (!globalThis.__EXECBRO_FLOWPOINT_WARNED__) {
+                globalThis.__EXECBRO_FLOWPOINT_WARNED__ = true;
+                console.warn(reason === "outdated"
+                    ? "[execbro] An AI agent tried to use flowpoints, but this app's execbro-sdk version does not support them. Upgrade it: npm install execbro-sdk@latest, then reload."
+                    : "[execbro] An AI agent tried to use flowpoints, but execbro-sdk is not initialized. Install it (npm install execbro-sdk) and call init() at app start.");
+            }
+            return JSON.stringify({ __missing: true, __reason: reason });
+        }
+        const s = g.getFlowpointSnapshot();
+        const entries = s.entries.map((e) => {
+            try { JSON.stringify(e.meta); return e; }
+            catch { return Object.assign({}, e, { meta: { __error: "meta not JSON-serializable" } }); }
+        });
+        return JSON.stringify({ contextId: s.contextId, entries });
+    })()`;
+}
+export function buildClearExpression() {
+    return `(() => {
+        const g = globalThis.__EXECBRO__ ?? globalThis.__RN_AI_DEVTOOLS__;
+        return g && typeof g.clearFlowpoints === "function" ? String(g.clearFlowpoints()) : "0";
+    })()`;
+}
+export function parseDrainResult(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && parsed.__missing === true) {
+            return { missing: true, reason: parsed.__reason === "outdated" ? "outdated" : "uninitialized" };
+        }
+        if (parsed && typeof parsed.contextId === "string" && Array.isArray(parsed.entries)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function formatMeta(meta) {
+    if (meta === undefined)
+        return "";
+    if (typeof meta === "string")
+        return meta;
+    try {
+        return JSON.stringify(meta);
+    }
+    catch {
+        return String(meta);
+    }
+}
+export function matchesPoint(entry, match) {
+    if (match.step !== undefined && entry.step !== match.step)
+        return false;
+    if (match.level !== undefined && entry.level !== match.level)
+        return false;
+    if (match.metaIncludes !== undefined &&
+        !formatMeta(entry.meta).toLowerCase().includes(match.metaIncludes.toLowerCase())) {
+        return false;
+    }
+    return true;
+}
+/** Per flow name, the run id of the chronologically last entry. Assumes entries sorted by t. */
+export function resolveLastRuns(entries) {
+    const last = new Map();
+    for (const entry of entries) {
+        last.set(entry.name, entry.run);
+    }
+    return last;
+}
+export function filterFlowpoints(entries, filters) {
+    let result = entries;
+    if (filters.name !== undefined)
+        result = result.filter((e) => e.name === filters.name);
+    if (filters.run === "last") {
+        const lastRuns = resolveLastRuns(result);
+        result = result.filter((e) => lastRuns.get(e.name) === e.run);
+    }
+    else if (filters.run !== undefined) {
+        result = result.filter((e) => e.run === filters.run);
+    }
+    if (filters.step !== undefined)
+        result = result.filter((e) => e.step === filters.step);
+    if (filters.level !== undefined)
+        result = result.filter((e) => e.level === filters.level);
+    if (filters.metaIncludes !== undefined) {
+        const needle = filters.metaIncludes.toLowerCase();
+        result = result.filter((e) => formatMeta(e.meta).toLowerCase().includes(needle));
+    }
+    if (filters.since !== undefined)
+        result = result.filter((e) => e.t > filters.since);
+    const limit = filters.limit ?? 200;
+    if (result.length > limit)
+        result = result.slice(result.length - limit);
+    return result;
+}
+function formatPointLine(entry, t0, indent) {
+    const delta = `+${entry.t - t0}ms`.padEnd(9);
+    const levelPrefix = entry.level !== "info" ? `[${entry.level}] ` : "";
+    const meta = entry.meta !== undefined ? `  ${formatMeta(entry.meta)}` : "";
+    return `${indent}${delta}${levelPrefix}${entry.step}${meta}`;
+}
+function formatRunBlock(runId, runEntries, latest, indent) {
+    const span = runEntries[runEntries.length - 1].t - runEntries[0].t;
+    const label = latest ? ` (latest)` : "";
+    const header = `${indent}run ${runId}${label} — ${runEntries.length} points (${span}ms span):`;
+    const lines = runEntries.map((e) => formatPointLine(e, runEntries[0].t, indent + "  "));
+    return [header, ...lines].join("\n");
+}
+/** Compact grouped text: flow → run → points with inter-point deltas. Assumes entries sorted by t. */
+export function formatFlowpoints(entries) {
+    const lastRuns = resolveLastRuns(entries);
+    const byName = new Map();
+    for (const entry of entries) {
+        let runs = byName.get(entry.name);
+        if (!runs) {
+            runs = new Map();
+            byName.set(entry.name, runs);
+        }
+        let run = runs.get(entry.run);
+        if (!run) {
+            run = [];
+            runs.set(entry.run, run);
+        }
+        run.push(entry);
+    }
+    const blocks = [];
+    for (const [name, runs] of byName) {
+        const runIds = [...runs.keys()];
+        if (runIds.length === 1) {
+            const runEntries = runs.get(runIds[0]);
+            const span = runEntries[runEntries.length - 1].t - runEntries[0].t;
+            const header = `Flow "${name}" run ${runIds[0]} — ${runEntries.length} points (${span}ms span):`;
+            blocks.push([header, ...runEntries.map((e) => formatPointLine(e, runEntries[0].t, "  "))].join("\n"));
+        }
+        else {
+            const header = `Flow "${name}" — ${runIds.length} runs`;
+            const runBlocks = runIds.map((id) => formatRunBlock(id, runs.get(id), id === lastRuns.get(name), "  "));
+            blocks.push([header, ...runBlocks].join("\n"));
+        }
+    }
+    return blocks.join("\n\n");
+}
+const flowpointStores = new Map();
+export function getFlowpointStore(deviceName) {
+    let store = flowpointStores.get(deviceName);
+    if (!store) {
+        store = createFlowpointStore();
+        flowpointStores.set(deviceName, store);
+    }
+    return store;
+}
+/** All stored entries across devices, sorted chronologically. */
+export function allStoredFlowpoints() {
+    const all = [];
+    for (const store of flowpointStores.values()) {
+        all.push(...store.entries);
+    }
+    return all.sort((a, b) => a.t - b.t);
+}
+/**
+ * Remove entries from the server stores. Cursors/contextIds are kept so cleared
+ * entries never re-drain. When deviceName is given, only that device's store is
+ * touched; otherwise all stores are.
+ */
+export function clearFlowpointStores(name, deviceName) {
+    let removed = 0;
+    const stores = deviceName !== undefined ? [getFlowpointStore(deviceName)] : [...flowpointStores.values()];
+    for (const store of stores) {
+        if (name === undefined) {
+            removed += store.entries.length;
+            store.entries = [];
+        }
+        else {
+            const before = store.entries.length;
+            store.entries = store.entries.filter((e) => e.name !== name);
+            removed += before - store.entries.length;
+        }
+    }
+    return removed;
+}
+const LOGBOX_FLOWPOINTS_OUTDATED = "An AI agent tried to use flowpoints, but this app's execbro-sdk version does not support them.\n" +
+    "Upgrade it: npm install execbro-sdk@latest, then rebuild/reload.";
+const LOGBOX_FLOWPOINTS_UNINITIALIZED = "An AI agent tried to use flowpoints, but execbro-sdk is not initialized.\n" +
+    "Install it (npm install execbro-sdk) and call init() at app start.";
+// Once per device+reason per server session — LogBox banners must not repeat on every poll.
+const flowpointLogBoxNotified = new Set();
+export const SDK_FLOWPOINTS_MISSING = "Flowpoints require the execbro-sdk: npm install execbro-sdk, call init() at app start, " +
+    "then instrument the flow with flowpoint({ name, step }). Older SDK versions without " +
+    "flowpoint support must be upgraded. A notice with these instructions was also shown on " +
+    'the device (LogBox error banner). See get_usage_guide(topic="flowpoints").';
+export const SDK_FLOWPOINTS_OUTDATED = "This app's execbro-sdk version predates flowpoints. Upgrade it (npm install execbro-sdk@latest), " +
+    "rebuild/reload the app, then retry. A notice with these instructions was also shown on the " +
+    'device (LogBox error banner). See get_usage_guide(topic="flowpoints").';
+export async function drainFlowpoints(deviceName, device) {
+    const result = await executeInApp(buildDrainExpression(), false, { timeoutMs: 5000, originatingToolName: "flowpoints" }, device);
+    if (!result.success) {
+        return { ok: false, error: result.error || "executeInApp failed" };
+    }
+    const parsed = parseDrainResult(result.result ?? "");
+    if (parsed === null) {
+        return { ok: false, error: "Failed to parse flowpoint snapshot from the app" };
+    }
+    if ("missing" in parsed) {
+        const notifyKey = `${deviceName}:${parsed.reason}`;
+        if (!flowpointLogBoxNotified.has(notifyKey)) {
+            flowpointLogBoxNotified.add(notifyKey);
+            await pushLogBox(parsed.reason === "outdated" ? LOGBOX_FLOWPOINTS_OUTDATED : LOGBOX_FLOWPOINTS_UNINITIALIZED, "error", false, "logbox", "Flowpoints", device);
+        }
+        return {
+            ok: false,
+            error: parsed.reason === "outdated" ? SDK_FLOWPOINTS_OUTDATED : SDK_FLOWPOINTS_MISSING,
+            sdkMissing: true,
+        };
+    }
+    applyDrain(getFlowpointStore(deviceName), parsed);
+    return { ok: true };
+}
+/**
+ * Subsequence assertion: expected steps must appear in order within the run; extra
+ * points in between are allowed. Unexpected error-level points fail the verification
+ * unless allowErrors is true or the error point matched an expected step.
+ */
+export function verifyFlow(name, runId, runEntries, expect, allowErrors) {
+    const matchers = expect.map((x) => (typeof x === "string" ? { step: x } : x));
+    const t0 = runEntries.length > 0 ? runEntries[0].t : 0;
+    const matchedIndexes = new Set();
+    const lines = [];
+    let pass = true;
+    let cursor = 0;
+    for (const matcher of matchers) {
+        let found = -1;
+        for (let i = cursor; i < runEntries.length; i++) {
+            if (matchesPoint(runEntries[i], matcher)) {
+                found = i;
+                break;
+            }
+        }
+        if (found === -1) {
+            pass = false;
+            lines.push(`  ✗ ${matcher.step} — not seen`);
+        }
+        else {
+            matchedIndexes.add(found);
+            cursor = found + 1;
+            lines.push(`  ✓ ${matcher.step} (+${runEntries[found].t - t0}ms)`);
+        }
+    }
+    if (!allowErrors) {
+        runEntries.forEach((entry, i) => {
+            if (entry.level === "error" && !matchedIndexes.has(i)) {
+                pass = false;
+                const meta = entry.meta !== undefined ? ` ${formatMeta(entry.meta)}` : "";
+                lines.push(`  ! ${entry.step} [error] (+${entry.t - t0}ms)${meta} — unexpected error point`);
+            }
+        });
+    }
+    const header = `${pass ? "PASS" : "FAIL"} — flow "${name}" run ${runId}:`;
+    return { pass, text: [header, ...lines].join("\n") };
+}
+//# sourceMappingURL=flowpoints.js.map