Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
69bb6ba
refactor(limrun): ship Limrun as the @agent-device/limrun plugin
thymikee Nov 20, 2026
486d98e
chore(gates): admit the Limrun plugin package and its own SDK dependency
thymikee Nov 20, 2026
457d9f5
fix(connection): forget an ended lease without loading the provider p…
thymikee Nov 20, 2026
9debd88
fix(connection): keep a recorded ended-lease policy as the authority
thymikee Nov 20, 2026
c5cfe46
fix(connection): read an unrecorded ended-lease policy from the plugi…
thymikee Nov 20, 2026
605fba1
fix(connection): answer the ended-lease policy at the point of use
thymikee Nov 20, 2026
4b7035b
fix(connect): admit the provider plugin before authentication and bef…
thymikee Nov 20, 2026
9dd0535
fix(auth): keep a new connect login in memory until its provider is a…
thymikee Nov 20, 2026
29eec20
refactor(connection): read the connection provider from one helper
thymikee Nov 20, 2026
a91b0cb
fix(auth): store a pending login unless the provider plugin is refused
thymikee Nov 20, 2026
175e020
fix(connect): hold a login only until its provider is admitted
thymikee Nov 21, 2026
e49a029
test(connect): name the new tests for the modules they pin
thymikee Nov 21, 2026
73f9941
test(cli): drop an unused helper export
thymikee Nov 21, 2026
8e72bdc
perf(cli): load the connect preflight and pre-command failure modules…
thymikee Nov 21, 2026
e8a45c7
chore(release): make @agent-device/limrun public
thymikee Nov 21, 2026
d0b77b8
fix(cli): keep a deferred cloud login from overwriting newer auth state
thymikee Nov 21, 2026
b32c9d9
refactor(cli): save a connect login when it is approved, as on the base
thymikee Nov 22, 2026
5911afd
docs(website): list Limrun with the plugin providers on the Run anywh…
thymikee Nov 22, 2026
1db7701
fix(website): install the Limrun plugin the 0.22 nightly reader needs
thymikee Nov 22, 2026
0d5dc6e
fix(cli): let a remote daemon answer for a provider this host lacks
thymikee Nov 22, 2026
010c6d4
fix(provider-limrun): keep a verification failure's cause in the plugin
thymikee Nov 22, 2026
bdaa850
fix(provider-limrun): strip the instance token from error details
thymikee Nov 22, 2026
8ece3dc
fix(cli): keep a provider's lease policy on every route
thymikee Nov 22, 2026
99e1e82
fix(provider-limrun): keep credentials out of published errors
thymikee Nov 22, 2026
972b036
fix(limrun): scrub authenticated peer failures at provider boundaries
thymikee Nov 22, 2026
eb28689
fix(limrun): redact diagnostics without changing runner replies
thymikee Nov 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions .fallowrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
// which dependency analysis cannot follow from the exec's path string.
"scripts/release-install-hints.ts",
"packages/provider-aws-device-farm/test/package-smoke.mjs",
"packages/provider-limrun/test/package-smoke.mjs",
"packages/provider-browserstack/test/package-smoke.mjs",
"packages/provider-browserstack/tsdown.config.ts",
"packages/provider-testmu/test/package-smoke.mjs",
Expand Down Expand Up @@ -40,6 +41,7 @@
"src/sdk/install-source.ts",
"src/sdk/plugins.ts",
"src/sdk/plugin-webdriver.ts",
"src/sdk/plugin-device-host.ts",
"src/sdk/android-adb.ts",
"src/sdk/contracts.ts",
"src/sdk/selectors.ts",
Expand Down Expand Up @@ -113,9 +115,6 @@
// @agent-device/maestro owns the source import, while the published root
// build externalizes yaml and retains runtime imports in packed chunks.
"yaml",
// @agent-device/provider-limrun owns the source import, while the published
// root build externalizes @limrun/api and retains runtime imports in packed chunks.
"@limrun/api",
// @agent-device/browserstack and @agent-device/testmu import agent-device type-only, and their
// tsconfigs map those specifiers through this workspace link to core source so typecheck needs
// no build; Fallow then credits the source files rather than the package.
Expand Down
23 changes: 0 additions & 23 deletions LICENSES/xdelta3-wasm.txt

This file was deleted.

2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ The same session and evidence model works at every step: the agent explores the
| --- | --- | --- |
| Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. |
| CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). |
| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, and TestMu AI through `agent-device plugins add`, or Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. |
| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, and Limrun through `agent-device plugins add`), or [contact Callstack](mailto:hello@callstack.com) for team QA. |

## How it works

Expand Down
6 changes: 0 additions & 6 deletions THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,6 @@ the package-level BSD license. These are retained in
[`LICENSES/jpeg-js.txt`](LICENSES/jpeg-js.txt) and included with the Apache License
2.0 in the generated notice file whenever `jpeg-js` is bundled.

`@limrun/xdelta3-wasm` 0.2.0 omits license files from its npm archive. Its Apache-2.0
license text and xdelta3 source attribution are retained through
[`LICENSES/xdelta3-wasm.txt`](LICENSES/xdelta3-wasm.txt) and
[`LICENSES/Apache-2.0.txt`](LICENSES/Apache-2.0.txt). The build verifies the package
version before including these notices.

## Maestro conformance fixtures

The 42 upstream flows in `scripts/maestro-conformance/corpus/upstream/` are copied
Expand Down
1 change: 1 addition & 0 deletions examples/sdk/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
"agent-device/android-adb": ["../../src/sdk/android-adb.ts"],
"agent-device/plugins": ["../../src/sdk/plugins.ts"],
"agent-device/plugins/webdriver": ["../../src/sdk/plugin-webdriver.ts"],
"agent-device/plugins/device-host": ["../../src/sdk/plugin-device-host.ts"],
"agent-device/contracts": ["../../src/sdk/contracts.ts"],
"agent-device/finders": ["../../src/sdk/finders.ts"],
"agent-device/selectors": ["../../src/sdk/selectors.ts"],
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -321,10 +321,10 @@
"@agent-device/host-kit": "workspace:*",
"@agent-device/host-swift": "workspace:*",
"@agent-device/kernel": "workspace:*",
"@agent-device/limrun": "workspace:*",
"@agent-device/platform-android": "workspace:*",
"@agent-device/platform-apple": "workspace:*",
"@agent-device/plugins": "workspace:*",
"@agent-device/provider-limrun": "workspace:*",
"@agent-device/provider-webdriver": "workspace:*",
"@agent-device/provision-kit": "workspace:*",
"@agent-device/proxy": "workspace:*",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { AppError } from '@agent-device/kernel/errors';
import { IOS_SIMULATOR } from './device-fixtures.ts';
import type { ExecResult } from '@agent-device/host-kit/command';
import { handleRunnerTransportErrorAfterCommandSend } from '../runner-command-recovery.ts';
import type { RunnerCommand } from '../runner-contract.ts';
import type { RunnerCommand, RunnerEndpoint } from '../runner-contract.ts';
import { RUNNER_REPLY_LOST_REASON } from '../runner-error-classification.ts';
import type { RunnerSession } from '../runner-session.ts';
import {
Expand All @@ -27,12 +27,12 @@ afterEach(async () => {
server = undefined;
});

function makeRunnerSession(port: number): RunnerSession {
function makeRunnerSession(port: number, http?: RunnerEndpoint['http']): RunnerSession {
return makeLocalRunnerSession({
sessionId: `fake:${port}`,
device: IOS_SIMULATOR,
deviceId: IOS_SIMULATOR.id,
endpoint: { port, token: 'runner-token-fixture' },
endpoint: { port, token: 'runner-token-fixture', http },
xctestrunPath: '/tmp/fake.xctestrun',
jsonPath: '/tmp/fake.json',
testPromise: new Promise<ExecResult>(() => {}),
Expand All @@ -50,14 +50,23 @@ async function runRecovery(params: {
script: FakeRunnerResponse[];
command?: RunnerCommand;
transportError?: AppError;
scrubText?: (text: string) => string;
}): Promise<{
result: Promise<Record<string, unknown>>;
session: RunnerSession;
invalidate: ReturnType<typeof vi.fn>;
transportError: AppError;
}> {
server = await startFakeRunnerServer(params.script);
const session = makeRunnerSession(server.port);
const session = makeRunnerSession(
server.port,
params.scrubText
? {
url: `http://127.0.0.1:${server.port}/command`,
diagnostics: { scrubText: params.scrubText, scrubPayload: (payload) => payload },
}
: undefined,
);
const invalidate = vi.fn(async () => {});
const transportError = params.transportError ?? new AppError('COMMAND_FAILED', 'socket hang up');
const result = handleRunnerTransportErrorAfterCommandSend({
Expand Down Expand Up @@ -124,6 +133,23 @@ test('an unknown lifecycle state invalidates the session and says so', async ()
assert.equal(invalidate.mock.calls[0]?.[1], 'transport_error_after_command_send');
});

test('an unknown provider lifecycle state is scrubbed when published', async () => {
const token = 'synthetic-instance-token';
const { result, invalidate } = await runRecovery({
script: [{ kind: 'ok', data: { lifecycleState: token } }],
scrubText: (text) => text.replaceAll(token, '[REDACTED]'),
});
await assert.rejects(
result,
(error: unknown) =>
error instanceof AppError &&
error.message.includes('invalidated the runner session') &&
!error.message.includes(token) &&
error.details?.lifecycleState === '[REDACTED]',
);
assert.equal(invalidate.mock.calls.length, 1);
});

test('notAccepted from a restarted runner fails the lost command as unknown, naming the lost reply', async () => {
const { result, invalidate } = await runRecovery({
script: [{ kind: 'ok', data: { lifecycleState: 'notAccepted' } }],
Expand Down
21 changes: 15 additions & 6 deletions packages/apple-runner/src/runner-command-recovery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,7 @@ async function tryRecoverRunnerCommandAfterTransportError(
};
}

const scrubText = session.endpoint.http?.diagnostics?.scrubText;
const lifecycleState = typeof status.lifecycleState === 'string' ? status.lifecycleState : '';
// Terminal evidence says the runner finished *this* command, so that command's abandoned charge pays
// off and no other's does. `accepted`, `started`, and a state this daemon cannot name all keep the
Expand All @@ -273,7 +274,7 @@ async function tryRecoverRunnerCommandAfterTransportError(
data: {
command: command.command,
commandId: command.commandId,
lifecycleState,
lifecycleState: scrubText?.(lifecycleState) ?? lifecycleState,
...readinessPreflight,
// Whether this terminal evidence discharged a debt. Absent when the state is not terminal, so
// nothing was attempted; `false` when the command held no abandoned charge to pay.
Expand All @@ -286,6 +287,7 @@ async function tryRecoverRunnerCommandAfterTransportError(
command,
transportError,
options,
scrubText,
);
}

Expand All @@ -295,6 +297,7 @@ function handleRunnerCommandStatusRecovery(
command: RunnerCommand,
transportError: AppError,
options: AppleRunnerCommandOptions,
scrubText?: (text: string) => string,
): RunnerTransportRecovery {
if (lifecycleState === 'completed') {
return handleCompletedRunnerStatus(status, command, transportError);
Expand All @@ -307,6 +310,7 @@ function handleRunnerCommandStatusRecovery(
// surrenders its budget to a condition that clears on its own.
const classification = classifyRunnerReportedError(
typeof status.lifecycleErrorCode === 'string' ? status.lifecycleErrorCode : undefined,
scrubText,
);
return {
type: 'skipInvalidation',
Expand All @@ -319,6 +323,7 @@ function handleRunnerCommandStatusRecovery(
command,
transportError,
options,
scrubText,
),
};
}
Expand All @@ -341,14 +346,15 @@ function handleRunnerCommandStatusRecovery(
};
}

const publishedState = scrubText?.(lifecycleState) ?? lifecycleState;
return {
type: 'retainInvalidation',
reason: lifecycleState ? 'unknown_lifecycle_state' : 'missing_lifecycle_state',
lifecycleState,
lifecycleState: publishedState,
lostReply: {
recovery: 'lifecycle_state_not_recoverable',
lifecycleState,
cause: `lifecycle status was ${lifecycleState ? `"${lifecycleState}"` : 'missing'}`,
lifecycleState: publishedState,
cause: `lifecycle status was ${publishedState ? `"${publishedState}"` : 'missing'}`,
hint: unknownLifecycleStateHint(command.command),
},
};
Expand Down Expand Up @@ -392,13 +398,16 @@ function runnerStatusFailureError(
command: RunnerCommand,
transportError: AppError,
options: AppleRunnerCommandOptions,
scrubText: (text: string) => string = (text) => text,
): AppError {
const errorMessage =
typeof status.lifecycleErrorMessage === 'string'
? status.lifecycleErrorMessage
? scrubText(status.lifecycleErrorMessage)
: 'Runner command failed';
const hint =
typeof status.lifecycleErrorHint === 'string' ? status.lifecycleErrorHint : undefined;
typeof status.lifecycleErrorHint === 'string'
? scrubText(status.lifecycleErrorHint)
: undefined;
const readinessPreflight = readReadinessPreflightRecoveryDetails(transportError);
return new AppError(
classification.code,
Expand Down
69 changes: 34 additions & 35 deletions packages/apple-runner/src/runner-contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -524,14 +524,10 @@ export type RunnerReportedErrorClass = Readonly<{
}>;
}>;

/**
* The one reading of a runner-reported error code (#2484 follow-up). A runner failure reaches the
* host by two routes — the command's own response, and the lifecycle journal a status probe reads
* back after the transport response was lost — and both must classify it identically, or the same
* runner condition surfaces under two codes with only one of them marked retriable.
*/
/** Classifies live and retained runner failures from the original protocol code. */
export function classifyRunnerReportedError(
runnerErrorCode: string | undefined,
scrubText?: (text: string) => string,
): RunnerReportedErrorClass {
const row = runnerErrorCodeRow(runnerErrorCode);
// A code the table does not declare carries no dispatch evidence, so it publishes `unknown`.
Expand All @@ -542,7 +538,10 @@ export function classifyRunnerReportedError(
? (row.diagnosticOnly.wireCode ?? 'COMMAND_FAILED')
: toAppErrorCode(runnerErrorCode),
details: Object.freeze({
runnerErrorCode,
runnerErrorCode:
row || runnerErrorCode === undefined
? runnerErrorCode
: (scrubText?.(runnerErrorCode) ?? runnerErrorCode),
...(row?.diagnosticOnly?.retriable === true ? { retriable: true as const } : {}),
...(row?.reason === undefined ? {} : { reason: row.reason }),
dispatched,
Expand Down Expand Up @@ -612,26 +611,21 @@ function backDismissHint(controls: readonly BackDismissControl[]): string | unde
: 'Press one of details.dismissControls by its selector to dismiss this screen; back only pops the navigation stack.';
}

/**
* The one decoding of a runner response body (#2662). The envelope arrives at three readers — a
* command's own response, the lifecycle journal a status probe reads back after the transport
* response was lost, and the adoption `uptime` probe — and all three must agree on what is
* readable, or a body one of them refuses becomes an answer for another.
*
* Only a JSON object can be an envelope. A body that is not JSON at all, and a JSON scalar or array
* that carries no `ok`, are both transport-shaped: neither is something the runner's encoder emits,
* and reading either as an empty reply would let a proxy page or a half-written body answer for a
* command the runner may still be executing.
*/
export function decodeRunnerResponseBody(text: string): RunnerResponsePayload {
/** Decodes command, retained journal, and adoption replies with the same envelope rules. */
export function decodeRunnerResponseBody(
text: string,
scrubText?: (text: string) => string,
): RunnerResponsePayload {
let parsed: unknown;
try {
parsed = JSON.parse(text);
} catch {
throw new AppError('COMMAND_FAILED', 'Invalid runner response', { text });
parsed = undefined;
}
if (!isRunnerEnvelopeObject(parsed)) {
throw new AppError('COMMAND_FAILED', 'Invalid runner response', { text });
throw new AppError('COMMAND_FAILED', 'Invalid runner response', {
text: scrubText?.(text) ?? text,
});
}
return parsed;
}
Expand All @@ -653,15 +647,20 @@ export function readRunnerResponseData(payload: RunnerResponsePayload): Record<s
export function buildRunnerResponseError(
payload: RunnerResponsePayload,
logPath?: string,
diagnostics?: NonNullable<RunnerEndpoint['http']>['diagnostics'],
): AppError {
const runnerErrorCode = readRunnerErrorCode(payload.error?.code);
const rawCode = payload.error?.code;
const runnerErrorCode = typeof rawCode === 'string' ? rawCode.trim() || undefined : undefined;
const text = diagnostics?.scrubText ?? ((value) => value);
const errorMessage =
typeof payload.error?.message === 'string' ? payload.error.message : undefined;
const hint = typeof payload.error?.hint === 'string' ? payload.error.hint : undefined;
const classification = classifyRunnerReportedError(runnerErrorCode);
const dismissControls = readBackDismissControls(runnerErrorCode, payload.error);
typeof payload.error?.message === 'string' ? text(payload.error.message) : undefined;
const hint = typeof payload.error?.hint === 'string' ? text(payload.error.hint) : undefined;
const classification = classifyRunnerReportedError(runnerErrorCode, text);
const dismissControls = readBackDismissControls(runnerErrorCode, payload.error).filter(
(control) => !diagnostics || diagnostics.scrubPayload(control) === control,
);
return new AppError(classification.code, errorMessage ?? 'Runner error', {
runner: payload,
runner: diagnostics ? diagnostics.scrubPayload(payload) : payload,
...classification.details,
...(dismissControls.length > 0 ? { dismissControls } : {}),
xcodebuild: {
Expand All @@ -674,10 +673,6 @@ export function buildRunnerResponseError(
});
}

function readRunnerErrorCode(rawCode: unknown): string | undefined {
return typeof rawCode === 'string' && rawCode.trim().length > 0 ? rawCode.trim() : undefined;
}

export function withRunnerCommandId(command: RunnerCommand): RunnerCommand {
if (command.command === 'status') return command;
if (command.commandId?.trim()) return command;
Expand All @@ -693,7 +688,6 @@ export function assertRunnerRequestActive(requestId: string | undefined): void {
throw createRequestCanceledError();
}

// ── Listener endpoint and token ─────────────────────────────────────────────────────────────────
const RUNNER_TOKEN_HEADER = 'X-Agent-Device-Runner-Token';
const RUNNER_TOKEN_ENFORCED_HEADER = 'X-Agent-Device-Runner-Auth';
const RUNNER_TOKEN_BYTES = 24;
Expand All @@ -704,7 +698,14 @@ export type RunnerEndpoint = Readonly<{
port: number;
token: string;
/** A provider's authenticated forwarding route; omitted for local and USB runners. */
http?: Readonly<{ url: string; headers?: Readonly<Record<string, string>> }>;
http?: Readonly<{
url: string;
headers?: Readonly<Record<string, string>>;
diagnostics?: Readonly<{
scrubText(text: string): string;
scrubPayload(payload: unknown): unknown;
}>;
}>;
}>;

export function mintRunnerToken(): string {
Expand Down Expand Up @@ -739,8 +740,6 @@ export function requireTokenEnforcingRunner(response: Response): Response {
});
}

// --- Sequence commands ---

export const SEQUENCEABLE_RUNNER_STEP_KINDS = ['tap', 'doubleTap', 'longPress'] as const;
export type SequenceableRunnerStepKind = (typeof SEQUENCEABLE_RUNNER_STEP_KINDS)[number];

Expand Down
Loading
Loading