@phren/cli 0.3.57 → 0.3.58
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bridge/computer-identity.d.ts +4 -2
- package/dist/bridge/computer-identity.js +7 -3
- package/dist/bridge/conductor-group.d.ts +1 -1
- package/dist/bridge/conductor-group.js +2 -2
- package/dist/bridge/conductor-sets.d.ts +6 -0
- package/dist/bridge/conductor-sets.js +8 -2
- package/dist/bridge/server-routes.d.ts +1 -0
- package/dist/bridge/server-routes.js +1 -1
- package/dist/bridge/server.js +6 -1
- package/dist/bridge/simulator-stream.d.ts +118 -0
- package/dist/bridge/simulator-stream.js +284 -0
- package/dist/bridge/simulators.d.ts +12 -0
- package/dist/bridge/simulators.js +32 -26
- package/dist/bridge-hook.mjs +1039 -667
- package/dist/modules/registry.js +2 -2
- package/package.json +1 -1
|
@@ -39,8 +39,10 @@ export declare function computerLabel(name: string): string;
|
|
|
39
39
|
/** Folds what this Hook knows into one row per real computer. A machines.yaml
|
|
40
40
|
* name joins a computer when its first label matches any name that computer
|
|
41
41
|
* has, or when it shares a profile with names already folded into exactly one
|
|
42
|
-
*
|
|
43
|
-
*
|
|
42
|
+
* peer (a profile two computers claim folds nothing). This computer knows its
|
|
43
|
+
* own names, so a name matching none of them is another machine even when it
|
|
44
|
+
* shares this computer's profile. The rest become unlinked rows: names
|
|
45
|
+
* sharing a label or a profile are one computer. */
|
|
44
46
|
export declare function foldComputers(facts: IdentityFacts, options?: {
|
|
45
47
|
trusted?: boolean;
|
|
46
48
|
}): Computer[];
|
|
@@ -28,8 +28,10 @@ function addAlias(row, name, rows = [row]) {
|
|
|
28
28
|
/** Folds what this Hook knows into one row per real computer. A machines.yaml
|
|
29
29
|
* name joins a computer when its first label matches any name that computer
|
|
30
30
|
* has, or when it shares a profile with names already folded into exactly one
|
|
31
|
-
*
|
|
32
|
-
*
|
|
31
|
+
* peer (a profile two computers claim folds nothing). This computer knows its
|
|
32
|
+
* own names, so a name matching none of them is another machine even when it
|
|
33
|
+
* shares this computer's profile. The rest become unlinked rows: names
|
|
34
|
+
* sharing a label or a profile are one computer. */
|
|
33
35
|
export function foldComputers(facts, options = {}) {
|
|
34
36
|
const localName = facts.local.names.find(name => !name.includes(".")) ?? facts.local.names[0] ?? "local";
|
|
35
37
|
const linked = [{ ...(facts.local.id ? { id: facts.local.id } : {}), name: localName, aliases: [], local: true, linked: true, reachable: true }];
|
|
@@ -73,7 +75,9 @@ export function foldComputers(facts, options = {}) {
|
|
|
73
75
|
const unfolded = [];
|
|
74
76
|
for (const [name, profile] of rest) {
|
|
75
77
|
const claimed = claims.get(profile);
|
|
76
|
-
|
|
78
|
+
// A MacBook Air set up with this Linux box's profile is not this box: it
|
|
79
|
+
// became an alias here and the box called itself "air" in its own set.
|
|
80
|
+
if (claimed?.size === 1 && ![...claimed][0].local)
|
|
77
81
|
fold([...claimed][0], name, profile, false);
|
|
78
82
|
else
|
|
79
83
|
unfolded.push([name, profile]);
|
|
@@ -37,7 +37,7 @@ export type PeerAnswer = {
|
|
|
37
37
|
/** Its conductor module is off, so it cannot run a conductor. */
|
|
38
38
|
disabled?: boolean;
|
|
39
39
|
});
|
|
40
|
-
export declare function askPeers(peers: readonly HookPeer[], caller: Caller, ask?: Ask): Promise<PeerAnswer[]>;
|
|
40
|
+
export declare function askPeers(peers: readonly HookPeer[], caller: Caller, ask?: Ask, timeout?: number): Promise<PeerAnswer[]>;
|
|
41
41
|
export interface GroupConductor {
|
|
42
42
|
/** A live conductor on a member of this computer's set. */
|
|
43
43
|
found?: {
|
|
@@ -11,10 +11,10 @@ export async function localCaller() {
|
|
|
11
11
|
export function callerQuery(caller) {
|
|
12
12
|
return new URLSearchParams({ name: caller.name, ...(caller.hostKey ? { hostKey: caller.hostKey } : {}) }).toString();
|
|
13
13
|
}
|
|
14
|
-
export async function askPeers(peers, caller, ask = peerRequest) {
|
|
14
|
+
export async function askPeers(peers, caller, ask = peerRequest, timeout = 8_000) {
|
|
15
15
|
return Promise.all(peers.map(async (peer) => {
|
|
16
16
|
try {
|
|
17
|
-
const answer = await ask(peer, `/v1/conductor?${callerQuery(caller)}`, undefined,
|
|
17
|
+
const answer = await ask(peer, `/v1/conductor?${callerQuery(caller)}`, undefined, timeout);
|
|
18
18
|
const computer = object(answer.computer);
|
|
19
19
|
const conductor = answer.conductor && typeof answer.conductor === "object" ? object(answer.conductor) : undefined;
|
|
20
20
|
const set = object(answer.set);
|
|
@@ -13,6 +13,12 @@ interface LocalInfo {
|
|
|
13
13
|
* says whether this computer lists the caller back. */
|
|
14
14
|
export declare function conductorAnswer(info: LocalInfo, url: URL): Promise<Json>;
|
|
15
15
|
/** `GET /v1/sets`: this computer's set and every set its one-way peers are in, plus unlinked computers. */
|
|
16
|
+
/** How long the sets view waits for each peer. A live peer answers in a
|
|
17
|
+
* second or two; an unreachable one held every reading of the view for the
|
|
18
|
+
* full 8 s, and the phone, which reads every computer's sets, gave up on
|
|
19
|
+
* the slow ones and showed linked computers as unlinked. A peer past this
|
|
20
|
+
* shows as unreachable in this reading only; conductor checks keep 8 s. */
|
|
21
|
+
export declare const SETS_PEER_TIMEOUT_MS = 4000;
|
|
16
22
|
export declare function readSets(info: LocalInfo): Promise<Json>;
|
|
17
23
|
/** `POST /v1/sets/name`: names this computer's set. The owner's call is sent
|
|
18
24
|
* on to every reachable member; a member's relay (with `namedAt`) is kept
|
|
@@ -19,10 +19,16 @@ export async function conductorAnswer(info, url) {
|
|
|
19
19
|
...(caller.name || caller.hostKey ? { knowsCaller: links.knowsCaller } : {}), ...(set ? { set } : {}) };
|
|
20
20
|
}
|
|
21
21
|
/** `GET /v1/sets`: this computer's set and every set its one-way peers are in, plus unlinked computers. */
|
|
22
|
+
/** How long the sets view waits for each peer. A live peer answers in a
|
|
23
|
+
* second or two; an unreachable one held every reading of the view for the
|
|
24
|
+
* full 8 s, and the phone, which reads every computer's sets, gave up on
|
|
25
|
+
* the slow ones and showed linked computers as unlinked. A peer past this
|
|
26
|
+
* shows as unreachable in this reading only; conductor checks keep 8 s. */
|
|
27
|
+
export const SETS_PEER_TIMEOUT_MS = 4_000;
|
|
22
28
|
export async function readSets(info) {
|
|
23
29
|
const [{ peers, peerError }, conductor, set, { computers }] = await Promise.all([optionalHookPeers(), localConductor(), readSetName(),
|
|
24
30
|
readComputers({ local: { id: info.computer.id } })]);
|
|
25
|
-
const answers = await askPeers(peers, await localCaller());
|
|
31
|
+
const answers = await askPeers(peers, await localCaller(), undefined, SETS_PEER_TIMEOUT_MS);
|
|
26
32
|
// Old /v1/conductor replies list peer names without ids. Resolve unknown
|
|
27
33
|
// names through the existing identity directory, also on older Hooks.
|
|
28
34
|
// Skip this extra round when names already identify every member.
|
|
@@ -31,7 +37,7 @@ export async function readSets(info) {
|
|
|
31
37
|
if (!answer.ok || answer.knowsCaller === false || !answer.peers?.some(name => indirect.has(computerLabel(name))))
|
|
32
38
|
return [];
|
|
33
39
|
try {
|
|
34
|
-
const directory = await peerRequest(answer.peer, "/v1/computers", undefined,
|
|
40
|
+
const directory = await peerRequest(answer.peer, "/v1/computers", undefined, 2 * SETS_PEER_TIMEOUT_MS);
|
|
35
41
|
return (Array.isArray(directory.computers) ? directory.computers.slice(0, 64) : []).flatMap(value => {
|
|
36
42
|
const row = object(value);
|
|
37
43
|
return typeof row.id === "string" && typeof row.name === "string" ? [{ id: row.id, name: row.name,
|
|
@@ -89,7 +89,7 @@ async function childActivity(source, session) {
|
|
|
89
89
|
export const capabilities = { transcript: true, progress: true, images: true, prompt: true, stop: true,
|
|
90
90
|
terminal: "ssh-pty", shell: "ssh-pty", paneTerminal: "ssh-pty", paneLayout: true, deskPresence: true, herdr: true, sessionRename: true, diff: true, webServers: true, webPreview: "ssh-exec", activity: true,
|
|
91
91
|
approvals: true, questions: false, accountUsage: true, providers: ["codex", "claude", "copilot", "opencode"],
|
|
92
|
-
files: true, repositoryFiles: true, fileResolution: true, subagents: true, sideQuestions: true, dispatch: true, conductorSets: true, setLink: true, ownerInbox: true, workerReports: true, queuedHandOff: true, approvalPush: "direct-apns", simulators: process.platform === "darwin", code: true, codeFiles: true, overviewStream: true, speech: true, speechTimestamps: true, speechTimestampStream: true, speechLive: true, speechVoices: true, speechFormats: [...SPEECH_FORMATS], transcribe: true, memoryStore: true, promptOnce: true, promptStatus: true, deliveryFrames: true, paneDeliveries: true, resources: true, sudo: true, sudoOutcome: true, previewDeltas: true, quickChat: true, agentFolder: true, launchPermissionMode: true, sessionMove: true, moveNewChat: true, moveConductor: true, moveToComputer: true, moveConductorToComputer: true, moveResume: true, claudeAccountAdd: true, workerRelocation: 1, projectMemory: true, fileWrite: true, fileSearch: true, gitReview: true, memoryStoreBatch: true, gitHosts: true, projectHostToken: true };
|
|
92
|
+
files: true, repositoryFiles: true, fileResolution: true, subagents: true, sideQuestions: true, dispatch: true, conductorSets: true, setLink: true, ownerInbox: true, workerReports: true, queuedHandOff: true, approvalPush: "direct-apns", simulators: process.platform === "darwin", simulatorStream: process.platform === "darwin", code: true, codeFiles: true, overviewStream: true, speech: true, speechTimestamps: true, speechTimestampStream: true, speechLive: true, speechVoices: true, speechFormats: [...SPEECH_FORMATS], transcribe: true, memoryStore: true, promptOnce: true, promptStatus: true, deliveryFrames: true, paneDeliveries: true, resources: true, sudo: true, sudoOutcome: true, previewDeltas: true, quickChat: true, agentFolder: true, launchPermissionMode: true, sessionMove: true, moveNewChat: true, moveConductor: true, moveToComputer: true, moveConductorToComputer: true, moveResume: true, claudeAccountAdd: true, workerRelocation: 1, projectMemory: true, fileWrite: true, fileSearch: true, gitReview: true, memoryStoreBatch: true, gitHosts: true, projectHostToken: true };
|
|
93
93
|
export function capabilitiesForModules(snapshot) {
|
|
94
94
|
const allowed = new Set(snapshot.modules.flatMap(module => module.capabilities));
|
|
95
95
|
const result = Object.fromEntries(Object.entries(capabilities).filter(([name]) => allowed.has(name)));
|
package/dist/bridge/server.js
CHANGED
|
@@ -24,6 +24,7 @@ import { cpus, hostname, loadavg } from "node:os";
|
|
|
24
24
|
import path from "node:path";
|
|
25
25
|
import { WebSocketServer } from "ws";
|
|
26
26
|
import { relayLiveSpeech } from "./speech-live.js";
|
|
27
|
+
import { streamSimulator } from "./simulator-stream.js";
|
|
27
28
|
import { failRelay, relayTranscription } from "./speech-transcribe.js";
|
|
28
29
|
import { ActivityJournal } from "./activity.js";
|
|
29
30
|
import { countTick } from "./metrics.js";
|
|
@@ -280,7 +281,7 @@ export async function serve(version, options = {}) {
|
|
|
280
281
|
http.on("upgrade", (request, socket, head) => {
|
|
281
282
|
try {
|
|
282
283
|
const url = new URL(request.url || "/", "http://phren.local");
|
|
283
|
-
if (!["/v1/transcripts", "/v1/status", "/v1/overview", "/v1/speech/transcribe", "/v1/speech/live"].includes(url.pathname) || url.origin !== "http://phren.local") {
|
|
284
|
+
if (!["/v1/transcripts", "/v1/status", "/v1/overview", "/v1/speech/transcribe", "/v1/speech/live", "/v1/simulators/stream"].includes(url.pathname) || url.origin !== "http://phren.local") {
|
|
284
285
|
socket.destroy();
|
|
285
286
|
return;
|
|
286
287
|
}
|
|
@@ -305,6 +306,10 @@ export async function serve(version, options = {}) {
|
|
|
305
306
|
void relayTranscription(client, url.searchParams).catch(() => failRelay(client));
|
|
306
307
|
return;
|
|
307
308
|
}
|
|
309
|
+
if (url.pathname === "/v1/simulators/stream") {
|
|
310
|
+
void streamSimulator(client, url.searchParams).catch(() => client.close(1011, "Simulator stream unavailable"));
|
|
311
|
+
return;
|
|
312
|
+
}
|
|
308
313
|
if (url.pathname === "/v1/speech/live") {
|
|
309
314
|
void relayLiveSpeech(client, url.searchParams).catch(() => client.close(1011, "Spoken replies unavailable"));
|
|
310
315
|
return;
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import type { Readable } from "node:stream";
|
|
2
|
+
import { type Json } from "./protocol.js";
|
|
3
|
+
/**
|
|
4
|
+
* `WS /v1/simulators/stream?udid=&fps=&size=&quality=`: one booted
|
|
5
|
+
* simulator's screen, live. The native helper (native/simcast.swift) reads the
|
|
6
|
+
* device's framebuffer through CoreSimulator, as `simctl io` does, and writes
|
|
7
|
+
* each changed frame as a length-prefixed JPEG; this side forwards them.
|
|
8
|
+
*
|
|
9
|
+
* Why JPEG frames from the framebuffer, not the alternatives:
|
|
10
|
+
* - `simctl io screenshot` took about 1.1 s a shot (Xcode 27.1, M1 Max),
|
|
11
|
+
* which is today's 1 fps poll and no more.
|
|
12
|
+
* - `simctl io recordVideo` writes a QuickTime movie that is only readable
|
|
13
|
+
* once finalized, so it cannot feed a live socket.
|
|
14
|
+
* - ScreenCaptureKit on the Simulator window needs a Screen Recording grant
|
|
15
|
+
* (which macOS re-asks for monthly), captures the window chrome, and stops
|
|
16
|
+
* when the window is minimized; the framebuffer needs no grant.
|
|
17
|
+
* - H.264 halves the bytes but ties frames together: a dropped frame corrupts
|
|
18
|
+
* the picture until the next keyframe, so "always the latest frame" would
|
|
19
|
+
* need keyframe requests across the socket. Every JPEG stands alone, so a
|
|
20
|
+
* frame the phone can't take yet is simply replaced by the next one.
|
|
21
|
+
* - The helper sends only frames whose framebuffer changed (its IOSurface
|
|
22
|
+
* seed moved): a still screen costs nothing on the wire.
|
|
23
|
+
*
|
|
24
|
+
* Frames: a text `{ type: "start", format: "jpeg", fps, size, quality, ack }`,
|
|
25
|
+
* then one binary message per frame, each a whole JPEG. A phone that asks
|
|
26
|
+
* with `ack=1` sends `{ type: "ack" }` for each frame it receives, and at
|
|
27
|
+
* most two frames are unacknowledged: the SSH channel and TCP buffers between
|
|
28
|
+
* here and the phone then never hold more than that, so what the phone shows
|
|
29
|
+
* is at most two frames old however slow the link. Without it, a frame is
|
|
30
|
+
* done once written to the gateway's socket. When the stream
|
|
31
|
+
* ends, the socket closes with the reason (1008 for a bad request, 1011 when
|
|
32
|
+
* capture failed); the phone then falls back to `/v1/simulators/screenshot`.
|
|
33
|
+
* Closing the socket stops the helper. Taps and keys stay on
|
|
34
|
+
* `/v1/simulators/action`.
|
|
35
|
+
*/
|
|
36
|
+
/** A JPEG larger than this is a broken helper, not a frame. */
|
|
37
|
+
export declare const MAX_FRAME_BYTES: number;
|
|
38
|
+
/** The wire budget: about 24 Mbit/s, so animations at full rate on Wi-Fi, and
|
|
39
|
+
* the phone asks for a smaller `size` on a slower link. */
|
|
40
|
+
export declare const STREAM_BYTES_PER_SECOND: number;
|
|
41
|
+
/** Each stream runs its own helper; a few phones may watch at once. */
|
|
42
|
+
export declare const MAX_STREAMS = 4;
|
|
43
|
+
export interface StreamOptions {
|
|
44
|
+
udid: string;
|
|
45
|
+
fps: number;
|
|
46
|
+
size: number;
|
|
47
|
+
quality: number;
|
|
48
|
+
ack: boolean;
|
|
49
|
+
}
|
|
50
|
+
/** Frames in flight when the phone acknowledges them: one decoding on the
|
|
51
|
+
* phone while the next crosses the network. */
|
|
52
|
+
export declare const ACK_WINDOW = 2;
|
|
53
|
+
/** The query, validated before anything runs. */
|
|
54
|
+
export declare function streamOptions(query: URLSearchParams): StreamOptions;
|
|
55
|
+
/** Splits the helper's stdout into frames: a 4-byte big-endian length, then
|
|
56
|
+
* that many bytes. Pipes deliver arbitrary chunks, so a frame may span many. */
|
|
57
|
+
export declare class FrameReader {
|
|
58
|
+
private buffered;
|
|
59
|
+
private bytes;
|
|
60
|
+
push(chunk: Buffer): Buffer[];
|
|
61
|
+
}
|
|
62
|
+
/** Sends the newest frame only. At most `window` frames are in flight (until
|
|
63
|
+
* written, or until acknowledged when `acked`); frames that arrive meanwhile
|
|
64
|
+
* replace the one waiting, so a slow link sees fewer frames, never older
|
|
65
|
+
* ones. A byte budget, refilled continuously with one second of burst, bounds
|
|
66
|
+
* the bitrate the same way. */
|
|
67
|
+
export declare class LatestFrame {
|
|
68
|
+
private send;
|
|
69
|
+
private options;
|
|
70
|
+
private now;
|
|
71
|
+
private waiting?;
|
|
72
|
+
private inFlight;
|
|
73
|
+
private tokens;
|
|
74
|
+
private refilled;
|
|
75
|
+
private timer?;
|
|
76
|
+
private closed;
|
|
77
|
+
sent: number;
|
|
78
|
+
dropped: number;
|
|
79
|
+
constructor(send: (frame: Buffer, done: (error?: Error) => void) => void, options?: {
|
|
80
|
+
bytesPerSecond?: number;
|
|
81
|
+
window?: number;
|
|
82
|
+
acked?: boolean;
|
|
83
|
+
}, now?: () => number);
|
|
84
|
+
offer(frame: Buffer): void;
|
|
85
|
+
/** The phone has a frame; an acknowledgement it owes nothing for is ignored. */
|
|
86
|
+
ack(): void;
|
|
87
|
+
close(): void;
|
|
88
|
+
private get bytesPerSecond();
|
|
89
|
+
private pump;
|
|
90
|
+
}
|
|
91
|
+
/** The phone's socket, or a test double. */
|
|
92
|
+
export interface StreamClient {
|
|
93
|
+
readonly readyState: number;
|
|
94
|
+
send(data: string | Buffer, options: {
|
|
95
|
+
binary: boolean;
|
|
96
|
+
}, done?: (error?: Error) => void): void;
|
|
97
|
+
close(code?: number, reason?: string): void;
|
|
98
|
+
once(event: "close" | "error", listener: () => void): unknown;
|
|
99
|
+
on(event: "message", listener: (data: Buffer, isBinary: boolean) => void): unknown;
|
|
100
|
+
}
|
|
101
|
+
/** The capture process, or a test double. */
|
|
102
|
+
export interface CaptureProcess {
|
|
103
|
+
readonly stdout: Readable | null;
|
|
104
|
+
readonly stderr: Readable | null;
|
|
105
|
+
kill(signal?: NodeJS.Signals): boolean;
|
|
106
|
+
once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
|
|
107
|
+
once(event: "error", listener: (error: Error) => void): unknown;
|
|
108
|
+
}
|
|
109
|
+
export interface StreamDeps {
|
|
110
|
+
booted: () => Promise<Json[]>;
|
|
111
|
+
helper: () => Promise<string>;
|
|
112
|
+
spawn: (binary: string, args: string[]) => CaptureProcess;
|
|
113
|
+
platform: () => NodeJS.Platform;
|
|
114
|
+
bytesPerSecond?: number;
|
|
115
|
+
}
|
|
116
|
+
/** Streams running now, for tests and health. */
|
|
117
|
+
export declare function activeSimulatorStreams(): number;
|
|
118
|
+
export declare function streamSimulator(client: StreamClient, query: URLSearchParams, deps?: StreamDeps): Promise<void>;
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
import { spawn as spawnChild } from "node:child_process";
|
|
2
|
+
import { BridgeError } from "./protocol.js";
|
|
3
|
+
import { bootedSimulators, SIMULATOR_UDID, verifiedHelper } from "./simulators.js";
|
|
4
|
+
/**
|
|
5
|
+
* `WS /v1/simulators/stream?udid=&fps=&size=&quality=`: one booted
|
|
6
|
+
* simulator's screen, live. The native helper (native/simcast.swift) reads the
|
|
7
|
+
* device's framebuffer through CoreSimulator, as `simctl io` does, and writes
|
|
8
|
+
* each changed frame as a length-prefixed JPEG; this side forwards them.
|
|
9
|
+
*
|
|
10
|
+
* Why JPEG frames from the framebuffer, not the alternatives:
|
|
11
|
+
* - `simctl io screenshot` took about 1.1 s a shot (Xcode 27.1, M1 Max),
|
|
12
|
+
* which is today's 1 fps poll and no more.
|
|
13
|
+
* - `simctl io recordVideo` writes a QuickTime movie that is only readable
|
|
14
|
+
* once finalized, so it cannot feed a live socket.
|
|
15
|
+
* - ScreenCaptureKit on the Simulator window needs a Screen Recording grant
|
|
16
|
+
* (which macOS re-asks for monthly), captures the window chrome, and stops
|
|
17
|
+
* when the window is minimized; the framebuffer needs no grant.
|
|
18
|
+
* - H.264 halves the bytes but ties frames together: a dropped frame corrupts
|
|
19
|
+
* the picture until the next keyframe, so "always the latest frame" would
|
|
20
|
+
* need keyframe requests across the socket. Every JPEG stands alone, so a
|
|
21
|
+
* frame the phone can't take yet is simply replaced by the next one.
|
|
22
|
+
* - The helper sends only frames whose framebuffer changed (its IOSurface
|
|
23
|
+
* seed moved): a still screen costs nothing on the wire.
|
|
24
|
+
*
|
|
25
|
+
* Frames: a text `{ type: "start", format: "jpeg", fps, size, quality, ack }`,
|
|
26
|
+
* then one binary message per frame, each a whole JPEG. A phone that asks
|
|
27
|
+
* with `ack=1` sends `{ type: "ack" }` for each frame it receives, and at
|
|
28
|
+
* most two frames are unacknowledged: the SSH channel and TCP buffers between
|
|
29
|
+
* here and the phone then never hold more than that, so what the phone shows
|
|
30
|
+
* is at most two frames old however slow the link. Without it, a frame is
|
|
31
|
+
* done once written to the gateway's socket. When the stream
|
|
32
|
+
* ends, the socket closes with the reason (1008 for a bad request, 1011 when
|
|
33
|
+
* capture failed); the phone then falls back to `/v1/simulators/screenshot`.
|
|
34
|
+
* Closing the socket stops the helper. Taps and keys stay on
|
|
35
|
+
* `/v1/simulators/action`.
|
|
36
|
+
*/
|
|
37
|
+
/** A JPEG larger than this is a broken helper, not a frame. */
|
|
38
|
+
export const MAX_FRAME_BYTES = 4 * 1024 * 1024;
|
|
39
|
+
/** The wire budget: about 24 Mbit/s, so animations at full rate on Wi-Fi, and
|
|
40
|
+
* the phone asks for a smaller `size` on a slower link. */
|
|
41
|
+
export const STREAM_BYTES_PER_SECOND = 3 * 1024 * 1024;
|
|
42
|
+
/** Each stream runs its own helper; a few phones may watch at once. */
|
|
43
|
+
export const MAX_STREAMS = 4;
|
|
44
|
+
const OPEN = 1;
|
|
45
|
+
/** Frames in flight when the phone acknowledges them: one decoding on the
|
|
46
|
+
* phone while the next crosses the network. */
|
|
47
|
+
export const ACK_WINDOW = 2;
|
|
48
|
+
/** The query, validated before anything runs. */
|
|
49
|
+
export function streamOptions(query) {
|
|
50
|
+
const udid = query.get("udid") ?? "";
|
|
51
|
+
if (!SIMULATOR_UDID.test(udid))
|
|
52
|
+
throw new BridgeError(400, "Invalid simulator identifier.");
|
|
53
|
+
const int = (name, fallback, min, max) => {
|
|
54
|
+
const raw = query.get(name);
|
|
55
|
+
if (raw === null)
|
|
56
|
+
return fallback;
|
|
57
|
+
if (!/^\d{1,5}$/.test(raw) || Number(raw) < min || Number(raw) > max)
|
|
58
|
+
throw new BridgeError(400, `${name} must be a whole number from ${min} to ${max}.`);
|
|
59
|
+
return Number(raw);
|
|
60
|
+
};
|
|
61
|
+
// size is the longest side in pixels; quality is the JPEG quality in percent.
|
|
62
|
+
const ack = query.get("ack");
|
|
63
|
+
if (ack !== null && ack !== "1" && ack !== "0")
|
|
64
|
+
throw new BridgeError(400, "ack must be 1 or 0.");
|
|
65
|
+
return { udid: udid.toUpperCase(), fps: int("fps", 24, 1, 30), size: int("size", 1280, 240, 1600), quality: int("quality", 60, 30, 90), ack: ack === "1" };
|
|
66
|
+
}
|
|
67
|
+
/** Splits the helper's stdout into frames: a 4-byte big-endian length, then
|
|
68
|
+
* that many bytes. Pipes deliver arbitrary chunks, so a frame may span many. */
|
|
69
|
+
export class FrameReader {
|
|
70
|
+
buffered = [];
|
|
71
|
+
bytes = 0;
|
|
72
|
+
push(chunk) {
|
|
73
|
+
this.buffered.push(chunk);
|
|
74
|
+
this.bytes += chunk.length;
|
|
75
|
+
const frames = [];
|
|
76
|
+
while (this.bytes >= 4) {
|
|
77
|
+
const head = this.buffered[0].length >= 4 ? this.buffered[0] : Buffer.concat(this.buffered);
|
|
78
|
+
const length = head.readUInt32BE(0);
|
|
79
|
+
if (length === 0 || length > MAX_FRAME_BYTES)
|
|
80
|
+
throw new Error(`frame of ${length} bytes`);
|
|
81
|
+
if (this.bytes < 4 + length)
|
|
82
|
+
break;
|
|
83
|
+
const all = this.buffered.length === 1 ? this.buffered[0] : Buffer.concat(this.buffered);
|
|
84
|
+
frames.push(all.subarray(4, 4 + length));
|
|
85
|
+
const rest = all.subarray(4 + length);
|
|
86
|
+
this.buffered = rest.length ? [rest] : [];
|
|
87
|
+
this.bytes = rest.length;
|
|
88
|
+
}
|
|
89
|
+
return frames;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
/** Sends the newest frame only. At most `window` frames are in flight (until
|
|
93
|
+
* written, or until acknowledged when `acked`); frames that arrive meanwhile
|
|
94
|
+
* replace the one waiting, so a slow link sees fewer frames, never older
|
|
95
|
+
* ones. A byte budget, refilled continuously with one second of burst, bounds
|
|
96
|
+
* the bitrate the same way. */
|
|
97
|
+
export class LatestFrame {
|
|
98
|
+
send;
|
|
99
|
+
options;
|
|
100
|
+
now;
|
|
101
|
+
waiting;
|
|
102
|
+
inFlight = 0;
|
|
103
|
+
tokens;
|
|
104
|
+
refilled;
|
|
105
|
+
timer;
|
|
106
|
+
closed = false;
|
|
107
|
+
sent = 0;
|
|
108
|
+
dropped = 0;
|
|
109
|
+
constructor(send, options = {}, now = Date.now) {
|
|
110
|
+
this.send = send;
|
|
111
|
+
this.options = options;
|
|
112
|
+
this.now = now;
|
|
113
|
+
this.tokens = this.bytesPerSecond;
|
|
114
|
+
this.refilled = now();
|
|
115
|
+
}
|
|
116
|
+
offer(frame) {
|
|
117
|
+
if (this.closed)
|
|
118
|
+
return;
|
|
119
|
+
if (this.waiting)
|
|
120
|
+
this.dropped++;
|
|
121
|
+
this.waiting = frame;
|
|
122
|
+
this.pump();
|
|
123
|
+
}
|
|
124
|
+
/** The phone has a frame; an acknowledgement it owes nothing for is ignored. */
|
|
125
|
+
ack() {
|
|
126
|
+
if (!this.options.acked || this.inFlight === 0)
|
|
127
|
+
return;
|
|
128
|
+
this.inFlight--;
|
|
129
|
+
this.pump();
|
|
130
|
+
}
|
|
131
|
+
close() { this.closed = true; this.waiting = undefined; clearTimeout(this.timer); }
|
|
132
|
+
get bytesPerSecond() { return this.options.bytesPerSecond ?? STREAM_BYTES_PER_SECOND; }
|
|
133
|
+
pump() {
|
|
134
|
+
if (this.closed || this.inFlight >= (this.options.window ?? 1) || !this.waiting || this.timer)
|
|
135
|
+
return;
|
|
136
|
+
const now = this.now();
|
|
137
|
+
this.tokens = Math.min(this.bytesPerSecond, this.tokens + (now - this.refilled) * this.bytesPerSecond / 1000);
|
|
138
|
+
this.refilled = now;
|
|
139
|
+
if (this.tokens < 0) {
|
|
140
|
+
// Over budget: the frame waits (and may be replaced) until it refills.
|
|
141
|
+
this.timer = setTimeout(() => { this.timer = undefined; this.pump(); }, Math.ceil(-this.tokens * 1000 / this.bytesPerSecond));
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
144
|
+
const frame = this.waiting;
|
|
145
|
+
this.waiting = undefined;
|
|
146
|
+
this.inFlight++;
|
|
147
|
+
this.tokens -= frame.length;
|
|
148
|
+
this.send(frame, error => {
|
|
149
|
+
if (error) {
|
|
150
|
+
this.close();
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
this.sent++;
|
|
154
|
+
if (this.options.acked)
|
|
155
|
+
return;
|
|
156
|
+
this.inFlight--;
|
|
157
|
+
this.pump();
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
const defaultDeps = {
|
|
162
|
+
booted: bootedSimulators,
|
|
163
|
+
helper: () => verifiedHelper("simcast"),
|
|
164
|
+
spawn: (binary, args) => spawnChild(binary, args, { stdio: ["ignore", "pipe", "pipe"] }),
|
|
165
|
+
platform: () => process.platform,
|
|
166
|
+
};
|
|
167
|
+
let active = 0;
|
|
168
|
+
/** Streams running now, for tests and health. */
|
|
169
|
+
export function activeSimulatorStreams() { return active; }
|
|
170
|
+
/** WebSocket close reasons are at most 123 bytes. */
|
|
171
|
+
function reason(text) { return Buffer.from(text).subarray(0, 120).toString("utf8").replace(/�+$/, ""); }
|
|
172
|
+
export async function streamSimulator(client, query, deps = defaultDeps) {
|
|
173
|
+
let options;
|
|
174
|
+
try {
|
|
175
|
+
options = streamOptions(query);
|
|
176
|
+
}
|
|
177
|
+
catch (error) {
|
|
178
|
+
client.close(1008, reason(error.message));
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
if (deps.platform() !== "darwin") {
|
|
182
|
+
client.close(1008, "Simulators run on macOS only.");
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
if (active >= MAX_STREAMS) {
|
|
186
|
+
client.close(1013, "Too many simulator streams; try again.");
|
|
187
|
+
return;
|
|
188
|
+
}
|
|
189
|
+
// The slot is held until the work it pays for is over: discovery and the
|
|
190
|
+
// build still running after the socket closed, and a helper that takes up
|
|
191
|
+
// to 2 s to exit. Releasing it on close would let connect-close cycles pile
|
|
192
|
+
// up simctl and helper processes past MAX_STREAMS.
|
|
193
|
+
active++;
|
|
194
|
+
let released = false;
|
|
195
|
+
const release = () => { if (!released) {
|
|
196
|
+
released = true;
|
|
197
|
+
active--;
|
|
198
|
+
} };
|
|
199
|
+
let ended = false, child, killer;
|
|
200
|
+
const latest = new LatestFrame((frame, done) => {
|
|
201
|
+
if (client.readyState !== OPEN) {
|
|
202
|
+
done(new Error("closed"));
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
client.send(frame, { binary: true }, done);
|
|
206
|
+
}, { bytesPerSecond: deps.bytesPerSecond, window: options.ack ? ACK_WINDOW : 1, acked: options.ack });
|
|
207
|
+
client.on("message", (data, isBinary) => {
|
|
208
|
+
if (isBinary || data.length > 64)
|
|
209
|
+
return;
|
|
210
|
+
try {
|
|
211
|
+
if (JSON.parse(data.toString("utf8")).type === "ack")
|
|
212
|
+
latest.ack();
|
|
213
|
+
}
|
|
214
|
+
catch { /* not ours */ }
|
|
215
|
+
});
|
|
216
|
+
const end = (code, why) => {
|
|
217
|
+
if (ended)
|
|
218
|
+
return;
|
|
219
|
+
ended = true;
|
|
220
|
+
latest.close();
|
|
221
|
+
if (child) {
|
|
222
|
+
const running = child;
|
|
223
|
+
running.kill("SIGTERM");
|
|
224
|
+
// A helper stuck in CoreSimulator still goes.
|
|
225
|
+
killer = setTimeout(() => running.kill("SIGKILL"), 2_000);
|
|
226
|
+
killer.unref?.();
|
|
227
|
+
running.once("exit", () => clearTimeout(killer));
|
|
228
|
+
}
|
|
229
|
+
if (code !== undefined && client.readyState === OPEN)
|
|
230
|
+
client.close(code, reason(why ?? "Simulator stream ended."));
|
|
231
|
+
};
|
|
232
|
+
client.once("close", () => end());
|
|
233
|
+
client.once("error", () => end());
|
|
234
|
+
try {
|
|
235
|
+
if (!(await deps.booted()).some(device => device.udid === options.udid)) {
|
|
236
|
+
end(1008, "That simulator is not booted.");
|
|
237
|
+
return;
|
|
238
|
+
}
|
|
239
|
+
// A socket that closed during discovery doesn't go on to build the helper.
|
|
240
|
+
if (ended || client.readyState !== OPEN) {
|
|
241
|
+
end();
|
|
242
|
+
return;
|
|
243
|
+
}
|
|
244
|
+
const binary = await deps.helper();
|
|
245
|
+
if (ended || client.readyState !== OPEN) {
|
|
246
|
+
end();
|
|
247
|
+
return;
|
|
248
|
+
}
|
|
249
|
+
child = deps.spawn(binary, [options.udid, String(options.fps), String(options.size), (options.quality / 100).toFixed(2)]);
|
|
250
|
+
child.once("exit", release);
|
|
251
|
+
child.once("error", release);
|
|
252
|
+
}
|
|
253
|
+
catch (error) {
|
|
254
|
+
end(1011, error instanceof BridgeError ? error.message : "Couldn't start the simulator stream.");
|
|
255
|
+
return;
|
|
256
|
+
}
|
|
257
|
+
finally {
|
|
258
|
+
if (!child)
|
|
259
|
+
release();
|
|
260
|
+
}
|
|
261
|
+
const reader = new FrameReader();
|
|
262
|
+
let stderr = "";
|
|
263
|
+
child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-400); });
|
|
264
|
+
child.stdout?.on("data", (chunk) => {
|
|
265
|
+
if (ended)
|
|
266
|
+
return;
|
|
267
|
+
let frames;
|
|
268
|
+
try {
|
|
269
|
+
frames = reader.push(chunk);
|
|
270
|
+
}
|
|
271
|
+
catch {
|
|
272
|
+
end(1011, "The simulator stream sent a broken frame.");
|
|
273
|
+
return;
|
|
274
|
+
}
|
|
275
|
+
for (const frame of frames)
|
|
276
|
+
latest.offer(frame);
|
|
277
|
+
});
|
|
278
|
+
child.once("error", () => end(1011, "Couldn't start the simulator stream."));
|
|
279
|
+
child.once("exit", () => {
|
|
280
|
+
const last = stderr.trim().split("\n").at(-1);
|
|
281
|
+
end(1011, last ? `Simulator stream ended: ${last}` : "Simulator stream ended.");
|
|
282
|
+
});
|
|
283
|
+
client.send(JSON.stringify({ type: "start", format: "jpeg", fps: options.fps, size: options.size, quality: options.quality, ack: options.ack }), { binary: false });
|
|
284
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type Json } from "./protocol.js";
|
|
2
|
+
export declare const SIMULATOR_UDID: RegExp;
|
|
2
3
|
/** The iOS simulators booted on this Mac, from `simctl`; none elsewhere. */
|
|
3
4
|
export declare function bootedSimulators(): Promise<Json[]>;
|
|
4
5
|
/** A PNG of one booted simulator's screen. */
|
|
@@ -23,6 +24,17 @@ export type SimulatorAction = {
|
|
|
23
24
|
text: string;
|
|
24
25
|
submit?: boolean;
|
|
25
26
|
};
|
|
27
|
+
/** The native helpers, compiled once per Hook version with swiftc, which any
|
|
28
|
+
* Mac with the simulators has. simtap (native/simtap.swift) finds the
|
|
29
|
+
* Simulator window through the Accessibility API and posts touches and keys
|
|
30
|
+
* with CGEvent. AppleScript would need Automation consent, which a launchd
|
|
31
|
+
* agent can never be prompted for; the helper needs one Accessibility grant.
|
|
32
|
+
* Its `prompt` command puts it in the Accessibility list and shows the system
|
|
33
|
+
* dialog. simcast (native/simcast.swift) streams a simulator's framebuffer
|
|
34
|
+
* for simulator-stream.ts and needs no grant. */
|
|
35
|
+
export type NativeHelper = "simtap" | "simcast";
|
|
36
|
+
/** A helper, hashed again right before it runs. */
|
|
37
|
+
export declare function verifiedHelper(name?: NativeHelper): Promise<string>;
|
|
26
38
|
/** The steps for the Accessibility grant, for the 403 and the docs. */
|
|
27
39
|
export declare function accessibilityHelp(binary: string): string;
|
|
28
40
|
export declare function simulatorAct(udid: string, request: SimulatorAction): Promise<Json>;
|