lynkeus 0.4.0 → 0.5.0

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 } : {}) };
 };
@@ -80,6 +182,36 @@ export const service = () => {
     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

@@ -24,6 +24,8 @@ 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. */
@@ -39,6 +41,10 @@ export type LynkeusConfig = {
     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
@@ -91,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/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/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[];

package/lib/knowledge/analyticsTraffic.js

@@ -0,0 +1,109 @@
+const isPlain = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const plain = (v) => (isPlain(v) ? v : undefined);
+const list = (v) => (Array.isArray(v) ? v : v === undefined ? [] : [v]);
+const named = (provider, items, name, props) => items.filter(isPlain).flatMap((item) => {
+    const n = name(item);
+    if (typeof n !== 'string' || !n)
+        return [];
+    const p = plain(props(item));
+    return [{ provider, name: n, ...(p ? { props: p } : {}) }];
+});
+const segment = (body, _path, provider) => {
+    const b = plain(body);
+    return named(provider, list(b?.batch ?? b), (i) => i.event ?? (i.type === 'screen' || i.type === 'page' ? `${i.type}: ${i.name}` : i.type), (i) => i.properties ?? i.traits);
+};
+const amplitude = (body) => named('amplitude', list(plain(body)?.events), (i) => i.event_type, (i) => i.event_properties);
+const posthog = (body) => {
+    const b = plain(body);
+    return named('posthog', list(b?.batch ?? (Array.isArray(body) ? body : b)), (i) => i.event, (i) => i.properties);
+};
+const mixpanel = (body) => named('mixpanel', list(body), (i) => i.event ?? (i.$set ? '$set' : undefined), (i) => i.properties ?? i.$set);
+/** Host pattern → the service, and how to read its body when there is a known shape. */
+const SERVICES = [
+    { host: /(^|\.)segment\.(io|com)$/, provider: 'segment', read: segment },
+    { host: /(^|\.)amplitude\.com$/, provider: 'amplitude', read: amplitude },
+    { host: /(^|\.)posthog\.com$/, provider: 'posthog', read: posthog },
+    { host: /(^|\.)mixpanel\.com$/, provider: 'mixpanel', read: mixpanel },
+    { host: /(^|\.)sentry\.io$|^sentry\./, provider: 'sentry' },
+    { host: /(^|\.)(datadoghq\.(com|eu)|ddog-gov\.com)$/, provider: 'datadog' },
+    { host: /(^|\.)app-measurement\.com$|^firebaselogging/, provider: 'firebase' },
+    { host: /(^|\.)appsflyer(sdk)?\.com$/, provider: 'appsflyer' },
+    { host: /(^|\.)branch\.io$/, provider: 'branch' },
+    { host: /(^|\.)braze\.(com|eu)$/, provider: 'braze' },
+    { host: /(^|\.)onesignal\.com$/, provider: 'onesignal' },
+    { host: /(^|\.)intercom\.(io|com)$/, provider: 'intercom' },
+    { host: /(^|\.)bugsnag\.com$/, provider: 'bugsnag' },
+    { host: /(^|\.)adjust\.(com|net|world)$/, provider: 'adjust' },
+    { host: /(^|\.)clevertap-prod\.com$|(^|\.)wzrkt\.com$/, provider: 'clevertap' },
+    { host: /(^|\.)heapanalytics\.com$/, provider: 'heap' },
+    { host: /(^|\.)statsig(api)?\.(com|net)$/, provider: 'statsig' },
+    { host: /(^|\.)launchdarkly\.com$/, provider: 'launchdarkly' },
+    // Segment-compatible: the same batch shape.
+    { host: /(^|\.)rudderstack\.com$|(^|\.)rudderlabs\.com$/, provider: 'rudderstack', read: segment },
+    { host: /^(track|cdp|track-eu|cdp-eu)\.customer\.io$/, provider: 'customerio', read: segment },
+    { host: /(^|\.)google-analytics\.com$|(^|\.)analytics\.google\.com$/, provider: 'googleanalytics' },
+    { host: /(^|\.)googletagmanager\.com$/, provider: 'googletagmanager' },
+    { host: /^graph\.facebook\.com$/, provider: 'meta' },
+    { host: /(^|\.)tiktok(v)?\.com$|(^|\.)tiktokapis\.com$/, provider: 'tiktok' },
+    { host: /(^|\.)iterable\.com$/, provider: 'iterable' },
+    { host: /(^|\.)moengage\.com$/, provider: 'moengage' },
+    { host: /(^|\.)kochava\.com$/, provider: 'kochava' },
+    { host: /(^|\.)singular\.net$/, provider: 'singular' },
+    { host: /(^|\.)emb-api\.com$|(^|\.)embrace\.io$/, provider: 'embrace' },
+    { host: /(^|\.)instabug\.com$|(^|\.)luciq\.ai$/, provider: 'instabug' },
+    { host: /(^|\.)smartlook\.(cloud|com)$/, provider: 'smartlook' },
+    { host: /(^|\.)urbanairship\.com$|(^|\.)airship\.(com|eu)$|(^|\.)asnapieu\.com$/, provider: 'airship' },
+    { host: /(^|\.)snplow\.net$|(^|\.)snowplowanalytics\.com$/, provider: 'snowplow' },
+    { host: /(^|\.)fullstory\.com$/, provider: 'fullstory' },
+    { host: /(^|\.)mparticle\.com$/, provider: 'mparticle' },
+    { host: /(^|\.)pendo\.io$/, provider: 'pendo' },
+    { host: /(^|\.)lr-ingest\.(io|com)$|(^|\.)logrocket\.(io|com)$/, provider: 'logrocket' },
+    { host: /(^|\.)newrelic\.com$|(^|\.)nr-data\.net$/, provider: 'newrelic' },
+    { host: /(^|\.)hotjar\.(com|io)$/, provider: 'hotjar' },
+    { host: /(^|\.)count\.ly$/, provider: 'countly' },
+];
+const parse = (text) => {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Mixpanel's classic endpoint sends `data=<base64 JSON>` as a form.
+        const data = /(?:^|&)data=([^&]+)/.exec(text)?.[1];
+        if (!data)
+            return undefined;
+        try {
+            const raw = decodeURIComponent(data);
+            return JSON.parse(raw.startsWith('[') || raw.startsWith('{') ? raw : Buffer.from(raw, 'base64').toString('utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+};
+/** The service a request went to, when it is one of the known ones. */
+export const serviceOf = (url) => {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return SERVICES.find((s) => s.host.test(host))?.provider;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** What a step's requests told analytics services: each body's events, or one per call to a service it cannot read. */
+export const trafficEvents = (requests) => requests.flatMap((r) => {
+    let url;
+    try {
+        url = new URL(r.url);
+    }
+    catch {
+        return [];
+    }
+    const service = SERVICES.find((s) => s.host.test(url.hostname.toLowerCase()));
+    if (!service)
+        return [];
+    const events = service.read?.(parse(r.request?.body), url.pathname, service.provider);
+    return events?.length ? events : [{ provider: service.provider, name: `${r.method} ${url.pathname}` }];
+});

package/lib/knowledge/errors.js

@@ -39,6 +39,12 @@ const RULES = [
         cause: (m) => `nothing is listening on ${m[1]}:${m[2]}`,
         fix: () => `start the backend (or the lynkeus driver, if this is the agent's socket) and check the port the entry dials.`,
     },
+    {
+        // Babel loads the project's config with require(); a plugin shipped as ESM only loads that way from Node 22.12.
+        re: /ERR_REQUIRE_ESM(?:[^\n]*?require\(\) of ES Module (\S+))?|require\(\) of ES Module (\S+)/,
+        cause: (m) => `Node ${process.versions.node} cannot require() an ES module${m[1] || m[2] ? ` (${m[1] || m[2]})` : ''}, which the babel config loads`,
+        fix: () => `run with Node 22.12 or newer (lynkeus-headless needs >=22), where require() loads ES modules.`,
+    },
     {
         re: /Test environment jest-environment-\w+ cannot be found|Unexpected token 'export'|SyntaxError: Cannot use import statement/,
         cause: () => `jest is not transforming a dependency (ESM in node_modules)`,

package/lib/knowledge/events.d.ts

@@ -2,9 +2,11 @@ export type AppEvent = {
     name: string;
     props?: Record<string, unknown>;
 };
+/** `provider`: the service the app's own list feeds, when the project says (`cases.appEvents`). */
 export type RunEvent = AppEvent & {
     step: number;
     route?: string;
+    provider?: string;
 };
 type Drainable = {
     command<T = unknown>(name: string, params?: unknown): Promise<T>;

package/lib/knowledge/why.d.ts

@@ -15,6 +15,8 @@ export type Evidence = {
         text?: string;
         route?: string;
     };
+    /** Whether the app made any request before `requests` begins: `requests` may be only those of the failed command. */
+    fetchedBefore?: boolean;
 };
 export type Finding = {
     rule: string;

package/lib/knowledge/why.js

@@ -128,7 +128,7 @@ export const explain = (e) => {
             rule: 'in-flight',
             message: `${e.inFlight} request(s) still in flight when the command gave up: the screen had not finished loading. A longer timeout, or wait for the request it needs.`,
         });
-    if (done.length === 0 && e.inFlight === 0 && e.target?.route)
+    if (done.length === 0 && e.inFlight === 0 && e.target?.route && !e.fetchedBefore)
         out.push({
             rule: 'no-requests',
             message: 'no request left the app while this ran: nothing was fetched. Is the user logged in, and is the app talking to the backend it should?',

package/lib/mcp/server.js

@@ -67,11 +67,13 @@ In a project you do not know, call status first: it lists what is set up and, fo
 
 To set lynkeus up: call init (it installs lynkeus-agent, mounts it from the app's entry and makes the project's token; nobody sets a variable). The agent has native code, so the app must then be built again (npx react-native run-ios or run-android; npx expo run:ios or run:android, never Expo Go) with Metro restarted with --reset-cache. Do that with your shell if you have one, or ask the person to. Then status until an app is attached.
 
-To write a test: call case_init once if the project has no cases, and read the README.md it writes for the format. Go to the screen with press, type and wait, calling screen to see what is there; prefer testIDs (#id) over text. Write the case as a markdown file in the cases folder, then call case_run with that file. A failed step comes back with the screen it failed on: fix the case or report the app's bug, do not weaken the check.
+To write a test: call case_init once if the project has no cases, and read the README.md it writes for the format. Go to the screen with press, type and wait, calling screen to see what is there (press with settle: true answers with the screen once the app has settled; a screen read right after a press can still be the one it left); prefer testIDs (#id) over text. Write the case as a markdown file in the cases folder, then call case_run with that file. A failed step comes back with the screen it failed on: fix the case or report the app's bug, do not weaken the check.
 
 To test without a simulator: call headless_init (it installs what the Node host needs and writes its entry; an Expo Router app works too), then headless_doctor for the native modules still to mock, then case_run with host. The backend the app talks to must be local: set apiUrl in lynkeus.config.json.
 
-To share a run: case_run with out, screenshots and push uploads it and prints the report's address. That needs LYNKEUS_REPORTS_KEY in this server's environment.`;
+To share a run: case_run with out, screenshots and push uploads it and prints the report's address. That needs LYNKEUS_REPORTS_KEY in this server's environment.
+
+For a run with everything (frames, film, requests, analytics, backend): case_run with out, screenshots, video (film needs fastsim), traces and push. When the run ends it warns about evidence it could not keep: pass that on.`;
 export const serve = async (session, options = {}) => {
     const { version } = createRequire(import.meta.url)('../../package.json');
     const server = new Server({ name: 'lynkeus', version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
@@ -115,10 +117,20 @@ export const serve = async (session, options = {}) => {
         const c = byName.get(request.params.name);
         if (!c)
             return { ...text(`✗ no tool ${request.params.name}`), isError: true };
-        const r = await execute(argvFor(c, (request.params.arguments ?? {})), session.ctx);
+        const input = (request.params.arguments ?? {});
+        // An argument the tool does not take is dropped by argvFor; a run would then go on without it (every case
+        // instead of the one named), so it is refused, with what the tool does take.
+        const known = Object.keys(schemaFor(c).properties);
+        const unknown = Object.keys(input).filter((key) => !known.includes(key));
+        if (unknown.length)
+            return { ...text(`✗ ${request.params.name} takes no ${unknown.join(', ')}; it takes ${known.join(', ') || 'no arguments'}`), isError: true };
+        const r = await execute(argvFor(c, input), session.ctx);
         if (r.error)
             return { ...text(`✗ ${r.error}${r.why ? `\n\nwhy:\n${r.why}` : ''}`), isError: true };
-        return text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
+        const body = text(r.text || (r.json !== undefined ? JSON.stringify(r.json, null, 2) : 'ok'));
+        // A command that ended with a non-zero code (a failed case, a server that does not keep the contract) is
+        // reported as such, with everything it said, so a model does not read it as success.
+        return r.code === 0 ? body : { ...body, isError: true };
     });
     // The client going away ends the server: the session holds the driver's port open, and a server left behind
     // keeps the next one (or a case run) from binding it.

package/lib/runtime.d.ts

@@ -8,5 +8,13 @@ export type Outcome = {
     why?: string;
 };
 /** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
-export declare const whyFor: (base: Base, expected?: Expected) => Promise<string>;
+export declare const whyFor: (base: Base, expected?: Expected, startedAt?: number) => Promise<string>;
+/**
+ * The requests made while the failed command ran, and a little before: a 403 from minutes ago is not why a wait
+ * failed now. Only when the app's clock reads like this machine's (a simulator, an emulator); a host on a clock of
+ * its own keeps them all.
+ */
+export declare const duringCommand: <R extends {
+    startedAt: number;
+}>(requests: R[], startedAt: number | undefined, now?: number) => R[];
 export declare const execute: (argv: string[], base: Base) => Promise<Outcome>;

package/lib/runtime.js

@@ -8,16 +8,37 @@ import { describeWhy, explain } from './knowledge/why.js';
 import { helpFor, parseFor, resolve } from './registry.js';
 import { expectedOf } from './targets.js';
 /** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
-export const whyFor = async (base, expected) => {
+export const whyFor = async (base, expected, startedAt) => {
     try {
         const device = await base.device();
         const [screen, requests, trace] = await Promise.all([device.screen(), device.requests(), device.trace()]);
-        return describeWhy(explain({ screen, requests: requests.requests.slice(-40), inFlight: requests.inFlight, trace: trace.events.slice(-40), target: expected }));
+        const during = duringCommand(requests.requests, startedAt);
+        return describeWhy(explain({
+            screen,
+            requests: during.slice(-40),
+            inFlight: requests.inFlight,
+            trace: trace.events.slice(-40),
+            target: expected,
+            fetchedBefore: during.length < requests.requests.length,
+        }));
     }
     catch {
         return '';
     }
 };
+/**
+ * The requests made while the failed command ran, and a little before: a 403 from minutes ago is not why a wait
+ * failed now. Only when the app's clock reads like this machine's (a simulator, an emulator); a host on a clock of
+ * its own keeps them all.
+ */
+export const duringCommand = (requests, startedAt, now = Date.now()) => {
+    if (startedAt === undefined || requests.length === 0)
+        return requests;
+    const latest = Math.max(...requests.map((r) => r.startedAt));
+    if (Math.abs(latest - now) > 10 * 60_000)
+        return requests;
+    return requests.filter((r) => r.startedAt >= startedAt - 3000);
+};
 const TARGET_ARG = { press: 0, see: 0, wait: 0, swipe: 1, nav: 0, type: 1 };
 export const execute = async (argv, base) => {
     const found = resolve(argv);
@@ -35,6 +56,7 @@ export const execute = async (argv, base) => {
     }
     if (parsed.flags.help)
         return { code: 0, text: helpFor(command) };
+    const startedAt = Date.now();
     try {
         const result = await command.run({ ...base, ...parsed });
         if (result === undefined)
@@ -47,7 +69,7 @@ export const execute = async (argv, base) => {
         const out = { code: 1, error: error instanceof Error ? error.message : String(error) };
         const at = TARGET_ARG[command.name];
         if (at !== undefined) {
-            const why = await whyFor(base, expectedOf(parsed.args[at]));
+            const why = await whyFor(base, expectedOf(parsed.args[at]), startedAt);
             if (why)
                 out.why = why;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkeus",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Drive a React Native app running lynkeus-agent from the terminal, a test runner or an MCP client: screens, flows, smoke, crawl, and the app's screen graph.",
   "type": "module",
   "bin": "./lib/cli.js",
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "lynkeus-client": "^0.4.0",
-    "lynkeus-protocol": "^0.4.0",
+    "lynkeus-client": "^0.5.0",
+    "lynkeus-protocol": "^0.5.0",
     "pngjs": "^7.0.0",
     "ts-morph": "^24.0.0",
     "yaml": "^2"
@@ -47,5 +47,8 @@
     "tsx": "^4.19.2",
     "typescript": "^6.0.3"
   },
-  "homepage": "https://github.com/lynkeushq/lynkeus#readme"
+  "homepage": "https://github.com/lynkeushq/lynkeus#readme",
+  "optionalDependencies": {
+    "sharp": "^0.34.4"
+  }
 }