@kingsoftcloud/agentkit-personal-assistant 0.0.0-stage → 0.1.7

package/scripts/verification/verify-desktop-applications-linux.mjs

@@ -0,0 +1,46 @@
+/**
+ * 仅在全新一次性 Linux 容器中验证真实 dock 点击、文件管理器与进程清理。
+ * 禁止在正在运行的云端 Pod 执行；已有 :99 桌面时会在写文件前拒绝启动。
+ * 截图为显式验收产物，不记录视频流。此结果不替代目标 AppArmor 证明。
+ */
+import assert from 'node:assert/strict';import {execFile as cb} from 'node:child_process';import {promisify} from 'node:util';import {readFile,readdir,writeFile,mkdir,access,stat} from 'node:fs/promises';
+import {createComputerAgentServer} from '../../runtime/computer-agentd.mjs';import {createDesktopController} from '../../runtime/desktop-session.mjs';
+import {createCloudBrowser} from '../../runtime/cloud-browser.mjs';import {startCdpTransport} from '../../runtime/cloud-browser-cdp.mjs';
+const args=process.argv.slice(2), index=args.indexOf('--evidence');
+const evidence=index<0?'/tmp/pa-desktop-app-evidence':args[index+1];
+assert.equal(process.platform,'linux','仅用于一次性 Linux 容器');
+assert.ok(!process.env.KUBERNETES_SERVICE_HOST,'禁止在 Kubernetes Pod 中新建验收桌面，请使用现存 Broker 的网关验收脚本');
+try { await access('/tmp/.X11-unix/X99'); throw new Error('检测到现有 :99 桌面，禁止启动第二套验收桌面'); } catch(error) { if(error.code!=='ENOENT')throw error; }
+await mkdir(evidence,{recursive:true});
+const exec=promisify(cb),delay=ms=>new Promise(r=>setTimeout(r,ms)),env={...process.env,DISPLAY:':99',AGENTKIT_DESKTOP_MODE:'1',AGENTKIT_WORKSPACE_DIR:'/workspace',COMPUTER_PORT:'0',USER_ID:'local-proof',ASSISTANT_ID:'local-proof',COMPUTER_ID:'local-proof'};
+process.env.AGENTKIT_DESKTOP_MODE='1';process.env.DISPLAY=':99';
+const identity={userId:'local-proof',assistantId:'local-proof',computerId:'local-proof',botId:'local-proof',taskId:'local-proof'};let desktop;const transports=[],launchErrors=[];const service=createComputerAgentServer({env,logger:{info:line=>console.info(line),error:line=>{console.error(line);try{const event=JSON.parse(line);if(event.event==='desktop-app-launch-failed')launchErrors.push(event)}catch{}}},desktopFactory:options=>(desktop=createDesktopController(options)),browserFactory:options=>createCloudBrowser({...options,transportFactory:async args=>{const transport=await startCdpTransport(args);transports.push(transport);return transport}})});const report={scope:'本地 Linux 依赖probe+候选源码，非最终镜像/目标AppArmor',checks:[]};
+const ps=async()=>{const a=[];for(const p of await readdir('/proc'))if(/^\d+$/.test(p)){try{const state=await readFile(`/proc/${p}/status`,'utf8');if(/^State:\s+Z/m.test(state))continue;const comm=(await readFile(`/proc/${p}/comm`,'utf8')).trim(),args=(await readFile(`/proc/${p}/cmdline`,'utf8')).split('\0').filter(Boolean);if(args.length&&(['Xvfb','fluxbox','xterm','tint2','thunar','dbus-daemon','xfconfd'].includes(comm)||(comm==='chromium'&&!args.some(s=>s.startsWith('--type=')))))a.push({pid:+p,comm,args})}catch{}}return a};
+const wait=async(fn,label,timeout=6000)=>{const end=Date.now()+timeout;while(Date.now()<end){try{const r=await fn();if(r)return r}catch{}await delay(50)}throw new Error('timeout '+label)};
+const geometry=async id=>Object.fromEntries((await exec('xdotool',['getwindowgeometry','--shell',id],{env})).stdout.trim().split('\n').map(x=>x.split('=')));
+const window=async pattern=>{let ids;try{ids=(await exec('xdotool',['search','--onlyvisible','--class',pattern],{env})).stdout.trim().split('\n')}catch{return null}for(const id of ids){const g=await geometry(id);if(+g.WIDTH>=300&&+g.HEIGHT>=200)return{id,geometry:g,name:(await exec('xdotool',['getwindowname',id],{env})).stdout.trim()}}return null};
+let port,leaseId,sessionId;
+const post=async(path,payload={},status=200)=>{const r=await fetch(`http://127.0.0.1:${port}/broker/${path}`,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({...identity,leaseId,sessionId,...payload})});const b=await r.json();assert.equal(r.status,status,JSON.stringify(b));return b};
+const click=async(x,y)=>{for(const event of [{type:'pointermove',x,y},{type:'button',button:1,action:'down',x,y},{type:'button',button:1,action:'up'}])await post('desktop/input',{event},202)};
+try{
+ await writeFile('/workspace/PA_VISIBLE_FILE.txt','本地真实文件管理器验收\n');service.listen();await service.whenReady;port=service.server.address().port;
+ leaseId=(await post('lease/acquire')).lease.leaseId;sessionId=(await post('desktop/session')).sessionId;
+ const dockId=await wait(async()=>{try{return(await exec('xdotool',['search','--onlyvisible','--name','^AgentKit Dock$'],{env})).stdout.trim().split('\n')[0]}catch{return null}},'dock visible');const dg=await geometry(dockId);report.dockGeometry=dg;
+ await exec('import',['-display',':99','-window','root',evidence+'/dock-three-apps.png'],{env});
+ const initial=await ps(),oldChrome=initial.find(x=>x.comm==='chromium');assert.ok(oldChrome);report.initialProcesses=initial;
+ const originalProfile=transports[0].userDataDir;assert.equal(originalProfile,'/var/lib/agentkit/computer/chromium-profile');assert.equal((await stat(originalProfile)).mode&0o777,0o700);await writeFile(originalProfile+'/fixture-sentinel','private-local-fixture');const fixtureCookie={name:'pa_local_fixture',value:'local-proof-not-a-credential',url:'https://example.com/',expires:Math.floor(Date.now()/1000)+3600};await transports[0].connection.send('Storage.setCookies',{cookies:[fixtureCookie]});
+ const positions={browser:{x:+dg.X+32,y:+dg.Y+27},terminal:{x:+dg.X+82,y:+dg.Y+27},files:{x:+dg.X+132,y:+dg.Y+27}};
+ await click(positions.files.x,positions.files.y);const files=await wait(()=>window('Thunar'),'visible workspace folder');report.fileWindow=files;assert.match(files.name,/workspace/i);await delay(300);await exec('import',['-display',':99','-window','root',evidence+'/workspace-file-manager.png'],{env});report.checks.push({name:'真实点击文件入口打开 /workspace 并显示目录',passed:true});
+ await click(positions.terminal.x,positions.terminal.y);await wait(async()=>{const id=(await exec('xdotool',['getactivewindow'],{env})).stdout.trim();return(await exec('xprop',['-display',':99','-id',id,'WM_CLASS'],{env})).stdout.includes('XTerm')},'terminal focus');report.checks.push({name:'真实点击终端入口复用现有终端',passed:true});
+ await click(positions.browser.x,positions.browser.y);await wait(async()=>{const id=(await exec('xdotool',['getactivewindow'],{env})).stdout.trim();return(await exec('xdotool',['getwindowname',id],{env})).stdout.includes('Chromium')},'browser focus');assert.equal((await ps()).find(x=>x.comm==='chromium').pid,oldChrome.pid);report.checks.push({name:'真实点击浏览器入口复用受管 Chromium 主进程',passed:true,pid:oldChrome.pid});
+ let fileWindow=files;
+ for(let n=0;n<10;n++){
+  await exec('xdotool',['windowclose',fileWindow.id],{env});await wait(async()=>!desktop.stats().fileManagerRunning,'file manager exit');
+  await click(positions.files.x,positions.files.y);fileWindow=await wait(()=>window('Thunar'),'file reopen');const current=await ps();for(const comm of ['Xvfb','tint2','thunar'])assert.equal(current.filter(x=>x.comm===comm).length,1,comm+' duplicated');
+ }
+ report.checks.push({name:'文件管理器连续开关十次，Xvfb/tint2/thunar 始终各一个',passed:true});
+ await click(positions.browser.x,positions.browser.y);await wait(async()=>{const id=(await exec('xdotool',['getactivewindow'],{env})).stdout.trim();return(await exec('xprop',['-display',':99','-id',id,'WM_CLASS'],{env})).stdout.includes('Chromium')},'browser foreground before close');const chromeWindow=await window('Chromium');assert.ok(chromeWindow);report.beforeBrowserClose=chromeWindow;await exec('import',['-display',':99','-window','root',evidence+'/before-browser-close.png'],{env});await click(+chromeWindow.geometry.X + +chromeWindow.geometry.WIDTH - 20,+chromeWindow.geometry.Y + 20);await wait(async()=>!await window('Chromium'),'actual browser close button');await click(positions.browser.x,positions.browser.y);const reopened=await wait(()=>window('Chromium'),'managed browser reopen');const after=await ps();assert.equal(after.filter(x=>x.comm==='chromium').length,1);report.checks.push({name:'浏览器关窗后从同一入口恢复，仍仅一个受管主进程',passed:true,beforePid:oldChrome.pid,afterPid:after.find(x=>x.comm==='chromium').pid,window:reopened});
+ await wait(()=>transports.length>=2&&transports.at(-1).connection&&!transports.at(-1).connection.closed,'reopened managed CDP');const recovered=transports.at(-1);assert.equal(recovered.userDataDir,originalProfile);assert.equal(await readFile(originalProfile+'/fixture-sentinel','utf8'),'private-local-fixture');const cookies=await recovered.connection.send('Storage.getCookies',{});assert.ok(cookies.cookies.some(c=>c.name===fixtureCookie.name&&c.value===fixtureCookie.value));report.checks.push({name:'真实关闭并恢复后私有 profile 路径、fixture cookie 与 sentinel 保留',passed:true,samePrivateProfile:true,fixtureCookiePreserved:true,sentinelPreserved:true});
+ await post('desktop/close');report.parkedStats=desktop.stats();assert.equal(report.parkedStats.dockRunning,true);assert.equal(report.parkedStats.fileManagerRunning,true);report.checks.push({name:'关闭观察保留 dock、文件管理器与原桌面',passed:true});
+ report.beforeDispose=await ps();await service.close();assert.equal(await readFile(originalProfile+'/fixture-sentinel','utf8'),'private-local-fixture');await delay(200);report.afterDispose=await ps();assert.equal(report.afterDispose.length,0,JSON.stringify(report.afterDispose));report.checks.push({name:'dispose 清理 X/WM/dock/终端/浏览器及私有DBus进程组',passed:true});report.launchErrors=launchErrors;assert.deepEqual(launchErrors,[],'应用入口不能出现被窗口表象掩盖的失败');report.passed=true;
+}catch(e){report.passed=false;report.error={message:e.message,stack:e.stack};console.error(e);await service.close().catch(()=>{});process.exitCode=1}finally{await writeFile(evidence+'/report.json',JSON.stringify(report,null,2));console.log(JSON.stringify({passed:report.passed,checks:report.checks,error:report.error,dockGeometry:report.dockGeometry,fileWindow:report.fileWindow},null,2))}

package/scripts/verification/verify-desktop-input-linux.mjs

@@ -0,0 +1,127 @@
+/** 在真实 Linux/X11 中验证输入与窗口保留；不替代目标 Pod/AppArmor 验收。 */
+import assert from 'node:assert/strict';
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createDesktopController } from '../../runtime/desktop-session.mjs';
+import { createCloudBrowser } from '../../runtime/cloud-browser.mjs';
+
+const execFile = promisify(execFileCallback), args = process.argv.slice(2);
+const argument = (name, fallback) => { const index = args.indexOf(name); return index === -1 ? fallback : args[index + 1]; };
+const observerMs = Number(argument('--observer-ms', 180_000));
+const parkMs = Number(argument('--park-ms', 720_000));
+assert.ok(Number.isFinite(observerMs) && observerMs >= 0 && Number.isFinite(parkMs) && parkMs >= 0);
+const evidence = argument('--evidence', '/tmp/pa-desktop-evidence');
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const workspace = await mkdtemp(join(tmpdir(), 'pa-real-input-'));
+await mkdir(evidence, { recursive: true });
+process.env.AGENTKIT_DESKTOP_MODE = '1';
+const desktop = createDesktopController(), browser = createCloudBrowser({ workspace });
+const report = { environment: '本地 Linux 容器，非预发目标 AppArmor', startedAt: new Date().toISOString(), observerMs, parkMs, checks: [] };
+const pass = (name, data = {}) => { const check = { name, passed: true, ...data }; report.checks.push(check); console.log(JSON.stringify(check)); };
+const waitFile = async (path, bytes = 1) => {
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    try { const value = await readFile(path); if (value.length >= bytes) return value; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    await delay(25);
+  }
+  throw new Error(`terminal did not create ${path}`);
+};
+const processList = async () => {
+  const found = [];
+  for (const pid of await readdir('/proc')) if (/^\d+$/.test(pid)) {
+    try {
+      const argv = (await readFile(`/proc/${pid}/cmdline`, 'utf8')).split('\0');
+      if (/(?:^|\/)(?:Xvfb|fluxbox|xterm|chromium)$/.test(argv[0])) found.push({ pid: Number(pid), binary: argv[0], argv });
+    } catch { /* 已结束的子进程无需采集。 */ }
+  }
+  return found;
+};
+try {
+  report.appArmor = (await readFile('/proc/self/attr/current', 'utf8').catch(() => 'unavailable')).trim();
+  const session = await desktop.openSession({ identity: { userId: 'local-proof', assistantId: 'local-proof', computerId: 'local-proof' }, controllable: true, leaseId: 'local-proof' });
+  const input = event => desktop.input({ sessionId: session.sessionId, event });
+  const text = value => input({ type: 'text', text: value });
+  const key = value => input({ type: 'key', key: value });
+  await input({ type: 'button', action: 'down', button: 1, x: 120, y: 140 });
+  await input({ type: 'button', action: 'up', button: 1 });
+  await key('ctrl+c');
+  const typedFile = join(workspace, 'typed');
+  await text(`cat > ${typedFile}`); await key('Enter'); await delay(100);
+  const ascii = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'.repeat(3).slice(0, 100);
+  const chinese = '你好云电脑'.repeat(10);
+  for (const value of [ascii, chinese]) { await Promise.all([...value].map(character => text(character))); await key('Enter'); }
+  await key('ctrl+d');
+  const received = (await waitFile(typedFile, Buffer.byteLength(`${ascii}\n${chinese}\n`))).toString('utf8');
+  assert.equal(received, `${ascii}\n${chinese}\n`);
+  pass('100 ASCII 与 50 中文快速输入逐字一致，Enter 正常', { asciiCharacters: ascii.length, chineseCharacters: [...chinese].length, utf8Bytes: Buffer.byteLength(received) });
+
+  const backspaceFile = join(workspace, 'backspace');
+  await text('printf %s ABCX'); await key('Backspace'); await text(` > ${backspaceFile}`); await key('Enter');
+  assert.equal((await waitFile(backspaceFile, 3)).toString(), 'ABC');
+  pass('Backspace 正常，不与前后 text 乱序');
+
+  const bad = join(workspace, 'ctrlc-failed'), good = join(workspace, 'ctrlc-ok');
+  await text(`sleep 30; touch ${bad}`); await key('Enter'); await delay(100); await key('ctrl+c');
+  await text(`printf ok > ${good}`); await key('Enter');
+  assert.equal((await waitFile(good, 2)).toString(), 'ok');
+  await assert.rejects(readFile(bad), { code: 'ENOENT' });
+  pass('Ctrl+C 中断终端程序，后续输入继续执行');
+
+  const completion = join(workspace, 'completion'); await mkdir(completion);
+  await writeFile(join(completion, 'unique-entry'), 'fixture');
+  const tabFile = join(workspace, 'tab');
+  await text(`printf %s ${completion}/uni`); await key('Tab'); await text(` > ${tabFile}`); await key('Enter');
+  assert.equal((await waitFile(tabFile, Buffer.byteLength(join(completion, 'unique-entry')))).toString(), join(completion, 'unique-entry'));
+  pass('Tab 在真实终端完成文件名补全');
+
+  const escapeFile = join(workspace, 'escape');
+  await text(`stty -icanon -echo; dd bs=1 count=1 of=${escapeFile}; stty sane`); await key('Enter'); await delay(100); await key('Escape');
+  assert.deepEqual(await waitFile(escapeFile), Buffer.from([27]));
+  pass('Esc 到达真实终端，字节为 27');
+
+  const font = await execFile('fc-match', ['Noto Sans CJK SC', '--format=%{family}\n']);
+  assert.match(font.stdout, /Noto Sans CJK SC/);
+  // xterm 字体度量可能把右侧撑满；左侧 10px 一定在窗口外的根桌面。
+  await input({ type: 'button', action: 'click', button: 3, x: 10, y: 500 });
+  await delay(250);
+  await execFile('import', ['-display', process.env.DISPLAY || ':99', '-window', 'root', join(evidence, 'menu-chinese.png')]);
+  pass('菜单中文字体已解析，显式截图已保存', { font: font.stdout.trim(), screenshot: 'menu-chinese.png' });
+  await key('Escape');
+
+  await browser.openDesktopWindow();
+  await desktop.frameBinary({ sessionId: session.sessionId });
+  const initial = await processList();
+  for (const binary of ['Xvfb', 'fluxbox', 'xterm', 'chromium']) assert.ok(initial.some(value => value.binary.split('/').at(-1) === binary), `missing real process: ${binary}`);
+  await writeFile(join(evidence, 'processes-before.json'), JSON.stringify(initial, null, 2));
+  console.log(JSON.stringify({ waiting: '旁观保活', milliseconds: observerMs }));
+  await delay(observerMs);
+  assert.equal(desktop.getSession(session.sessionId)?.idle, false);
+  assert.equal(desktop.stats().xserverRunning, true);
+  assert.ok((await desktop.frameBinary({ sessionId: session.sessionId })).bytes > 0);
+  pass('真实计时旁观不休眠且仍出帧', { elapsedMs: observerMs });
+  desktop.closeSession(session.sessionId);
+  console.log(JSON.stringify({ waiting: '无观察者保留窗口', milliseconds: parkMs }));
+  await delay(parkMs);
+  assert.equal(desktop.stats().collectorRunning, false);
+  const reopened = await desktop.openSession({ identity: {} });
+  const retained = await processList();
+  await writeFile(join(evidence, 'processes-after.json'), JSON.stringify(retained, null, 2));
+  const windows = initial.filter(value => /(?:^|\/)(?:Xvfb|fluxbox|xterm)$/.test(value.binary) || (/(?:^|\/)chromium$/.test(value.binary) && !value.argv.some(arg => arg.startsWith('--type='))));
+  for (const child of windows) assert.ok(retained.some(value => value.pid === child.pid), `window process restarted: ${child.binary} ${child.pid}`);
+  assert.ok((await desktop.frameBinary({ sessionId: reopened.sessionId })).bytes > 0);
+  await execFile('import', ['-display', process.env.DISPLAY || ':99', '-window', 'root', join(evidence, 'retained-windows.png')]);
+  pass('无观察者后恢复仍为原 X11/WM/终端/Chromium 进程', { elapsedMs: parkMs, preservedPids: windows.map(value => value.pid), screenshot: 'retained-windows.png' });
+  report.passed = true;
+} catch (error) {
+  report.passed = false; report.error = { code: error.code, message: error.message, stack: error.stack };
+  console.error(error); process.exitCode = 1;
+} finally {
+  report.finishedAt = new Date().toISOString();
+  await writeFile(join(evidence, 'report.json'), JSON.stringify(report, null, 2));
+  await browser.dispose(); await desktop.dispose(); await rm(workspace, { recursive: true, force: true });
+  console.log(`REPORT_JSON ${JSON.stringify(report)}`);
+}

package/scripts/verification/verify-desktop-pod-gateway.mjs

@@ -0,0 +1,204 @@
+/**
+ * 仅在已运行的 computer 容器内执行。stdin 接收 JSON 凭据，只访问既有 Broker/Gateway，
+ * 不创建 Controller/Xvfb、不修改策略、不关闭用户窗口。测试文件保留供验收追查。
+ */
+import assert from 'node:assert/strict';
+import { spawn, execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { openGatewayDesktop } from './gateway-desktop-client.mjs';
+
+const execFile = promisify(execFileCallback), sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+let raw = ''; for await (const chunk of process.stdin) { raw += chunk; if (raw.length > 16384) throw new Error('verification stdin exceeds limit'); }
+let input;
+try { input = JSON.parse(raw); } catch { throw new Error('verification stdin must be valid JSON'); }
+raw = '';
+assert.ok(input.gatewayUrl && input.apiKey && input.agentId && input.botId && input.secondaryBotId && input.secondaryBotId !== input.botId, 'stdin requires gatewayUrl/apiKey/agentId/botId/secondaryBotId');
+const observerMs = input.observerMs ?? 180000, parkMs = input.parkMs ?? 720000;
+assert.ok(Number.isSafeInteger(observerMs) && observerMs >= 0 && Number.isSafeInteger(parkMs) && parkMs >= 0);
+const workspace = process.env.AGENTKIT_WORKSPACE_DIR || '/workspace', artifacts = process.env.AGENTKIT_ARTIFACTS_DIR || '/artifacts';
+const files = await mkdtemp(join(workspace, '.pa-e2e-')), evidence = await mkdtemp(join(artifacts, 'desktop-e2e-'));
+const identity = { userId: process.env.USER_ID, assistantId: process.env.ASSISTANT_ID, computerId: process.env.COMPUTER_ID };
+assert.equal(identity.assistantId, input.agentId, 'test Agent must match this running Pod');
+assert.ok(identity.userId && identity.computerId);
+const report = { startedAt: new Date().toISOString(), agentId: input.agentId, computerId: identity.computerId, evidence, files, observerMs, parkMs, checks: [] };
+const connections = []; let fixtureTerminal, reopenedSession;
+const record = (name, details = {}) => { const result = { name, passed: true, ...details }; report.checks.push(result); console.log(JSON.stringify(result)); };
+const safeError = error => ({ code: error.code, status: error.status, message: String(error.message).replaceAll(String(input.apiKey), '[redacted]').slice(0, 1000) });
+const broker = async (path, payload = {}, expectedStatus = 200) => {
+  const response = await fetch(`http://127.0.0.1:${process.env.COMPUTER_PORT || 8787}${path}`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...identity, ...payload }), signal: AbortSignal.timeout(12000),
+  });
+  if (response.status !== expectedStatus) throw Object.assign(new Error(`Broker ${path} HTTP ${response.status}: ${(await response.text()).slice(0, 300)}`), { status: response.status });
+  return response.headers.get('content-type')?.includes('application/json') ? response.json() : response.arrayBuffer();
+};
+const guiProcesses = async () => {
+  const found = [];
+  for (const pid of await readdir('/proc')) if (/^\d+$/u.test(pid)) try {
+    const argv = (await readFile(`/proc/${pid}/cmdline`, 'utf8')).split('\0'), binary = argv[0].split('/').at(-1);
+    if (['Xvfb', 'fluxbox', 'xterm', 'ffmpeg', 'tint2', 'thunar', 'Thunar', 'dbus-run-session', 'dbus-daemon'].includes(binary) || (binary === 'chromium' && !argv.some(value => value.startsWith('--type=')))) found.push({ pid: Number(pid), binary, argv });
+  } catch { /* 进程退出的瞬时竞态。 */ }
+  return found;
+};
+const waitFor = async (predicate, description, timeout = 10000) => {
+  const deadline = Date.now() + timeout;
+  do { const value = await predicate(); if (value) return value; await sleep(25); } while (Date.now() < deadline);
+  throw new Error(`timeout: ${description}`);
+};
+const waitFile = (path, bytes) => waitFor(async () => { try { const value = await readFile(path); return value.length >= bytes && value; } catch (error) { if (error.code !== 'ENOENT') throw error; } }, path);
+const connect = async (botId, mode) => {
+  const value = await openGatewayDesktop({ ...input, botId, mode, taskId: `pod-e2e-${randomUUID()}` });
+  connections.push(value.client); return value;
+};
+const acquire = client => client.request({ type: 'control.acquire', controlEpoch: client.controlEpoch }, value => value.type === 'control' && value.readOnly === false);
+const release = client => client.request({ type: 'control.release', controlEpoch: client.controlEpoch }, value => value.type === 'control' && value.readOnly === true);
+const event = (client, value) => client.request({ type: 'input', controlEpoch: client.controlEpoch, event: value }, reply => reply.type === 'input-accepted');
+const key = (client, value) => event(client, { type: 'key', key: value });
+const text = (client, value) => event(client, { type: 'text', text: value });
+const click = async client => {
+  await event(client, { type: 'pointermove', x: 120, y: 150 });
+  await event(client, { type: 'button', button: 1, action: 'down', x: 120, y: 150 });
+  await event(client, { type: 'button', button: 1, action: 'up' });
+};
+
+try {
+  const currentProfile = (await readFile('/proc/self/attr/current', 'utf8')).trim();
+  const serviceProfile = (await readFile('/proc/1/attr/current', 'utf8')).trim();
+  assert.match(currentProfile, /^agentengine-dsh-sandbox-v1(?:\s|$)/u);
+  assert.match(serviceProfile, /^agentengine-dsh-sandbox-v1(?:\s|$)/u);
+  report.appArmor = { current: currentProfile, service: serviceProfile };
+  record('真实目标 DSH AppArmor profile 生效', report.appArmor);
+  for (const path of ['/health', '/v1/status']) {
+    const response = await fetch(`http://127.0.0.1:${process.env.COMPUTER_PORT || 8787}${path}`);
+    assert.equal(response.status, 200); const value = await response.json();
+    assert.equal(value.computerId, identity.computerId); assert.equal(value.assistantId, input.agentId); assert.equal(value.desktopReady, true);
+  }
+  const original = await guiProcesses();
+  assert.equal(original.filter(value => value.binary === 'Xvfb').length, 1, '运行前必须已有且只有一个 Xvfb');
+  assert.equal(original.filter(value => value.binary === 'tint2').length, 1, '运行前必须已有且只有一个应用底栏');
+  record('当前 Broker 健康且已有单个真实桌面');
+
+  const { client: reader, ready: readReady } = await connect(input.botId, 'read');
+  assert.equal(readReady.readOnly, true);
+  await assert.rejects(event(reader, { type: 'text', text: 'MUST_NOT_APPEAR' }), { status: 403, code: 'DESKTOP_READ_ONLY' });
+  await assert.rejects(acquire(reader), { status: 403 });
+  await waitFor(() => reader.frames.length > 0, '只读票据仍能看到桌面');
+  record('真实网关 read 票据拒绝输入和接管，仍能接收 JPEG');
+
+  const { client: primary, ready } = await connect(input.botId, 'control');
+  assert.equal(ready.readOnly, true); assert.equal(ready.controlAvailable, true);
+  await waitFor(() => primary.frames.length > 0, '首帧');
+  const firstFrameMs = primary.ticketMs + primary.frames[0].at - primary.openedAt;
+  assert.ok(firstFrameMs <= 3000, `first frame ${firstFrameMs}ms exceeds 3s`);
+  record('网关出票、WSS 与首帧真实通过', { ticketMs: primary.ticketMs, handshakeMs: primary.handshakeMs, firstFrameMs, firstFrameBytes: primary.frames[0].bytes });
+  await acquire(primary);
+
+  // 独立验收终端复用现有 DISPLAY，不触碰用户正在运行的 shell/程序。
+  const title = `PA_E2E_${randomUUID()}`;
+  fixtureTerminal = spawn('xterm', ['-display', process.env.DISPLAY || ':99', '-u8', '-fa', 'DejaVu Sans Mono', '-fs', '12', '-geometry', '56x24+30+80', '-title', title,
+    '-xrm', 'XTerm*VT100.translations: #override\\nCtrl Shift <Key>V: insert-selection(CLIPBOARD)', '-e', 'bash', '--noprofile', '--norc'], {
+    cwd: files, env: { ...process.env, LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', PS1: 'pa-e2e> ', HISTFILE: '/dev/null' }, stdio: 'ignore',
+  });
+  let terminalError; fixtureTerminal.once('error', error => { terminalError = error; });
+  await waitFor(async () => { if (terminalError) throw terminalError; try { return (await execFile('xdotool', ['search', '--onlyvisible', '--name', `^${title}$`])).stdout.trim(); } catch { return false; } }, '验收终端窗口');
+  await click(primary);
+  const typedPath = join(files, 'typed');
+  await text(primary, `cat > ${typedPath}`); await key(primary, 'Enter');
+  const ascii = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'.repeat(3).slice(0, 100), chinese = '你好云电脑'.repeat(10);
+  await text(primary, ascii); await key(primary, 'Enter'); await text(primary, chinese); await key(primary, 'Enter'); await key(primary, 'ctrl+d');
+  assert.equal((await waitFile(typedPath, 252)).toString('utf8'), `${ascii}\n${chinese}\n`);
+  record('通过真实 Gateway→Runtime WS→Broker，100 ASCII 与 50 中文精确回显', { utf8Bytes: 252 });
+  const bs = join(files, 'backspace');
+  await text(primary, 'printf %s ABCX'); await key(primary, 'Backspace'); await text(primary, ` > ${bs}`); await key(primary, 'Enter');
+  assert.equal((await waitFile(bs, 3)).toString(), 'ABC');
+  const interrupted = join(files, 'must-not-exist'), continued = join(files, 'ctrlc');
+  await text(primary, `sleep 30; touch ${interrupted}`); await key(primary, 'Enter'); await sleep(100); await key(primary, 'ctrl+c');
+  await text(primary, `printf ok > ${continued}`); await key(primary, 'Enter');
+  assert.equal((await waitFile(continued, 2)).toString(), 'ok'); await assert.rejects(readFile(interrupted), { code: 'ENOENT' });
+  record('真实 WS 的 Backspace 与 Ctrl+C 不乱序、不中断用户终端');
+  const escaped = join(files, 'escape');
+  await text(primary, `stty -icanon -echo; dd bs=1 count=1 of=${escaped}; stty sane`); await key(primary, 'Enter'); await sleep(100); await key(primary, 'Escape');
+  assert.deepEqual(await waitFile(escaped, 1), Buffer.from([27]));
+  const completion = join(files, 'unique-completion'); await writeFile(completion, 'fixture');
+  const completed = join(files, 'tab');
+  await text(primary, `printf %s ${files}/unique-comp`); await key(primary, 'Tab'); await text(primary, ` > ${completed}`); await key(primary, 'Enter');
+  assert.equal((await waitFile(completed, Buffer.byteLength(completion))).toString(), completion);
+  record('真实 WS 的 Esc 与 Tab 补全正确');
+  // 真实容器 cgroup 计数，包含采集/编码、Broker 和本验收的协议开销。
+  const cpuSeconds = async () => {
+    try { return Number((await readFile('/sys/fs/cgroup/cpu.stat', 'utf8')).match(/^usage_usec (\d+)$/mu)?.[1]) / 1e6; }
+    catch (error) { if (error.code !== 'ENOENT') throw error; return Number(await readFile('/sys/fs/cgroup/cpuacct/cpuacct.usage', 'utf8')) / 1e9; }
+  };
+  const cpuBefore = await cpuSeconds(), activeAt = Date.now(); await sleep(2000);
+  const cpuAfter = await cpuSeconds(), measuredMs = Date.now() - activeAt;
+  const activeFrames = primary.frames.filter(frame => frame.at >= activeAt).length, activeFps = activeFrames / 2;
+  assert.ok(activeFps >= 10, `active fps ${activeFps} < 10`);
+  const cpuPercentOfOneCore = (cpuAfter - cpuBefore) / (measuredMs / 1000) * 100;
+  assert.ok(Number.isFinite(cpuPercentOfOneCore) && cpuPercentOfOneCore >= 0);
+  record('有操作后的真实串流至少 10 fps，单帧不超过 300 KiB', { activeFps, maxFrameBytes: Math.max(...primary.frames.map(frame => frame.bytes)), measuredMs, cpuPercentOfOneCore });
+
+  const { client: secondary } = await connect(input.secondaryBotId, 'control');
+  await assert.rejects(acquire(secondary), { status: 409 });
+  await waitFor(() => secondary.frames.length > 0, '冲突后的只读旁观');
+  await release(primary); await acquire(secondary); await release(secondary);
+  record('第二内部 Bot 接管冲突 409，旁观允许，第一个释放后可取得控制权');
+  const cycles = [];
+  for (let i = 0; i < 10; i++) {
+    const began = Date.now(); await acquire(primary); const acquiredMs = Date.now() - began;
+    await click(primary);
+    const releaseAt = Date.now(); await release(primary); const releasedMs = Date.now() - releaseAt;
+    assert.ok(acquiredMs <= 600, `acquire ${acquiredMs}ms > 600ms`); assert.ok(releasedMs <= 300, `release ${releasedMs}ms > 300ms`);
+    cycles.push({ acquiredMs, releasedMs });
+  }
+  record('同一 WS 连续十次接管/释放成功，画面连接保留', { cycles });
+  await execFile('import', ['-display', process.env.DISPLAY || ':99', '-window', 'root', join(evidence, 'terminal-input.png')]);
+  await reader.close(); await secondary.close();
+  console.log(JSON.stringify({ waiting: '真实网关旁观保活', milliseconds: observerMs }));
+  const previousFrameCount = primary.frames.length, observerStarted = Date.now(); await sleep(observerMs);
+  assert.equal(primary.closed, false); assert.ok(primary.frames.length > previousFrameCount || observerMs === 0);
+  const idleFrames = primary.frames.filter(frame => frame.at >= observerStarted + 15000);
+  const idleFps = idleFrames.length > 1 ? (idleFrames.length - 1) * 1000 / (idleFrames.at(-1).at - idleFrames[0].at) : null;
+  if (observerMs >= 30000) { assert.ok(idleFps !== null && idleFps <= 1, `idle fps ${idleFps} exceeds 1`); }
+  record('保持真实网关观察会话期间不休眠', { elapsedMs: observerMs, idleFps });
+  const retained = (await guiProcesses()).filter(value => value.binary !== 'ffmpeg');
+  await writeFile(join(evidence, 'processes-before.json'), JSON.stringify(retained.map(({ pid, binary }) => ({ pid, binary })), null, 2));
+  await primary.close();
+  const stopCaptureBegan = Date.now();
+  await waitFor(async () => !(await guiProcesses()).some(value => value.binary === 'ffmpeg' && value.argv.includes('x11grab')), '其他观察者仍在，不能冒充无观察者阶段', 30000);
+  record('关闭所有验收观察者后采集进程停止', { stoppedWithinMs: Date.now() - stopCaptureBegan });
+  console.log(JSON.stringify({ waiting: '无观察者保留窗口', milliseconds: parkMs }));
+  const parkedAt = Date.now(); let noObserverSamples = 0;
+  while (Date.now() - parkedAt < parkMs) {
+    assert.ok(!(await guiProcesses()).some(value => value.binary === 'ffmpeg' && value.argv.includes('x11grab')), '无观察者阶段出现新的采集器，不能继续宣称无人旁观');
+    noObserverSamples++; await sleep(Math.min(1000, Math.max(1, parkMs - (Date.now() - parkedAt))));
+  }
+  reopenedSession = await broker('/broker/desktop/session', { botId: input.botId, taskId: `restore-${randomUUID()}`, mode: 'read' });
+  const frame = await broker('/broker/desktop/frame-binary', { sessionId: reopenedSession.sessionId }); assert.ok(frame.byteLength > 0 && frame.byteLength <= 307200);
+  const after = await guiProcesses();
+  for (const process of retained) assert.ok(after.some(value => value.pid === process.pid), `原窗口进程被重建: ${process.binary} ${process.pid}`);
+  assert.equal(after.filter(value => value.binary === 'Xvfb').length, 1);
+  await writeFile(join(evidence, 'processes-after.json'), JSON.stringify(after.map(({ pid, binary }) => ({ pid, binary })), null, 2));
+  await execFile('import', ['-display', process.env.DISPLAY || ':99', '-window', 'root', join(evidence, 'restored-desktop.png')]);
+  record('无观察者等待后恢复仍为原 X11/WM/应用进程', { elapsedMs: Date.now() - parkedAt, noObserverSamples, preservedPids: retained.map(value => value.pid) });
+  report.passed = true;
+} catch (error) { report.passed = false; report.error = safeError(error); console.error(JSON.stringify(report.error)); process.exitCode = 1; }
+finally {
+  report.cleanupErrors = [];
+  for (const connection of connections) try { if (!connection.closed && connection.readOnly === false) await release(connection); await connection.close(); } catch (error) { report.cleanupErrors.push(safeError(error)); }
+  if (reopenedSession) try { await broker('/broker/desktop/close', { sessionId: reopenedSession.sessionId }); } catch (error) { report.cleanupErrors.push(safeError(error)); }
+  if (fixtureTerminal && fixtureTerminal.exitCode === null && fixtureTerminal.signalCode === null) {
+    fixtureTerminal.kill('SIGTERM');
+    await Promise.race([new Promise(resolve => fixtureTerminal.once('exit', resolve)), sleep(2000)]);
+    if (fixtureTerminal.exitCode === null && fixtureTerminal.signalCode === null) {
+      fixtureTerminal.kill('SIGKILL');
+      await Promise.race([new Promise(resolve => fixtureTerminal.once('exit', resolve)), sleep(1000)]);
+      if (fixtureTerminal.exitCode === null && fixtureTerminal.signalCode === null) report.cleanupErrors.push({ code: 'FIXTURE_TERMINAL_REAP_FAILED', message: '验收终端未退出' });
+    }
+  }
+  if (report.cleanupErrors.length) { report.passed = false; process.exitCode = 1; }
+  report.finishedAt = new Date().toISOString();
+  await writeFile(join(evidence, 'report.json'), JSON.stringify(report, null, 2));
+  console.log(`REPORT_JSON ${JSON.stringify(report)}`);
+}

package/scripts/verify-cloud-turn.mjs

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+const secrets=[process.env.AGENTKIT_RUNTIME_TOKEN,process.env.AGENTKIT_MODEL_API_KEY].filter(Boolean);
+const print=v=>{let s=JSON.stringify(v);for(const secret of secrets)s=s.split(secret).join('[REDACTED]');console.log(s);};
+const base='http://127.0.0.1:8080';
+const request=async(path,body)=>{const r=await fetch(base+path,{method:body?'POST':'GET',headers:{authorization:`Bearer ${process.env.AGENTKIT_RUNTIME_TOKEN}`,'content-type':'application/json'},...(body?{body:JSON.stringify(body)}:{})});const data=await r.json();if(!r.ok){print({event:'request-failed',status:r.status,data});throw Error(`HTTP ${r.status}`);}return{status:r.status,data};};
+const session=await request('/v1/sessions',{botId:'default',title:'Studio关闭后的云端真实回合验收'});print({event:'session-created',...session});
+const sessionId=session.data.sessionId;
+const receipt=await request(`/v1/sessions/${sessionId}/turns`,{botId:'default',input:'请只回复 PA_CLOUD_20261025_OK，不要调用任何工具。'});print({event:'turn-accepted',...receipt});
+for(let i=0;i<120;i++){
+ const {data}=await request(`/v1/sessions/${sessionId}/turns?botId=default`);const turn=data.turns.find(t=>t.turnId===receipt.data.turnId);
+ if(turn&&['completed','failed','cancelled'].includes(turn.status)){
+  print({event:'turn-finished',turn});const messages=await request(`/v1/sessions/${sessionId}/messages?botId=default`);print({event:'final-messages',...messages});
+  assert.equal(turn.status,'completed');assert.ok(messages.data.messages.some(m=>m.role==='assistant'&&m.content.includes('PA_CLOUD_20261025_OK')));process.exit(0);
+ }
+ if(i%10===0)print({event:'turn-running',elapsedSeconds:i,turnId:receipt.data.turnId,status:turn?.status});
+ await new Promise(resolve=>setTimeout(resolve,1000));
+}
+throw Error('cloud turn did not finish in 120 seconds');

package/scripts/verify-computer-broker.mjs

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict';
+const base='http://127.0.0.1:8787';
+const identity={userId:process.env.USER_ID,assistantId:process.env.ASSISTANT_ID,computerId:process.env.COMPUTER_ID};
+for(const path of ['/health','/v1/status']){const r=await fetch(base+path);const body=await r.json();console.log(JSON.stringify({test:path,status:r.status,body}));assert.equal(r.status,200);}
+const post=async(path,body)=>{const r=await fetch(base+path,{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({...identity,...body})});return{status:r.status,body:await r.json()};};
+const first={botId:'default',taskId:'cloud-acceptance-owner',ttlMs:10000,idempotencyKey:'cloud-acceptance-owner'};
+const second={botId:'researcher',taskId:'cloud-acceptance-observer',ttlMs:10000,idempotencyKey:'cloud-acceptance-observer'};
+const acquired=await post('/broker/lease/acquire',first);console.log(JSON.stringify({test:'first-bot-acquire',status:acquired.status,leasePresent:!!acquired.body.lease?.leaseId}));assert.equal(acquired.status,200);
+try{const conflict=await post('/broker/lease/acquire',second);console.log(JSON.stringify({test:'second-bot-conflict',...conflict}));assert.equal(conflict.status,409);}finally{const released=await post('/broker/lease/release',{...first,leaseId:acquired.body.lease.leaseId});console.log(JSON.stringify({test:'first-bot-release',...released}));assert.equal(released.body.released,true);}
+const next=await post('/broker/lease/acquire',second);console.log(JSON.stringify({test:'second-bot-acquire-after-release',status:next.status,leasePresent:!!next.body.lease?.leaseId}));assert.equal(next.status,200);await post('/broker/lease/release',{...second,leaseId:next.body.lease.leaseId});

package/src/automation-tools.mjs

@@ -0,0 +1,18 @@
+/** 闭包固定 Bot；任务由云端持久调度器执行，关闭 Studio 不影响触发。 */
+export function registerAutomationTools({ agent, botId, service }) {
+  agent.ctx.get('tools').register({
+    name: 'assistant_schedule',
+    description: 'Create/list/cancel a persistent one-off cloud task. Convert the user time using their timezone; runAt must include a timezone offset. The cloud DSH executes input even after Studio closes. Never create a task without the user asking for it.',
+    parameters: { type: 'object', required: ['action'], additionalProperties: false, properties: {
+      action: { type: 'string', enum: ['create', 'list', 'cancel'] }, scheduleId: { type: 'string' }, runAt: { type: 'string' }, input: { type: 'string' },
+    } },
+    output: { schema: { type: 'object', required: ['result'], properties: { result: { type: 'string' } } }, render: (_args, value) => [{ type: 'text', text: value.result }] },
+    async execute(args) {
+      const current = service();
+      if (!current) throw new Error('云端调度服务尚未就绪');
+      if (!['create', 'list', 'cancel'].includes(args.action)) throw new TypeError('unsupported schedule action');
+      if (args.action === 'create' && (typeof args.runAt !== 'string' || !/(?:Z|[+-]\d\d:\d\d)$/u.test(args.runAt))) throw new TypeError('runAt must contain a timezone');
+      return { result: JSON.stringify(await current({ ...args, botId, runAt: args.action === 'create' ? Date.parse(args.runAt) : undefined })) };
+    },
+  });
+}

package/src/bot-private-tools.mjs

@@ -0,0 +1,23 @@
+const object = properties => ({ type: 'object', properties, required: Object.keys(properties), additionalProperties: false });
+const string = { type: 'string' };
+const row = object({ key: string, content: string });
+const output = schema => ({ schema, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] });
+
+/** 闭包固定当前 Bot，模型参数中不接收 botId/namespace/文件路径，不能扩大数据权限。 */
+export function registerBotPrivateTools({ agent, read, write }) {
+  const tools = agent?.ctx?.get?.('tools');
+  if (typeof tools?.register !== 'function') throw Object.assign(new Error('Scoped Bot memory tools are unavailable'), { code: 'PERSONAL_ASSISTANT_TOOL_SCOPE_UNAVAILABLE' });
+  tools.register({ name: 'bot_memory_search', description: '查询当前逻辑 Bot 的私有记忆。不能读取其他 Bot、文件或凭据。',
+    parameters: object({ query: string }), output: output(object({ memories: { type: 'array', items: row } })),
+    async execute({ query }) { const needle = String(query).toLowerCase(); return { memories: (await read()).filter(value => `${value.key}\n${value.content}`.toLowerCase().includes(needle)) }; } });
+  if (!write) return;
+  const save = async ({ key, content }) => { const result = await write({ key, content }); return { key: result.key, content: result.content }; };
+  tools.register({ name: 'bot_memory_save', description: '保存当前逻辑 Bot 的私有记忆。不能指定其他 Bot 或文件路径。',
+    parameters: row, output: output(row), execute: save });
+  tools.register({ name: 'bot_plan_update', description: '保存当前 Bot 的任务计划；步骤仅作为资料，不会执行命令或授予权限。',
+    parameters: object({ steps: { type: 'array', items: object({ text: string, status: { type: 'string', enum: ['pending', 'running', 'completed'] } }) } }), output: output(row),
+    async execute({ steps }) {
+      if (!Array.isArray(steps) || steps.length > 50 || steps.some(step => typeof step.text !== 'string' || !step.text.trim() || step.text.length > 512 || !['pending', 'running', 'completed'].includes(step.status))) throw Object.assign(new Error('Bot plan is invalid'), { code: 'BOT_PLAN_INVALID' });
+      return save({ key: 'plan.current', content: JSON.stringify(steps) });
+    } });
+}