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

package/runtime/assistant-runtime.mjs

@@ -0,0 +1,317 @@
+import { createServer } from 'node:http';
+import { readFile, mkdir } from 'node:fs/promises';
+import { createComputerBrokerClient, createHttpComputerBrokerTransport } from '../src/computer-broker.mjs';
+import { createComputerToolset } from '../src/cloud-computer-tools.mjs';
+import { BotRegistry } from '../src/bot-registry.mjs';
+import { createPersonalAssistantStateStore } from '../src/persistent-state.mjs';
+import { createCloudSessionChannel } from './cloud-session-channel.mjs';
+import { attachDesktopWebSocket } from './desktop-ws.mjs';
+import { pathToFileURL } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { createScheduleManager } from '../src/schedule-manager.mjs';
+import { createCloudFileStore } from '../src/cloud-files.mjs';
+
+export async function startAssistantRuntime({ runtime, env = process.env, argv = [] } = {}) {
+const values = new Map();
+for (let index = 0; index < argv.length; index += 1) {
+  const key = argv[index];
+  if (!key.startsWith('--')) continue;
+  values.set(key.slice(2), argv[index + 1]?.startsWith('--') ? '' : (argv[++index] ?? ''));
+}
+const required = name => {
+  const value = values.get(name) || env[name.toUpperCase().replaceAll('-', '_')];
+  if (!value) throw new Error(`missing ${name}`);
+  return value;
+};
+const assistantId = required('assistant-id');
+const computerId = required('computer-id');
+const userId = required('user-id');
+const brokerEndpoint = env.COMPUTER_BROKER_URL || required('computer-broker');
+const host = env.AGENTKIT_RUNTIME_HOST || '0.0.0.0';
+const port = Number(env.AGENTKIT_RUNTIME_PORT || 8080);
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('invalid runtime port');
+const capabilities = String(values.get('capabilities') || env.AGENTKIT_PERSONAL_ASSISTANT_CAPABILITIES || '').split(',').map(item => item.trim()).filter(Boolean);
+const workspace = values.get('workspace') || env.WORKSPACE_PATH || env.AGENTKIT_WORKSPACE_DIR || '/workspace';
+const artifacts = values.get('artifacts') || env.AGENTKIT_ARTIFACTS_DIR || `${workspace}/files`;
+const state = values.get('state') || env.ASSISTANT_STATE_PATH || env.AGENTKIT_STATE_DIR || `${workspace}/.agentkit/state`;
+const runtimeToken = env.AGENTKIT_RUNTIME_TOKEN || '';
+const registryPath = values.get('bot-registry') || env.BOT_REGISTRY_PATH;
+await mkdir(workspace, { recursive: true, mode: 0o700 });
+await mkdir(artifacts, { recursive: true, mode: 0o750 });
+await mkdir(state, { recursive: true, mode: 0o700 });
+const stateStore = await createPersonalAssistantStateStore(state).init();
+const cloudFiles = createCloudFileStore(`${workspace}/workspace`);
+let bots = [];
+if (registryPath) {
+  const parsed = JSON.parse(await readFile(registryPath, 'utf8'));
+  bots = Array.isArray(parsed) ? parsed : (Array.isArray(parsed.bots) ? parsed.bots : []);
+}
+const registry = runtime?.registry ?? new BotRegistry({ profileId: assistantId, bots });
+const turnBridge = runtime?.turnBridge;
+turnBridge?.setMemoryProvider?.(botId => stateStore.memory(botId), (botId, value) => stateStore.putMemory({ ...value, botId }));
+turnBridge?.setSessionOwnerResolver?.(async sessionId => (await stateStore.read('sessions')).find(row => row.sessionId === sessionId)?.botId);
+
+const broker = createComputerBrokerClient({ transport: createHttpComputerBrokerTransport({ baseUrl: brokerEndpoint }) });
+
+const send = (response, status, body) => {
+  response.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  response.end(JSON.stringify(body));
+};
+const readBody = request => new Promise((resolve, reject) => {
+  const chunks = [];
+  request.on('data', chunk => chunks.push(chunk));
+  request.on('end', () => {
+    try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')); } catch (error) { reject(Object.assign(error, { code: 'INVALID_JSON' })); }
+  });
+  request.on('error', reject);
+});
+const requireRuntimeToken = request => {
+  const authorization = String(request.headers.authorization || '');
+  if (!runtimeToken || authorization !== `Bearer ${runtimeToken}`) throw Object.assign(new Error('runtime token required'), { code: 'RUNTIME_UNAUTHORIZED', status: 401 });
+};
+const brokerDesktopRequest = async (path, body) => {
+  const result = await fetch(`${brokerEndpoint}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...body, userId, assistantId, computerId }) });
+  const payload = await result.json().catch(() => ({ error: 'COMPUTER_BROKER_INVALID_RESPONSE' }));
+  if (!result.ok) throw Object.assign(new Error(payload.error || 'computer broker request failed'), { code: payload.error || 'COMPUTER_BROKER_REQUEST_FAILED', status: result.status });
+  return payload;
+};
+const brokerDesktopFrameBinary = async body => {
+  const result = await fetch(`${brokerEndpoint}/broker/desktop/frame-binary`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ...body, userId, assistantId, computerId }) });
+  if (!result.ok) { const payload = await result.json().catch(() => ({})); throw Object.assign(new Error(payload.error || 'computer frame failed'), { code: payload.error || 'COMPUTER_FRAME_FAILED', status: result.status }); }
+  return { unchanged: result.headers.get('x-desktop-unchanged') === '1', seq: Number(result.headers.get('x-desktop-seq') || 0), width: Number(result.headers.get('x-desktop-width') || 1280), height: Number(result.headers.get('x-desktop-height') || 800), bytes: Number(result.headers.get('x-desktop-bytes') || 0), nextFrameDelayMs: Number(result.headers.get('x-desktop-next-frame-delay-ms') || 80), data: Buffer.from(await result.arrayBuffer()) };
+};
+const botIdOf = value => {
+  const botId = String(value ?? '').trim();
+  if (!botId) throw Object.assign(new Error('botId is required'), { code: 'BOT_REQUIRED' });
+  registry.require(botId);
+  return botId;
+};
+const taskIdOf = value => {
+  const taskId = String(value ?? 'runtime-action').trim();
+  if (!taskId || taskId.length > 128) throw Object.assign(new Error('taskId is invalid'), { code: 'TASK_INVALID' });
+  return taskId;
+};
+const actionToolName = value => {
+  const tool = String(value ?? '').trim();
+  const allowed = new Set([
+    'cloud_browser_open', 'cloud_browser_snapshot', 'cloud_browser_click',
+    'cloud_browser_type', 'cloud_browser_press', 'cloud_browser_screenshot',
+    'cloud_browser_download', 'cloud_browser_close', 'cloud_bash', 'cloud_run_code',
+  ]);
+  if (!allowed.has(tool)) throw Object.assign(new Error('unsupported personal assistant tool'), { code: 'TOOL_UNSUPPORTED' });
+  return tool;
+};
+const computerStatus = async body => broker.status({ userId, assistantId, botId: botIdOf(body.botId), computerId });
+const computerAction = async body => {
+  const botId = botIdOf(body.botId);
+  const tool = actionToolName(body.tool || body.name);
+  const taskId = taskIdOf(body.taskId);
+  const toolset = createComputerToolset({ broker, userId, assistantId, botId, computerId, taskId });
+  try { return await toolset.executeRaw(tool, body.args || {}, { taskId }); }
+  finally { await toolset.dispose(); }
+};
+// A deterministic, side-effect-free broker smoke: status, lease acquisition,
+// and the close action all cross the localhost broker. `cloud_browser_close`
+// does not launch a browser and therefore works even on a fresh Computer Pod.
+const computerSmoke = async body => {
+  const botId = botIdOf(body.botId);
+  const taskId = taskIdOf(body.taskId || 'broker-smoke');
+  const status = await broker.status({ userId, assistantId, botId, computerId });
+  const toolset = createComputerToolset({ broker, userId, assistantId, botId, computerId, taskId });
+  try {
+    const action = await toolset.executeRaw('cloud_browser_close', {}, { taskId });
+    return { status, action, smoke: 'passed' };
+  } finally {
+    await toolset.dispose();
+  }
+};
+
+const urlOf = request => new URL(request.url || '/', `http://${host}:${port}`);
+const stateBotId = value => botIdOf(value);
+const sessionCreate = async body => {
+  const botId = stateBotId(body.botId);
+  return stateStore.createSession({ botId, title: body.title, metadata: body.metadata });
+};
+const memoryWrite = async body => {
+  const botId = stateBotId(body.botId);
+  return stateStore.putMemory({ botId, key: body.key, content: body.content, metadata: body.metadata });
+};
+const scheduleWrite = async body => {
+  const botId = stateBotId(body.botId);
+  if (!turnBridge?.available) throw Object.assign(new Error('cloud DSH Session Controller unavailable'), { code: 'DSH_SESSION_CONTROLLER_UNAVAILABLE', status: 503 });
+  const input = String(body.input ?? body.metadata?.input ?? '').trim();
+  if (!input || Buffer.byteLength(input) > 64 * 1024) throw Object.assign(new Error('schedule input is required'), { code: 'SCHEDULE_INPUT_REQUIRED' });
+  if (!Number.isSafeInteger(body.runAt) || body.runAt <= Date.now()) throw Object.assign(new Error('schedule must be in the future'), { code: 'SCHEDULE_INVALID' });
+  const sessionId = body.sessionId || (await stateStore.createSession({ botId, title: `定时任务：${body.scheduleId}` })).sessionId;
+  await requireSession(botId, sessionId);
+  const row = await stateStore.putSchedule({ botId, scheduleId: body.scheduleId, runAt: body.runAt, metadata: { ...body.metadata, input, sessionId, generation: randomUUID() } });
+  await patchSchedule(row, { status: 'pending' });
+  armSchedule(row);
+  return { ...row, status: 'pending' };
+};
+const sessionResource = pathname => {
+  const match = pathname.match(/^\/v1\/sessions\/([^/]+)\/(messages|turns)$/u);
+  return match ? { sessionId: decodeURIComponent(match[1]), resource: match[2] } : null;
+};
+const messageWrite = async (body, sessionId) => {
+  const botId = stateBotId(body.botId);
+  await requireSession(botId, sessionId);
+  return stateStore.appendMessage({ botId, sessionId, role: body.role, content: body.content, metadata: body.metadata });
+};
+const requireSession = async (botId, sessionId) => {
+  if (!(await stateStore.sessions(botId)).some(item => item.sessionId === sessionId)) throw Object.assign(new Error('session not found for Bot'), { code: 'SESSION_NOT_FOUND', status: 404 });
+};
+const updateTurn = (turnId, patch) => stateStore.mutate('turns', rows => {
+  const row = rows.find(item => item.turnId === turnId);
+  if (!row) return null;
+  Object.assign(row, patch, { updatedAt: new Date().toISOString() });
+  return row;
+});
+const pendingTurns = new Set();
+const submissionLocks = new Map();
+const scheduler = runtime?.scheduleManager ?? createScheduleManager();
+const scheduleKey = row => `task-${createHash('sha256').update(JSON.stringify([row.botId, row.scheduleId])).digest('hex')}`;
+const patchSchedule = (record, patch) => stateStore.mutate('schedules', rows => {
+  const row = rows.find(item => item.botId === record.botId && item.scheduleId === record.scheduleId);
+  if (!row || row.metadata?.generation !== record.metadata?.generation) return null;
+  Object.assign(row, patch);
+  return row;
+});
+function armSchedule(row) {
+  scheduler.scheduleOnce({ scheduleId: scheduleKey(row), runAt: Math.min(Math.max(Date.now() + 1, row.nextRunAt), Date.now() + 2_147_483_647), task: async () => {
+    try {
+      if (row.nextRunAt > Date.now()) { armSchedule(row); return; }
+      const claimed = await patchSchedule(row, { status: 'running', startedAt: new Date().toISOString() });
+      if (!claimed) return;
+      const receipt = await turnWrite({ botId: row.botId, input: row.metadata.input, metadata: { scheduleId: row.scheduleId } }, row.metadata.sessionId);
+      await Promise.allSettled([...pendingTurns]);
+      const turn = (await stateStore.turns(row.botId, row.metadata.sessionId)).find(item => item.turnId === receipt.turnId);
+      await patchSchedule(row, { status: turn?.status === 'completed' ? 'completed' : 'failed', turnId: receipt.turnId, finishedAt: new Date().toISOString(), error: turn?.error || null });
+      console.info(JSON.stringify({ event: 'personal-assistant.schedule.finished', botId: row.botId, scheduleId: row.scheduleId, turnId: receipt.turnId, status: turn?.status || 'failed' }));
+    } catch (error) { await patchSchedule(row, { status: 'failed', error: error.code || 'SCHEDULE_EXECUTION_FAILED' }); }
+  } });
+}
+const turnWrite = async (body, sessionId) => {
+  const key = JSON.stringify([body.botId, sessionId]);
+  const previous = submissionLocks.get(key) || Promise.resolve();
+  const current = previous.catch(() => {}).then(() => submitCloudTurn(body, sessionId));
+  submissionLocks.set(key, current);
+  try { return await current; } finally { if (submissionLocks.get(key) === current) submissionLocks.delete(key); }
+};
+const submitCloudTurn = async (body, sessionId) => {
+  const botId = stateBotId(body.botId);
+  await requireSession(botId, sessionId);
+  if (!turnBridge?.available) throw Object.assign(new Error('cloud DSH Session Controller unavailable'), { code: 'DSH_SESSION_CONTROLLER_UNAVAILABLE', status: 503 });
+  const clientTurnId = body.metadata?.clientTurnId;
+  if (clientTurnId) {
+    const existing = (await stateStore.turns(botId, sessionId)).find(row => row.metadata?.clientTurnId === clientTurnId);
+    if (existing) {
+      if (existing.input !== body.input) throw Object.assign(new Error('同一发送标识不能改变内容'), { code: 'CLIENT_TURN_CONFLICT', status: 409 });
+      return existing;
+    }
+  }
+  const turn = await stateStore.createTurn({ botId, sessionId, input: body.input, metadata: body.metadata });
+  const message = await stateStore.appendMessage({ botId, sessionId, role: 'user', content: body.input, metadata: { turnId: turn.turnId, ...(clientTurnId ? { clientTurnId } : {}) } });
+  try {
+    const content = [{ type: 'text', text: body.input }];
+    for (const attachment of body.attachments || []) {
+      const data = await cloudFiles.attachment({ botId, sessionId, path: attachment.path });
+      // 只有明确的图像附件进入模型图片通道；其他文件由工作区工具读取处理。
+      if (['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(attachment.mediaType)) {
+        const store = runtime?.ctx?.get?.('attachments');
+        if (!store?.saveImage) throw Object.assign(new Error('云端图片附件服务不可用'), { status: 503 });
+        const ref = await store.saveImage({ data, mediaType: attachment.mediaType, name: attachment.name });
+        content.push({ type: 'image', attachment: ref });
+      }
+    }
+    const receipt = await turnBridge.submitTurn({ botId, sessionId, input: body.input, parts: content, requestId: turn.turnId });
+    await updateTurn(turn.turnId, { status: 'running', execution: receipt.execution, requestId: receipt.requestId });
+    const pending = turnBridge.waitForTurn({ botId, sessionId, requestId: receipt.requestId, onProgress: progress => updateTurn(turn.turnId, { progress }) }).then(async result => {
+      for (const content of result.messages) await stateStore.appendMessage({ botId, sessionId, role: 'assistant', content, metadata: { turnId: turn.turnId, ...(clientTurnId ? { clientTurnId } : {}), execution: receipt.execution } });
+      await updateTurn(turn.turnId, { status: result.status, result: result.messages.join('\n'), error: result.error || null });
+      console.info(JSON.stringify({ event: 'personal-assistant.turn.finished', botId, sessionId, turnId: turn.turnId, status: result.status }));
+    }).catch(error => updateTurn(turn.turnId, { status: 'failed', error: error.code || error.message }));
+    pendingTurns.add(pending);
+    void pending.finally(() => pendingTurns.delete(pending));
+    return { ...turn, status: 'running', messageId: message.messageId, ...receipt };
+  } catch (error) {
+    await updateTurn(turn.turnId, { status: 'failed', error: error.code || error.message });
+    throw error;
+  }
+};
+
+// 尚未开始的任务可恢复；中断时不自动重放未知结果，避免重复执行操作。
+await stateStore.mutate('turns', rows => {
+  for (const row of rows) if (row.status === 'running' || row.status === 'queued') Object.assign(row, { status: 'interrupted', error: 'RUNTIME_PROCESS_INTERRUPTED', updatedAt: new Date().toISOString() });
+});
+for (const row of await stateStore.read('schedules')) {
+  if (row.status === 'running') await patchSchedule(row, { status: 'interrupted', error: 'SCHEDULE_PROCESS_INTERRUPTED' });
+  else if ((!row.status || row.status === 'pending') && row.metadata?.input && row.metadata?.sessionId) armSchedule(row);
+}
+runtime?.setAutomationService?.(async args => {
+  const botId = stateBotId(args.botId);
+  if (args.action === 'list') return { schedules: await stateStore.schedules(botId) };
+  if (args.action === 'create') return scheduleWrite({ botId, scheduleId: args.scheduleId || randomUUID(), runAt: args.runAt, input: args.input });
+  if (typeof args.scheduleId !== 'string') throw new TypeError('scheduleId is required');
+  const row = (await stateStore.schedules(botId)).find(row => row.scheduleId === args.scheduleId);
+  if (row?.status === 'running') throw Object.assign(new Error('任务已开始执行，不能伪报取消'), { status: 409 });
+  if (row) { scheduler.cancel(scheduleKey(row)); await patchSchedule(row, { status: 'cancelled' }); }
+  return { cancelled: Boolean(row) };
+});
+
+const server = createServer(async (request, response) => {
+  try {
+    const url = urlOf(request);
+    if (request.method === 'GET' && ['/health', '/ready', '/readyz'].includes(url.pathname)) return send(response, turnBridge?.available === true ? 200 : 503, { status: turnBridge?.available === true ? 'ready' : 'dsh-unavailable', assistantId, computerId, bots: registry.list().length, dshSessionController: turnBridge?.available === true, capabilities });
+    requireRuntimeToken(request);
+    if (request.method === 'GET' && url.pathname === '/v1/bots') return send(response, 200, { bots: registry.list() });
+    if (request.method === 'GET' && url.pathname === '/v1/sessions') return send(response, 200, { sessions: await stateStore.sessions(stateBotId(url.searchParams.get('botId'))) });
+    if (request.method === 'GET' && sessionResource(url.pathname)?.resource === 'messages') {
+      const resource = sessionResource(url.pathname);
+      const botId = stateBotId(url.searchParams.get('botId')); await requireSession(botId, resource.sessionId);
+      return send(response, 200, { messages: await stateStore.messages({ botId, sessionId: resource.sessionId }) });
+    }
+    if (request.method === 'GET' && sessionResource(url.pathname)?.resource === 'turns') {
+      const resource = sessionResource(url.pathname);
+      const botId = stateBotId(url.searchParams.get('botId')); await requireSession(botId, resource.sessionId);
+      return send(response, 200, { turns: await stateStore.turns(botId, resource.sessionId) });
+    }
+    if (request.method === 'GET' && url.pathname === '/v1/memory') return send(response, 200, { memories: await stateStore.memory(stateBotId(url.searchParams.get('botId')), url.searchParams.get('query') || '') });
+    if (request.method === 'GET' && url.pathname === '/v1/schedules') return send(response, 200, { schedules: await stateStore.schedules(stateBotId(url.searchParams.get('botId'))) });
+    if (request.method === 'DELETE' && url.pathname.startsWith('/v1/schedules/')) {
+      const botId = stateBotId(url.searchParams.get('botId')), scheduleId = decodeURIComponent(url.pathname.slice('/v1/schedules/'.length));
+      scheduler.cancel(scheduleKey({ botId, scheduleId }));
+      const removed = await stateStore.removeSchedule(botId, scheduleId);
+      return send(response, 200, { removed });
+    }
+    if (request.method !== 'POST') return send(response, 404, { error: 'not_found' });
+    const body = await readBody(request);
+    if (url.pathname === '/v1/computer/status') return send(response, 200, await computerStatus(body));
+    if (url.pathname === '/v1/computer/action') return send(response, 200, await computerAction(body));
+    if (url.pathname === '/v1/computer/smoke') return send(response, 200, await computerSmoke(body));
+    if (url.pathname === '/v1/computer/desktop/session') { requireRuntimeToken(request); return send(response, 200, await brokerDesktopRequest('/broker/desktop/session', { botId: botIdOf(body.botId), taskId: taskIdOf(body.taskId), leaseId: body.leaseId || undefined })); }
+    if (url.pathname === '/v1/computer/desktop/frame') { requireRuntimeToken(request); return send(response, 200, await brokerDesktopRequest('/broker/desktop/frame', { sessionId: body.sessionId, afterSeq: body.afterSeq })); }
+    if (url.pathname === '/v1/computer/desktop/input') { requireRuntimeToken(request); return send(response, 202, await brokerDesktopRequest('/broker/desktop/input', { sessionId: body.sessionId, botId: botIdOf(body.botId), taskId: taskIdOf(body.taskId), leaseId: body.leaseId, event: body.event })); }
+    if (url.pathname === '/v1/computer/desktop/close') { requireRuntimeToken(request); return send(response, 200, await brokerDesktopRequest('/broker/desktop/close', { sessionId: body.sessionId })); }
+    if (url.pathname === '/v1/sessions') return send(response, 201, await sessionCreate(body));
+    if (sessionResource(url.pathname)?.resource === 'messages') return send(response, 201, await messageWrite(body, sessionResource(url.pathname).sessionId));
+    if (sessionResource(url.pathname)?.resource === 'turns') return send(response, 202, await turnWrite(body, sessionResource(url.pathname).sessionId));
+    if (url.pathname === '/v1/memory') return send(response, 201, await memoryWrite(body));
+    if (url.pathname === '/v1/schedules') return send(response, 201, await scheduleWrite(body));
+    return send(response, 404, { error: 'not_found' });
+  } catch (error) {
+    const status = Number.isInteger(error?.status) && error.status >= 400 && error.status < 600 ? error.status : 400;
+    return send(response, status, { error: error?.code || error?.message || 'PERSONAL_ASSISTANT_RUNTIME_FAILED' });
+  }
+});
+attachDesktopWebSocket({ server, runtimeToken, assistantId, brokerDesktopRequest, brokerDesktopFrameBinary, botIdOf, taskIdOf, listBots: () => registry.list(), sessionRequest: createCloudSessionChannel({ assistantId, computerId, stateStore, registry, sessionCreate, turnWrite, scheduleWrite, cloudFiles }) });
+await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, resolve); });
+return { server, stateStore, waitForIdle: () => Promise.allSettled([...pendingTurns]), close: () => { scheduler.dispose(); return new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve())); } };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  // 没有真实 DSH Host 注入时 readiness 明确为 503，禁止伪造回合。
+  const handle = await startAssistantRuntime({ argv: process.argv.slice(2) });
+  const close = () => void handle.close().then(() => process.exit(0));
+  process.on('SIGTERM', close); process.on('SIGINT', close);
+}

package/runtime/check-manifest.mjs

@@ -0,0 +1,21 @@
+import { pathToFileURL } from 'node:url';
+import { loadPersonalAssistantManifest } from '../src/platform-manifest.mjs';
+
+export const PERSONAL_ASSISTANT_MANIFEST_PATH = '/app/code/agentengine.yaml';
+
+/** 独立init校验只读声明及公开身份，不需要模型key、runtime token或可写目录。 */
+export function checkPersonalAssistantManifest(env = process.env, { loadManifest = loadPersonalAssistantManifest } = {}) {
+  if (env.AGENTENGINE_MANIFEST_PATH !== PERSONAL_ASSISTANT_MANIFEST_PATH) throw Object.assign(new Error('MANAGED_MANIFEST_PATH_INVALID'), { code: 'MANAGED_MANIFEST_PATH_INVALID' });
+  const manifest = loadManifest(env);
+  return { verified: true, runtime: manifest.runtime.name, version: manifest.runtime.version, manifestSha256: env.AGENTENGINE_MANIFEST_SHA256 };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    if (process.argv.length !== 4 || process.argv[2] !== '--manifest' || process.argv[3] !== PERSONAL_ASSISTANT_MANIFEST_PATH) throw Object.assign(new Error('MANAGED_MANIFEST_ARGUMENTS_INVALID'), { code: 'MANAGED_MANIFEST_ARGUMENTS_INVALID' });
+    console.info(JSON.stringify(checkPersonalAssistantManifest()));
+  } catch (error) {
+    console.error(JSON.stringify({ error: error.code || 'MANAGED_MANIFEST_CHECK_FAILED' }));
+    process.exitCode = 1;
+  }
+}

package/runtime/cloud-browser-cdp.mjs

@@ -0,0 +1,313 @@
+/** Minimal Chromium DevTools Protocol transport: one browser, one WebSocket, no reconnect. */
+import { spawn as spawnChild } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, mkdirSync, chmodSync, lstatSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+
+export const DEVTOOLS_PORT_FILE = 'DevToolsActivePort';
+export const DEVTOOLS_LAUNCH_TIMEOUT_MS = 30_000;
+export const CDP_COMMAND_TIMEOUT_MS = 30_000;
+const CDP_CONNECT_TIMEOUT_MS = 10_000;
+const MAX_STDERR_BYTES = 4096;
+const persistentProfileOwners = new Map();
+
+const fail = (message, code = 'ASSISTANT_BROWSER_CDP_UNAVAILABLE') => Object.assign(new Error(message), { code });
+const delay = ms => new Promise(resolvePromise => setTimeout(resolvePromise, ms));
+
+/**
+ * Chromium flags for the managed image. Chromium's own sandbox is unavailable in
+ * most managed containers, so the egress proxy stays authoritative for network
+ * policy; `--proxy-bypass-list=<-loopback>` keeps loopback inside the proxy too.
+ * 桌面模式的首屏是本机 127.0.0.1 的欢迎页，因此回环必须显式放行，否则页面会被
+ * 出口代理吃掉而白屏；公网流量仍然全部走代理。
+ * 桌面窗口固定 `--class=Chromium`：否则 `--app=<地址>` 会把 WM_CLASS 设成地址本身，
+ * dock 的任务按钮匹配不到 chromium.desktop，只能显示一个灰色兜底图标。
+ * 托管容器里 Chromium 自带沙箱不可用，`--no-sandbox` 会让窗口版 Chromium 顶部弹出
+ * “You are using an unsupported command-line flag” 信息栏；`--test-type` 抑制该提示栏，
+ * 不改变 CDP/自动化语义，也不影响页面能力。
+ */
+export function chromiumArgs({ userDataDir, proxy, windowSize = '1280,800', desktop = false, startUrl, openUrl }) {
+  return [
+    ...(desktop ? ['--ozone-platform=x11', '--window-position=520,90', '--test-type', '--lang=zh-CN', '--accept-lang=zh-CN,zh', '--class=Chromium', '--hide-crash-restore-bubble'] : ['--headless=new']),
+    // 应用窗口承载首屏：没有地址栏、没有多余标签条。
+    ...(desktop && startUrl ? [`--app=${startUrl}`] : []),
+    // 普通窗口模式：把首页作为位置参数交给 Chromium，避免先出一个空白标签再补一个页面。
+    ...(desktop && !startUrl && openUrl ? [openUrl] : []),
+    '--disable-gpu', '--disable-dev-shm-usage', '--no-sandbox',
+    '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-sync',
+    '--disable-background-networking', '--disable-breakpad', '--disable-crash-reporter',
+    '--disable-translate', '--mute-audio', '--hide-scrollbars',
+    `--window-size=${desktop ? '740,620' : windowSize}`,
+    '--remote-debugging-port=0', '--remote-debugging-address=127.0.0.1',
+    `--user-data-dir=${userDataDir}`,
+    `--proxy-server=${proxy}`,
+    '--proxy-bypass-list=<-loopback>,127.0.0.1,localhost',
+  ];
+}
+
+/** Read `<user-data-dir>/DevToolsActivePort`; Chromium writes port and browser WebSocket path. */
+export function readDevToolsEndpoint(userDataDir) {
+  let content;
+  try { content = readFileSync(join(userDataDir, DEVTOOLS_PORT_FILE), 'utf8'); } catch { return null; }
+  const [portLine, pathLine] = content.split(/\r?\n/);
+  const port = Number(portLine);
+  const path = (pathLine || '').trim();
+  if (!Number.isInteger(port) || port < 1 || port > 65535 || !path.startsWith('/')) return null;
+  return { port, path, endpoint: `ws://127.0.0.1:${port}${path}` };
+}
+
+export function createProfileDir() {
+  return mkdtempSync(join(tmpdir(), 'agentkit-cloud-browser-'));
+}
+
+/** Kill the detached Chromium process group; fall back to the single pid. */
+export function killProcessTree(pid, signal = 'SIGKILL') {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return;
+  try { process.kill(-pid, signal); } catch { try { process.kill(pid, signal); } catch {} }
+}
+
+function collectStderr(child, state) {
+  child?.stderr?.on?.('data', chunk => {
+    if (state.bytes >= MAX_STDERR_BYTES) return;
+    const slice = chunk.subarray(0, MAX_STDERR_BYTES - state.bytes);
+    state.text += slice.toString('utf8');
+    state.bytes += slice.length;
+  });
+}
+
+const childExited = child => child.exitCode !== null && child.exitCode !== undefined || Boolean(child.signalCode);
+const waitForOwnChild = (child, timeoutMs) => {
+  if (!child || childExited(child)) return Promise.resolve();
+  return new Promise((resolvePromise, rejectPromise) => {
+    const finish = error => { clearTimeout(timer); child.removeListener?.('exit', exited); error ? rejectPromise(error) : resolvePromise(); };
+    const exited = () => finish();
+    const timer = setTimeout(() => finish(fail('自有 Chromium 进程仍未退出，拒绝复用私有配置目录', 'ASSISTANT_BROWSER_PROCESS_STILL_RUNNING')), timeoutMs);
+    child.once('exit', exited);
+    if (childExited(child)) finish();
+  });
+};
+async function stopOwnChromium(child, kill, { wait = false, graceMs = 0 } = {}) {
+  if (!child?.pid || childExited(child)) return;
+  // 正常关窗/Browser.close 可先完成 SQLite 等状态写入；只等待自己的 child。
+  if (wait && graceMs) { try { await waitForOwnChild(child, graceMs); return; } catch (error) { if (error.code !== 'ASSISTANT_BROWSER_PROCESS_STILL_RUNNING') throw error; } }
+  try { kill(child.pid, 'SIGKILL'); } catch {
+    if (wait) throw fail('无法停止自有 Chromium，拒绝复用私有配置目录', 'ASSISTANT_BROWSER_PROCESS_STILL_RUNNING');
+  }
+  if (wait) await waitForOwnChild(child, 2000);
+}
+
+function preparePersistentProfile(userDataDir) {
+  if (!userDataDir || !isAbsolute(userDataDir)) throw fail('持久浏览器配置目录必须为绝对路径', 'ASSISTANT_BROWSER_PROFILE_INVALID');
+  try {
+    mkdirSync(userDataDir, { recursive: true, mode: 0o700 });
+    if (!lstatSync(userDataDir).isDirectory() || lstatSync(userDataDir).isSymbolicLink()) throw fail('浏览器私有配置目录不能是符号链接', 'ASSISTANT_BROWSER_PROFILE_INVALID');
+    chmodSync(userDataDir, 0o700);
+    // 旧 child 已由调用方 dispose 等待退出。只清调试端口元数据，不碰锁或登录数据。
+    rmSync(join(userDataDir, DEVTOOLS_PORT_FILE), { force: true });
+  } catch (error) {
+    if (String(error.code).startsWith('ASSISTANT_BROWSER_')) throw error;
+    throw fail(`浏览器私有配置目录不可用: ${error.code || 'filesystem-error'}`, 'ASSISTANT_BROWSER_PROFILE_UNAVAILABLE');
+  }
+}
+
+export async function launchChromium({
+  chromium, proxy, userDataDir, spawn = spawnChild,
+  launchTimeoutMs = DEVTOOLS_LAUNCH_TIMEOUT_MS, now = Date.now, pollMs = 25, env = process.env,
+  preserveUserDataDir = false, startUrl, openUrl,
+} = {}) {
+  if (preserveUserDataDir) {
+    const previous = persistentProfileOwners.get(userDataDir);
+    if (previous && !childExited(previous)) throw fail('自有 Chromium 仍占用私有配置目录，拒绝启动第二个实例', 'ASSISTANT_BROWSER_PROCESS_STILL_RUNNING');
+    preparePersistentProfile(userDataDir);
+  }
+  else if (userDataDir === undefined) userDataDir = createProfileDir();
+  const cleanupProfile = () => { if (!preserveUserDataDir) rmSync(userDataDir, { recursive: true, force: true }); };
+  const desktop = env.AGENTKIT_DESKTOP_MODE === '1';
+  // 桌面浏览器展示的是本地时间（欢迎页时钟、页面里的 Date），必须与桌面其它
+  // 进程同一时区；非桌面模式只沿用宿主 TZ，不改变既有口径。
+  const timeZone = typeof env.TZ === 'string' && env.TZ
+    ? env.TZ
+    : desktop ? String(env.AGENTKIT_DESKTOP_TIME_ZONE || 'Asia/Shanghai') : undefined;
+  const args = chromiumArgs({ userDataDir, proxy, desktop, startUrl, openUrl });
+  const stderr = { text: '', bytes: 0 };
+  let child;
+  try {
+    child = spawn(chromium, args, {
+      detached: true,
+      stdio: ['ignore', 'ignore', 'pipe'],
+      env: {
+        PATH: '/usr/local/bin:/usr/bin:/bin', HOME: userDataDir, TMPDIR: '/tmp',
+        // 桌面窗口给用户看：界面与页面语言都用简体中文；LC_ALL 会盖过 LANG，桌面模式不能设。
+        // 无头自动化不改变既有口径（历史行为是 C.UTF-8 + 默认语言）。
+        ...(desktop
+          ? { LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_CN:zh' }
+          : { LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' }),
+        ...(timeZone ? { TZ: timeZone } : {}),
+        ...(desktop ? { DISPLAY: env.DISPLAY || ':99' } : {}),
+      },
+    });
+  } catch (error) {
+    cleanupProfile();
+    throw fail(`Chromium 启动失败: ${error?.code || 'spawn-error'}`, 'ASSISTANT_BROWSER_LAUNCH_FAILED');
+  }
+  if (preserveUserDataDir && child?.pid) {
+    persistentProfileOwners.set(userDataDir, child);
+    child.once('exit', () => { if (persistentProfileOwners.get(userDataDir) === child) persistentProfileOwners.delete(userDataDir); });
+  }
+  collectStderr(child, stderr);
+  let exit, spawnError;
+  child?.once?.('exit', (code, signal) => { exit = { code, signal }; });
+  child?.once?.('error', error => { spawnError = error; });
+  const deadline = now() + launchTimeoutMs;
+  while (now() < deadline) {
+    const endpoint = readDevToolsEndpoint(userDataDir);
+    if (endpoint) return { child, userDataDir, endpoint, stderr };
+    if (spawnError) { cleanupProfile(); throw fail(`Chromium 启动失败: ${spawnError.code || 'spawn-error'}`, 'ASSISTANT_BROWSER_LAUNCH_FAILED'); }
+    if (exit) {
+      await stopOwnChromium(child, killProcessTree, { wait: preserveUserDataDir });
+      cleanupProfile();
+      const detail = stderr.text.trim().slice(0, 500);
+      throw fail(`Chromium 在调试端口就绪前退出（${exit.code ?? exit.signal}）${detail ? `: ${detail}` : ''}`, 'ASSISTANT_BROWSER_LAUNCH_FAILED');
+    }
+    await delay(pollMs);
+  }
+  await stopOwnChromium(child, killProcessTree, { wait: preserveUserDataDir });
+  cleanupProfile();
+  throw fail('Chromium 调试端口在限定时间内未就绪', 'ASSISTANT_BROWSER_LAUNCH_FAILED');
+}
+
+/** One JSON-RPC channel. Commands time out individually; a closed channel never reconnects. */
+export class CdpConnection {
+  #ws; #pending = new Map(); #nextId = 0; #closed = false; #commandTimeoutMs;
+
+  constructor(ws, { commandTimeoutMs = CDP_COMMAND_TIMEOUT_MS } = {}) {
+    this.#ws = ws;
+    this.#commandTimeoutMs = commandTimeoutMs;
+    ws.addEventListener?.('message', event => this.#onMessage(event));
+    ws.addEventListener?.('close', () => this.#rejectAll(fail('云端浏览器调试连接已关闭', 'ASSISTANT_BROWSER_CDP_CLOSED')));
+    ws.addEventListener?.('error', () => this.#rejectAll(fail('云端浏览器调试连接出错', 'ASSISTANT_BROWSER_CDP_ERROR')));
+  }
+
+  get closed() { return this.#closed; }
+
+  send(method, params = {}, { sessionId, timeoutMs = this.#commandTimeoutMs } = {}) {
+    if (this.#closed) return Promise.reject(fail('云端浏览器调试连接已关闭', 'ASSISTANT_BROWSER_CDP_CLOSED'));
+    if (typeof method !== 'string' || !method) return Promise.reject(fail('CDP 方法名无效', 'ASSISTANT_BROWSER_CDP_ERROR'));
+    const id = ++this.#nextId;
+    return new Promise((resolvePromise, rejectPromise) => {
+      // Keep the timeout ref'd: an in-flight command must keep the process
+      // alive long enough for the timeout to fire instead of leaving a
+      // promise that the event loop silently abandons (Node 22 cancels it).
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        rejectPromise(fail(`云端浏览器命令 ${method} 超时`, 'ASSISTANT_BROWSER_CDP_TIMEOUT'));
+      }, timeoutMs);
+      this.#pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timer, method });
+      try { this.#ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })); }
+      catch {
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        rejectPromise(fail(`云端浏览器命令 ${method} 发送失败`, 'ASSISTANT_BROWSER_CDP_ERROR'));
+      }
+    });
+  }
+
+  #onMessage(event) {
+    let message;
+    try { message = JSON.parse(typeof event === 'string' ? event : event?.data); } catch { return; }
+    if (!message || typeof message.id !== 'number') return;
+    const pending = this.#pending.get(message.id);
+    if (!pending) return;
+    this.#pending.delete(message.id);
+    clearTimeout(pending.timer);
+    if (message.error) pending.reject(fail(`CDP ${pending.method} 失败: ${String(message.error.message || '').slice(0, 300)}`, 'ASSISTANT_BROWSER_CDP_ERROR'));
+    else pending.resolve(message.result || {});
+  }
+
+  #rejectAll(error) {
+    if (this.#closed && this.#pending.size === 0) return;
+    this.#closed = true;
+    for (const pending of this.#pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.#pending.clear();
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#rejectAll(fail('云端浏览器调试连接已关闭', 'ASSISTANT_BROWSER_CDP_CLOSED'));
+    try { this.#ws.close(); } catch {}
+  }
+}
+
+/** Connect once to the browser-level WebSocket endpoint. */
+export async function connectCdp({
+  endpoint, WebSocketImpl = globalThis.WebSocket,
+  commandTimeoutMs = CDP_COMMAND_TIMEOUT_MS, connectTimeoutMs = CDP_CONNECT_TIMEOUT_MS,
+} = {}) {
+  if (typeof WebSocketImpl !== 'function') throw fail('运行环境缺少 WebSocket 实现', 'ASSISTANT_BROWSER_CDP_UNAVAILABLE');
+  if (typeof endpoint !== 'string' || !endpoint.startsWith('ws://')) throw fail('Chromium 调试端点无效', 'ASSISTANT_BROWSER_LAUNCH_FAILED');
+  const ws = new WebSocketImpl(endpoint);
+  await new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { ws.close(); } catch {}
+      rejectPromise(fail('连接 Chromium 调试端口超时', 'ASSISTANT_BROWSER_CDP_TIMEOUT'));
+    }, connectTimeoutMs);
+    timer.unref?.();
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) rejectPromise(error); else resolvePromise();
+    };
+    ws.addEventListener?.('open', () => finish());
+    ws.addEventListener?.('error', () => finish(fail('无法连接 Chromium 调试端口', 'ASSISTANT_BROWSER_CDP_UNAVAILABLE')));
+    ws.addEventListener?.('close', () => finish(fail('Chromium 调试端口连接已关闭', 'ASSISTANT_BROWSER_CDP_UNAVAILABLE')));
+  });
+  return new CdpConnection(ws, { commandTimeoutMs });
+}
+
+/**
+ * Launch and connect one Chromium. `dispose()` closes the channel, kills the
+ * process group. 普通临时配置会删除；Computer 明确声明的持久私有配置保留。
+ */
+export async function startCdpTransport({
+  chromium, proxy, spawn = spawnChild, WebSocketImpl = globalThis.WebSocket,
+  kill = killProcessTree, launchTimeoutMs = DEVTOOLS_LAUNCH_TIMEOUT_MS,
+  commandTimeoutMs = CDP_COMMAND_TIMEOUT_MS, now = Date.now, userDataDir, endpoint: fixedEndpoint,
+  env = process.env,
+  preserveUserDataDir = false, startUrl,
+} = {}) {
+  if (preserveUserDataDir && (!userDataDir || !isAbsolute(userDataDir))) throw fail('持久浏览器配置目录必须为绝对路径', 'ASSISTANT_BROWSER_PROFILE_INVALID');
+  const launched = fixedEndpoint
+    ? { child: undefined, userDataDir, endpoint: { endpoint: fixedEndpoint }, stderr: { text: '' } }
+    : await launchChromium({ chromium, proxy, spawn, launchTimeoutMs, now, userDataDir, env, preserveUserDataDir, startUrl });
+  let connection;
+  try { connection = await connectCdp({ endpoint: launched.endpoint.endpoint, WebSocketImpl, commandTimeoutMs }); }
+  catch (error) {
+    await stopOwnChromium(launched.child, kill, { wait: preserveUserDataDir });
+    if (launched.userDataDir && !preserveUserDataDir) await rm(launched.userDataDir, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+  let disposing;
+  return {
+    connection,
+    child: launched.child,
+    userDataDir: launched.userDataDir,
+    stderr: launched.stderr,
+    dispose() {
+      if (disposing) return disposing;
+      disposing = (async () => {
+        try { connection.close(); } catch {}
+        await stopOwnChromium(launched.child, kill, { wait: preserveUserDataDir, graceMs: preserveUserDataDir ? 1000 : 0 });
+        if (launched.userDataDir && !preserveUserDataDir) await rm(launched.userDataDir, { recursive: true, force: true }).catch(() => {});
+      })();
+      return disposing;
+    },
+  };
+}