Skip to content

Commit 2add31f

Browse files
strzhaoclaude
andcommitted
feat(takeover): script-friendly hold and host-context release on the human-control admin API
A bypass script can now pin one device without a lease: takeover hold writes a host hold through the daemon's host-only /admin/human-control/holds API with a single-device scope, and takeover release without a session or lease removes a host hold by id. The hold names its device with --device-key or with --platform plus device selectors, resolved through the normal device listing and spelled with leaseDeviceKey the way the daemon spells one; --lease-backend or --platform names the backend; --reason and --ttl-ms (default 60000) carry the reason the blocked agent sees and the safety window. The foreground lease takeover, status, and lease-owned release behavior is unchanged. New CLI flags: --device-key, --reason, --ttl-ms, classified intentionally outside provider-backed integration coverage in the progress model. Versioned help and the takeover schema (usage, flagsByAction, supportedFlags) stay in sync. Co-Authored-By: Claude Code <[email protected]>
1 parent a68693c commit 2add31f

11 files changed

Lines changed: 840 additions & 13 deletions

File tree

‎packages/client/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ import { createLeaseClient } from './lease-client.ts';
7575
import { normalizeScreenshotCaptureResult } from './screenshot-result.ts';
7676

7777
export { pickScreenshotResultData } from './screenshot-result.ts';
78+
export { normalizeHumanControlHold } from './lease-client.ts';
7879

7980
export function createAgentDeviceClient(
8081
config: AgentDeviceClientConfig = {},

‎packages/client/src/lease-client.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ export function createLeaseClient(
5252
};
5353
}
5454

55-
function normalizeHumanControlHold(value: unknown): HumanControlHold {
55+
export function normalizeHumanControlHold(value: unknown): HumanControlHold {
5656
if (
5757
!isRecord(value) ||
5858
!isRecord(value.scope) ||

‎packages/command-registry/src/flag-definitions-connection.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,37 @@ export const CONNECTION_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
141141
projectConfig: false,
142142
recorded: false,
143143
},
144+
{
145+
key: 'deviceKey',
146+
names: ['--device-key'],
147+
type: 'string',
148+
usageLabel: '--device-key <key>',
149+
usageDescription:
150+
'Exact lease device key (platform:target:id) a takeover hold pins; device selectors derive it when omitted',
151+
projectConfig: false,
152+
recorded: false,
153+
},
154+
{
155+
key: 'reason',
156+
names: ['--reason'],
157+
type: 'string',
158+
usageLabel: '--reason <text>',
159+
usageDescription: 'Human-control hold reason a blocked agent sees (takeover hold)',
160+
projectConfig: false,
161+
recorded: false,
162+
},
163+
{
164+
key: 'ttlMs',
165+
names: ['--ttl-ms'],
166+
type: 'int',
167+
min: 1000,
168+
max: 86_400_000,
169+
usageLabel: '--ttl-ms <ms>',
170+
usageDescription:
171+
'Human-control hold TTL in milliseconds, 1000 to 86400000 (takeover hold; default 60000)',
172+
projectConfig: false,
173+
recorded: false,
174+
},
144175
{
145176
key: 'provider',
146177
names: ['--provider'],

‎packages/command-surface/src/schema/command-overrides.ts‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -167,11 +167,16 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
167167
text: {
168168
summary: 'Pause agent interactions while a person controls a device',
169169
description:
170-
'Temporarily hand control of the active remote lease device to a person. The foreground command pauses state-changing agent commands, renews the hold until Ctrl+C, and then releases it. Read-only diagnostics remain available. Uses the active connection and --session, with normal tenant and lease admission. status lists holds on that device; release removes a hold owned by the admitted lease. The host-only /admin/human-control/holds API uses the separate local daemon token. Holds do not survive daemon restart. Local takeover without a remote device lease is not supported.',
170+
'Temporarily hand control of a device to a person. The foreground command pauses state-changing agent commands on the active remote lease device, renews the hold until Ctrl+C, and then releases it. Read-only diagnostics remain available. It uses the active connection and --session, with normal tenant and lease admission. status lists holds on that device. release removes a hold owned by the admitted lease; without a session or lease it removes a host hold by id. hold pins one device for a script: it writes a host hold through the daemon host token, so lease allocation and device mutations on that device wait until the TTL passes or release removes the hold. Name the device with --device-key, or with --platform plus device selectors. Name the backend with --lease-backend or --platform. The host hold rides the /admin/human-control/holds API with the local daemon token, or --daemon-base-url and --daemon-auth-token. Holds do not survive daemon restart; re-establish them after reconnecting. Local takeover without a remote device lease is not supported.',
171+
},
172+
usageOverride: 'takeover [status | hold | release <hold-id>] [--session <name>]',
173+
listUsageOverride: 'takeover [status|hold|release]',
174+
positionalArgs: ['status|hold|release?', 'hold-id?'],
175+
flagsByAction: {
176+
hold: ['deviceKey', 'reason', 'ttlMs', 'platform', 'target', 'device', 'udid', 'serial'],
177+
status: ['session', 'tenant', 'runId', 'leaseId', 'sessionIsolation', 'daemonTransport'],
178+
release: ['session', 'tenant', 'runId', 'leaseId', 'sessionIsolation', 'daemonTransport'],
171179
},
172-
usageOverride: 'takeover [status | release <hold-id>] [--session <name>]',
173-
listUsageOverride: 'takeover [status|release]',
174-
positionalArgs: ['status|release?', 'hold-id?'],
175180
supportedFlags: [
176181
'stateDir',
177182
'session',
@@ -184,6 +189,14 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = {
184189
'leaseId',
185190
'leaseBackend',
186191
'sessionIsolation',
192+
'deviceKey',
193+
'reason',
194+
'ttlMs',
195+
'platform',
196+
'target',
197+
'device',
198+
'udid',
199+
'serial',
187200
],
188201
},
189202
'react-devtools': {

‎packages/contracts/src/cli-flags.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ export type CliFlags = CloudProviderProfileFields &
4848
runId?: string;
4949
leaseId?: string;
5050
leaseBackend?: LeaseBackend;
51+
deviceKey?: string;
52+
reason?: string;
53+
ttlMs?: number;
5154
provider?: string;
5255
providerSessionId?: string;
5356
force?: boolean;

‎scripts/integration-progress-model.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,12 @@ function summarizeProviderScenarioFlagExclusions() {
258258
owner: 'proxy allocate-by-spec, request-router refusal, and lease-scope tests',
259259
keys: ['osVersion', 'imageTag', 'deviceMode', 'physical'],
260260
},
261+
{
262+
// `takeover hold` rides the host-only admin HTTP surface, so no provider scenario reaches it.
263+
name: 'takeover host hold',
264+
owner: 'takeover command and host hold admin tests',
265+
keys: ['deviceKey', 'reason', 'ttlMs'],
266+
},
261267
{
262268
name: 'cloud artifact provider lookup',
263269
owner:

‎src/__tests__/takeover-command.test.ts‎

Lines changed: 216 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,41 @@ import assert from 'node:assert/strict';
33
import { afterEach, beforeEach, test, vi } from 'vitest';
44
import { createAgentDeviceClient } from '@agent-device/client';
55
import {
6+
renderTakeoverHold,
67
renderTakeoverStarted,
78
renderTakeoverStatus,
89
takeoverCommand,
910
} from '../cli/commands/takeover.ts';
1011
import type { DaemonRequest } from '@agent-device/kernel/contracts';
1112
import { TAKEOVER_CLI_FLAGS } from './test-utils/client-lease-fixtures.ts';
1213

13-
const mocks = vi.hoisted(() => ({ writeCommandOutput: vi.fn() }));
14+
const mocks = vi.hoisted(() => ({
15+
writeCommandOutput: vi.fn(),
16+
putHostHumanControlHold: vi.fn(),
17+
removeHostHumanControlHold: vi.fn(),
18+
resolveHostHoldAdmin: vi.fn(),
19+
}));
1420
vi.mock('../cli/commands/shared.ts', () => ({ writeCommandOutput: mocks.writeCommandOutput }));
15-
beforeEach(() => mocks.writeCommandOutput.mockReset());
21+
vi.mock('../cli/commands/takeover-hold-admin.ts', () => ({
22+
putHostHumanControlHold: mocks.putHostHumanControlHold,
23+
removeHostHumanControlHold: mocks.removeHostHumanControlHold,
24+
resolveHostHoldAdmin: mocks.resolveHostHoldAdmin,
25+
}));
26+
beforeEach(() => {
27+
mocks.writeCommandOutput.mockReset();
28+
mocks.putHostHumanControlHold.mockReset();
29+
mocks.removeHostHumanControlHold.mockReset();
30+
mocks.resolveHostHoldAdmin.mockReset();
31+
mocks.resolveHostHoldAdmin.mockResolvedValue({
32+
baseUrl: 'http://127.0.0.1:4310',
33+
token: 'host-token',
34+
});
35+
mocks.putHostHumanControlHold.mockImplementation(async ({ holdId }) => ({
36+
...HUMAN_CONTROL_HOLD,
37+
id: holdId,
38+
}));
39+
mocks.removeHostHumanControlHold.mockResolvedValue(true);
40+
});
1641
afterEach(() => vi.useRealTimers());
1742

1843
function createControlLatch() {
@@ -55,13 +80,13 @@ test('takeover status and release use the configured lease client', async () =>
5580
await takeoverCommand({
5681
host: createTestHostEnvironment(),
5782
client,
58-
flags: TAKEOVER_CLI_FLAGS,
83+
flags: { ...TAKEOVER_CLI_FLAGS, session: 'remote-session' },
5984
positionals: ['status'],
6085
});
6186
await takeoverCommand({
6287
host: createTestHostEnvironment(),
6388
client,
64-
flags: TAKEOVER_CLI_FLAGS,
89+
flags: { ...TAKEOVER_CLI_FLAGS, session: 'remote-session' },
6590
positionals: ['release', 'operator-1'],
6691
});
6792
assert.deepEqual(
@@ -142,3 +167,190 @@ test('a failed heartbeat stops foreground takeover and attempts release', async
142167
await rejected;
143168
assert.equal(transport.mock.calls.at(-1)?.[0].positionals?.[0], 'remove');
144169
});
170+
171+
test('takeover hold pins the exact device key with the default TTL and reason', async () => {
172+
const { client } = clientForTest();
173+
await takeoverCommand({
174+
host: createTestHostEnvironment(),
175+
client,
176+
flags: { ...TAKEOVER_CLI_FLAGS, leaseBackend: 'ios-instance', deviceKey: 'ios:mobile:sim-1' },
177+
positionals: ['hold'],
178+
});
179+
assert.equal(mocks.putHostHumanControlHold.mock.calls.length, 1);
180+
const call = mocks.putHostHumanControlHold.mock.calls[0]?.[0] as Record<string, unknown>;
181+
assert.deepEqual(call.scope, { backend: 'ios-instance', deviceKey: 'ios:mobile:sim-1' });
182+
const input = call.input as Record<string, unknown>;
183+
assert.equal(input.ttlMs, 60_000);
184+
assert.equal(input.reason, 'A script outside agent-device is holding this device.');
185+
assert.match(String(call.holdId), /^takeover-/);
186+
assert.equal(mocks.resolveHostHoldAdmin.mock.calls.length, 1);
187+
});
188+
189+
test('takeover hold names a custom reason and TTL', async () => {
190+
const { client } = clientForTest();
191+
await takeoverCommand({
192+
host: createTestHostEnvironment(),
193+
client,
194+
flags: {
195+
...TAKEOVER_CLI_FLAGS,
196+
leaseBackend: 'android-instance',
197+
deviceKey: 'android:mobile:serial-1',
198+
reason: 'flashing the device',
199+
ttlMs: 60000,
200+
},
201+
positionals: ['hold'],
202+
});
203+
const call = mocks.putHostHumanControlHold.mock.calls[0]?.[0] as Record<string, unknown>;
204+
assert.equal((call.input as Record<string, unknown>).reason, 'flashing the device');
205+
assert.equal((call.input as Record<string, unknown>).ttlMs, 60000);
206+
});
207+
208+
test('takeover hold derives the lease device key from one resolved device', async () => {
209+
const { client, transport } = clientForTest();
210+
const devices = vi.fn(async () => [
211+
{
212+
platform: 'android' as const,
213+
target: 'mobile' as const,
214+
kind: 'device' as const,
215+
id: 'serial-1',
216+
name: 'Pixel',
217+
identifiers: {},
218+
},
219+
]);
220+
const holdClient = { ...client, devices: { ...client.devices, list: devices } };
221+
await takeoverCommand({
222+
host: createTestHostEnvironment(),
223+
client: holdClient,
224+
flags: { ...TAKEOVER_CLI_FLAGS, platform: 'android', serial: 'serial-1' },
225+
positionals: ['hold'],
226+
});
227+
const call = mocks.putHostHumanControlHold.mock.calls[0]?.[0] as Record<string, unknown>;
228+
assert.deepEqual(call.scope, {
229+
backend: 'android-instance',
230+
deviceKey: 'android:mobile:serial-1',
231+
});
232+
assert.equal(transport.mock.calls.length, 0);
233+
});
234+
235+
test('takeover hold refuses two device answers, an unnamed backend, and ambiguous selectors', async () => {
236+
const { client } = clientForTest();
237+
const ambiguousClient = {
238+
...client,
239+
devices: {
240+
...client.devices,
241+
list: vi.fn(async () => [
242+
{
243+
platform: 'android' as const,
244+
target: 'mobile' as const,
245+
kind: 'device' as const,
246+
id: 'a',
247+
name: 'A',
248+
identifiers: {},
249+
},
250+
{
251+
platform: 'android' as const,
252+
target: 'mobile' as const,
253+
kind: 'device' as const,
254+
id: 'b',
255+
name: 'B',
256+
identifiers: {},
257+
},
258+
]),
259+
},
260+
};
261+
const cases: Array<{
262+
flags: typeof TAKEOVER_CLI_FLAGS;
263+
client: typeof client;
264+
message: RegExp;
265+
}> = [
266+
{
267+
flags: { ...TAKEOVER_CLI_FLAGS, deviceKey: 'android:mobile:a', serial: 'serial-1' },
268+
client,
269+
message: /not both/,
270+
},
271+
{
272+
flags: { ...TAKEOVER_CLI_FLAGS, deviceKey: 'android:mobile:a' },
273+
client,
274+
message: /lease backend/,
275+
},
276+
{
277+
flags: { ...TAKEOVER_CLI_FLAGS, platform: 'android', serial: 'serial-1' },
278+
client: ambiguousClient,
279+
message: /Several devices match/,
280+
},
281+
{
282+
flags: { ...TAKEOVER_CLI_FLAGS, platform: 'android', serial: 'missing' },
283+
client: {
284+
...client,
285+
devices: { ...client.devices, list: vi.fn(async () => []) },
286+
},
287+
message: /No device matches/,
288+
},
289+
];
290+
for (const { flags, client: caseClient, message } of cases) {
291+
await assert.rejects(
292+
takeoverCommand({
293+
host: createTestHostEnvironment(),
294+
client: caseClient,
295+
flags,
296+
positionals: ['hold'],
297+
}),
298+
(error: unknown) => {
299+
assert.equal((error as { code?: string }).code, 'INVALID_ARGS');
300+
assert.match((error as Error).message, message);
301+
return true;
302+
},
303+
);
304+
}
305+
assert.equal(mocks.putHostHumanControlHold.mock.calls.length, 0);
306+
});
307+
308+
test('takeover hold rejects positional arguments', async () => {
309+
const { client } = clientForTest();
310+
await assert.rejects(
311+
takeoverCommand({
312+
host: createTestHostEnvironment(),
313+
client,
314+
flags: { ...TAKEOVER_CLI_FLAGS },
315+
positionals: ['hold', 'extra'],
316+
}),
317+
{ code: 'INVALID_ARGS' },
318+
);
319+
assert.equal(mocks.resolveHostHoldAdmin.mock.calls.length, 0);
320+
});
321+
322+
test('takeover release without a lease scope removes a host hold', async () => {
323+
const { client, transport } = clientForTest();
324+
await takeoverCommand({
325+
host: createTestHostEnvironment(),
326+
client,
327+
flags: { ...TAKEOVER_CLI_FLAGS },
328+
positionals: ['release', 'takeover-1'],
329+
});
330+
assert.deepEqual(mocks.removeHostHumanControlHold.mock.calls[0]?.[0], {
331+
connection: { baseUrl: 'http://127.0.0.1:4310', token: 'host-token' },
332+
holdId: 'takeover-1',
333+
});
334+
assert.equal(transport.mock.calls.length, 0);
335+
});
336+
337+
test('takeover release keeps the lease-owned path when a session names the request', async () => {
338+
const { client, transport } = clientForTest();
339+
await takeoverCommand({
340+
host: createTestHostEnvironment(),
341+
client,
342+
flags: { ...TAKEOVER_CLI_FLAGS, session: 'remote-session' },
343+
positionals: ['release', 'operator-1'],
344+
});
345+
assert.equal(mocks.removeHostHumanControlHold.mock.calls.length, 0);
346+
assert.deepEqual(
347+
transport.mock.calls.map(([req]) => req.positionals),
348+
[['remove', 'operator-1']],
349+
);
350+
});
351+
352+
test('takeover hold output names the release command', () => {
353+
assert.match(renderTakeoverHold(HUMAN_CONTROL_HOLD), /Human control active for ios:mobile:sim-1/);
354+
assert.match(renderTakeoverHold(HUMAN_CONTROL_HOLD), /takeover release operator-1/);
355+
assert.match(renderTakeoverHold(HUMAN_CONTROL_HOLD), /Hold: operator-1/);
356+
});

0 commit comments

Comments
 (0)