lynkeus 0.3.0 → 0.5.0

package/lib/commands/map.js

@@ -25,6 +25,23 @@ const describeAffected = (affected, chain) => {
     }
     return lines;
 };
+/** Source files a branch changed against `base`, committed or not. */
+export const changedSources = (root, base, err) => {
+    const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' });
+    try {
+        const names = `${git('diff', '--name-only', `${base}...HEAD`)}\n${git('diff', '--name-only', 'HEAD')}`;
+        return [
+            ...new Set(names
+                .split('\n')
+                .map((l) => l.trim())
+                .filter((l) => /\.[cm]?[jt]sx?$/.test(l))),
+        ];
+    }
+    catch (error) {
+        err(`could not diff against ${base}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+};
 export const mapCommands = [
     define({
         name: 'map build',
@@ -214,20 +231,7 @@ export const mapCommands = [
         run: async (ctx) => {
             const graph = ctx.graph();
             const base = ctx.flags.base;
-            const git = (...args) => execFileSync('git', args, { cwd: ctx.root, encoding: 'utf8' });
-            let changed = [];
-            try {
-                const names = `${git('diff', '--name-only', `${base}...HEAD`)}\n${git('diff', '--name-only', 'HEAD')}`;
-                changed = [
-                    ...new Set(names
-                        .split('\n')
-                        .map((l) => l.trim())
-                        .filter((l) => /\.[cm]?[jt]sx?$/.test(l))),
-                ];
-            }
-            catch (error) {
-                ctx.err(`could not diff against ${base}: ${error instanceof Error ? error.message : String(error)}`);
-            }
+            const changed = changedSources(ctx.root, base, ctx.err);
             const affected = screensAffectedBy(graph, changed, ctx.flags.depth);
             const lines = [`changed against ${base}: ${changed.length} source file(s)`, ...describeAffected(affected, true)];
             if (!affected.length && changed.length)

package/lib/commands/os.js

@@ -30,11 +30,27 @@ export const osCommands = [
     define({
         name: 'os appstate',
         group: 'os',
-        summary: 'Headless: AppState listeners see the change (background, then active: what refetches or re-locks)',
-        positionals: [{ name: 'state', help: 'active | background | inactive', required: true }],
+        summary: 'AppState listeners see the change (background, then active: what refetches or re-locks); a host answers it, a simulator or an emulator does it for real',
+        positionals: [{ name: 'state', help: 'active | background | inactive (inactive: a host only)', required: true }],
+        flags: { app: { type: 'string', help: 'the app to bring back on a simulator or emulator (default: the config’s app)', value: 'bundleId' } },
         aliases: ['appstate'],
         needs: 'app',
-        run: agent('appstate', (ctx) => ({ state: ctx.args[0] })),
+        run: async (ctx) => {
+            const device = await ctx.device();
+            try {
+                return { json: await device.command('appstate', { state: ctx.args[0] }) };
+            }
+            catch (error) {
+                // A host stands in for the OS; on a simulator or an emulator the OS itself moves the app.
+                if ((await device.resolved()).id === 'headless')
+                    throw error;
+                const done = await simulator('appstate')(ctx);
+                // Back in front, the app dials in again; what comes next reads its screen.
+                if (ctx.args[0] === 'active')
+                    await device.server.waitForApp(15_000);
+                return done;
+            }
+        },
     }),
     define({
         name: 'os network',
@@ -61,7 +77,7 @@ export const osCommands = [
     define({
         name: 'os biometrics',
         group: 'os',
-        summary: 'Headless: the sensor and what the next prompts answer',
+        summary: 'The sensor and what the next prompts answer; on a simulator, --available enrolls Face ID or Touch ID or not',
         flags: {
             available: { type: 'string', help: 'FaceID | TouchID | none', value: 'kind' },
             next: { type: 'string', help: 'outcomes of the next prompts, in order', value: 'success,fail,cancel' },
@@ -69,11 +85,28 @@ export const osCommands = [
         },
         aliases: ['biometrics'],
         needs: 'app',
-        run: agent('biometrics', ({ flags }) => ({
-            available: flags.available || undefined,
-            next: flags.next ? flags.next.split(',') : undefined,
-            fallback: flags.fallback || undefined,
-        })),
+        run: async (ctx) => {
+            const device = await ctx.device();
+            const params = {
+                available: ctx.flags.available || undefined,
+                next: ctx.flags.next ? ctx.flags.next.split(',') : undefined,
+                fallback: ctx.flags.fallback || undefined,
+            };
+            try {
+                return { json: await device.command('biometrics', params) };
+            }
+            catch (error) {
+                const info = await device.resolved();
+                if (info.id === 'headless')
+                    throw error;
+                // A device's prompts answer the person in front of it: only a simulator's enrollment is set from outside.
+                // Anything else stays the host's, and the runner says the step cannot run here.
+                if (info.platform !== 'ios' || !params.available || params.next || params.fallback)
+                    throw error;
+                ctx.args = [String(params.available)];
+                return simulator('biometrics')(ctx);
+            }
+        },
     }),
     define({
         name: 'os scan',
@@ -102,7 +135,7 @@ export const osCommands = [
     define({
         name: 'mock',
         group: 'os',
-        summary: 'Headless: answer a request before the network (--sticky survives a reset)',
+        summary: 'Answer a request before the network: a host stands in for it, on a device the agent answers in the app (--sticky survives a host reset)',
         positionals: [{ name: 'route', help: "'GET /path' (a bare path matches any method)" }],
         flags: {
             status: { type: 'number', help: 'HTTP status to answer', default: 200, value: 'code' },

package/lib/commands/report.d.ts

@@ -10,6 +10,8 @@ export type Pushed = {
 };
 /** What a run changed against the one before, in a line or two for a terminal or a pull request comment. */
 export declare const describeChanges: (changes: Pushed["changes"]) => string[];
+/** An uncompressed tar: frames are PNG or AVIF, already compressed, and a tar is read as it arrives. */
+export declare const tarOf: (entries: [string, Uint8Array][]) => Uint8Array;
 /**
  * Uploads a run directory (`case run --out`) to the reports service: the run, its cases, then every frame and
  * film the cases name. A file the organization's plan does not keep (a film on Free) is left out and listed.
@@ -19,6 +21,8 @@ export declare const pushRun: (dir: string, o: {
     key: string;
     project: string;
     fetch?: Fetch;
+    onReady?: (url: string) => void;
+    onProgress?: (line: string) => void;
 }) => Promise<Pushed>;
 type Service = {
     url: string;

package/lib/commands/report.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { define } from '../registry.js';
+import { ageOf, megabytes, pruneRuns } from '../cases/runDirs.js';
+import { keptOrDeleted } from './cases.js';
 /** What a run changed against the one before, in a line or two for a terminal or a pull request comment. */
 export const describeChanges = (changes) => changes
     ? [
@@ -14,6 +16,41 @@ const answer = async (response, doing) => {
     const body = (await response.json().catch(() => ({})));
     throw new Error(`${doing}: ${body.error ?? `the service answered ${response.status}`}`);
 };
+const UPLOADS_AT_ONCE = 4;
+const CASES_PART = 256 * 1024;
+const UPLOAD_ATTEMPTS = 3;
+// A ustar header holds a name of up to 100 bytes and a folder of up to 155 before it.
+const fitsTar = (file) => {
+    const cut = file.lastIndexOf('/');
+    return Buffer.byteLength(file.slice(cut + 1)) <= 100 && Buffer.byteLength(cut > 0 ? file.slice(0, cut) : '') <= 155;
+};
+/** An uncompressed tar: frames are PNG or AVIF, already compressed, and a tar is read as it arrives. */
+export const tarOf = (entries) => {
+    const blocks = [];
+    for (const [file, data] of entries) {
+        const header = Buffer.alloc(512);
+        const cut = file.lastIndexOf('/');
+        header.write(file.slice(cut + 1), 0, 'utf8');
+        header.write('0000644\0', 100);
+        header.write('0000000\0', 108);
+        header.write('0000000\0', 116);
+        header.write(`${data.length.toString(8).padStart(11, '0')}\0`, 124);
+        header.write(`${Math.floor(Date.now() / 1000)
+            .toString(8)
+            .padStart(11, '0')}\0`, 136);
+        header.write('0', 156);
+        header.write('ustar\0', 257);
+        header.write('00', 263);
+        if (cut > 0)
+            header.write(file.slice(0, cut), 345, 'utf8');
+        header.fill(' ', 148, 156);
+        const sum = header.reduce((n, b) => n + b, 0);
+        header.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148);
+        blocks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+    }
+    blocks.push(Buffer.alloc(1024));
+    return Buffer.concat(blocks);
+};
 /**
  * Uploads a run directory (`case run --out`) to the reports service: the run, its cases, then every frame and
  * film the cases name. A file the organization's plan does not keep (a film on Free) is left out and listed.
@@ -30,35 +67,100 @@ export const pushRun = async (dir, o) => {
         body: JSON.stringify({ project: o.project, run }),
     }), 'creating the run');
     const id = String(created.id);
-    await answer(await call(`${base}/v1/runs/${id}/cases`, { method: 'PUT', headers: auth, body: cases }), 'sending its cases');
-    const named = new Set();
+    // A dropped connection, a 5xx or a 429 is tried again, waiting longer each time.
+    const sendWithRetries = async (target, body, doing) => {
+        for (let attempt = 1;; attempt++) {
+            const response = await call(target, { method: 'PUT', headers: auth, body }).catch((error) => {
+                if (attempt >= UPLOAD_ATTEMPTS)
+                    throw new Error(`${doing}: ${error instanceof Error ? error.message : String(error)}`);
+                return undefined;
+            });
+            if (response && ((response.status < 500 && response.status !== 429) || attempt >= UPLOAD_ATTEMPTS))
+                return response;
+            await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** (attempt - 1)));
+        }
+    };
+    // The run file in parts of about 256 KB: with every request's headers and bodies it runs to megabytes, more
+    // than the service reads in one request. A service from before parts answers without `part`, and then
+    // takes the whole file in one.
+    const parts = [];
+    for (const line of cases.split('\n').filter((l) => l.trim())) {
+        const last = parts.length - 1;
+        if (last >= 0 && Buffer.byteLength(parts[last]) + Buffer.byteLength(line) < CASES_PART)
+            parts[last] += `\n${line}`;
+        else
+            parts.push(line);
+    }
+    for (const [n, part] of parts.entries()) {
+        const sent = await answer(await sendWithRetries(`${base}/v1/runs/${id}/cases?part=${n}`, Buffer.from(part), 'sending its cases'), 'sending its cases');
+        if (sent.part === undefined) {
+            await answer(await call(`${base}/v1/runs/${id}/cases`, { method: 'PUT', headers: auth, body: cases }), 'sending its cases');
+            break;
+        }
+    }
+    // The report opens as soon as its cases are in: their steps, results and requests show at once, and each
+    // frame as it arrives.
+    const finished = await answer(await call(`${base}/v1/runs/${id}/finish`, { method: 'POST', headers: auth }), 'finishing the run');
+    o.onReady?.(String(finished.url));
+    // Per case: its frames, sent as one tar, and its film, sent on its own (a film can be bigger than a request).
+    const work = [];
     for (const line of cases.split('\n')) {
         if (!line.trim())
             continue;
         const c = JSON.parse(line);
-        for (const p of [c.video, ...(c.steps ?? []).map((s) => s.screenshot)])
-            if (p)
-                named.add(p);
+        const frames = (c.steps ?? []).map((s) => s.screenshot).filter((p) => !!p && fs.existsSync(path.join(dir, p)));
+        const film = c.video && fs.existsSync(path.join(dir, c.video)) ? c.video : undefined;
+        work.push({ frames: [...new Set(frames)], ...(film ? { film } : {}) });
     }
     let files = 0;
     const refused = [];
-    for (const file of named) {
-        const local = path.join(dir, file);
-        if (!fs.existsSync(local))
-            continue;
-        const response = await call(`${base}/v1/runs/${id}/files/${file.split('/').map(encodeURIComponent).join('/')}`, {
-            method: 'PUT',
-            headers: auth,
-            body: fs.readFileSync(local),
-        });
+    const sendFile = async (file) => {
+        const target = `${base}/v1/runs/${id}/files/${file.split('/').map(encodeURIComponent).join('/')}`;
+        const response = await sendWithRetries(target, fs.readFileSync(path.join(dir, file)), `sending ${file}`);
         if (response.status === 402)
             refused.push(file);
         else {
             await answer(response, `sending ${file}`);
             files += 1;
         }
-    }
-    const finished = await answer(await call(`${base}/v1/runs/${id}/finish`, { method: 'POST', headers: auth }), 'finishing the run');
+    };
+    // A suite with screenshots is thousands of frames: a request per frame took one over 20 minutes to send. A
+    // service from before bundles answers 404, and the frames then go one by one, as they used to.
+    let bundles = true;
+    const sendFrames = async (frames) => {
+        const fits = frames.filter(fitsTar);
+        if (bundles && fits.length > 0) {
+            const response = await sendWithRetries(`${base}/v1/runs/${id}/bundle`, tarOf(fits.map((f) => [f, fs.readFileSync(path.join(dir, f))])), `sending ${fits.length} frames`);
+            if (response.status === 404 || response.status === 405)
+                bundles = false;
+            else {
+                await answer(response, `sending ${fits.length} frames`);
+                files += fits.length;
+                for (const f of frames.filter((f) => !fitsTar(f)))
+                    await sendFile(f);
+                return;
+            }
+        }
+        for (const f of frames)
+            await sendFile(f);
+    };
+    const queue = [...work];
+    const total = work.length;
+    let sent = 0;
+    let bytes = 0;
+    const started = Date.now();
+    const sizeOf = (c) => [...c.frames, ...(c.film ? [c.film] : [])].reduce((n, f) => n + fs.statSync(path.join(dir, f)).size, 0);
+    await Promise.all(Array.from({ length: Math.min(UPLOADS_AT_ONCE, queue.length) }, async () => {
+        for (let c = queue.shift(); c !== undefined; c = queue.shift()) {
+            await sendFrames(c.frames);
+            if (c.film)
+                await sendFile(c.film);
+            sent += 1;
+            bytes += sizeOf(c);
+            if (sent === total || sent % Math.max(1, Math.ceil(total / 10)) === 0)
+                o.onProgress?.(`frames: ${sent}/${total} cases, ${(bytes / 1024 / 1024).toFixed(1)} MB in ${((Date.now() - started) / 1000).toFixed(0)} s`);
+        }
+    }));
     const changes = finished.changes;
     return { url: String(finished.url), files, refused, ...(changes ? { changes } : {}) };
 };
@@ -75,11 +177,41 @@ export const plan = async (o) => {
     return { ...now, url: String((await ask(o, 'POST', route, o.go === 'upgrade' ? 'opening checkout' : 'opening the billing portal')).url) };
 };
 export const service = () => {
-    const url = process.env.LYNKEUS_REPORTS_URL;
+    const url = process.env.LYNKEUS_REPORTS_URL || 'https://lynkeus.io';
     const key = process.env.LYNKEUS_REPORTS_KEY;
-    return url && key ? { url, key } : 'set LYNKEUS_REPORTS_URL and LYNKEUS_REPORTS_KEY (the organization’s API key)';
+    return key ? { url, key } : 'set LYNKEUS_REPORTS_KEY to an API key of your organization (lynkeus.io, API keys); LYNKEUS_REPORTS_URL names another service';
 };
 export const reportCommands = [
+    define({
+        name: 'report prune',
+        group: 'runs',
+        summary: 'Delete the runs `case run --out` left in a folder that ended more than a while ago',
+        details: 'Looks at the folder given, or each folder right under it, and deletes the ones that hold a run (`run.json` and `cases.jsonl`) older than --older. Nothing else is touched. Pushed reports stay on the service; this only frees the disk.',
+        positionals: [{ name: 'dir', help: 'a run folder, or the folder that holds them' }],
+        flags: {
+            older: { type: 'string', help: 'how old a run must be: 7d, 12h, 30m', value: 'age', default: '7d' },
+            'dry-run': { type: 'boolean', help: 'list what would go, delete nothing' },
+        },
+        needs: 'nothing',
+        session: false,
+        mcp: false,
+        run: async (ctx) => {
+            const root = path.resolve(ctx.args[0] ?? '.');
+            if (!fs.existsSync(root))
+                return { text: `${ctx.args[0]}: no such folder`, code: 2 };
+            const older = ageOf(String(ctx.flags.older ?? '7d'));
+            if (older === undefined)
+                return { text: `--older ${ctx.flags.older}: give it as 7d, 12h or 30m`, code: 2 };
+            const dry = !!ctx.flags['dry-run'];
+            const { removed, bytes } = pruneRuns(root, older, dry);
+            if (removed.length === 0)
+                return { text: 'no run old enough to delete', json: { removed, bytes } };
+            return {
+                text: [...removed.map((d) => `${dry ? 'would delete' : 'deleted'} ${d}`), `${dry ? 'would free' : 'freed'} ${megabytes(bytes)}`].join('\n'),
+                json: { removed, bytes },
+            };
+        },
+    }),
     define({
         name: 'report push',
         group: 'runs',
@@ -101,8 +233,12 @@ export const reportCommands = [
                 return { text: to, code: 2 };
             const project = typeof ctx.flags.project === 'string' ? ctx.flags.project : path.basename(ctx.root);
             try {
-                const pushed = await pushRun(dir, { ...to, project });
-                const notes = [...describeChanges(pushed.changes), ...(pushed.refused.length ? [`not kept on this plan: ${pushed.refused.join(', ')}`] : [])];
+                const pushed = await pushRun(dir, { ...to, project, onReady: (url) => ctx.err(`report: ${url} (its frames are on their way)`), onProgress: ctx.err });
+                const notes = [
+                    ...describeChanges(pushed.changes),
+                    ...(pushed.refused.length ? [`not kept on this plan: ${pushed.refused.join(', ')}`] : []),
+                    keptOrDeleted(dir, ctx.config.report?.afterPush === 'delete' ? 'delete' : 'keep', pushed.refused.length === 0),
+                ];
                 return { text: [pushed.url, ...notes].join('\n'), json: pushed };
             }
             catch (error) {

package/lib/config.d.ts

@@ -5,6 +5,17 @@ export declare const graphFile: (root?: string) => string;
 export declare const edgesFile: (root?: string) => string;
 export declare const frontierFile: (root?: string) => string;
 export declare const runsDir: (root?: string) => string;
+export declare const tokenFile: (root?: string) => string;
+/**
+ * The secret the app and its driver share. LYNKEUS_TOKEN wins; otherwise it is the one `lynkeus init` wrote to
+ * `.lynkeus/token`, which the app's bundle reads too, so nobody has to set a variable in two terminals.
+ */
+export declare const readToken: (root?: string) => string | undefined;
+/** Makes the project's token if it has none, and keeps it out of git: `.lynkeus` also holds what a team commits. */
+export declare const ensureToken: (root?: string) => {
+    token: string;
+    made: boolean;
+};
 export declare const loadGraph: (root?: string) => ScreenGraph | null;
 /**
  * `lynkeus.config.json` in the app's folder: what would otherwise be repeated
@@ -13,16 +24,27 @@ export declare const loadGraph: (root?: string) => ScreenGraph | null;
  */
 export type LynkeusConfig = {
     cases?: CasesConfig;
+    /** What `lynkeus ci` brings up around a suite: the project's backend and the app's hosts. */
+    ci?: CiConfig;
     /** The headless entry (default `qa/headless.tsx`). */
     entry?: string;
     /** The environment variable the app reads its API base from; the headless entry refuses one that is not local. */
     apiEnv?: string;
+    /**
+     * The local backend `headless start` hands the app under `apiEnv` when the environment sets none: an agent
+     * starting the host over MCP cannot export a variable.
+     */
+    apiUrl?: string;
     /** The driver port the app dials. */
     port?: number;
     /** Simulator udid or name. */
     device?: string;
     /** Bundle id or application id. */
     app?: string;
+    /** What a pushed run's local folder becomes: kept (the default), or deleted once the service has every file. */
+    report?: {
+        afterPush?: 'keep' | 'delete';
+    };
     /**
      * The language this app speaks, passed on and never interpreted: `os
      * language` defaults to it, the headless entry mocks this locale, and an MCP
@@ -75,6 +97,25 @@ export type LynkeusConfig = {
 export declare const configFile: (root?: string) => string;
 /** The app's configuration, under the one `LYNKEUS_CONFIG` names: cases and fixtures often live in a repository of their own. */
 export declare const loadConfig: (root?: string) => LynkeusConfig;
+export type CiConfig = {
+    /** Shell commands that bring the project's backend up and down, and a URL that answers once it can serve. */
+    backend?: {
+        up: string;
+        down?: string;
+        ready?: string;
+        timeoutMs?: number;
+    };
+    /** How many hosts of the app, and the command that starts one (`{port}` is where it dials). Default: headless. */
+    hosts?: {
+        count?: number;
+        command?: string;
+        timeoutMs?: number;
+    };
+    /** Upload the run (needs LYNKEUS_REPORTS_KEY). */
+    push?: boolean;
+    /** Extra `case run` flags, as on the command line. */
+    run?: string[];
+};
 export declare const portFromEnv: (config?: LynkeusConfig) => number | undefined;
 /** A list of regular expressions from the configuration, as one that matches any of them. */
 export declare const anyOf: (patterns: string[] | undefined) => RegExp | undefined;

package/lib/config.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJson } from './files.js';
@@ -6,6 +7,35 @@ export const graphFile = (root) => path.join(lynkeusDir(root), 'graph.json');
 export const edgesFile = (root) => path.join(lynkeusDir(root), 'edges.jsonl');
 export const frontierFile = (root) => path.join(lynkeusDir(root), 'frontier.jsonl');
 export const runsDir = (root) => path.join(lynkeusDir(root), 'runs');
+export const tokenFile = (root) => path.join(lynkeusDir(root), 'token');
+/**
+ * The secret the app and its driver share. LYNKEUS_TOKEN wins; otherwise it is the one `lynkeus init` wrote to
+ * `.lynkeus/token`, which the app's bundle reads too, so nobody has to set a variable in two terminals.
+ */
+export const readToken = (root) => {
+    if (process.env.LYNKEUS_TOKEN)
+        return process.env.LYNKEUS_TOKEN;
+    try {
+        return fs.readFileSync(tokenFile(root), 'utf8').trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Makes the project's token if it has none, and keeps it out of git: `.lynkeus` also holds what a team commits. */
+export const ensureToken = (root) => {
+    const had = readToken(root);
+    if (had)
+        return { token: had, made: false };
+    const token = crypto.randomBytes(24).toString('hex');
+    fs.mkdirSync(lynkeusDir(root), { recursive: true });
+    fs.writeFileSync(tokenFile(root), `${token}\n`, { mode: 0o600 });
+    const ignore = path.join(lynkeusDir(root), '.gitignore');
+    const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
+    if (!ignored.split('\n').includes('token'))
+        fs.writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith('\n') ? '\n' : ''}token\n`);
+    return { token, made: true };
+};
 export const loadGraph = (root) => {
     const file = graphFile(root);
     return fs.existsSync(file) ? readJson(file) : null;

package/lib/device/agentVersion.d.ts

@@ -5,3 +5,10 @@ export declare const CLI_VERSION: string;
  * nothing): what to tell the person running it, or nothing when the two match.
  */
 export declare const agentMismatch: (hello: Pick<HelloEvent, "agentVersion">, cli?: string) => string | undefined;
+/** Who said hello: the app and where it runs, enough to tell two apps dialing the same port apart. */
+export declare const helloIdentity: (hello: Pick<HelloEvent, "platform" | "native" | "app">) => string;
+/**
+ * The driver keeps the app that dialed in last. Two apps or hosts dialing the same port take turns
+ * without an error, each step going to whichever came last: say so the first time a different one comes in.
+ */
+export declare const appSwitched: (before: string | undefined, now: string, port: number) => string | undefined;

package/lib/device/agentVersion.js

@@ -10,3 +10,17 @@ export const agentMismatch = (hello, cli = CLI_VERSION) => {
     const agent = hello.agentVersion ? `lynkeus-agent ${hello.agentVersion}` : 'a lynkeus-agent too old to say its version';
     return `⚠️  The app runs ${agent}, this CLI is lynkeus ${cli}: they can misread each other without an error. Install lynkeus-agent@${cli} in the app and rebuild it (or run the lynkeus CLI of the agent's version).`;
 };
+/** Who said hello: the app and where it runs, enough to tell two apps dialing the same port apart. */
+export const helloIdentity = (hello) => {
+    const app = hello.app ?? {};
+    const name = typeof app.name === 'string' ? app.name : 'an app';
+    const runtime = typeof app.runtime === 'string' ? app.runtime : hello.native ? 'native' : 'hosted';
+    return `${name} (${hello.platform}, ${runtime})`;
+};
+/**
+ * The driver keeps the app that dialed in last. Two apps or hosts dialing the same port take turns
+ * without an error, each step going to whichever came last: say so the first time a different one comes in.
+ */
+export const appSwitched = (before, now, port) => before && before !== now
+    ? `⚠️  Another app attached on port ${port}: ${before} gave way to ${now}. Two apps or hosts are dialing this port and steps go to whichever dialed last; stop one, or give each its own LYNKEUS_PORT.`
+    : undefined;

package/lib/device/devices.js

@@ -50,6 +50,12 @@ export const pickAgentDevice = async (wanted) => {
     const devices = await bootedSimulators();
     const id = wanted ?? process.env.LYNKEUS_DEVICE;
     const device = id ? devices.find((d) => d.id === id || d.name.includes(id)) : devices[0];
+    if (!device && id) {
+        // An adb serial names an Android device; which platform the app is on is only known once it dials in.
+        const android = (await androidDevices()).find((d) => d.id === id);
+        if (android)
+            return android;
+    }
     if (!device) {
         // A headless host dials the driver itself: nothing to boot or attach to.
         if (!id && devices.length === 0)

package/lib/device/driver.js

@@ -4,7 +4,7 @@
  * only launching, screenshots and the status bar go through simctl or adb.
  */
 import { AgentServer } from 'lynkeus-client';
-import { portFromEnv } from '../config.js';
+import { portFromEnv, readToken } from '../config.js';
 import { withoutHost } from '../knowledge/problems.js';
 import { lifecycleFor } from './platform.js';
 export class Device {
@@ -17,7 +17,7 @@ export class Device {
         this.info = info;
         this.#resolving = options.resolving;
         // The app serves commands only to a driver that presents its token; without one, anything on the loopback could drive a dev build.
-        this.server = options.server ?? new AgentServer({ token: process.env.LYNKEUS_TOKEN, port: portFromEnv() });
+        this.server = options.server ?? new AgentServer({ token: readToken(), port: portFromEnv() });
         this.#lifecycle = lifecycleFor(info.platform);
         this.#appId = options.appId ?? null;
     }

package/lib/knowledge/analyticsTraffic.d.ts

@@ -0,0 +1,10 @@
+import type { RequestRecord } from 'lynkeus-protocol';
+export type TrafficEvent = {
+    provider: string;
+    name: string;
+    props?: Record<string, unknown>;
+};
+/** The service a request went to, when it is one of the known ones. */
+export declare const serviceOf: (url: string) => string | undefined;
+/** What a step's requests told analytics services: each body's events, or one per call to a service it cannot read. */
+export declare const trafficEvents: (requests: RequestRecord[]) => TrafficEvent[];