dsh-apk-vm 0.8.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.js CHANGED
@@ -23,15 +23,21 @@ import { fileURLToPath } from 'node:url';
23
23
 
24
24
  import { AndroidVm } from './lib/android.js';
25
25
  import { InstanceManager } from './lib/instances.js';
26
+ import { OWNER_SCOPE, normalizeScope } from './lib/vm-ownership.js';
27
+ import { checkOwnerAccess, ownerFromHttp } from './lib/http-owner.js';
26
28
  import { ScrcpySession, annexbToAvcc, CONTROL_MESSAGE_TYPE } from './lib/scrcpy.js';
27
29
  import { detectEnvironment, createAvd, installSystemImage, installSdkPackages, bootstrapSdk, DEFAULT_SYSTEM_IMAGE } from './lib/setup.js';
28
30
  import { acceptWebSocket } from './lib/ws.js';
29
- import { parseUiHierarchy, decorateUiNodes, buildInspectorPayload } from './lib/ui-inspector.js';
31
+ import { parseUiHierarchy, decorateUiNodes, buildInspectorPayload, snapshotIdForXml } from './lib/ui-inspector.js';
30
32
  import { FlowRecorder } from './lib/flows.js';
33
+ import { normalizeCodebook, resolveControl, suggestFeatures } from './lib/control-codebook.js';
34
+ import { attachNodeImageFeatures } from './lib/image-features.js';
35
+ import { SkillStore, SkillRecorder, runSkill, normalizeSkill, skillSummary } from './lib/app-skills.js';
31
36
  import { collectStorage, cleanTempFiles, cleanSnapshots, cleanOrphanAvds, formatBytes } from './lib/storage.js';
32
37
  import { buildApksFromAab, aabInfo, detectBundletool } from './lib/aab.js';
33
38
  import { readHarFile, summarizeHar, filterHar, toCurl } from './lib/har.js';
34
39
  import { runAssertions, compareScreenshot, createTestReport, reportMarkdown } from './lib/ui-tests.js';
40
+ import { SshAdbTunnel } from './lib/remote.js';
35
41
 
36
42
  const PLUGIN_VERSION = (() => {
37
43
  try {
@@ -278,6 +284,7 @@ export function apply(ctx, config = {}) {
278
284
  scrcpyBitrate: cfg.scrcpyBitrate || 6_000_000,
279
285
  scrcpyMaxFps: cfg.scrcpyMaxFps || 60,
280
286
  idleTimeoutMs: cfg.instanceIdleMs || 15 * 60 * 1000,
287
+ leaseTtlMs: cfg.leaseTtlMs || 30 * 60 * 1000,
281
288
  dnsServers: Array.isArray(cfg.dnsServers) ? cfg.dnsServers.map(String) : undefined,
282
289
  networkMode: cfg.networkMode || undefined,
283
290
  tcpdumpPath: cfg.tcpdumpPath || undefined,
@@ -294,8 +301,25 @@ export function apply(ctx, config = {}) {
294
301
  instanceManager.onCreated = (id) => {
295
302
  registerInstanceRoutes?.(id);
296
303
  };
304
+ // A closed conversation must not keep the default VM claimed forever.
305
+ // TTL expiry is the fallback when the sessions service is unavailable.
306
+ ctx.inject(['sessions'], (host) => {
307
+ host.effect(() => {
308
+ if (typeof host.on !== 'function') return () => {};
309
+ const off = host.on('session/disposed', (session) => {
310
+ const id = session && (session.id || (session.header && session.header.id));
311
+ if (!id) return;
312
+ const released = instanceManager.releaseBySession(id);
313
+ if (released.length) vm._pushLog(`released VM lease(s) after session ${id}: ${released.map((entry) => entry.instanceId).join(', ')}`);
314
+ });
315
+ return () => {
316
+ if (typeof off === 'function') off();
317
+ };
318
+ }, 'dsh-apk-vm: release VM leases when a session is disposed');
319
+ });
297
320
  }
298
321
  let installInFlight = null;
322
+ let remoteTunnel = null;
299
323
  let startKick = null;
300
324
  let autoStartKicked = false;
301
325
  const frame = { buffer: null, at: 0, inFlight: null, receivedAt: [] };
@@ -655,6 +679,14 @@ export function apply(ctx, config = {}) {
655
679
  }
656
680
 
657
681
  const rootsFor = () => resolveRoots(ctx, cfg.roots);
682
+ // Semantic App Skills live in the workspace (not the OS temp dir), so a
683
+ // recorded "go to checkout" recipe survives VM restarts and can be reviewed.
684
+ const skillStore = new SkillStore({
685
+ dir: cfg.skillsDir
686
+ ? path.resolve(String(cfg.skillsDir))
687
+ : path.join(rootsFor()[0] || process.cwd(), '.apk-vm', 'skills'),
688
+ });
689
+ const skillRecorder = new SkillRecorder({ store: skillStore });
658
690
  const snapshotApk = () => (lastApk ? { ...lastApk } : null);
659
691
 
660
692
  /** Resolve, install and launch one APK; shared by the HTTP route, upload and Agent tool. */
@@ -835,6 +867,7 @@ export function apply(ctx, config = {}) {
835
867
  origin: serverOrigin,
836
868
  multiInstance: Boolean(instanceManager),
837
869
  client: lastClientReport,
870
+ owner: instanceManager ? instanceManager.ownerInfo('default') : null,
838
871
  instances: [
839
872
  {
840
873
  id: 'default',
@@ -846,6 +879,9 @@ export function apply(ctx, config = {}) {
846
879
  root: status.root === true,
847
880
  apk: snapshotApk(),
848
881
  owner: instanceManager ? instanceManager.defaultOwner : null,
882
+ ownerInfo: instanceManager ? instanceManager.ownerInfo('default') : null,
883
+ ownerLabel: instanceManager && instanceManager.ownerInfo('default') ? instanceManager.ownerInfo('default').label : null,
884
+ scope: instanceManager && instanceManager.ownerInfo('default') ? instanceManager.ownerInfo('default').scope : null,
849
885
  lastUsedAt: null,
850
886
  idleMs: null,
851
887
  videoClients: null,
@@ -874,12 +910,94 @@ export function apply(ctx, config = {}) {
874
910
  sendError(res, 500, error && error.message ? error.message : error);
875
911
  }
876
912
  };
913
+ // HTTP callers identify themselves with x-apk-vm-owner/scope/session/
914
+ // workspace/label headers (query parameters are accepted too). A POST that
915
+ // controls a running VM must match the current lease; reads stay read-only.
916
+ const OWNER_GUARDED_POST_PATHS = new Set([
917
+ '/apk-vm/controls',
918
+ '/apk-vm/skills',
919
+ '/apk-vm/flows',
920
+ '/apk-vm/input',
921
+ '/apk-vm/touch',
922
+ '/apk-vm/clipboard',
923
+ '/apk-vm/vm',
924
+ '/apk-vm/device',
925
+ '/apk-vm/remote',
926
+ '/apk-vm/install',
927
+ '/apk-vm/upload',
928
+ '/apk-vm/stream',
929
+ '/apk-vm/stream/quality',
930
+ '/apk-vm/ui-test',
931
+ '/apk-vm/snapshots',
932
+ '/apk-vm/network',
933
+ '/apk-vm/network/har',
934
+ '/apk-vm/debug/shell',
935
+ '/apk-vm/debug/prop',
936
+ '/apk-vm/debug/push',
937
+ '/apk-vm/debug/pull',
938
+ '/apk-vm/debug/reboot',
939
+ '/apk-vm/debug/action',
940
+ '/apk-vm/debug/rotate',
941
+ '/apk-vm/debug/proxy',
942
+ '/apk-vm/debug/ca',
943
+ '/apk-vm/debug/record',
944
+ ]);
945
+
946
+ function requestQuery(req) {
947
+ try {
948
+ return new URL(String(req.url || '/'), 'http://apk-vm.local').searchParams;
949
+ } catch {
950
+ return new URLSearchParams();
951
+ }
952
+ }
953
+
954
+ function httpOwnerFromRequest(req) {
955
+ const values = ownerFromHttp(req.headers || {}, requestQuery(req));
956
+ return values ? instanceManager.ownerFor(values) : null;
957
+ }
958
+
959
+ function assertHttpOwner(req, res, instanceId = 'default') {
960
+ if (!instanceManager) return true;
961
+ const lease = instanceManager.ownerInfo(instanceId);
962
+ const incoming = httpOwnerFromRequest(req);
963
+ const access = checkOwnerAccess(lease, incoming, instanceId);
964
+ if (!access.ok) {
965
+ sendJson(res, access.status || 409, {
966
+ ok: false,
967
+ error: access.error,
968
+ code: access.code || 'vm-busy',
969
+ owner: access.owner || lease,
970
+ });
971
+ return false;
972
+ }
973
+ if (access.autoClaim) {
974
+ try {
975
+ instanceManager.claimOwner(instanceId, incoming);
976
+ } catch (error) {
977
+ sendJson(res, error.status === 409 ? 409 : 400, {
978
+ ok: false,
979
+ error: error.message,
980
+ code: error.code || null,
981
+ owner: error.owner || null,
982
+ });
983
+ return false;
984
+ }
985
+ }
986
+ if (access.touch) instanceManager.touchOwner(instanceId, incoming.key);
987
+ return true;
988
+ }
989
+
877
990
  const register = (pathname, handler) => {
878
991
  disposers.push(
879
992
  webServer.register({
880
993
  kind: 'exact',
881
994
  path: pathname,
882
- handler: wrapHandler(handler),
995
+ handler: wrapHandler(async (req, res) => {
996
+ if (req.method === 'POST' && OWNER_GUARDED_POST_PATHS.has(pathname) && !assertHttpOwner(req, res, 'default')) {
997
+ return;
998
+ }
999
+ await handler(req, res);
1000
+ }),
883
1001
  }),
884
1002
  );
885
1003
  };
@@ -929,6 +1047,318 @@ export function apply(ctx, config = {}) {
929
1047
  }
930
1048
  }
931
1049
 
1050
+ function activeSkill(instanceId) {
1051
+ return skillRecorder.active(instanceId);
1052
+ }
1053
+
1054
+ function codebookForRequest(instanceId, supplied) {
1055
+ const active = activeSkill(instanceId);
1056
+ if (active) return active.skill.codebook;
1057
+ if (supplied) return normalizeCodebook(supplied);
1058
+ throw new Error('no codebook: start a Skill recording first or pass codebook');
1059
+ }
1060
+
1061
+ async function resolveControlOnDevice(api, codebook, code, options = {}) {
1062
+ const value = String(code || '').trim();
1063
+ if (!value) throw new Error('control code is required');
1064
+ const dump = await api.uiDump();
1065
+ const parsed = parseUiHierarchy(dump.xml);
1066
+ const wantsImage = options.withImage === true
1067
+ || (codebook.entries || []).some((entry) => entry.features && entry.features.image);
1068
+ if (wantsImage && typeof api.screenshotBuffer === 'function') {
1069
+ try {
1070
+ attachNodeImageFeatures(await api.screenshotBuffer(), parsed.nodes);
1071
+ } catch {
1072
+ // Image matching will report a clear "no screenshot image features" error.
1073
+ }
1074
+ }
1075
+ let screen = null;
1076
+ try {
1077
+ screen = await api.screenSize();
1078
+ } catch {
1079
+ screen = null;
1080
+ }
1081
+ const result = resolveControl(codebook, value, parsed.nodes, { screen });
1082
+ if (!result.node || !result.node.bounds || !result.node.bounds.center) {
1083
+ throw new Error(`control ${value} has no usable bounds on the current screen`);
1084
+ }
1085
+ return { ...result, snapshotId: snapshotIdForXml(dump.xml), screen };
1086
+ }
1087
+
1088
+ function recordControlStep(instanceId, step, body) {
1089
+ if (body && body.record === false) return false;
1090
+ if (!activeSkill(instanceId)) return false;
1091
+ skillRecorder.add(instanceId, step);
1092
+ return true;
1093
+ }
1094
+
1095
+ async function handleControlRequest(req, res, instanceId, apiFactory) {
1096
+ if (req.method !== 'POST') {
1097
+ sendError(res, 405, 'POST only');
1098
+ return;
1099
+ }
1100
+ const body = await readJsonBody(req);
1101
+ const action = String(body.action || '').toLowerCase().replace(/-/g, '_');
1102
+ const api = apiFactory();
1103
+ try {
1104
+ await ensureToolApiReady(api, 'control');
1105
+ if (action === 'ui') {
1106
+ const inspector = buildInspectorPayload(await api.uiDump(), await api.screenSize().catch(() => null));
1107
+ sendJson(res, 200, { ok: true, ...inspector });
1108
+ return;
1109
+ }
1110
+ if (action === 'codebook') {
1111
+ const active = activeSkill(instanceId);
1112
+ if (active) {
1113
+ const codebook = await skillRecorder.updateCodebook(instanceId, body.codebook || {});
1114
+ sendJson(res, 200, { ok: true, codebook, recording: true });
1115
+ return;
1116
+ }
1117
+ const skillId = String(body.skillId || body.id || '').trim();
1118
+ if (!skillId) throw new Error('no active recording; codebook needs skillId');
1119
+ const skill = await skillStore.get(skillId);
1120
+ if (!skill) throw new Error(`unknown Skill: ${skillId}`);
1121
+ skill.codebook = normalizeCodebook(body.codebook || {});
1122
+ const saved = await skillStore.save(skill);
1123
+ sendJson(res, 200, { ok: true, skill: skillSummary(saved), codebook: saved.codebook });
1124
+ return;
1125
+ }
1126
+ if (action === 'launch') {
1127
+ const pkg = String(body.packageName || body.package || '').trim();
1128
+ if (!pkg) throw new Error('control launch requires package');
1129
+ const result = await api.launchPackage(pkg);
1130
+ recordControlStep(instanceId, { action: 'launch', package: pkg }, body);
1131
+ sendJson(res, 200, { ok: true, action, package: pkg, result, recorded: Boolean(activeSkill(instanceId)) });
1132
+ return;
1133
+ }
1134
+ const codebook = codebookForRequest(instanceId, body.codebook);
1135
+ if (action === 'features') {
1136
+ const code = String(body.code || '').trim();
1137
+ if (!code) throw new Error('control features requires code');
1138
+ const target = await resolveControlOnDevice(api, codebook, code, { withImage: true });
1139
+ const image = target.node && target.node.imageFeatures
1140
+ ? {
1141
+ name: String(body.imageName || code).slice(0, 120),
1142
+ hash: target.node.imageFeatures.hash,
1143
+ avgColor: target.node.imageFeatures.avgColor,
1144
+ dominantColor: target.node.imageFeatures.dominantColor,
1145
+ maxDistance: body.maxDistance,
1146
+ colorTolerance: body.colorTolerance,
1147
+ }
1148
+ : null;
1149
+ const entry = {
1150
+ code,
1151
+ ...(body.name ? { name: String(body.name) } : {}),
1152
+ features: { ...suggestFeatures(target.node), ...(image ? { image } : {}) },
1153
+ };
1154
+ sendJson(res, 200, {
1155
+ ok: true,
1156
+ action,
1157
+ code: target.code,
1158
+ snapshotId: target.snapshotId,
1159
+ features: target.node.features || suggestFeatures(target.node),
1160
+ imageFeatures: target.node.imageFeatures || null,
1161
+ suggestedEntry: entry,
1162
+ });
1163
+ return;
1164
+ }
1165
+ if (action === 'assert' || action === 'wait') {
1166
+ const code = String(body.code || '').trim();
1167
+ const exists = body.exists !== false;
1168
+ let target = null;
1169
+ let error = null;
1170
+ try {
1171
+ target = await resolveControlOnDevice(api, codebook, code);
1172
+ } catch (caught) {
1173
+ error = caught;
1174
+ }
1175
+ if (exists && !target) throw error || new Error(`control ${code} is not visible`);
1176
+ if (!exists && target) throw new Error(`control ${code} is visible; exists=false assertion failed`);
1177
+ const step = { action: action === 'wait' ? 'waitFor' : 'assert', code };
1178
+ if (!exists) step.exists = false;
1179
+ const recorded = recordControlStep(instanceId, step, body);
1180
+ sendJson(res, 200, {
1181
+ ok: true,
1182
+ action,
1183
+ code,
1184
+ exists,
1185
+ snapshotId: target ? target.snapshotId : null,
1186
+ recorded,
1187
+ });
1188
+ return;
1189
+ }
1190
+ if (action === 'swipe') {
1191
+ const fromCode = String(body.fromCode || body.from || '').trim();
1192
+ const toCode = String(body.toCode || body.to || '').trim();
1193
+ let from = null;
1194
+ let to = null;
1195
+ if (fromCode) from = await resolveControlOnDevice(api, codebook, fromCode);
1196
+ if (toCode) to = await resolveControlOnDevice(api, codebook, toCode);
1197
+ let x1 = from ? from.node.bounds.center.x : Number(body.x1);
1198
+ let y1 = from ? from.node.bounds.center.y : Number(body.y1);
1199
+ let x2 = to ? to.node.bounds.center.x : Number(body.x2);
1200
+ let y2 = to ? to.node.bounds.center.y : Number(body.y2);
1201
+ if (![x1, y1, x2, y2].every(Number.isFinite)) {
1202
+ throw new Error('control swipe needs fromCode/toCode or numeric x1,y1,x2,y2');
1203
+ }
1204
+ const durationMs = Math.max(1, Math.min(60000, Number(body.durationMs) || 300));
1205
+ await api.input({ type: 'swipe', x1, y1, x2, y2, durationMs });
1206
+ const step = fromCode || toCode
1207
+ ? { action: 'swipe', fromCode: fromCode || undefined, toCode: toCode || undefined, durationMs }
1208
+ : { action: 'swipe', x1, y1, x2, y2, durationMs };
1209
+ const recorded = recordControlStep(instanceId, step, body);
1210
+ sendJson(res, 200, { ok: true, action, fromCode: fromCode || null, toCode: toCode || null, x1, y1, x2, y2, recorded });
1211
+ return;
1212
+ }
1213
+ const code = String(body.code || '').trim();
1214
+ const target = await resolveControlOnDevice(api, codebook, code);
1215
+ const center = target.node.bounds.center;
1216
+ if (action === 'tap') {
1217
+ await api.input({ type: 'tap', x: center.x, y: center.y });
1218
+ const recorded = recordControlStep(instanceId, { action: 'tap', code }, body);
1219
+ sendJson(res, 200, { ok: true, action, code: target.code, x: center.x, y: center.y, snapshotId: target.snapshotId, recorded });
1220
+ return;
1221
+ }
1222
+ if (action === 'input') {
1223
+ const text = body.text === undefined ? (body.value === undefined ? '' : String(body.value)) : String(body.text);
1224
+ const submit = body.submit === true;
1225
+ await api.input({ type: 'tap', x: center.x, y: center.y });
1226
+ await new Promise((resolve) => setTimeout(resolve, 120));
1227
+ if (text) await api.input({ type: 'text', text: text.slice(0, 4096) });
1228
+ if (submit) await api.input({ type: 'key', key: 'ENTER' });
1229
+ const recorded = recordControlStep(instanceId, { action: 'input', code, value: text, ...(submit ? { submit: true } : {}) }, body);
1230
+ sendJson(res, 200, { ok: true, action, code: target.code, chars: text.length, submit, snapshotId: target.snapshotId, recorded });
1231
+ return;
1232
+ }
1233
+ if (action === 'long_press') {
1234
+ const durationMs = Math.max(300, Math.min(60000, Number(body.durationMs) || 800));
1235
+ await api.input({ type: 'swipe', x1: center.x, y1: center.y, x2: center.x, y2: center.y, durationMs });
1236
+ const recorded = recordControlStep(instanceId, { action: 'longPress', code, durationMs }, body);
1237
+ sendJson(res, 200, { ok: true, action, code: target.code, durationMs, snapshotId: target.snapshotId, recorded });
1238
+ return;
1239
+ }
1240
+ throw new Error(`unsupported control action: ${action || '(missing)'}`);
1241
+ } catch (error) {
1242
+ sendJson(res, 400, {
1243
+ ok: false,
1244
+ error: error && error.message ? error.message : String(error),
1245
+ code: error && error.code ? error.code : null,
1246
+ candidates: error && error.candidates ? error.candidates : [],
1247
+ codebookCodes: error && error.codebookCodes ? error.codebookCodes : [],
1248
+ });
1249
+ }
1250
+ }
1251
+
1252
+ async function handleSkillsRequest(req, res, instanceId, apiFactory) {
1253
+ if (req.method === 'GET') {
1254
+ const active = activeSkill(instanceId);
1255
+ sendJson(res, 200, {
1256
+ ok: true,
1257
+ instance: instanceId,
1258
+ skills: (await skillStore.list()).map(skillSummary),
1259
+ recording: active ? { ...skillSummary(active.skill), codebook: active.skill.codebook } : null,
1260
+ });
1261
+ return;
1262
+ }
1263
+ if (req.method !== 'POST') {
1264
+ sendError(res, 405, 'GET or POST only');
1265
+ return;
1266
+ }
1267
+ const body = await readJsonBody(req);
1268
+ const action = String(body.action || '').toLowerCase().replace(/-/g, '_');
1269
+ try {
1270
+ if (action === 'start') {
1271
+ const started = await skillRecorder.start(instanceId, {
1272
+ name: body.name || body.skillName,
1273
+ id: body.skillId || body.id,
1274
+ package: body.packageName || body.package,
1275
+ description: body.description,
1276
+ target: body.targetCode || body.target,
1277
+ codebook: body.codebook,
1278
+ });
1279
+ sendJson(res, 200, { ok: true, action, recording: started });
1280
+ return;
1281
+ }
1282
+ if (action === 'stop') {
1283
+ const saved = await skillRecorder.stop(instanceId, {
1284
+ name: body.name || body.skillName,
1285
+ package: body.packageName || body.package,
1286
+ description: body.description,
1287
+ });
1288
+ sendJson(res, 200, { ok: true, action, skill: skillSummary(saved), result: saved });
1289
+ return;
1290
+ }
1291
+ if (action === 'cancel') {
1292
+ const cancelled = skillRecorder.cancel(instanceId);
1293
+ sendJson(res, 200, { ok: true, action, cancelled });
1294
+ return;
1295
+ }
1296
+ if (action === 'save') {
1297
+ const source = body.skill && typeof body.skill === 'object' ? { ...body.skill } : { ...body };
1298
+ if (!source.id && body.skillId) source.id = body.skillId;
1299
+ if (!source.name && body.skillName) source.name = body.skillName;
1300
+ delete source.action;
1301
+ const saved = await skillStore.save(normalizeSkill(source));
1302
+ sendJson(res, 200, { ok: true, action, skill: skillSummary(saved), result: saved });
1303
+ return;
1304
+ }
1305
+ if (action === 'get') {
1306
+ const id = String(body.skillId || body.id || '').trim();
1307
+ if (!id) throw new Error('get requires skillId');
1308
+ const skill = await skillStore.get(id);
1309
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
1310
+ sendJson(res, 200, { ok: true, action, result: skill });
1311
+ return;
1312
+ }
1313
+ if (action === 'delete') {
1314
+ const id = String(body.skillId || body.id || '').trim();
1315
+ if (!id) throw new Error('delete requires skillId');
1316
+ const removed = await skillStore.remove(id);
1317
+ sendJson(res, 200, { ok: true, action, removed });
1318
+ return;
1319
+ }
1320
+ if (action === 'codebook') {
1321
+ const id = String(body.skillId || body.id || '').trim();
1322
+ if (!id) throw new Error('codebook requires skillId (or use /apk-vm/controls while recording)');
1323
+ const skill = await skillStore.get(id);
1324
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
1325
+ skill.codebook = normalizeCodebook(body.codebook || {});
1326
+ const saved = await skillStore.save(skill);
1327
+ sendJson(res, 200, { ok: true, action, skill: skillSummary(saved), codebook: saved.codebook });
1328
+ return;
1329
+ }
1330
+ if (action === 'run') {
1331
+ const id = String(body.skillId || body.id || '').trim();
1332
+ if (!id) throw new Error('run requires skillId');
1333
+ const skill = await skillStore.get(id);
1334
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
1335
+ const api = apiFactory();
1336
+ await ensureToolApiReady(api, 'skill_run');
1337
+ const result = await runSkill(skill, api, {
1338
+ speed: body.speed,
1339
+ untilCode: body.untilCode || body.targetCode,
1340
+ variables: body.variables,
1341
+ dryRun: body.dryRun === true,
1342
+ timeoutMs: body.timeoutMs,
1343
+ package: body.packageName || body.package,
1344
+ });
1345
+ sendJson(res, 200, { ok: true, action, result });
1346
+ return;
1347
+ }
1348
+ throw new Error(`unsupported Skill action: ${action || '(missing)'}`);
1349
+ } catch (error) {
1350
+ sendJson(res, 400, {
1351
+ ok: false,
1352
+ error: error && error.message ? error.message : String(error),
1353
+ code: error && error.code ? error.code : null,
1354
+ candidates: error && error.candidates ? error.candidates : [],
1355
+ stepsRun: error && error.stepsRun,
1356
+ stepIndex: error && error.stepIndex,
1357
+ events: error && error.events ? error.events : [],
1358
+ });
1359
+ }
1360
+ }
1361
+
932
1362
  register('/apk-vm/flows', async (req, res) => {
933
1363
  await handleFlowRequest(req, res, 'default', async (payload) => {
934
1364
  const status = await vm.status();
@@ -937,6 +1367,14 @@ export function apply(ctx, config = {}) {
937
1367
  });
938
1368
  });
939
1369
 
1370
+ register('/apk-vm/skills', async (req, res) => {
1371
+ await handleSkillsRequest(req, res, 'default', () => defaultToolApi());
1372
+ });
1373
+
1374
+ register('/apk-vm/controls', async (req, res) => {
1375
+ await handleControlRequest(req, res, 'default', () => defaultToolApi());
1376
+ });
1377
+
940
1378
  function storageSdkRoot() {
941
1379
  if (vm.sdkRoot) return vm.sdkRoot;
942
1380
  if (vm.adbPath) return path.dirname(path.dirname(vm.adbPath));
@@ -1091,6 +1529,63 @@ export function apply(ctx, config = {}) {
1091
1529
  sendError(res, 400, `unsupported setup action: ${action || '(missing)'}`);
1092
1530
  });
1093
1531
 
1532
+ register('/apk-vm/ownership', async (req, res) => {
1533
+ if (!instanceManager) {
1534
+ sendError(res, 503, 'multi-instance support is disabled');
1535
+ return;
1536
+ }
1537
+ if (req.method === 'GET' || req.method === 'HEAD') {
1538
+ const query = requestQuery(req);
1539
+ const instanceId = String(query.get('instanceId') || query.get('id') || 'default');
1540
+ sendJson(res, 200, {
1541
+ ok: true,
1542
+ instanceId,
1543
+ owner: instanceManager.ownerInfo(instanceId),
1544
+ default: instanceManager.ownerInfo('default'),
1545
+ owners: instanceManager.ownerList(),
1546
+ });
1547
+ return;
1548
+ }
1549
+ if (req.method !== 'POST') {
1550
+ sendError(res, 405, 'GET or POST only');
1551
+ return;
1552
+ }
1553
+ const body = await readJsonBody(req);
1554
+ const action = String(body.action || 'status').toLowerCase();
1555
+ const instanceId = String(body.instanceId || body.id || 'default');
1556
+ const owner = instanceManager.ownerFor({
1557
+ key: body.ownerKey || body.key || (body.owner && body.owner.key) || undefined,
1558
+ scope: body.ownerScope || body.scope || (body.owner && body.owner.scope) || 'shared',
1559
+ sessionId: body.sessionId || (body.owner && body.owner.sessionId) || null,
1560
+ workspace: body.workspace || (body.owner && body.owner.workspace) || null,
1561
+ label: body.ownerLabel || body.label || (body.owner && body.owner.label) || '桌面面板',
1562
+ source: 'panel',
1563
+ });
1564
+ try {
1565
+ if (action === 'claim') {
1566
+ const result = instanceManager.claimOwner(instanceId, owner, { force: body.force === true });
1567
+ sendJson(res, 200, { ok: true, instanceId, ...result });
1568
+ return;
1569
+ }
1570
+ if (action === 'release') {
1571
+ const released = instanceManager.releaseOwner(instanceId, owner, { force: body.force === true });
1572
+ sendJson(res, 200, { ok: true, instanceId, released });
1573
+ return;
1574
+ }
1575
+ if (action === 'touch') {
1576
+ sendJson(res, 200, { ok: true, owner: instanceManager.touchOwner(instanceId, owner.key) });
1577
+ return;
1578
+ }
1579
+ sendJson(res, 200, {
1580
+ ok: true,
1581
+ default: instanceManager.ownerInfo('default'),
1582
+ owners: instanceManager.ownerList(),
1583
+ });
1584
+ } catch (error) {
1585
+ sendError(res, error.status === 409 ? 409 : 400, error.message);
1586
+ }
1587
+ });
1588
+
1094
1589
  register('/apk-vm/instances', async (req, res) => {
1095
1590
  if (!instanceManager) {
1096
1591
  sendError(res, 503, 'multi-instance support is disabled');
@@ -1098,6 +1593,7 @@ export function apply(ctx, config = {}) {
1098
1593
  }
1099
1594
  if (req.method === 'GET') {
1100
1595
  const defaultStatus = await vm.status();
1596
+ const defaultOwnerInfo = instanceManager ? instanceManager.ownerInfo('default') : null;
1101
1597
  if (instanceManager) {
1102
1598
  for (const instance of instanceManager.instances.values()) {
1103
1599
  try {
@@ -1120,7 +1616,8 @@ export function apply(ctx, config = {}) {
1120
1616
  serial: defaultStatus.serial || null,
1121
1617
  root: defaultStatus.root === true,
1122
1618
  apk: snapshotApk(),
1123
- owner: instanceManager.defaultOwner,
1619
+ owner: defaultOwnerInfo ? defaultOwnerInfo.key : null,
1620
+ ownerInfo: defaultOwnerInfo,
1124
1621
  lastUsedAt: null,
1125
1622
  idleMs: null,
1126
1623
  videoClients: null,
@@ -1135,6 +1632,17 @@ export function apply(ctx, config = {}) {
1135
1632
  try {
1136
1633
  const instance = await instanceManager.create({ name: body.name });
1137
1634
  registerInstanceRoutes?.(instance.id);
1635
+ const owner = body.ownerKey || body.ownerScope
1636
+ ? instanceManager.ownerFor({
1637
+ key: body.ownerKey || undefined,
1638
+ scope: body.ownerScope || body.scope || 'shared',
1639
+ sessionId: body.sessionId || null,
1640
+ workspace: body.workspace || null,
1641
+ label: body.ownerLabel || body.label || 'panel',
1642
+ source: 'panel',
1643
+ })
1644
+ : null;
1645
+ if (owner) instanceManager.claimOwner(instance.id, owner, { force: body.force === true });
1138
1646
  if (body.start === true) void instance.start();
1139
1647
  sendJson(res, 201, {
1140
1648
  ok: true,
@@ -1145,11 +1653,13 @@ export function apply(ctx, config = {}) {
1145
1653
  port: instance.port,
1146
1654
  state: instance.vm.state,
1147
1655
  serial: instance.vm._serialActive || null,
1656
+ owner: owner ? owner.key : null,
1657
+ ownerInfo: owner ? instanceManager.ownerInfo(instance.id) : null,
1148
1658
  },
1149
1659
  maxInstances: instanceManager.maxInstances,
1150
1660
  });
1151
1661
  } catch (error) {
1152
- sendError(res, 400, error.message);
1662
+ sendError(res, error.status === 409 ? 409 : 400, error.message);
1153
1663
  }
1154
1664
  return;
1155
1665
  }
@@ -1169,6 +1679,7 @@ export function apply(ctx, config = {}) {
1169
1679
  sendError(res, 404, `unknown instance: ${id || '(missing)'}`);
1170
1680
  return;
1171
1681
  }
1682
+ if (req.method === 'POST' && !assertHttpOwner(req, res, id)) return;
1172
1683
  const ready = async () => {
1173
1684
  const status = await instance.status();
1174
1685
  if (status.state !== 'ready') {
@@ -1287,6 +1798,14 @@ export function apply(ctx, config = {}) {
1287
1798
  });
1288
1799
  return;
1289
1800
  }
1801
+ if (rest === 'skills') {
1802
+ await handleSkillsRequest(req, res, id, () => extraToolApi(instance));
1803
+ return;
1804
+ }
1805
+ if (rest === 'controls') {
1806
+ await handleControlRequest(req, res, id, () => extraToolApi(instance));
1807
+ return;
1808
+ }
1290
1809
  if (rest === 'snapshots') {
1291
1810
  if (req.method === 'GET') {
1292
1811
  sendJson(res, 200, instance.vm.listNamedSnapshots());
@@ -1595,6 +2114,8 @@ export function apply(ctx, config = {}) {
1595
2114
  'debug/pull',
1596
2115
  'debug/reboot',
1597
2116
  'flows',
2117
+ 'skills',
2118
+ 'controls',
1598
2119
  'network',
1599
2120
  'network/pcap',
1600
2121
  'snapshots',
@@ -1787,6 +2308,65 @@ export function apply(ctx, config = {}) {
1787
2308
  sendJson(res, 200, { ok: true, attached: serial, vm: await vm.status(), devices: await vm.listDevices() });
1788
2309
  });
1789
2310
 
2311
+ register('/apk-vm/remote', async (req, res) => {
2312
+ if (req.method === 'GET') {
2313
+ sendJson(res, 200, { ok: true, tunnel: remoteTunnel ? remoteTunnel.status() : null });
2314
+ return;
2315
+ }
2316
+ if (req.method !== 'POST') {
2317
+ sendError(res, 405, 'GET or POST only');
2318
+ return;
2319
+ }
2320
+ const body = await readJsonBody(req);
2321
+ const action = String(body.action || 'connect').toLowerCase();
2322
+ try {
2323
+ if (action === 'disconnect') {
2324
+ if (remoteTunnel) {
2325
+ await remoteTunnel.stop();
2326
+ remoteTunnel = null;
2327
+ }
2328
+ await stopScrcpy();
2329
+ await vm.detachDevice();
2330
+ frame.buffer = null;
2331
+ frame.at = 0;
2332
+ sendJson(res, 200, { ok: true, detached: true, tunnel: null, vm: await vm.status() });
2333
+ return;
2334
+ }
2335
+ if (action !== 'connect') throw new Error(`unsupported remote action: ${action}`);
2336
+ if (remoteTunnel) {
2337
+ await remoteTunnel.stop();
2338
+ remoteTunnel = null;
2339
+ }
2340
+ const tunnel = new SshAdbTunnel({
2341
+ host: body.host,
2342
+ user: body.user,
2343
+ port: body.sshPort,
2344
+ keyPath: body.keyPath,
2345
+ remotePort: body.remotePort,
2346
+ localPort: body.localPort,
2347
+ sshPath: body.sshPath,
2348
+ });
2349
+ const started = await tunnel.start().catch(async (error) => {
2350
+ await tunnel.stop();
2351
+ throw error;
2352
+ });
2353
+ remoteTunnel = tunnel;
2354
+ try {
2355
+ await stopScrcpy();
2356
+ await vm.attachDevice(started.serial);
2357
+ } catch (error) {
2358
+ await tunnel.stop();
2359
+ remoteTunnel = null;
2360
+ throw error;
2361
+ }
2362
+ frame.buffer = null;
2363
+ frame.at = 0;
2364
+ sendJson(res, 200, { ok: true, tunnel: tunnel.status(), vm: await vm.status() });
2365
+ } catch (error) {
2366
+ sendError(res, 400, error.message);
2367
+ }
2368
+ });
2369
+
1790
2370
  register('/apk-vm/vm', async (req, res) => {
1791
2371
  if (req.method !== 'POST') {
1792
2372
  sendError(res, 405, 'POST only');
@@ -2522,6 +3102,14 @@ export function apply(ctx, config = {}) {
2522
3102
  host.effect(() => mountRoutes(host.webServer), 'dsh-apk-vm: http routes');
2523
3103
  });
2524
3104
 
3105
+ ctx.effect(() => {
3106
+ return () => {
3107
+ const tunnel = remoteTunnel;
3108
+ remoteTunnel = null;
3109
+ if (tunnel) void tunnel.stop().catch(() => {});
3110
+ };
3111
+ }, 'dsh-apk-vm: ssh tunnel');
3112
+
2525
3113
  // Optional warm start: boot the VM right after the plugin activates so the
2526
3114
  // first panel/tab open lands on a running (or nearly booted) device. This is
2527
3115
  // what makes the visible "open the VM" step effectively instant; opt in with
@@ -2608,6 +3196,7 @@ export function apply(ctx, config = {}) {
2608
3196
  removePortForward: (local) => vm.removePortForward(local),
2609
3197
  screenRecord: (options) => vm.screenRecord(options),
2610
3198
  perfSnapshot: () => vm.perfSnapshot(),
3199
+ screenshotBuffer: () => vm.screenshot(),
2611
3200
  screenshot: async () => {
2612
3201
  const buffer = await vm.screenshot();
2613
3202
  const target = path.join(os.tmpdir(), `apk-vm-shot-${Date.now()}.png`);
@@ -2660,6 +3249,7 @@ export function apply(ctx, config = {}) {
2660
3249
  removePortForward: (local) => instance.vm.removePortForward(local),
2661
3250
  screenRecord: (options) => instance.screenRecord(options),
2662
3251
  perfSnapshot: () => instance.perfSnapshot(),
3252
+ screenshotBuffer: () => instance.screenshot(),
2663
3253
  screenshot: async () => {
2664
3254
  const buffer = await instance.screenshot();
2665
3255
  const target = path.join(os.tmpdir(), `apk-vm-shot-${instance.id}-${Date.now()}.png`);
@@ -2669,20 +3259,55 @@ export function apply(ctx, config = {}) {
2669
3259
  };
2670
3260
  }
2671
3261
 
3262
+ function toolOwnerContext(args, exec) {
3263
+ const session = exec && exec.agent ? exec.agent.session : null;
3264
+ const header = session && session.header ? session.header : {};
3265
+ const sessionId = header.id || header.sessionId || (session && session.id) ||
3266
+ (exec && (exec.sessionId || exec.agentId || (exec.agent && exec.agent.id))) || null;
3267
+ const workspace = header.cwd || (exec && exec.agent && exec.agent.cwd) ||
3268
+ (exec && exec.cwd) || null;
3269
+ return {
3270
+ scope: normalizeScope((args && (args.ownerScope || args.owner_scope)) || OWNER_SCOPE.SHARED),
3271
+ sessionId,
3272
+ workspace,
3273
+ label: (args && (args.ownerLabel || args.owner_label)) || null,
3274
+ source: 'tool',
3275
+ };
3276
+ }
3277
+
3278
+ function ownerTakeoverRequested(args) {
3279
+ return Boolean(args && (args.ownerForce === true || args.takeover === true));
3280
+ }
3281
+
2672
3282
  async function resolveToolApi(args, exec) {
2673
3283
  const requested = String((args && args.instance) || '').trim();
3284
+ const action = String((args && args.action) || '');
3285
+ // Ownership inspection/list is intentionally read-only: an Agent must be
3286
+ // able to see why a VM is busy without claiming or forcing it.
3287
+ if (action === 'owner_status' || action === 'list_instances') {
3288
+ if (requested && requested !== 'default') {
3289
+ if (!instanceManager) throw new Error('multi-instance support is disabled');
3290
+ const instance = instanceManager.get(requested);
3291
+ if (!instance) throw new Error(`unknown apk_vm instance: ${requested}`);
3292
+ return extraToolApi(instance);
3293
+ }
3294
+ return defaultToolApi();
3295
+ }
3296
+ const owner = toolOwnerContext(args, exec);
3297
+ const force = ownerTakeoverRequested(args);
2674
3298
  if (requested) {
2675
- if (requested === 'default') return defaultToolApi();
3299
+ if (requested === 'default') {
3300
+ if (instanceManager) instanceManager.claimOwner('default', owner, { force });
3301
+ return defaultToolApi();
3302
+ }
2676
3303
  if (!instanceManager) throw new Error('multi-instance support is disabled');
2677
3304
  const instance = instanceManager.get(requested);
2678
3305
  if (!instance) throw new Error(`unknown apk_vm instance: ${requested}`);
3306
+ instanceManager.claimOwner(instance.id, owner, { force });
2679
3307
  return extraToolApi(instance);
2680
3308
  }
2681
- if (instanceManager && exec && exec.agent) {
2682
- const session = exec.agent.session;
2683
- const header = session && session.header ? session.header : {};
2684
- const key = header.id || header.sessionId || (session && session.id) || 'anonymous';
2685
- const assigned = await instanceManager.forAgent(key);
3309
+ if (instanceManager && exec && (exec.agent || owner.sessionId)) {
3310
+ const assigned = await instanceManager.forOwner(owner, { force });
2686
3311
  if (assigned && assigned.default === true) return defaultToolApi();
2687
3312
  if (assigned && assigned.id) registerInstanceRoutes?.(assigned.id);
2688
3313
  return extraToolApi(assigned);
@@ -2753,6 +3378,171 @@ export function apply(ctx, config = {}) {
2753
3378
  return Boolean(args.text || args.resourceId || args.contentDesc || args.className);
2754
3379
  }
2755
3380
 
3381
+ function toolCodebook(instanceId, args) {
3382
+ const active = skillRecorder.active(instanceId);
3383
+ if (active) return active.skill.codebook;
3384
+ if (args && args.codebook) return normalizeCodebook(args.codebook);
3385
+ throw new Error('no active Skill codebook; start skill_start first or pass codebook');
3386
+ }
3387
+
3388
+ async function toolResolveControl(api, codebook, code, options = {}) {
3389
+ const value = String(code || '').trim();
3390
+ if (!value) throw new Error('control code is required');
3391
+ const dump = await api.uiDump();
3392
+ const parsed = parseUiHierarchy(dump.xml);
3393
+ const wantsImage = options.withImage === true
3394
+ || (codebook.entries || []).some((entry) => entry.features && entry.features.image);
3395
+ if (wantsImage && typeof api.screenshotBuffer === 'function') {
3396
+ try {
3397
+ attachNodeImageFeatures(await api.screenshotBuffer(), parsed.nodes);
3398
+ } catch {
3399
+ // Image matching will report a clear "no screenshot image features" error.
3400
+ }
3401
+ }
3402
+ let screen = null;
3403
+ try {
3404
+ screen = await api.screenSize();
3405
+ } catch {
3406
+ screen = null;
3407
+ }
3408
+ const result = resolveControl(codebook, value, parsed.nodes, { screen });
3409
+ if (!result.node || !result.node.bounds || !result.node.bounds.center) {
3410
+ throw new Error(`control ${value} has no usable bounds on the current screen`);
3411
+ }
3412
+ return { ...result, snapshotId: snapshotIdForXml(dump.xml), screen };
3413
+ }
3414
+
3415
+ function toolRecordControl(instanceId, step, args) {
3416
+ if (args && args.record === false) return false;
3417
+ if (!skillRecorder.active(instanceId)) return false;
3418
+ skillRecorder.add(instanceId, step);
3419
+ return true;
3420
+ }
3421
+
3422
+ async function toolControlAction(api, action, args) {
3423
+ await ensureToolApiReady(api, action);
3424
+ if (action === 'control_ui') {
3425
+ const payload = buildInspectorPayload(await api.uiDump(), await api.screenSize().catch(() => null));
3426
+ return { ok: true, summary: `${payload.controls.length} control(s), snapshot ${payload.snapshotId || '?'}`, result: payload };
3427
+ }
3428
+ if (action === 'control_launch') {
3429
+ const pkg = String(args.packageName || args.package || '').trim();
3430
+ if (!pkg) throw new Error('control_launch requires packageName');
3431
+ const result = await api.launchPackage(pkg);
3432
+ const recorded = toolRecordControl(api.id, { action: 'launch', package: pkg }, args);
3433
+ return { ok: true, summary: `launched ${pkg}${recorded ? ' (recorded)' : ''}`, result: { package: pkg, result, recorded } };
3434
+ }
3435
+ if (action === 'control_codebook') {
3436
+ const active = skillRecorder.active(api.id);
3437
+ if (active) {
3438
+ const codebook = await skillRecorder.updateCodebook(api.id, args.codebook || {});
3439
+ return { ok: true, summary: `updated recording codebook (${codebook.entries.length} codes)`, result: { codebook } };
3440
+ }
3441
+ const id = String(args.skillId || '').trim();
3442
+ if (!id) throw new Error('control_codebook needs skillId when no recording is active');
3443
+ const skill = await skillStore.get(id);
3444
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
3445
+ skill.codebook = normalizeCodebook(args.codebook || {});
3446
+ const saved = await skillStore.save(skill);
3447
+ return { ok: true, summary: `saved codebook for ${saved.name} (${saved.codebook.entries.length} codes)`, result: { skill: saved } };
3448
+ }
3449
+ const codebook = toolCodebook(api.id, args);
3450
+ if (action === 'control_features') {
3451
+ const code = String(args.code || '').trim();
3452
+ if (!code) throw new Error('control_features requires code');
3453
+ const target = await toolResolveControl(api, codebook, code, { withImage: true });
3454
+ const image = target.node && target.node.imageFeatures
3455
+ ? {
3456
+ name: String(args.imageName || code).slice(0, 120),
3457
+ hash: target.node.imageFeatures.hash,
3458
+ avgColor: target.node.imageFeatures.avgColor,
3459
+ dominantColor: target.node.imageFeatures.dominantColor,
3460
+ maxDistance: args.maxDistance,
3461
+ colorTolerance: args.colorTolerance,
3462
+ }
3463
+ : null;
3464
+ const entry = {
3465
+ code,
3466
+ ...(args.name ? { name: String(args.name) } : {}),
3467
+ features: { ...suggestFeatures(target.node), ...(image ? { image } : {}) },
3468
+ };
3469
+ return {
3470
+ ok: true,
3471
+ summary: `features for ${target.code}${image ? ` + image ${image.name}` : ''}`,
3472
+ result: {
3473
+ code: target.code,
3474
+ snapshotId: target.snapshotId,
3475
+ features: target.node.features || suggestFeatures(target.node),
3476
+ imageFeatures: target.node.imageFeatures || null,
3477
+ suggestedEntry: entry,
3478
+ },
3479
+ };
3480
+ }
3481
+ if (action === 'control_assert' || action === 'control_wait') {
3482
+ const code = String(args.code || '').trim();
3483
+ const exists = args.exists !== false;
3484
+ let target = null;
3485
+ let error = null;
3486
+ try {
3487
+ target = await toolResolveControl(api, codebook, code);
3488
+ } catch (caught) {
3489
+ error = caught;
3490
+ }
3491
+ if (exists && !target) throw error || new Error(`control ${code} is not visible`);
3492
+ if (!exists && target) throw new Error(`control ${code} is visible; exists=false assertion failed`);
3493
+ const recordAction = action === 'control_wait' ? 'waitFor' : 'assert';
3494
+ const recorded = toolRecordControl(api.id, { action: recordAction, code, ...(exists ? {} : { exists: false }) }, args);
3495
+ return {
3496
+ ok: true,
3497
+ summary: `${code} ${exists ? 'visible' : 'absent'}${recorded ? ' (recorded)' : ''}`,
3498
+ result: { code, exists, snapshotId: target ? target.snapshotId : null, recorded },
3499
+ };
3500
+ }
3501
+ if (action === 'control_swipe') {
3502
+ const fromCode = String(args.fromCode || '').trim();
3503
+ const toCode = String(args.toCode || '').trim();
3504
+ const from = fromCode ? await toolResolveControl(api, codebook, fromCode) : null;
3505
+ const to = toCode ? await toolResolveControl(api, codebook, toCode) : null;
3506
+ const x1 = from ? from.node.bounds.center.x : Number(args.x1);
3507
+ const y1 = from ? from.node.bounds.center.y : Number(args.y1);
3508
+ const x2 = to ? to.node.bounds.center.x : Number(args.x2);
3509
+ const y2 = to ? to.node.bounds.center.y : Number(args.y2);
3510
+ if (![x1, y1, x2, y2].every(Number.isFinite)) throw new Error('control_swipe needs fromCode/toCode or x1,y1,x2,y2');
3511
+ const durationMs = Math.max(1, Math.min(60000, Number(args.durationMs) || 300));
3512
+ await api.input({ type: 'swipe', x1, y1, x2, y2, durationMs });
3513
+ const step = fromCode || toCode
3514
+ ? { action: 'swipe', fromCode: fromCode || undefined, toCode: toCode || undefined, durationMs }
3515
+ : { action: 'swipe', x1, y1, x2, y2, durationMs };
3516
+ const recorded = toolRecordControl(api.id, step, args);
3517
+ return { ok: true, summary: `swiped ${fromCode || `${x1},${y1}`} -> ${toCode || `${x2},${y2}`}${recorded ? ' (recorded)' : ''}`, result: { x1, y1, x2, y2, recorded } };
3518
+ }
3519
+ const code = String(args.code || '').trim();
3520
+ const target = await toolResolveControl(api, codebook, code);
3521
+ const center = target.node.bounds.center;
3522
+ if (action === 'control_tap') {
3523
+ await api.input({ type: 'tap', x: center.x, y: center.y });
3524
+ const recorded = toolRecordControl(api.id, { action: 'tap', code }, args);
3525
+ return { ok: true, summary: `tapped ${target.code} at ${center.x},${center.y}${recorded ? ' (recorded)' : ''}`, result: { code: target.code, x: center.x, y: center.y, snapshotId: target.snapshotId, recorded } };
3526
+ }
3527
+ if (action === 'control_long_press') {
3528
+ const durationMs = Math.max(300, Math.min(60000, Number(args.durationMs) || 800));
3529
+ await api.input({ type: 'swipe', x1: center.x, y1: center.y, x2: center.x, y2: center.y, durationMs });
3530
+ const recorded = toolRecordControl(api.id, { action: 'longPress', code, durationMs }, args);
3531
+ return { ok: true, summary: `long-pressed ${target.code}${recorded ? ' (recorded)' : ''}`, result: { code: target.code, durationMs, recorded } };
3532
+ }
3533
+ if (action === 'control_input') {
3534
+ const text = args.text === undefined ? (args.value === undefined ? '' : String(args.value)) : String(args.text);
3535
+ const submit = args.submit === true;
3536
+ await api.input({ type: 'tap', x: center.x, y: center.y });
3537
+ await new Promise((resolve) => setTimeout(resolve, 120));
3538
+ if (text) await api.input({ type: 'text', text: text.slice(0, 4096) });
3539
+ if (submit) await api.input({ type: 'key', key: 'ENTER' });
3540
+ const recorded = toolRecordControl(api.id, { action: 'input', code, value: text, ...(submit ? { submit: true } : {}) }, args);
3541
+ return { ok: true, summary: `typed ${text.length} char(s) into ${target.code}${submit ? ' + ENTER' : ''}${recorded ? ' (recorded)' : ''}`, result: { code: target.code, chars: text.length, submit, recorded } };
3542
+ }
3543
+ throw new Error(`unsupported control action: ${action}`);
3544
+ }
3545
+
2756
3546
  const apkVmTool = {
2757
3547
  name: 'apk_vm',
2758
3548
  description:
@@ -2760,7 +3550,10 @@ export function apply(ctx, config = {}) {
2760
3550
  'The VM is usually already running (warm start); adbd runs as root once ready. ' +
2761
3551
  'Actions: info, shell, logcat, getprop, setprop, packages, install, push, pull, reboot, root, ' +
2762
3552
  'force_stop, clear_data, uninstall, rotate, ui_dump, inspect_ui, proxy, install_ca, network, record, perf, screenshot, tap, swipe, long_press, key, text, ' +
2763
- 'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, flow_start, flow_stop, flow_list, flow_replay, storage, clean_storage. ' +
3553
+ 'apk_info, find_ui, assert_text, tap_text, clipboard_get, clipboard_set, devices, attach_device, detach_device, start, stop, list_instances, create_instance, destroy_instance, owner_status, claim_vm, release_vm, flow_start, flow_stop, flow_list, flow_replay, storage, clean_storage, ' +
3554
+ 'skill_list, skill_get, skill_save, skill_delete, skill_start, skill_stop, skill_cancel, skill_run, skill_codebook, control_ui, control_features, control_codebook, control_tap, control_input, control_long_press, control_swipe, control_assert, control_wait, control_launch. ' +
3555
+ 'App-operation Skills use a persisted Control Codebook (stable codes such as LOGIN_BTN or A01) instead of raw coordinates; record once with skill_start + control_* then replay with skill_run to reach a page quickly. ' +
3556
+ 'VM ownership: pass ownerScope=conversation or project to use a dedicated VM for this session/project; shared is the default. owner_status / claim_vm / release_vm inspect or change the current lease. A VM owned by another conversation is never taken silently: the tool returns a vm-busy error unless ownerForce=true (explicit takeover). ' +
2764
3557
  'Multi-instance: pass `instance` to target an isolated VM; omit it to use the calling Agent\'s ' +
2765
3558
  'assigned instance (first Agent gets the default VM, later Agents get isolated instances). ' +
2766
3559
  'Use shell for low-level Android commands, logcat for logs, ' +
@@ -2773,9 +3566,12 @@ export function apply(ctx, config = {}) {
2773
3566
  properties: {
2774
3567
  action: {
2775
3568
  type: 'string',
2776
- description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|network|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage',
3569
+ description: 'info|shell|logcat|getprop|setprop|packages|install|push|pull|reboot|root|force_stop|clear_data|uninstall|rotate|ui_dump|inspect_ui|proxy|install_ca|network|record|perf|screenshot|tap|swipe|long_press|key|text|apk_info|find_ui|assert_text|tap_text|clipboard_get|clipboard_set|devices|attach_device|detach_device|start|stop|list_instances|create_instance|destroy_instance|owner_status|claim_vm|release_vm|flow_start|flow_stop|flow_list|flow_replay|storage|clean_storage|skill_list|skill_get|skill_save|skill_delete|skill_start|skill_stop|skill_cancel|skill_run|skill_codebook|control_ui|control_features|control_codebook|control_tap|control_input|control_long_press|control_swipe|control_assert|control_wait|control_launch',
2777
3570
  },
2778
3571
  instance: { type: 'string', description: 'Target VM instance id (default or an extra instance from list_instances). Omit for the calling Agent\'s assigned instance.' },
3572
+ ownerScope: { type: 'string', enum: ['shared', 'conversation', 'project'], description: 'VM ownership scope: shared (default), conversation (dedicated per DSH session), or project (dedicated per workspace).' },
3573
+ ownerLabel: { type: 'string', description: 'Optional human-readable owner label shown in the VM panel.' },
3574
+ ownerForce: { type: 'boolean', description: 'Explicitly take over a VM owned by another conversation/project (default false; conflicts return vm-busy).' },
2779
3575
  instanceName: { type: 'string', description: 'create_instance: optional name for the new isolated instance.' },
2780
3576
  start: { type: 'boolean', description: 'create_instance: start the new instance immediately when true.' },
2781
3577
  command: { type: 'string', description: 'Shell command for action=shell.' },
@@ -2822,6 +3618,24 @@ export function apply(ctx, config = {}) {
2822
3618
  testHost: { type: 'string', description: 'network test: host to ping/TCP-test (default: emulator host alias).' },
2823
3619
  testPort: { type: 'integer', description: 'network test: TCP port.' },
2824
3620
  pcapPath: { type: 'string', description: 'network pcap: host path ending in .pcap; capture starts on the next emulator start.' },
3621
+ code: { type: 'string', description: 'Control Codebook code or semantic name (e.g. A01, LOGIN_BTN); used by control_* and Skill steps.' },
3622
+ imageName: { type: 'string', description: 'control_features: human name for the captured image feature (e.g. star-icon).' },
3623
+ maxDistance: { type: 'number', description: 'control_features: optional image dHash distance tolerance (default 10).' },
3624
+ colorTolerance: { type: 'number', description: 'control_features: optional RGB colour tolerance (default 36).' },
3625
+ skillId: { type: 'string', description: 'Skill id for skill_get/skill_save/skill_delete/skill_run/skill_codebook.' },
3626
+ skillName: { type: 'string', description: 'Human name for skill_start/skill_stop.' },
3627
+ skillSteps: { type: 'array', description: 'skill_save: array of semantic steps (each uses code/selector, never raw coordinates).', items: { type: 'object', additionalProperties: true } },
3628
+ codebook: { type: 'object', description: 'Control Codebook: { entries: [{ code, name, aliases, features: {...} }] } or an entries array.', additionalProperties: true },
3629
+ targetCode: { type: 'string', description: 'Skill target code; skill_run stops successfully once it is visible.' },
3630
+ untilCode: { type: 'string', description: 'skill_run: alias for targetCode.' },
3631
+ fromCode: { type: 'string', description: 'control_swipe: code of the start control.' },
3632
+ toCode: { type: 'string', description: 'control_swipe: code of the end control.' },
3633
+ speed: { type: 'number', description: 'Skill replay delay multiplier (1 = recorded speed, 2 = twice as fast).' },
3634
+ variables: { type: 'object', description: 'Skill replay variables interpolated into {{name}} placeholders.', additionalProperties: true },
3635
+ dryRun: { type: 'boolean', description: 'skill_run: resolve checks without touching the device.' },
3636
+ exists: { type: 'boolean', description: 'control_assert: expected visibility (default true; false asserts absent).' },
3637
+ record: { type: 'boolean', description: 'control_*: record the step while a Skill recording is active (default true).' },
3638
+ description: { type: 'string', description: 'skill_start/skill_save: optional human description.' },
2825
3639
  },
2826
3640
  required: ['action'],
2827
3641
  },
@@ -2851,6 +3665,7 @@ export function apply(ctx, config = {}) {
2851
3665
 
2852
3666
  if (action === 'list_instances') {
2853
3667
  const defaultStatus = await vm.status();
3668
+ const defaultOwnerInfo = instanceManager ? instanceManager.ownerInfo('default') : null;
2854
3669
  const instances = [
2855
3670
  {
2856
3671
  id: 'default',
@@ -2860,12 +3675,16 @@ export function apply(ctx, config = {}) {
2860
3675
  state: defaultStatus.state,
2861
3676
  serial: defaultStatus.serial || null,
2862
3677
  root: defaultStatus.root === true,
3678
+ owner: instanceManager ? instanceManager.defaultOwner : null,
3679
+ ownerInfo: defaultOwnerInfo,
3680
+ ownerLabel: defaultOwnerInfo ? defaultOwnerInfo.label : null,
3681
+ scope: defaultOwnerInfo ? defaultOwnerInfo.scope : null,
2863
3682
  },
2864
3683
  ...(instanceManager ? instanceManager.list() : []),
2865
3684
  ];
2866
3685
  return {
2867
3686
  ok: true,
2868
- summary: instances.map((entry) => `${entry.id}:${entry.state}${entry.serial ? '@' + entry.serial : ''}`).join(', '),
3687
+ summary: instances.map((entry) => `${entry.id}:${entry.state}${entry.serial ? '@' + entry.serial : ''}${entry.ownerInfo ? ' owned:' + entry.ownerInfo.label : ''}`).join(', '),
2869
3688
  result: { instances, maxInstances: instanceManager ? instanceManager.maxInstances : 1 },
2870
3689
  };
2871
3690
  }
@@ -2873,11 +3692,16 @@ export function apply(ctx, config = {}) {
2873
3692
  if (!instanceManager) throw new Error('multi-instance support is disabled');
2874
3693
  const instance = await instanceManager.create({ name: args.instanceName || args.name });
2875
3694
  registerInstanceRoutes?.(instance.id);
3695
+ if (args.ownerScope) {
3696
+ const owner = toolOwnerContext(args, exec);
3697
+ instanceManager.claimOwner(instance.id, owner, { force: ownerTakeoverRequested(args) });
3698
+ }
2876
3699
  if (args.start === true) void instance.start();
3700
+ const ownerInfo = instanceManager.ownerInfo(instance.id);
2877
3701
  return {
2878
3702
  ok: true,
2879
- summary: `created instance ${instance.id} (avd=${instance.avdName}, port=${instance.port})`,
2880
- result: { id: instance.id, avdName: instance.avdName, port: instance.port },
3703
+ summary: `created instance ${instance.id} (avd=${instance.avdName}, port=${instance.port})${ownerInfo ? ' for ' + ownerInfo.label : ''}`,
3704
+ result: { id: instance.id, avdName: instance.avdName, port: instance.port, owner: ownerInfo },
2881
3705
  };
2882
3706
  }
2883
3707
  if (action === 'destroy_instance') {
@@ -2923,6 +3747,40 @@ export function apply(ctx, config = {}) {
2923
3747
  frame.buffer = null;
2924
3748
  return { ok: true, summary: 'detached external device; managed AVD identity restored', result: await vm.status() };
2925
3749
  }
3750
+ if (action === 'owner_status') {
3751
+ if (!instanceManager) throw new Error('multi-instance support is disabled');
3752
+ return {
3753
+ ok: true,
3754
+ summary: instanceManager.ownerList().length
3755
+ ? instanceManager.ownerList().map((entry) => `${entry.id}:${entry.label}`).join(', ')
3756
+ : 'no VM leases',
3757
+ result: { default: instanceManager.ownerInfo('default'), owners: instanceManager.ownerList() },
3758
+ };
3759
+ }
3760
+ if (action === 'claim_vm') {
3761
+ if (!instanceManager) throw new Error('multi-instance support is disabled');
3762
+ const id = String(args.instance || 'default');
3763
+ if (id !== 'default' && !instanceManager.get(id)) throw new Error(`unknown instance: ${id}`);
3764
+ const owner = toolOwnerContext(args, exec);
3765
+ const result = instanceManager.claimOwner(id, owner, { force: ownerTakeoverRequested(args) });
3766
+ return {
3767
+ ok: true,
3768
+ summary: `claimed ${id} for ${result.lease.label}${result.previous ? ` (took over from ${result.previous.label})` : ''}`,
3769
+ result: { instanceId: id, ...result },
3770
+ };
3771
+ }
3772
+ if (action === 'release_vm') {
3773
+ if (!instanceManager) throw new Error('multi-instance support is disabled');
3774
+ const id = String(args.instance || 'default');
3775
+ if (id !== 'default' && !instanceManager.get(id)) throw new Error(`unknown instance: ${id}`);
3776
+ const owner = toolOwnerContext(args, exec);
3777
+ const released = instanceManager.releaseOwner(id, owner, { force: ownerTakeoverRequested(args) });
3778
+ return {
3779
+ ok: true,
3780
+ summary: released ? `released ${id} (was ${released.label})` : `${id} is not leased`,
3781
+ result: { instanceId: id, released },
3782
+ };
3783
+ }
2926
3784
 
2927
3785
  const api = await resolveToolApi(args, exec);
2928
3786
  if (action === 'flow_list') {
@@ -2948,6 +3806,106 @@ export function apply(ctx, config = {}) {
2948
3806
  });
2949
3807
  return { ok: true, summary: `replayed ${replayed.steps} step(s) from ${replayed.name}`, result: replayed };
2950
3808
  }
3809
+ if (action.startsWith('skill_')) {
3810
+ if (action === 'skill_list') {
3811
+ const skills = await skillStore.list();
3812
+ const active = skillRecorder.active(api.id);
3813
+ return {
3814
+ ok: true,
3815
+ summary: `${skills.length} Skill(s) on ${api.id}${active ? `; recording ${active.skill.name}` : ''}`,
3816
+ result: { instance: api.id, skills: skills.map(skillSummary), recording: active ? skillSummary(active.skill) : null },
3817
+ };
3818
+ }
3819
+ if (action === 'skill_get') {
3820
+ const id = String(args.skillId || '').trim();
3821
+ if (!id) throw new Error('skill_get requires skillId');
3822
+ const skill = await skillStore.get(id);
3823
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
3824
+ return { ok: true, summary: `${skill.name}: ${skill.steps.length} step(s), ${skill.codebook.entries.length} code(s)`, result: skill };
3825
+ }
3826
+ if (action === 'skill_delete') {
3827
+ const id = String(args.skillId || '').trim();
3828
+ if (!id) throw new Error('skill_delete requires skillId');
3829
+ const removed = await skillStore.remove(id);
3830
+ return { ok: true, summary: `deleted Skill ${id}`, result: { removed } };
3831
+ }
3832
+ if (action === 'skill_start') {
3833
+ const started = await skillRecorder.start(api.id, {
3834
+ name: args.skillName || args.name,
3835
+ id: args.skillId,
3836
+ package: args.packageName,
3837
+ description: args.description,
3838
+ target: args.targetCode,
3839
+ codebook: args.codebook,
3840
+ });
3841
+ return { ok: true, summary: `recording Skill ${started.name}; use control_* with codes, then skill_stop`, result: started };
3842
+ }
3843
+ if (action === 'skill_stop') {
3844
+ const saved = await skillRecorder.stop(api.id, {
3845
+ name: args.skillName || args.name,
3846
+ package: args.packageName,
3847
+ description: args.description,
3848
+ });
3849
+ return { ok: true, summary: `saved Skill ${saved.name} (${saved.id}, ${saved.steps.length} steps)`, result: saved };
3850
+ }
3851
+ if (action === 'skill_cancel') {
3852
+ return { ok: true, summary: `cancelled recording on ${api.id}`, result: { cancelled: skillRecorder.cancel(api.id) } };
3853
+ }
3854
+ if (action === 'skill_save') {
3855
+ const id = String(args.skillId || '').trim();
3856
+ const existing = id ? await skillStore.get(id) : null;
3857
+ const source = {
3858
+ ...(existing || {}),
3859
+ ...(id ? { id } : {}),
3860
+ ...(args.skillName ? { name: args.skillName } : {}),
3861
+ ...(args.description ? { description: args.description } : {}),
3862
+ ...(args.packageName ? { package: args.packageName } : {}),
3863
+ ...(args.targetCode ? { target: args.targetCode } : {}),
3864
+ ...(args.codebook ? { codebook: args.codebook } : {}),
3865
+ ...(Array.isArray(args.skillSteps) ? { steps: args.skillSteps } : {}),
3866
+ };
3867
+ const saved = await skillStore.save(normalizeSkill(source));
3868
+ return { ok: true, summary: `saved Skill ${saved.name} (${saved.id}, ${saved.steps.length} steps)`, result: saved };
3869
+ }
3870
+ if (action === 'skill_codebook') {
3871
+ const active = skillRecorder.active(api.id);
3872
+ if (active) {
3873
+ const codebook = await skillRecorder.updateCodebook(api.id, args.codebook || {});
3874
+ return { ok: true, summary: `updated recording codebook (${codebook.entries.length} codes)`, result: { codebook } };
3875
+ }
3876
+ const id = String(args.skillId || '').trim();
3877
+ if (!id) throw new Error('skill_codebook requires skillId when no recording is active');
3878
+ const skill = await skillStore.get(id);
3879
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
3880
+ skill.codebook = normalizeCodebook(args.codebook || {});
3881
+ const saved = await skillStore.save(skill);
3882
+ return { ok: true, summary: `saved codebook for ${saved.name} (${saved.codebook.entries.length} codes)`, result: saved };
3883
+ }
3884
+ if (action === 'skill_run') {
3885
+ const id = String(args.skillId || '').trim();
3886
+ if (!id) throw new Error('skill_run requires skillId');
3887
+ const skill = await skillStore.get(id);
3888
+ if (!skill) throw new Error(`unknown Skill: ${id}`);
3889
+ await ensureToolApiReady(api, action);
3890
+ const result = await runSkill(skill, api, {
3891
+ speed: args.speed,
3892
+ untilCode: args.untilCode || args.targetCode,
3893
+ variables: args.variables,
3894
+ dryRun: args.dryRun === true,
3895
+ timeoutMs: args.timeoutMs,
3896
+ package: args.packageName,
3897
+ });
3898
+ return {
3899
+ ok: true,
3900
+ summary: `ran ${skill.name}: ${result.stepsRun}/${result.stepsTotal} step(s) in ${result.durationMs}ms${result.reached ? `, reached ${result.untilCode}` : result.untilCode ? `, target ${result.untilCode} not reached` : ''}`,
3901
+ result,
3902
+ };
3903
+ }
3904
+ throw new Error(`unsupported skill action: ${action}`);
3905
+ }
3906
+ if (action.startsWith('control_')) {
3907
+ return toolControlAction(api, action, args);
3908
+ }
2951
3909
  if (action === 'storage') {
2952
3910
  const report = await collectStorage({
2953
3911
  sdkRoot: storageSdkRoot(),