@buoy-gg/mcp 7.0.77 → 7.0.79

package/README.md

@@ -93,3 +93,13 @@ See the [Chrome Farm guide](https://buoy.gg/buoy/latest/docs/tools/chrome-farm).
 ---
 
 <sub>Part of <a href="https://buoy.gg">Buoy</a>, developer tools that live inside your app. Proprietary software. © Buoy LLC. <a href="https://buoy.gg/terms">Terms</a></sub>
+
+### Native Profiler
+
+Use `native_profile` to start, stop, or take a timed iOS Simulator or Android trace. Use `get_native_profile` to read it by ID. Start a trace, run a flow, then stop in a `finally` step. Needs a Buoy Pro app. iOS needs Xcode on macOS. Android needs adb on Mac or Linux. The report shows hot functions, hot threads, and busy spans. Each span names its source. RSS and frame counts stay unknown when absent. Under 30 frames means too few to judge. Samples cannot find sleeping hangs. [Read the guide](https://buoy.gg/buoy/latest/docs/tools/native-profiler).
+
+### Memory checks
+
+`memory_check` starts or stops a route loop. `get_memory_leaks` reads its report. Checks need Pro and a native dev build with `@buoy-gg/memory-leaks`. Clock is optional for timer counts. Routes needs a mounted `RouteTracker` for loops.
+
+Start returns a `runId`. Poll for results. The report shows suspects, GC proof and byte growth. A suspect is a clue. An empty list without GC proof does not prove clean. See the [Memory Leaks guide](https://buoy.gg/buoy/latest/docs/tools/memory-leaks).

package/dist/SyncClient-gqMRmB79.d.mts

@@ -0,0 +1,374 @@
+import { ToolCapability } from '@buoy-gg/sync-broker';
+
+type AccessLevel = "free" | "pro";
+
+interface SyncClientOptions {
+    /** Token supplied by an embedded host. Never read or write a token file. */
+    dashboardToken?: string;
+    /** Broker URL to connect to. @default http://localhost:42831 */
+    url?: string;
+    /** Broker port to probe/spawn on. @default 42831 */
+    port?: number;
+    /**
+     * If no broker is already running on the port, spawn one in-process so the
+     * MCP server works standalone (no desktop app needed). @default true
+     */
+    autoSpawnBroker?: boolean;
+    /** Default per-action timeout. @default 15000 */
+    actionTimeoutMs?: number;
+    /** Optional logger — writes to stderr by default (stdout is the MCP channel). */
+    log?: (msg: string) => void;
+}
+interface DeviceInfo {
+    deviceId: string;
+    deviceName: string;
+    platform?: string;
+    isConnected: boolean;
+    /** Whether the connected app reported an active Buoy Pro license. */
+    isPro: boolean;
+    /**
+     * The app's tier after admission. New sockets are "checking"; an account
+     * lock is "locked". Older apps report only `isPro`, which maps to Pro
+     * or locked because keys could only grant Pro before the tier split.
+     *
+     * Surfaced so `list_devices` can say WHY the MCP is blocked: "signed in on
+     * the free tier" and "no admitted account" are different problems.
+     */
+    tier: "checking" | "locked" | "free" | "pro";
+    /**
+     * More than one app is registered under this id right now (a pinned
+     * `externalSync.deviceId` copied onto two devices). Actions sent to it
+     * land on an arbitrary one. Broker-computed; false for apps too old to
+     * announce a runtime instance id.
+     */
+    collision: boolean;
+    tools: ToolCapability[];
+}
+/** How the client obtained its broker connection. */
+type BrokerMode = "connected" | "spawned";
+/**
+ * A headless "Dashboard" client of the Buoy sync broker — the same role the
+ * desktop app plays, but driven programmatically by the MCP server. Implements
+ * connect-or-spawn: connects to a running broker (e.g. the desktop app) if one
+ * is up, otherwise hosts its own in-process so it works standalone.
+ */
+declare class SyncClient {
+    private socket;
+    private admitted;
+    /** When this client was made: the startup window for {@link awaitBroker}. */
+    private readonly createdAt;
+    private lockedDevices;
+    private hostAccount;
+    private broker;
+    private readonly url;
+    private readonly port;
+    private readonly actionTimeoutMs;
+    private readonly log;
+    /** Latest capabilities announce per deviceId. */
+    private capabilities;
+    /** Latest device list from the broker's `all-devices-update`. */
+    private devices;
+    /**
+     * The device this session last named explicitly. Agents name a device once,
+     * then leave deviceId out on later calls; with several apps connected every
+     * one of those calls failed ("Multiple devices connected"), which cost a
+     * turn at the start of almost every benchmark run. An explicit id sets it,
+     * and so does the project-folder match in resolveDevice. It never switches on its own: if that device goes away, calls
+     * without an id fail instead of picking another app.
+     */
+    private sessionDevice;
+    /** Latest snapshot payload per `${deviceId}::${toolId}`. */
+    private snapshots;
+    /**
+     * Capture-mode watches this client holds, keyed by snapKey. Stored with
+     * their addressing because they have to be RE-SENT on every reconnect: the
+     * broker keys watch state by socket id, and a reconnect gets a new one.
+     */
+    private watching;
+    /** In-flight actions awaiting a result, keyed by requestId. */
+    private pendingActions;
+    /** Callbacks waiting for the next snapshot of `${deviceId}::${toolId}`. */
+    private snapshotWaiters;
+    /** When each cached snapshot arrived, keyed by snapKey (staleness reporting). */
+    private snapshotAt;
+    /** Liveness per device — see {@link noteTimeout}. */
+    private health;
+    /** Dev-server origin per device — see {@link noteDevServerOrigin}. */
+    private devServerOrigins;
+    /** Newest crash-report console entry id seen per device — see {@link noteCrashReport}. */
+    private crashSeen;
+    /** Lookups still working out a device's dev-server folder (origin probe, then lsof). */
+    private rootLookups;
+    /** Folder each device's dev server runs from — see {@link devServerRoot}. */
+    private devServerRoots;
+    /** Devices whose origin probe already ran (a production bundle has none). */
+    private originProbed;
+    /** Last time each device appeared in the broker's device list. */
+    private lastSeen;
+    private readonly dashboardToken?;
+    constructor(opts?: SyncClientOptions);
+    private readonly autoSpawn;
+    /** Connect to a running broker, or spawn one in-process, then handshake. */
+    start(): Promise<BrokerMode>;
+    private connectSocket;
+    /**
+     * Drop everything remembered about devices that have been gone a while.
+     *
+     * Deliberately NOT on disconnect: a crashed app often drops off the broker,
+     * and its cached console snapshot is the crash evidence — throwing that away
+     * the instant it disconnects would delete the answer. But device ids change
+     * with every simulator erase and fresh dev client, and each one can hold
+     * multi-MB snapshots, so a long-lived server has to forget eventually.
+     */
+    /** Whether the broker admitted this host's Buoy account. */
+    isAdmitted(): boolean;
+    private requireAdmission;
+    private transportLost;
+    private setAdmission;
+    private requireDeviceAccount;
+    private lockDevice;
+    private pruneStaleDevices;
+    /** Disconnect and tear down a spawned broker, if any. */
+    stop(): Promise<void>;
+    /** All devices the broker knows about, merged with their advertised tools. */
+    listDevices(): DeviceInfo[];
+    /** Connected devices only. */
+    connectedDevices(): DeviceInfo[];
+    /** Actions advertised for a tool, with the devices offering it. */
+    toolActions(toolId: string): {
+        deviceId: string;
+        deviceName: string;
+        actions: string[];
+    }[];
+    /**
+     * This project's own connected app, if the broker has admitted it. Picks
+     * nothing for the session; for warming up host tools before the first call.
+     */
+    peekProjectDevice(): string | null;
+    /**
+     * Resolve a concrete target deviceId. If `deviceId` is given it's used as-is.
+     * Otherwise, if exactly one device is connected, that one is chosen; if none
+     * or many, an informative error is thrown (callers can pass "All" explicitly).
+     */
+    resolveDevice(deviceId?: string): string;
+    /**
+     * Resolve a target device AND require the tier the current tool call needs.
+     * Most tools need Buoy Pro; the free ones (access/policy.ts) also take an app
+     * on the free tier. The level comes from the call's scope, set centrally in
+     * server.ts before any handler runs, so a handler can't pick its own. With no
+     * scope (work outside any tool call) the level is Pro. The app's own license
+     * check is the source of truth (the device reports it over the broker); this
+     * just reads it.
+     *
+     * `list_devices` deliberately does NOT call this — a user without access can
+     * still see their device and its tier, which explains what is blocked.
+     */
+    requireProDevice(deviceId?: string): string;
+    /**
+     * The check under every app call (callAction, getSnapshot, the snapshot
+     * cache, lastSync), on top of requireProDevice. A call to a Pro app always
+     * passes. A call to any other app passes only inside a free tool call and
+     * only for the app calls listed in access/policy.ts, so a Pro tool that
+     * forgot requireProDevice still can't act on a free app, and a free tool
+     * can't reach Pro data by any path. Work outside any tool call (reconnects,
+     * health pings) is plumbing and passes.
+     */
+    private checkAppCall;
+    /**
+     * A free app's tap must land on the app, not on Buoy's own panels: their
+     * controls do what Pro tools do. The app side leaves Buoy out of fuzzy
+     * matches but lets an exact testID or nativeTag through, so on a free app an
+     * exact tap goes through only when the app-only screen list shows that
+     * target. Anything this can't prove (a Buoy control, an off-screen target, a
+     * failed read, a broadcast to "All") is refused. Resolves to replacement
+     * params when it narrows the tap (never edits the caller's object, which a
+     * flow reuses on retries). Returns null, without an await, for every call it
+     * doesn't apply to.
+     */
+    private refuseBuoyPanelTap;
+    /**
+     * Whether a result for this device may carry Pro's why-data (render names,
+     * script names, JS origins). True for a Pro key or the Weekend Pass. A free
+     * tool works on a free app too; this decides how much of its result it
+     * gets (access/freeView.ts).
+     */
+    fullResultsFor(deviceId: string): boolean;
+    /**
+     * Whether this device was seen on a tier good enough for the current call,
+     * connected or not. For host controls that keep working after the app
+     * quits or crashes (see hostKit), and for the last-sync fallback.
+     */
+    deviceWasAllowed(deviceId: string): boolean;
+    /**
+     * Where a device stands for `level` (the current call's by default):
+     * connected and allowed ("ready"), not connected ("offline"), connected but
+     * its account not announced yet ("pending"), or announced on a tier without
+     * this access ("denied").
+     */
+    accessState(deviceId: string, level?: AccessLevel): "ready" | "offline" | "pending" | "denied";
+    private healthOf;
+    /** The device answered — it's alive. */
+    private noteOk;
+    /**
+     * The device didn't answer. A crashed app never answers again, so after the
+     * first miss we stop paying the full timeout on every subsequent call.
+     */
+    private noteTimeout;
+    /** True once a device has missed TWO calls and hasn't answered since. */
+    isUnresponsive(deviceId: string): boolean;
+    /**
+     * Full timeout normally; a short one for a device already not answering.
+     *
+     * A single missed call does not trigger the short budget — one slow
+     * `describeScreen` is not a crash. `app.ping` / `app.reloadApp` always get
+     * the full budget (they are the recovery path).
+     *
+     * Escape hatch: every RECOVERY_PROBE_MS a flagged device gets the full
+     * budget again so the short timeout cannot become self-sustaining.
+     */
+    private timeoutFor;
+    /**
+     * Plain-language diagnosis for a device that isn't answering, including the
+     * app's last words if the console tool got a crash flush out in time.
+     *
+     * A silent timeout is the worst possible answer here: the app is on a redbox,
+     * the reason is already captured, and without this the caller reads "timed
+     * out" and keeps retrying the same dead device.
+     */
+    unresponsiveNote(deviceId: string): string;
+    /**
+     * A fresh crash report from the console tool (its crash flush runs as the
+     * app's React tree dies) means actions waiting on that device will likely
+     * never be answered: navigate to a screen that throws used to sit out its
+     * full 15 s. Cut their wait to the short leash instead of failing them at
+     * once, and only after a ping goes unanswered: an ErrorBoundary can catch a
+     * render error and the app lives.
+     */
+    private noteCrashReport;
+    /**
+     * The newest error line the console tool synced for this device, if any.
+     * Reads the cached console snapshot rather than the device (which, by the
+     * time this matters, is not answering).
+     */
+    private lastFatalFor;
+    /** Age of the cached snapshot for a tool, in ms (null = never received). */
+    snapshotAgeMs(toolId: string, deviceId: string): number | null;
+    /**
+     * Remember where a device's bundle came from, reported by core's `app`
+     * adapter while the app is healthy. It is the only way to reload an app that
+     * has crashed: the in-app reload needs the React tree that the crash
+     * destroyed, but the dev server's reload is handled natively.
+     */
+    noteDevServerOrigin(deviceId: string, origin: unknown): void;
+    /**
+     * Ask a freshly-announced device where its bundle came from, once.
+     *
+     * Deliberately eager: this is the piece of information that can ONLY be
+     * collected while the app is healthy, and is only ever needed after it has
+     * stopped answering. One cheap round-trip per device buys the ability to
+     * recover a crashed app instead of telling the caller to go do it by hand.
+     */
+    private learnDevServerOrigin;
+    private trackRootLookup;
+    /**
+     * Wait (briefly) for project-folder lookups still running, so an agent's
+     * first call right after apps connect can still be matched to this
+     * project's app instead of failing with "Multiple devices connected". Only
+     * worth it when no device is chosen yet and several apps are connected.
+     */
+    /**
+     * Right after the MCP starts, the broker may not have admitted this client
+     * yet: a first call then failed with "A verified Buoy account ... required"
+     * although the account is fine. Every call gives admission (and the first
+     * device list) a moment; once admitted this returns at once.
+     */
+    awaitBroker(): Promise<void>;
+    settleDeviceChoice(maxMs?: number): Promise<void>;
+    /** The dev-server origin last reported by this device, if any. */
+    devServerOrigin(deviceId: string): string | null;
+    /**
+     * Keep the device RECORDING this tool, without asking it to stream.
+     *
+     * A dashboard watches for as long as its panel is open; this client is
+     * request/response, so it used to watch and unwatch around every single
+     * read. That works for a tool whose state just IS (the query cache, the env
+     * table) and is useless for one that records a timeline: the unwatch drops
+     * the device's subscriber count to zero, which stops capture, so nothing is
+     * ever recorded between two reads. The list comes back empty and reads as
+     * "the app made no requests" — a wrong conclusion that is very expensive to
+     * chase, because everything about the app looks fine.
+     *
+     * Capture-mode watches are held for the life of the connection and released
+     * on disconnect (the broker also drops them for us). They cost the device's
+     * ring buffer, not the socket: no snapshot is pushed, and reads still go
+     * through `request-devtool-state`.
+     */
+    private ensureWatching;
+    private sendWatch;
+    /**
+     * Re-arm every held watch after a reconnect.
+     *
+     * The broker tracks watches per SOCKET, so a reconnect (broker restart, a
+     * dropped wifi link) silently discards all of ours while `watching` still
+     * says we hold them — `ensureWatching` would then short-circuit forever and
+     * the device would never record again. Silent and permanent: the exact
+     * failure this whole capture-mode change exists to remove.
+     */
+    private rearmWatches;
+    /** Each device's current connection (socket id + nonce), to spot a reload. */
+    private deviceConnections;
+    /**
+     * Re-arm the watches for a device that came back on a NEW connection.
+     *
+     * A relaunch or JS reload gives the app a fresh socket and fresh adapters,
+     * whose capture starts switched off. Our watches still say "held", so
+     * `ensureWatching` short-circuited and the device never recorded again: after
+     * one restart, the storage timeline stayed empty for the rest of the session
+     * (found by the BK storage suite — every case after a relaunch read nothing).
+     */
+    private rearmReconnectedDevices;
+    /** Stop streaming a tool (releases the device-side backpressure). */
+    unwatch(toolId: string, targetDeviceId: string): void;
+    /** Last snapshot received for a tool/device, if any. */
+    cachedSnapshot(toolId: string, deviceId: string): unknown;
+    /**
+     * Get a tool's current state: arm capture (once, for the connection), ask
+     * for state explicitly, and resolve with the snapshot that comes back.
+     * Falls back to the last cached snapshot if the request times out.
+     *
+     * The capture watch is deliberately NOT released afterwards — see
+     * `ensureWatching`. It costs the device nothing on the socket, and dropping
+     * it is what made every timeline tool look permanently empty from here.
+     */
+    getSnapshot(toolId: string, deviceId?: string, opts?: {
+        timeoutMs?: number;
+        silent?: boolean;
+    }): Promise<{
+        deviceId: string;
+        payload: unknown;
+        stale?: string;
+    }>;
+    /**
+     * The last snapshot a device sent for a tool, kept after the device drops
+     * off. A fatal render error tears down the app's React tree, and Buoy's
+     * connection with it; @buoy-gg/console flushes its logs out first, so this
+     * is where the app's last words are once it can no longer be asked.
+     */
+    lastSync(deviceId: string, toolId: string): {
+        payload: unknown;
+        ageMs: number | null;
+    } | undefined;
+    /** Header line for data served from cache because the device went quiet. */
+    private staleNote;
+    private waitForSnapshot;
+    /**
+     * Invoke a remote action on a device and await its result. Pass deviceId to
+     * target one device, or "All" to broadcast (resolves with the first responder).
+     */
+    callAction(toolId: string, action: string, params?: unknown, deviceId?: string, opts?: {
+        timeoutMs?: number;
+        silent?: boolean;
+    }): Promise<unknown>;
+}
+
+export { type BrokerMode as B, type DeviceInfo as D, SyncClient as S, type SyncClientOptions as a };