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

package/src/computer-broker-protocol.mjs

@@ -0,0 +1,116 @@
+/**
+ * Public protocol boundary between Personal Assistant Runtime and Computer.
+ *
+ * These helpers validate and shape messages. They do not open sockets, spawn a
+ * browser, control a display, or imply that a computer is connected.
+ */
+
+export const COMPUTER_BROKER_PROTOCOL = 'personal-assistant.computer-broker/v1';
+export const COMPUTER_BROKER_ACTIONS = Object.freeze([
+  'computer.status',
+  'computer.lease.acquire',
+  'computer.lease.renew',
+  'computer.lease.release',
+  'computer.action',
+]);
+export const COMPUTER_ACTION_NAMES = Object.freeze([
+  'open',
+  'snapshot',
+  'screenshot',
+  'stream',
+  'click',
+  'type',
+  'press',
+  'download',
+  'scroll',
+  'clipboard.read',
+  'clipboard.write',
+  'files.list',
+  'files.read',
+  'files.write',
+  'desktop.capture',
+  'desktop.input',
+  'desktop.windows',
+  'desktop.focus',
+  'desktop.launch',
+  'terminal.exec',
+  'stop',
+]);
+
+function text(value, field) {
+  const result = String(value ?? '').trim();
+  if (!result) throw new TypeError(`${field} must be a non-empty string`);
+  return result;
+}
+
+function positiveInteger(value, field, fallback) {
+  const result = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(result) || result <= 0) throw new TypeError(`${field} must be a positive integer`);
+  return result;
+}
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${field} must be an object`);
+  return value;
+}
+
+export function createLeaseRequest(input = {}) {
+  return Object.freeze({
+    protocol: COMPUTER_BROKER_PROTOCOL,
+    ...(input.userId === undefined ? {} : { userId: text(input.userId, 'userId') }),
+    assistantId: text(input.assistantId, 'assistantId'),
+    botId: text(input.botId, 'botId'),
+    computerId: text(input.computerId, 'computerId'),
+    taskId: text(input.taskId, 'taskId'),
+    idempotencyKey: text(input.idempotencyKey ?? `${input.assistantId}:${input.botId}:${input.taskId}`, 'idempotencyKey'),
+    ttlMs: positiveInteger(input.ttlMs, 'ttlMs', 60_000),
+  });
+}
+
+export function createReleaseRequest(input = {}) {
+  return Object.freeze({
+    protocol: COMPUTER_BROKER_PROTOCOL,
+    ...(input.userId === undefined ? {} : { userId: text(input.userId, 'userId') }),
+    assistantId: text(input.assistantId, 'assistantId'),
+    botId: text(input.botId, 'botId'),
+    computerId: text(input.computerId, 'computerId'),
+    taskId: text(input.taskId, 'taskId'),
+    leaseId: text(input.leaseId, 'leaseId'),
+  });
+}
+
+export function createRenewRequest(input = {}) {
+  const ttlMs = positiveInteger(input.ttlMs, 'ttlMs', 60_000);
+  if (ttlMs > 300_000) throw new TypeError('ttlMs must not exceed 300000');
+  return Object.freeze({ ...createReleaseRequest(input), ttlMs });
+}
+
+export function createActionRequest(input = {}) {
+  const action = text(input.action, 'action');
+  if (!COMPUTER_ACTION_NAMES.includes(action)) throw new TypeError(`Unsupported computer action: ${action}`);
+  return Object.freeze({
+    protocol: COMPUTER_BROKER_PROTOCOL,
+    ...(input.userId === undefined ? {} : { userId: text(input.userId, 'userId') }),
+    assistantId: text(input.assistantId, 'assistantId'),
+    botId: text(input.botId, 'botId'),
+    computerId: text(input.computerId, 'computerId'),
+    taskId: text(input.taskId, 'taskId'),
+    leaseId: text(input.leaseId, 'leaseId'),
+    action,
+    args: Object.freeze({ ...object(input.args ?? {}, 'args') }),
+  });
+}
+
+export function createStatusRequest(input = {}) {
+  return Object.freeze({
+    protocol: COMPUTER_BROKER_PROTOCOL,
+    ...(input.userId === undefined ? {} : { userId: text(input.userId, 'userId') }),
+    assistantId: text(input.assistantId, 'assistantId'),
+    botId: text(input.botId, 'botId'),
+    computerId: text(input.computerId, 'computerId'),
+  });
+}
+
+export function isComputerBrokerMessage(value) {
+  return Boolean(value && typeof value === 'object' && value.protocol === COMPUTER_BROKER_PROTOCOL);
+}

package/src/computer-broker.mjs

@@ -0,0 +1,220 @@
+import { randomUUID } from 'node:crypto';
+import {
+  COMPUTER_BROKER_ACTIONS,
+  createActionRequest,
+  createLeaseRequest,
+  createReleaseRequest,
+  createRenewRequest,
+  createStatusRequest,
+} from './computer-broker-protocol.mjs';
+
+const BROKER_PATHS = Object.freeze({
+  'computer.status': '/broker/status',
+  'computer.lease.acquire': '/broker/lease/acquire',
+  'computer.lease.renew': '/broker/lease/renew',
+  'computer.lease.release': '/broker/lease/release',
+  'computer.action': '/broker/action',
+});
+
+function loopbackHost(value) {
+  const host = String(value || '').replace(/^\[|\]$/gu, '').toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
+
+/**
+ * HTTP transport for the localhost Computer Broker sidecar.
+ *
+ * The runtime and Computer containers share a network namespace. Keeping this
+ * transport loopback-only prevents a bad deployment from turning the broker
+ * into a cluster-reachable control endpoint. Tests can inject fetchImpl, but
+ * production callers should use the default fetch implementation.
+ */
+export function createHttpComputerBrokerTransport({ baseUrl, fetchImpl = globalThis.fetch, timeoutMs = 30_000 } = {}) {
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) throw new TypeError('baseUrl must be a non-empty string');
+  let endpoint;
+  try { endpoint = new URL(baseUrl); } catch { throw new TypeError('baseUrl must be a valid URL'); }
+  if (!['http:', 'https:'].includes(endpoint.protocol)) throw new TypeError('baseUrl must use http or https');
+  if (endpoint.username || endpoint.password) throw new TypeError('baseUrl must not contain credentials');
+  if (!loopbackHost(endpoint.hostname)) throw new TypeError('Computer Broker URL must resolve to loopback');
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 300_000) throw new TypeError('timeoutMs must be between 1 and 300000');
+  if (typeof fetchImpl !== 'function') throw new TypeError('fetchImpl must be a function');
+
+  return Object.freeze({
+    endpoint: endpoint.toString(),
+    async request(operation, payload, { signal } = {}) {
+      const path = BROKER_PATHS[operation];
+      if (!path) throw new TypeError(`Unsupported computer broker operation: ${operation}`);
+      const target = new URL(path, endpoint);
+      const controller = new AbortController();
+      // 长命令的执行期限由 Computer 自身约束；RPC 留出终止进程组及回传结果的余量。
+      const requested = payload?.action === 'terminal.exec' ? (payload.args?.timeoutMs ?? 120_000) : 0;
+      const executionMs = Number.isInteger(requested) && requested > 0 ? Math.min(requested, 300_000) : 0;
+      const deadlineMs = executionMs ? Math.max(timeoutMs, executionMs + 5000) : timeoutMs;
+      const timer = setTimeout(() => controller.abort(), deadlineMs);
+      const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+      try {
+        const response = await fetchImpl(target, {
+          method: 'POST',
+          headers: { accept: 'application/json', 'content-type': 'application/json' },
+          body: JSON.stringify(payload),
+          signal: combined,
+        });
+        const body = await response.json().catch(error => {
+          if (combined.aborted) throw error;
+          throw Object.assign(new Error(`Computer Broker returned non-JSON response (${response.status})`), { code: 'COMPUTER_BROKER_FAILED', status: response.ok ? 502 : response.status });
+        });
+        if (!response.ok) throw Object.assign(new Error(body.message || body.error || `Computer Broker returned HTTP ${response.status}`), { code: body.error || 'COMPUTER_BROKER_FAILED', status: response.status, ...(body.outcomeUnknown ? { outcomeUnknown: true } : {}) });
+        return body;
+      } catch (error) {
+        if (error.status) throw error;
+        const wrapped = new Error(`Computer Broker request failed: ${error?.message || 'network error'}`);
+        wrapped.code = signal?.aborted ? (typeof signal.reason?.code === 'string' ? signal.reason.code : 'COMPUTER_ACTION_ABORTED') : controller.signal.aborted ? 'COMPUTER_BROKER_TIMEOUT' : 'COMPUTER_BROKER_UNAVAILABLE';
+        if (operation === 'computer.action') { wrapped.outcomeUnknown = true; wrapped.message += '；动作可能已部分执行，请先核对结果，勿盲目重放'; }
+        if (signal?.reason?.status) wrapped.status = signal.reason.status;
+        wrapped.cause = error;
+        throw wrapped;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  });
+}
+
+export class ComputerBrokerUnavailableError extends Error {
+  constructor(message = 'Cloud Computer Broker is not connected') {
+    super(message);
+    this.name = 'ComputerBrokerUnavailableError';
+    this.code = 'COMPUTER_BROKER_UNAVAILABLE';
+  }
+}
+
+export class ComputerLeaseConflictError extends Error {
+  constructor(computerId) {
+    super(`Computer is already leased: ${computerId}`);
+    this.name = 'ComputerLeaseConflictError';
+    this.code = 'COMPUTER_LEASE_CONFLICT';
+  }
+}
+
+function requestTransport(transport) {
+  if (!transport || typeof transport.request !== 'function') throw new ComputerBrokerUnavailableError();
+  return transport;
+}
+
+/**
+ * Create the runtime-side client. A real transport is intentionally required;
+ * the default is disconnected so a deployment cannot claim computer access.
+ */
+export function createComputerBrokerClient({ transport, now = () => Date.now() } = {}) {
+  const transportOrNull = transport ?? null;
+  const call = async (operation, payload, options) => {
+    const active = requestTransport(transportOrNull);
+    if (!COMPUTER_BROKER_ACTIONS.includes(operation)) throw new TypeError(`Unsupported computer broker operation: ${operation}`);
+    return active.request(operation, payload, options);
+  };
+  return Object.freeze({
+    connected: () => Boolean(transportOrNull),
+    status: input => call('computer.status', createStatusRequest(input)),
+    acquireLease: input => call('computer.lease.acquire', createLeaseRequest(input)),
+    renewLease: (input, options) => call('computer.lease.renew', createRenewRequest(input), options),
+    releaseLease: input => call('computer.lease.release', createReleaseRequest(input)),
+    action: (input, options) => call('computer.action', createActionRequest(input), options),
+    now,
+  });
+}
+
+/**
+ * In-memory lease manager used by adapters and tests. It does not execute a
+ * computer action; it only serializes access to one computer ID.
+ */
+export class ComputerLeaseManager {
+  constructor({ now = () => Date.now(), leaseId = () => randomUUID() } = {}) {
+    this.now = now;
+    this.leaseId = leaseId;
+    this.leases = new Map();
+    this.idempotency = new Map();
+  }
+
+  _expire() {
+    const now = this.now();
+    for (const [computerId, lease] of this.leases) {
+      if (lease.expiresAt <= now) {
+        this.leases.delete(computerId);
+        this.idempotency.delete(lease.idempotencyKey);
+      }
+    }
+  }
+
+  acquire(input) {
+    this._expire();
+    const existingByKey = this.idempotency.get(input.idempotencyKey);
+    if (existingByKey && existingByKey.expiresAt > this.now()) return existingByKey;
+    const existing = this.leases.get(input.computerId);
+    if (existing) throw new ComputerLeaseConflictError(input.computerId);
+    const lease = Object.freeze({
+      leaseId: this.leaseId(),
+      ...(input.userId === undefined ? {} : { userId: input.userId }),
+      computerId: input.computerId,
+      assistantId: input.assistantId,
+      botId: input.botId,
+      taskId: input.taskId,
+      idempotencyKey: input.idempotencyKey,
+      expiresAt: this.now() + input.ttlMs,
+    });
+    this.leases.set(lease.computerId, lease);
+    this.idempotency.set(lease.idempotencyKey, lease);
+    return lease;
+  }
+
+  release(input) {
+    this._expire();
+    const lease = this.leases.get(input.computerId);
+    if (!lease || lease.leaseId !== input.leaseId) return false;
+    this.leases.delete(input.computerId);
+    this.idempotency.delete(lease.idempotencyKey);
+    return true;
+  }
+
+  renew(input) {
+    const lease = this.assert(input);
+    if (lease.assistantId !== input.assistantId || lease.botId !== input.botId || lease.userId !== input.userId) throw new Error('COMPUTER_LEASE_REQUIRED');
+    const renewed = Object.freeze({ ...lease, expiresAt: this.now() + input.ttlMs });
+    this.leases.set(lease.computerId, renewed); this.idempotency.set(lease.idempotencyKey, renewed);
+    return renewed;
+  }
+
+  assert(input) {
+    this._expire();
+    const lease = this.leases.get(input.computerId);
+    if (!lease || lease.leaseId !== input.leaseId || lease.taskId !== input.taskId) {
+      throw new Error('COMPUTER_LEASE_REQUIRED');
+    }
+    return lease;
+  }
+}
+
+/**
+ * Explicitly simulated transport for unit tests and local contract demos.
+ * The response includes `simulated: true` to prevent it being mistaken for a
+ * real Cloud Computer connection.
+ */
+export function createMockComputerBroker({ computerId = 'mock-computer', now = () => Date.now() } = {}) {
+  const leases = new ComputerLeaseManager({ now, leaseId: () => `mock-lease-${Math.random().toString(16).slice(2)}` });
+  const actions = [];
+  const transport = {
+    async request(operation, payload) {
+      if (operation === 'computer.status') return { protocol: payload.protocol, computerId, connected: true, simulated: true };
+      if (operation === 'computer.lease.acquire') return { protocol: payload.protocol, simulated: true, lease: leases.acquire(payload) };
+      if (operation === 'computer.lease.renew') return { protocol: payload.protocol, simulated: true, lease: leases.renew(payload) };
+      if (operation === 'computer.lease.release') return { protocol: payload.protocol, simulated: true, released: leases.release(payload) };
+      if (operation === 'computer.action') {
+        leases.assert(payload);
+        const event = Object.freeze({ protocol: payload.protocol, simulated: true, computerId, taskId: payload.taskId, action: payload.action, args: payload.args });
+        actions.push(event);
+        return { ...event, accepted: true };
+      }
+      throw new Error(`Unsupported mock operation: ${operation}`);
+    },
+  };
+  return Object.freeze({ client: createComputerBrokerClient({ transport, now }), actions, leases });
+}

package/src/desktop-tools.mjs

@@ -0,0 +1,64 @@
+// 模型只通过 Broker 操作与用户看到的同一桌面；没有本机 shell 或第二个浏览器。
+const actions = ['screenshot', 'click', 'double_click', 'right_click', 'type', 'key', 'scroll', 'drag', 'windows', 'focus', 'launch'];
+const field = (value, name, max = 16384) => {
+  if (typeof value !== 'string' || !value.length || Buffer.byteLength(value) > max) throw new TypeError(`${name} is invalid`);
+  return value;
+};
+const point = (args, x = 'x', y = 'y') => {
+  if (!Number.isInteger(args[x]) || args[x] < 0 || args[x] >= 1280 || !Number.isInteger(args[y]) || args[y] < 0 || args[y] >= 800) throw new TypeError('coordinates must be desktop pixels within 1280x800');
+  return { x: args[x], y: args[y] };
+};
+export function createDesktopTool({ action, agent } = {}) {
+  return {
+    name: 'cloud_computer',
+    description: 'Operate the entire shared cloud desktop, including browser, terminal and file manager. Use windows/launch/focus or screenshot to inspect, then click/type/key/scroll/drag. Coordinates are 1280x800 desktop pixels. Human takeover pauses new actions until control is returned. Screenshot requires an image-capable cloud model; never pretend to see an image when unavailable.',
+    parameters: { type: 'object', additionalProperties: false, required: ['action'], properties: {
+      action: { type: 'string', enum: actions }, x: { type: 'integer' }, y: { type: 'integer' }, toX: { type: 'integer' }, toY: { type: 'integer' },
+      text: { type: 'string' }, key: { type: 'string' }, deltaY: { type: 'integer', minimum: -20, maximum: 20 },
+      windowId: { type: 'string' }, application: { type: 'string', enum: ['browser', 'terminal', 'files'] },
+    } },
+    output: { schema: { type: 'object', required: ['result'], properties: {
+      result: { type: 'string' }, image: { type: 'object', required: ['attachmentId', 'mediaType', 'bytes', 'width', 'height'], properties: {
+        attachmentId: { type: 'string' }, mediaType: { type: 'string' }, bytes: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' }, name: { type: 'string' },
+      } },
+    } }, render: (_args, value) => [{ type: 'text', text: value.result }, ...(value.image ? [{ type: 'image', attachment: value.image }] : [])] },
+    async execute(args, execution = {}) {
+      if (!actions.includes(args.action)) throw new TypeError('unsupported desktop action');
+      const send = event => action('desktop.input', { event }, execution);
+      if (args.action === 'screenshot') {
+        const attachments = agent?.ctx?.get?.('attachments'), llm = agent?.ctx?.get?.('llm');
+        const route = execution.agent?.session?.requestHeader?.()?.config;
+        const info = await llm?.resolveModelInfo(route?.provider ?? agent?.options?.provider, route?.model ?? agent?.options?.model, execution.signal);
+        if (!info?.inputModalities?.includes('image')) throw new Error('当前云端模型不支持图片输入，请使用 windows、页面 snapshot 或切换视觉模型；此回合没有取得或看见截图。');
+        if (!attachments?.saveImage) throw new Error('云端图片附件服务尚未就绪');
+        const { image } = await action('desktop.capture', {}, execution);
+        const data = Buffer.from(image.data, 'base64');
+        if (data.length > 307200 || data.length !== image.bytes || image.mediaType !== 'image/jpeg') throw new Error('invalid desktop image');
+        const ref = await attachments.saveImage({ data, mediaType: image.mediaType, name: 'cloud-desktop.jpg' });
+        return { result: `共享云桌面：${image.width}x${image.height}，坐标与截图一致。`, image: ref };
+      }
+      let result;
+      if (args.action === 'windows') result = await action('desktop.windows', {}, execution);
+      else if (args.action === 'focus') result = await action('desktop.focus', { windowId: field(args.windowId, 'windowId', 32) }, execution);
+      else if (args.action === 'launch') {
+        if (!['browser', 'terminal', 'files'].includes(args.application)) throw new TypeError('unsupported application');
+        result = await action('desktop.launch', { application: args.application }, execution);
+      } else if (args.action === 'type') result = await send({ type: 'text', text: field(args.text, 'text') });
+      else if (args.action === 'key') result = await send({ type: 'key', key: field(args.key, 'key', 64), action: 'tap' });
+      else if (args.action === 'scroll') {
+        if (!Number.isInteger(args.deltaY) || args.deltaY < -20 || args.deltaY > 20) throw new TypeError('invalid scroll delta');
+        await send({ type: 'pointermove', ...point(args) }); result = await send({ type: 'wheel', deltaY: args.deltaY });
+      } else {
+        const start = point(args), events = [{ type: 'pointermove', ...start }];
+        if (args.action === 'drag') events.push({ type: 'button', button: 1, action: 'down', ...start }, { type: 'pointermove', ...point(args, 'toX', 'toY') }, { type: 'button', button: 1, action: 'up' });
+        else if (args.action === 'double_click') events.push({ type: 'button', button: 1, action: 'double', ...start });
+        else {
+          const button = args.action === 'right_click' ? 3 : 1;
+          events.push({ type: 'button', button, action: 'down', ...start }, { type: 'button', button, action: 'up' });
+        }
+        result = await action('desktop.input', { events }, execution);
+      }
+      return { result: JSON.stringify(result) };
+    },
+  };
+}

package/src/dsh-session-bridge.mjs

@@ -0,0 +1,207 @@
+import { randomUUID } from 'node:crypto';
+import { registerBotPrivateTools } from './bot-private-tools.mjs';
+
+const BOT_ID = /^[a-z][a-z0-9._-]{0,63}$/u;
+const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+
+/**
+ * Raised when the DSH Host did not inject its public Session Controller.
+ *
+ * The standalone cloud HTTP runtime intentionally does not manufacture a
+ * controller. It must be hosted by DSH (or be given an explicit adapter) before
+ * a turn can be called "executing".
+ */
+export class DshSessionControllerUnavailableError extends Error {
+  constructor(message = 'DSH Session Controller is not available') {
+    super(message);
+    this.name = 'DshSessionControllerUnavailableError';
+    this.code = 'DSH_SESSION_CONTROLLER_UNAVAILABLE';
+    this.status = 503;
+  }
+}
+
+function serviceFromContext(ctx) {
+  if (ctx && typeof ctx.get === 'function') {
+    try { return ctx.get('sessionController'); } catch { return undefined; }
+  }
+  return ctx?.sessionController;
+}
+
+function requiredIdentifier(value, field, pattern) {
+  const text = String(value ?? '').trim();
+  if (!pattern.test(text)) throw Object.assign(new TypeError(`${field} is invalid`), { code: 'DSH_TURN_INPUT_INVALID' });
+  return text;
+}
+
+function contentOf(input) {
+  const text = String(input ?? '').trim();
+  if (!text) throw Object.assign(new TypeError('input is required'), { code: 'DSH_TURN_INPUT_INVALID' });
+  return [{ type: 'text', text }];
+}
+
+/**
+ * Adapt the public DSH Host SessionController to the Personal Assistant turn
+ * contract. The controller remains the source of truth for execution and
+ * history; this bridge only performs session admission and prompt delivery.
+ */
+export function createDshTurnBridge({ ctx, sessionController, registry, platformPrompt = '', setupAgent, requestIdFactory = randomUUID } = {}) {
+  const controller = sessionController ?? serviceFromContext(ctx);
+  const available = Boolean(controller && typeof controller.prompt === 'function');
+  const installedPrompts = new WeakMap();
+  let memoryProvider;
+  let memoryWriter;
+  let sessionOwnerResolver;
+  const pending = new Map();
+  const sessionOwners = new Map();
+  const busySessions = new Set();
+  const unavailable = () => { throw new DshSessionControllerUnavailableError(); };
+  const memories = async botId => {
+    const rows = memoryProvider ? await memoryProvider(botId) : [];
+    const selected = [];
+    for (const row of rows.slice(-32).reverse()) {
+      const value = { key: String(row.key || ''), content: String(row.content || '').slice(0, 4096) };
+      if (Buffer.byteLength(JSON.stringify([...selected, value])) > 16 * 1024) break;
+      selected.push(value);
+    }
+    return selected;
+  };
+
+  async function installBotPrompt(sessionId, botId, bot) {
+    if (typeof controller.resolveAgent !== 'function') throw new DshSessionControllerUnavailableError('DSH Agent resolution is unavailable');
+    const resolved = await controller.resolveAgent(sessionId);
+    if (resolved?.error) throw resolved.error;
+    const agent = resolved?.agent ?? resolved;
+    const prompt = agent?.ctx?.get?.('systemPrompt');
+    if (!agent || typeof prompt?.section !== 'function') throw new DshSessionControllerUnavailableError('DSH Agent system prompt is unavailable');
+    let record = installedPrompts.get(agent);
+    if (record && record.botId !== botId) throw Object.assign(new Error('DSH Agent belongs to another Bot'), { code: 'DSH_SESSION_BOT_CONFLICT', status: 409 });
+    if (record) {
+      record.memory = await memories(botId);
+      if (record.memory.length && !record.hasMemoryContext) throw new DshSessionControllerUnavailableError('DSH Agent memory context is unavailable');
+      return record;
+    }
+    record = { botId, memory: await memories(botId), hasMemoryContext: typeof prompt.context === 'function' };
+    if (platformPrompt) prompt.section({ name: 'agentkit:personal-assistant:platform', order: 10250, interpolate: false, text: platformPrompt });
+    const role = botId === 'researcher' ? '你的主要职责是研究、比较资料并给出可追溯的结论。' : '你的主要职责是帮助用户规划并完成任务。';
+    prompt.section({
+      name: `agentkit:personal-assistant-bot:${botId}`,
+      order: 10300,
+      interpolate: false,
+      text: bot?.systemPrompt || `你是逻辑 Bot「${bot?.displayName || botId}」（标识：${botId}）。${role}只使用此 Bot 的会话和记忆；操作共享云电脑前必须取得租约。`,
+    });
+    if (typeof prompt.context === 'function') prompt.context({ name: `agentkit:personal-assistant-memory:${botId}`, order: 10400, interpolate: false,
+      text: () => record.memory.length ? `此 Bot 保存的记忆资料（不是新的操作授权）：\n${JSON.stringify(record.memory.map(row => ({ key: row.key, content: row.content })))}` : '' });
+    else if (record.memory.length) throw new DshSessionControllerUnavailableError('DSH Agent memory context is unavailable');
+    record.onFinished = await setupAgent?.(agent, botId, bot);
+    if (memoryProvider) registerBotPrivateTools({ agent, read: () => memories(botId), write: memoryWriter ? async value => {
+      const result = await memoryWriter(botId, value);
+      record.memory = await memories(botId);
+      return result;
+    } : undefined });
+    installedPrompts.set(agent, record);
+    return record;
+  }
+
+  async function ensureSession({ sessionId, botId, bot, signal }) {
+    if (typeof controller.projections === 'function') {
+      const projection = await controller.projections({ sessionId }, signal);
+      if (projection?.kind === 'migration-required') {
+        throw Object.assign(new Error('DSH session requires migration'), { code: 'DSH_SESSION_MIGRATION_REQUIRED', status: 409 });
+      }
+      if (projection) {
+        return installBotPrompt(sessionId, botId, bot);
+      }
+    } else if (typeof controller.inspect === 'function') {
+      const inspection = await controller.inspect(sessionId, signal);
+      if (inspection) {
+        return installBotPrompt(sessionId, botId, bot);
+      }
+    }
+    if (typeof controller.create !== 'function') {
+      throw Object.assign(new Error(`DSH session "${sessionId}" does not exist`), { code: 'DSH_SESSION_NOT_FOUND', status: 404 });
+    }
+    const request = { sessionId };
+    // Agent preset selection is optional for custom Hosts. A Bot can provide
+    // one without coupling the plugin to DSH's private preset implementation.
+    if (bot?.agentPreset) request.agentPreset = bot.agentPreset;
+    await controller.create(request);
+    return installBotPrompt(sessionId, botId, bot);
+  }
+
+  async function submitTurn({ botId, sessionId, input, parts, requestId, mode = 'queue', clientTimeZone, signal } = {}) {
+    if (!available) return unavailable();
+    const requestSignal = signal ?? new AbortController().signal;
+    const id = requiredIdentifier(botId, 'botId', BOT_ID);
+    const session = requiredIdentifier(sessionId, 'sessionId', SESSION_ID);
+    const bot = registry?.require ? registry.require(id) : undefined;
+    if (!['queue', 'steer'].includes(mode)) throw Object.assign(new TypeError('mode must be queue or steer'), { code: 'DSH_TURN_INPUT_INVALID' });
+    // parts 允许调用方直接给出完整 content（例如带图片的对话）；缺省仍按纯文本处理。
+    const content = Array.isArray(parts) && parts.length > 0 ? parts : contentOf(input);
+    const rpcId = requiredIdentifier(requestId ?? requestIdFactory(), 'requestId', SESSION_ID);
+    const owner = sessionOwners.get(session) ?? (sessionOwnerResolver ? await sessionOwnerResolver(session) : undefined);
+    if (owner && owner !== id) throw Object.assign(new Error('session belongs to another Bot'), { code: 'DSH_SESSION_BOT_CONFLICT', status: 409 });
+    if (busySessions.has(session)) throw Object.assign(new Error('session has an active turn'), { code: 'DSH_SESSION_BUSY', status: 409 });
+    busySessions.add(session);
+    try {
+    const resources = await ensureSession({ sessionId: session, botId: id, bot, signal: requestSignal });
+    sessionOwners.set(session, id);
+    const baseline = typeof controller.inspect === 'function' ? (await controller.inspect(session, requestSignal))?.events?.length || 0 : 0;
+    const request = { sessionId: session, requestId: rpcId, mode, content };
+    if (clientTimeZone !== undefined) request.clientTimeZone = String(clientTimeZone);
+    const result = await controller.prompt(request, requestSignal);
+    if (result?.accepted !== true) {
+      throw Object.assign(new Error('DSH Session Controller did not accept the turn'), { code: 'DSH_TURN_NOT_ACCEPTED', status: 503 });
+    }
+    pending.set(rpcId, { sessionId: session, botId: id, baseline, onFinished: resources?.onFinished });
+    return Object.freeze({ accepted: true, execution: 'dsh-session-controller', sessionId: session, botId: id, requestId: rpcId });
+    } catch (error) { busySessions.delete(session); throw error; }
+  }
+
+  async function waitForTurn({ botId, sessionId, requestId, timeoutMs = 300000, onProgress } = {}) {
+    const entry = pending.get(requestId);
+    if (!entry || entry.botId !== botId || entry.sessionId !== sessionId || typeof controller.inspect !== 'function') throw new DshSessionControllerUnavailableError('DSH turn observation is unavailable');
+    const deadline = Date.now() + timeoutMs;
+    let progressSeq = -1;
+    try {
+      while (Date.now() < deadline) {
+        const inspection = await controller.inspect(sessionId, new AbortController().signal);
+        const events = (inspection?.events || []).slice(entry.baseline);
+        const latest = events.findLast(event => event.type === 'tool/call' || event.type === 'tool/result');
+        if (latest && latest.seq !== progressSeq) {
+          progressSeq = latest.seq;
+          // DSH 的结果事件承载 ToolResultMessage，关联键在 message.toolCallId。
+          const called = latest.type === 'tool/call' ? latest : events.findLast(event => event.type === 'tool/call' && event.data?.callId === latest.data?.message?.toolCallId);
+          await onProgress?.({ tool: String(called?.data?.name || '').slice(0, 64), state: latest.type === 'tool/call' ? 'running' : 'settled' });
+        }
+        const end = events.find(event => event.type === 'turn/end');
+        if (end) {
+          const completed = events.slice(0, events.indexOf(end));
+          const messages = completed.filter(event => event.type === 'assistant/message').map(event => {
+            const content = event.data?.message?.content;
+            return typeof content === 'string' ? content : (Array.isArray(content) ? content.filter(part => part.type === 'text').map(part => part.text || '').join('') : '');
+          }).filter(Boolean);
+          const reason = end.data?.reason;
+          return { status: reason?.kind === 'completed' ? 'completed' : 'failed', messages, error: reason?.kind === 'completed' ? null : reason };
+        }
+        await new Promise(resolve => setTimeout(resolve, 250));
+      }
+      throw Object.assign(new Error('cloud DSH turn observation timed out'), { code: 'DSH_TURN_TIMEOUT' });
+    } finally {
+      try { if (typeof entry.onFinished === 'function') await entry.onFinished(); }
+      finally { pending.delete(requestId); busySessions.delete(sessionId); }
+    }
+  }
+
+  return Object.freeze({
+    available,
+    controller,
+    submitTurn,
+    waitForTurn,
+    setMemoryProvider(provider, writer) { memoryProvider = provider; memoryWriter = writer; },
+    setSessionOwnerResolver(resolveOwner) { sessionOwnerResolver = resolveOwner; },
+  });
+}
+
+export function sessionControllerFromContext(ctx) {
+  return serviceFromContext(ctx);
+}