Skip to content

Commit 77b62f4

Browse files
committed
feat(limrun): keep idle sessions alive with LIMRUN_KEEP_ALIVE
Limrun ends an instance after its inactivity timeout, which idle sessions hit while a model thinks between steps. The session's own client must send the ping, because a separate client leaves the ADB tunnel to go offline. The option is off by default so instance lifetime is unchanged unless requested.
1 parent 924e202 commit 77b62f4

6 files changed

Lines changed: 89 additions & 1 deletion

File tree

‎packages/provider-limrun/src/runtime.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,14 @@ import {
5757

5858
type LimrunRuntimeSession = LimrunIosSession | LimrunAndroidSession;
5959

60+
const KEEP_ALIVE_INTERVAL_MS = 30_000;
61+
6062
export type LimrunRuntimeOptions = {
6163
/** Organization API key. It creates and deletes instances for platforms without `instances`. */
6264
apiKey?: string;
6365
region?: string;
66+
/** Pings each leased instance every 30 s so Limrun's inactivity timeout does not end idle sessions. */
67+
keepAlive?: boolean;
6468
runtimeInstance?: string;
6569
instances?: LimrunInstanceAccess;
6670
};
@@ -106,6 +110,7 @@ export function createLimrunRuntime(
106110
class LimrunRuntimeImplementation implements ProviderDeviceRuntime {
107111
private readonly limrun: Limrun | undefined;
108112
private readonly sessions = new Map<string, LimrunRuntimeSession>();
113+
private readonly keepAliveTimers = new Map<string, NodeJS.Timeout>();
109114
private readonly appAliases = new Map<
110115
string,
111116
Readonly<{ assetName: string; installedAppId: string }>
@@ -258,6 +263,7 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime {
258263
(await this.attachSession(platform, lease)) ??
259264
(await this.createSession(platform, lease, context));
260265
this.sessions.set(lease.leaseId, session);
266+
if (this.options.keepAlive) this.startKeepAlive(lease.leaseId, session);
261267
return { limrunInstanceId: session.instanceId, device: session.device };
262268
}
263269

@@ -373,7 +379,22 @@ class LimrunRuntimeImplementation implements ProviderDeviceRuntime {
373379
return { limrunInstanceId: instanceIds[0], limrunInstanceCount: instanceIds.length };
374380
}
375381

382+
private startKeepAlive(leaseId: string, session: LimrunRuntimeSession): void {
383+
const timer = setInterval(() => {
384+
try {
385+
session.client.keepAlive();
386+
} catch {
387+
// A dead connection surfaces on the next real command.
388+
}
389+
}, KEEP_ALIVE_INTERVAL_MS);
390+
timer.unref();
391+
this.keepAliveTimers.set(leaseId, timer);
392+
}
393+
376394
private async terminateSession(session: LimrunRuntimeSession): Promise<void> {
395+
const leaseId = session.lease.leaseId;
396+
clearInterval(this.keepAliveTimers.get(leaseId));
397+
this.keepAliveTimers.delete(leaseId);
377398
session.client.disconnect();
378399
if (session.platform === 'android') await cleanupLimrunAndroidAdbTunnel(session);
379400
if (isAttachedLimrunInstanceId(session.instanceId)) return;

‎src/__tests__/limrun-runtime.test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ const limrunMockState = vi.hoisted(() => {
3737
]),
3838
androidOpenUrl: vi.fn(async () => undefined),
3939
androidDisconnect: vi.fn(),
40+
androidKeepAlive: vi.fn(),
4041
androidSendAsset: vi.fn(async () => undefined),
4142
androidTunnelClose,
4243
androidStartAdbTunnel: vi.fn(async () => ({
@@ -110,6 +111,7 @@ vi.mock('@limrun/api/ios-client', () => ({
110111
vi.mock('@limrun/api/instance-client', () => ({
111112
createInstanceClient: vi.fn(async () => ({
112113
disconnect: limrunMockState.androidDisconnect,
114+
keepAlive: limrunMockState.androidKeepAlive,
113115
openUrl: limrunMockState.androidOpenUrl,
114116
sendAsset: limrunMockState.androidSendAsset,
115117
startAdbTunnel: limrunMockState.androidStartAdbTunnel,
@@ -306,6 +308,52 @@ test('Limrun Android reverses localhost URL ports through the persistent ADB tun
306308
}
307309
});
308310

311+
test('Limrun keepAlive pings the session client every 30 s until release', async () => {
312+
vi.useFakeTimers();
313+
try {
314+
const runtime = new LimrunRuntime({ apiKey: 'lim_test_key', keepAlive: true });
315+
const lease = androidLease();
316+
await allocateLimrunDevice(runtime, lease);
317+
await vi.advanceTimersByTimeAsync(60_000);
318+
assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 2);
319+
320+
await runtime.leaseLifecycle.release?.(lease);
321+
await vi.advanceTimersByTimeAsync(60_000);
322+
assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 2);
323+
} finally {
324+
vi.useRealTimers();
325+
}
326+
});
327+
328+
test('Limrun keepAlive is off by default', async () => {
329+
vi.useFakeTimers();
330+
try {
331+
const runtime = new LimrunRuntime({ apiKey: 'lim_test_key' });
332+
await allocateLimrunDevice(runtime, androidLease());
333+
await vi.advanceTimersByTimeAsync(60_000);
334+
assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 0);
335+
await runtime.shutdown();
336+
} finally {
337+
vi.useRealTimers();
338+
}
339+
});
340+
341+
test('Limrun keepAlive keeps pinging after the client throws', async () => {
342+
vi.useFakeTimers();
343+
try {
344+
limrunMockState.androidKeepAlive.mockImplementationOnce(() => {
345+
throw new Error('socket closed');
346+
});
347+
const runtime = new LimrunRuntime({ apiKey: 'lim_test_key', keepAlive: true });
348+
await allocateLimrunDevice(runtime, androidLease());
349+
await vi.advanceTimersByTimeAsync(60_000);
350+
assert.equal(limrunMockState.androidKeepAlive.mock.calls.length, 2);
351+
await runtime.shutdown();
352+
} finally {
353+
vi.useRealTimers();
354+
}
355+
});
356+
309357
function androidLease(): SimulatorLease {
310358
return {
311359
leaseId: 'lease-android',

‎src/commands/schema/cli-help.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -642,6 +642,7 @@ Limrun direct-device flow:
642642
643643
Limrun creates remote iOS simulators and Android emulators only. Do not pass local device selectors such as --udid, --serial, or --device.
644644
To drive an existing instance without the API key, set LIM_IOS_INSTANCE_URL and LIM_IOS_INSTANCE_TOKEN, or LIM_ANDROID_INSTANCE_URL, LIM_ANDROID_INSTANCE_TOKEN, and LIM_ANDROID_INSTANCE_ADB_URL, from the instance status before connect. agent-device then never creates or deletes that instance; install, and apps before the first open, still need LIMRUN_API_KEY.
645+
Set LIMRUN_KEEP_ALIVE=1 to ping the instance every 30 seconds while a session is open, so an idle session does not hit the Limrun inactivity timeout. It is off by default.
645646
agent-device apps
646647
agent-device open Example.apk
647648
agent-device snapshot -i

‎src/provider-limrun-credentials.test.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ test('reads instance access with the lim CLI variable names', () => {
1515
expect(readLimrunCredentials({ ...IOS_ENV, ...ANDROID_ENV, LIMRUN_REGION: 'eu' })).toEqual({
1616
apiKey: undefined,
1717
region: 'eu',
18+
keepAlive: false,
1819
instances: {
1920
ios: { apiUrl: 'https://region.limrun.example/v1/ios_x/api', token: 'ios-token' },
2021
android: {
@@ -30,6 +31,7 @@ test('reads the API key alone and ignores the removed key alias', () => {
3031
expect(readLimrunCredentials({ LIMRUN_API_KEY: ' lim_key ' })).toEqual({
3132
apiKey: 'lim_key',
3233
region: undefined,
34+
keepAlive: false,
3335
instances: undefined,
3436
});
3537
expect(readLimrunCredentials({ LIM_API_KEY: 'lim_key', LIMRUN_REGION: 'eu' })).toBeUndefined();
@@ -47,3 +49,13 @@ test('rejects partial instance access instead of creating a new instance', () =>
4749
const { LIM_ANDROID_INSTANCE_ADB_URL: _adbUrl, ...withoutAdbUrl } = ANDROID_ENV;
4850
expect(() => readLimrunCredentials(withoutAdbUrl)).toThrow(/LIM_ANDROID_INSTANCE_ADB_URL/);
4951
});
52+
53+
test('reads LIMRUN_KEEP_ALIVE as an opt-in flag that never registers a runtime alone', () => {
54+
const keepAlive = (env: Record<string, string>) =>
55+
readLimrunCredentials({ ...IOS_ENV, ...env })?.keepAlive;
56+
expect(keepAlive({ LIMRUN_KEEP_ALIVE: '1' })).toBe(true);
57+
expect(keepAlive({ LIMRUN_KEEP_ALIVE: ' TRUE ' })).toBe(true);
58+
expect(keepAlive({ LIMRUN_KEEP_ALIVE: '0' })).toBe(false);
59+
expect(keepAlive({})).toBe(false);
60+
expect(readLimrunCredentials({ LIMRUN_KEEP_ALIVE: '1' })).toBeUndefined();
61+
});

‎src/provider-limrun-credentials.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import type { EnvMap } from '@agent-device/kernel/source-value';
55
export type LimrunCredentials = Readonly<{
66
apiKey?: string;
77
region?: string;
8+
keepAlive?: boolean;
89
instances?: LimrunInstanceAccess;
910
}>;
1011

@@ -29,6 +30,7 @@ export function limrunInstanceVariables(platform: 'ios' | 'android'): readonly s
2930
export function readLimrunCredentials(env: EnvMap): LimrunCredentials | undefined {
3031
const apiKey = env.LIMRUN_API_KEY?.trim() || undefined;
3132
const region = env.LIMRUN_REGION?.trim() || undefined;
33+
const keepAlive = ['1', 'true'].includes(env.LIMRUN_KEEP_ALIVE?.trim().toLowerCase() ?? '');
3234
const ios = readInstanceVars(env, INSTANCE_VARS.ios);
3335
const android = readInstanceVars(env, INSTANCE_VARS.android);
3436
if (!apiKey && !ios && !android) return undefined;
@@ -40,7 +42,7 @@ export function readLimrunCredentials(env: EnvMap): LimrunCredentials | undefine
4042
adbUrl: android.LIM_ANDROID_INSTANCE_ADB_URL,
4143
},
4244
};
43-
return { apiKey, region, instances: ios || android ? instances : undefined };
45+
return { apiKey, region, keepAlive, instances: ios || android ? instances : undefined };
4446
}
4547

4648
function readInstanceVars<Name extends string>(

‎website/docs/docs/limrun.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ agent-device disconnect
4343

4444
`install`, and `apps` before the first `open`, still need `LIMRUN_API_KEY`, because they use Limrun asset storage. After `open`, `apps` lists the apps installed on the instance without the key. Install the app before you hand over the instance. From the Node.js runtime, `getDeviceSession(device).installRemoteApp(url)` installs from a signed asset URL without the API key.
4545

46+
## Keeping idle sessions alive
47+
48+
Limrun ends an instance after its inactivity timeout, which an idle session reaches while a model thinks between steps. Set `LIMRUN_KEEP_ALIVE=1` (or `true`) to ping the instance every 30 seconds while a session is open. It is off by default, so instance lifetime is unchanged unless you ask for it. In the Node.js runtime, pass `keepAlive: true`.
49+
4650
## CLI workflow
4751

4852
A new Limrun instance does not contain your app. Run `install <package-or-bundle-id> <app-path-or-url>` before `open`. The install command allocates the instance when needed, so you do not need to run `devices` first.

0 commit comments

Comments
 (0)