lynkeus 0.4.0 → 0.5.0

package/src/config.ts

@@ -51,6 +51,8 @@ export 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. */
@@ -66,6 +68,8 @@ 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
@@ -126,6 +130,17 @@ export const loadConfig = (root?: string): LynkeusConfig => {
   return { ...own, ...extra };
 };
 
+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 const portFromEnv = (config: LynkeusConfig = {}): number | undefined => (process.env.LYNKEUS_PORT ? Number(process.env.LYNKEUS_PORT) : config.port);
 
 /** A list of regular expressions from the configuration, as one that matches any of them. */

package/src/device/agentVersion.ts

@@ -13,3 +13,20 @@ export const agentMismatch = (hello: Pick<HelloEvent, 'agentVersion'>, cli = CLI
   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: Pick<HelloEvent, 'platform' | 'native' | 'app'>): string => {
+  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: string | undefined, now: string, port: number): string | undefined =>
+  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/src/device/devices.ts

@@ -63,6 +63,11 @@ export const pickAgentDevice = async (wanted?: string): Promise<DeviceInfo> => {
   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) return HEADLESS_HOST;

package/src/knowledge/analyticsTraffic.ts

@@ -0,0 +1,142 @@
+// The analytics, crash and attribution services an app talks to over HTTP, known by where it sends: a JS
+// SDK (Segment, PostHog, Amplitude's browser SDK) never touches a native module, so its events show up only
+// as requests. Each request becomes the events its body carries, or one event named after the call.
+import type { RequestRecord } from 'lynkeus-protocol';
+
+export type TrafficEvent = { provider: string; name: string; props?: Record<string, unknown> };
+
+type Plain = Record<string, unknown>;
+// `provider` is the service the request went to: a reader of one shape serves every service that copies it.
+type Reader = (body: unknown, path: string, provider: string) => TrafficEvent[] | undefined;
+
+const isPlain = (v: unknown): v is Plain => !!v && typeof v === 'object' && !Array.isArray(v);
+const plain = (v: unknown): Plain | undefined => (isPlain(v) ? v : undefined);
+const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : v === undefined ? [] : [v]);
+
+const named = (provider: string, items: unknown[], name: (item: Plain) => unknown, props: (item: Plain) => unknown): TrafficEvent[] =>
+  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: Reader = (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: Reader = (body) =>
+  named(
+    'amplitude',
+    list(plain(body)?.events),
+    (i) => i.event_type,
+    (i) => i.event_properties,
+  );
+const posthog: Reader = (body) => {
+  const b = plain(body);
+  return named(
+    'posthog',
+    list(b?.batch ?? (Array.isArray(body) ? body : b)),
+    (i) => i.event,
+    (i) => i.properties,
+  );
+};
+const mixpanel: Reader = (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: RegExp; provider: string; read?: Reader }[] = [
+  { 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: string | undefined): unknown => {
+  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: string): string | undefined => {
+  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: RequestRecord[]): TrafficEvent[] =>
+  requests.flatMap((r) => {
+    let url: 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/src/knowledge/errors.ts

@@ -47,6 +47,12 @@ const RULES: Rule[] = [
     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/src/knowledge/events.ts

@@ -4,7 +4,8 @@ import path from 'node:path';
 import { readJsonl } from '../files.js';
 
 export type AppEvent = { name: string; props?: Record<string, unknown> };
-export type RunEvent = AppEvent & { step: number; route?: string };
+/** `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/src/knowledge/why.ts

@@ -14,6 +14,8 @@ export type Evidence = {
   trace?: TraceEvent[];
   /** What the failed command was looking for. */
   target?: { testId?: string; 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; message: string };
@@ -159,7 +161,7 @@ export const explain = (e: Evidence): Finding[] => {
       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/src/mcp/server.ts

@@ -68,11 +68,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: Session, options: { full?: boolean } = {}) => {
   const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
@@ -115,9 +117,19 @@ export const serve = async (session: Session, options: { full?: boolean } = {})
     if (request.params.name === 'app_locale' && locale) return text(locale);
     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 ?? {}) as Record<string, unknown>), session.ctx);
+    const input = (request.params.arguments ?? {}) as Record<string, unknown>;
+    // 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/src/runtime.ts

@@ -11,18 +11,38 @@ import { type Expected, expectedOf } from './targets.js';
 export type Outcome = { text?: string; json?: unknown; code: number; error?: string; why?: string };
 
 /** The screen, requests and trace after a failure, read as rules; empty when there is nothing to read. */
-export const whyFor = async (base: Base, expected?: Expected): Promise<string> => {
+export const whyFor = async (base: Base, expected?: Expected, startedAt?: number): Promise<string> => {
   try {
     const device = await base.device();
     const [screen, requests, trace] = await Promise.all([device.screen(), device.requests(), device.trace()]);
+    const during = duringCommand(requests.requests, startedAt);
     return describeWhy(
-      explain({ screen, requests: requests.requests.slice(-40), inFlight: requests.inFlight, trace: trace.events.slice(-40), target: expected }),
+      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 = <R extends { startedAt: number }>(requests: R[], startedAt: number | undefined, now = Date.now()): R[] => {
+  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: Record<string, number> = { press: 0, see: 0, wait: 0, swipe: 1, nav: 0, type: 1 };
 
 export const execute = async (argv: string[], base: Base): Promise<Outcome> => {
@@ -37,6 +57,7 @@ export const execute = async (argv: string[], base: Base): Promise<Outcome> => {
     throw error;
   }
   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) return { code: 0 };
@@ -46,7 +67,7 @@ export const execute = async (argv: string[], base: Base): Promise<Outcome> => {
     const out: Outcome = { 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;
     }
     return out;