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

package/src/persistent-state.mjs

@@ -0,0 +1,201 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const MAX_RECORDS = 10_000;
+const MAX_TEXT_BYTES = 64 * 1024;
+const identifier = (value, field) => {
+  const result = String(value ?? '').trim();
+  if (!/^[a-zA-Z0-9._:-]{1,128}$/u.test(result)) throw Object.assign(new TypeError(`${field} is invalid`), { code: 'STATE_IDENTIFIER_INVALID' });
+  return result;
+};
+const text = (value, field, required = true) => {
+  const result = String(value ?? '').trim();
+  if (required && !result) throw Object.assign(new TypeError(`${field} is required`), { code: 'STATE_FIELD_REQUIRED' });
+  if (Buffer.byteLength(result, 'utf8') > MAX_TEXT_BYTES) throw Object.assign(new TypeError(`${field} is too large`), { code: 'STATE_FIELD_TOO_LARGE' });
+  return result;
+};
+
+/**
+ * Durable profile-local state for sessions, memory and schedules.
+ *
+ * The state directory is supplied by runtime-service on the user's PVC. The
+ * plugin never removes it during disable/uninstall; DSH owns bundle selection
+ * while this store owns only the records created by the assistant runtime.
+ */
+export class PersonalAssistantStateStore {
+  constructor(root) {
+    this.root = String(root ?? '').trim();
+    if (!this.root.startsWith('/')) throw new TypeError('state root must be an absolute path');
+    this.pending = Promise.resolve();
+  }
+
+  async init() {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    for (const name of ['sessions', 'memory', 'schedules', 'messages', 'turns']) {
+      const path = this.file(name);
+      try { await readFile(path, 'utf8'); } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        await writeFile(path, '[]', { mode: 0o600 });
+      }
+    }
+    return this;
+  }
+
+  file(name) { return join(this.root, `${name}.json`); }
+
+  async read(name) {
+    try {
+      const parsed = JSON.parse(await readFile(this.file(name), 'utf8'));
+      return Array.isArray(parsed) ? parsed : [];
+    } catch (error) {
+      if (error?.code === 'ENOENT') return [];
+      throw Object.assign(new Error(`state file ${name} is invalid`), { code: 'STATE_CORRUPT', cause: error });
+    }
+  }
+
+  async write(name, rows) {
+    if (!Array.isArray(rows) || rows.length > MAX_RECORDS) throw new TypeError(`state collection ${name} is invalid`);
+    const target = this.file(name);
+    const temporary = `${target}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(rows)}\n`, { mode: 0o600 });
+    await rename(temporary, target);
+  }
+
+  mutate(name, operation) {
+    const run = this.pending.then(async () => {
+      const rows = await this.read(name);
+      const result = await operation(rows);
+      await this.write(name, rows);
+      return result;
+    });
+    this.pending = run.catch(() => {});
+    return run;
+  }
+
+  async sessions(botId) {
+    const id = identifier(botId, 'botId');
+    return (await this.read('sessions')).filter(row => row.botId === id);
+  }
+
+  messages({ botId, sessionId } = {}) {
+    const id = identifier(botId, 'botId');
+    const session = identifier(sessionId, 'sessionId');
+    return this.read('messages').then(rows => rows.filter(row => row.botId === id && row.sessionId === session));
+  }
+
+  appendMessage({ botId, sessionId, role, content, metadata = {} } = {}) {
+    const id = identifier(botId, 'botId');
+    const session = identifier(sessionId, 'sessionId');
+    const messageRole = identifier(role, 'role');
+    if (!['system', 'user', 'assistant', 'tool'].includes(messageRole)) {
+      throw Object.assign(new TypeError('role is invalid'), { code: 'MESSAGE_ROLE_INVALID' });
+    }
+    const value = text(content, 'content');
+    return this.mutate('messages', rows => {
+      const message = Object.freeze({
+        messageId: `message-${randomUUID()}`,
+        botId: id,
+        sessionId: session,
+        role: messageRole,
+        content: value,
+        metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {},
+        createdAt: new Date().toISOString(),
+      });
+      rows.push(message);
+      return message;
+    });
+  }
+
+  turns(botId, sessionId) {
+    const id = identifier(botId, 'botId');
+    const session = identifier(sessionId, 'sessionId');
+    return this.read('turns').then(rows => rows.filter(row => row.botId === id && row.sessionId === session));
+  }
+
+  createTurn({ botId, sessionId, input, metadata = {} } = {}) {
+    const id = identifier(botId, 'botId');
+    const session = identifier(sessionId, 'sessionId');
+    const value = text(input, 'input');
+    return this.mutate('turns', rows => {
+      const turn = Object.freeze({
+        turnId: `turn-${randomUUID()}`,
+        botId: id,
+        sessionId: session,
+        input: value,
+        status: 'queued',
+        metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {},
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      });
+      rows.push(turn);
+      return turn;
+    });
+  }
+
+  createSession({ botId, title = '', metadata = {} } = {}) {
+    const id = identifier(botId, 'botId');
+    return this.mutate('sessions', rows => {
+      const session = Object.freeze({
+        sessionId: `session-${randomUUID()}`,
+        botId: id,
+        title: text(title, 'title', false),
+        metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {},
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      });
+      rows.push(session);
+      return session;
+    });
+  }
+
+  memory(botId, query = '') {
+    const id = identifier(botId, 'botId');
+    const needle = text(query, 'query', false).toLowerCase();
+    return this.read('memory').then(rows => rows.filter(row => row.botId === id && (!needle || `${row.key}\n${row.content}`.toLowerCase().includes(needle))));
+  }
+
+  putMemory({ botId, key, content, metadata = {} } = {}) {
+    const id = identifier(botId, 'botId');
+    const memoryKey = identifier(key, 'key');
+    const value = text(content, 'content');
+    return this.mutate('memory', rows => {
+      const index = rows.findIndex(row => row.botId === id && row.key === memoryKey);
+      const next = { botId: id, key: memoryKey, content: value, metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {}, updatedAt: new Date().toISOString() };
+      if (index < 0) rows.push(next); else rows[index] = next;
+      return next;
+    });
+  }
+
+  schedules(botId) {
+    const id = identifier(botId, 'botId');
+    return this.read('schedules').then(rows => rows.filter(row => row.botId === id));
+  }
+
+  putSchedule({ botId, scheduleId, runAt, metadata = {} } = {}) {
+    const id = identifier(botId, 'botId');
+    const schedule = identifier(scheduleId, 'scheduleId');
+    const timestamp = Number(runAt);
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) throw Object.assign(new TypeError('runAt is invalid'), { code: 'SCHEDULE_INVALID' });
+    return this.mutate('schedules', rows => {
+      const index = rows.findIndex(row => row.botId === id && row.scheduleId === schedule);
+      const next = { botId: id, scheduleId: schedule, nextRunAt: timestamp, metadata: metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? { ...metadata } : {}, updatedAt: new Date().toISOString() };
+      if (index < 0) rows.push(next); else rows[index] = next;
+      return next;
+    });
+  }
+
+  removeSchedule(botId, scheduleId) {
+    const id = identifier(botId, 'botId');
+    const schedule = identifier(scheduleId, 'scheduleId');
+    return this.mutate('schedules', rows => {
+      const before = rows.length;
+      rows.splice(0, rows.length, ...rows.filter(row => !(row.botId === id && row.scheduleId === schedule)));
+      return before !== rows.length;
+    });
+  }
+}
+
+export function createPersonalAssistantStateStore(root) {
+  return new PersonalAssistantStateStore(root);
+}

package/src/platform-manifest.mjs

@@ -0,0 +1,24 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+/** 只读取平台挂载的原始声明；不从 Studio 或本地 profile 获取云端提示词。 */
+export function loadPersonalAssistantManifest(env, { parseDocument } = {}) {
+  const fail = code => { throw Object.assign(new Error(code), { code }); };
+  if (env.AGENTENGINE_MANIFEST_PROTOCOL !== 'runtime-manifest/v1' || env.AGENTENGINE_MANAGED_RUNTIME_NAME !== 'personal-assistant'
+    || !env.AGENTENGINE_MANAGED_RUNTIME_VERSION || !/^[a-f0-9]{64}$/u.test(env.AGENTENGINE_MANIFEST_SHA256 || '')) fail('MANAGED_RUNTIME_IDENTITY_INVALID');
+  const raw = readFileSync(env.AGENTENGINE_MANIFEST_PATH);
+  if (raw.length > 900 * 1024 || createHash('sha256').update(raw).digest('hex') !== env.AGENTENGINE_MANIFEST_SHA256) fail('MANAGED_MANIFEST_DIGEST_MISMATCH');
+  let manifest;
+  try {
+    const parse = parseDocument ?? createRequire('/opt/agentkit/dsh-runtime/package.json')('yaml').parseDocument;
+    const document = parse(new TextDecoder('utf-8', { fatal: true }).decode(raw), { uniqueKeys: true, version: '1.2' });
+    if (document.errors.length || document.warnings.length) throw Error('invalid YAML');
+    manifest = document.toJS({ maxAliasCount: 0 });
+  } catch { fail('MANAGED_MANIFEST_INVALID'); }
+  if (!manifest || manifest.framework !== 'personal-assistant' || manifest.artifact_type !== 'ManagedRuntime'
+    || manifest.runtime?.name !== 'personal-assistant' || manifest.runtime?.version !== env.AGENTENGINE_MANAGED_RUNTIME_VERSION) fail('MANAGED_RUNTIME_IDENTITY_MISMATCH');
+  if (typeof manifest.model !== 'string' || !manifest.model.trim() || manifest.model.length > 512) fail('MANAGED_MODEL_REQUIRED');
+  if (typeof manifest.prompt !== 'string' || Buffer.byteLength(manifest.prompt) > 900 * 1024 || manifest.prompt.includes('\0')) fail('MANAGED_PROMPT_INVALID');
+  return manifest;
+}

package/src/plugin-manifest.mjs

@@ -0,0 +1,82 @@
+/**
+ * Validators for the two manifest surfaces used by this project.
+ *
+ * `package.json.dsh` follows the DSH loader contract. The separate
+ * `personal-assistant.plugin.json` is an AgentKit application metadata file;
+ * DSH does not read its `metadata` values.
+ */
+
+const FORMAT = 'agentkit-personal-assistant.plugin/v1';
+const PLUGIN_ID = '@kingsoftcloud/agentkit-personal-assistant';
+const REQUIRED_DSH = '0.2.1-rc.2';
+const REQUIRED_HOST_API = `dsh-native/${REQUIRED_DSH}`;
+
+function fail(message) {
+  throw new TypeError(`Invalid personal-assistant manifest: ${message}`);
+}
+
+function string(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') fail(`${field} must be a non-empty string`);
+  return value;
+}
+
+function strings(value, field) {
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.trim() === '')) fail(`${field} must be an array of non-empty strings`);
+  if (new Set(value).size !== value.length) fail(`${field} must not contain duplicates`);
+  return value;
+}
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${field} must be an object`);
+  return value;
+}
+
+/** Validate the subset of package.json.dsh consumed by DSH's loader. */
+export function validateDshPackageManifest(manifest) {
+  const root = object(manifest, 'package.json');
+  string(root.name, 'package.json.name');
+  string(root.version, 'package.json.version');
+  const dsh = root.dsh === undefined ? {} : object(root.dsh, 'package.json.dsh');
+  const bundle = dsh.bundle === undefined ? undefined : object(dsh.bundle, 'package.json.dsh.bundle');
+  if (bundle !== undefined) {
+    const patch = bundle.patch;
+    if (!(typeof patch === 'string' && patch.trim() !== '') && !(Array.isArray(patch) && patch.length > 0 && patch.every(item => typeof item === 'string' && item.trim() !== ''))) {
+      fail('package.json.dsh.bundle.patch must be a path or non-empty path array');
+    }
+  }
+  const client = dsh.client === undefined ? undefined : object(dsh.client, 'package.json.dsh.client');
+  if (client !== undefined) {
+    string(client.platform, 'package.json.dsh.client.platform');
+    if (client.inject !== undefined) strings(client.inject, 'package.json.dsh.client.inject');
+    if (client.external !== undefined) strings(client.external, 'package.json.dsh.client.external');
+    if (client.immediately !== undefined && typeof client.immediately !== 'boolean') fail('package.json.dsh.client.immediately must be a boolean');
+  }
+  return root;
+}
+
+/** Validate the application-owned personal-assistant.plugin.json shape. */
+export function validatePersonalAssistantManifest(manifest) {
+  const root = object(manifest, 'personal-assistant.plugin.json');
+  const allowedRoot = new Set(['$schema', 'format', 'pluginId', 'version', 'compatibility', 'metadata']);
+  for (const key of Object.keys(root)) if (!allowedRoot.has(key)) fail(`unrecognized top-level field: ${key}`);
+  if (root.format !== FORMAT) fail(`format must be ${FORMAT}`);
+  if (root.pluginId !== PLUGIN_ID) fail(`pluginId must be ${PLUGIN_ID}`);
+  string(root.version, 'version');
+  const compatibility = object(root.compatibility, 'compatibility');
+  if (compatibility.requiredDsh !== REQUIRED_DSH) fail(`compatibility.requiredDsh must be ${REQUIRED_DSH}`);
+  if (compatibility.requiredHostApi !== REQUIRED_HOST_API) fail(`compatibility.requiredHostApi must be ${REQUIRED_HOST_API}`);
+  if (!Number.isInteger(compatibility.requiredHostContract) || compatibility.requiredHostContract < 1) fail('compatibility.requiredHostContract must be a positive integer');
+  const allowedMetadata = new Set(['defaultEnabled', 'autoConnect', 'capabilities', 'contributes', 'entrypoints']);
+  const metadata = object(root.metadata, 'metadata');
+  for (const key of Object.keys(metadata)) if (!allowedMetadata.has(key)) fail(`unrecognized metadata field: ${key}`);
+  if (typeof metadata.defaultEnabled !== 'boolean') fail('metadata.defaultEnabled must be a boolean');
+  if (typeof metadata.autoConnect !== 'boolean') fail('metadata.autoConnect must be a boolean');
+  strings(metadata.capabilities, 'metadata.capabilities');
+  strings(metadata.contributes, 'metadata.contributes');
+  const entrypoints = object(metadata.entrypoints, 'metadata.entrypoints');
+  for (const key of Object.keys(entrypoints)) if (!new Set(['host', 'client']).has(key)) fail(`unrecognized metadata.entrypoints field: ${key}`);
+  if (entrypoints.host !== '.' || entrypoints.client !== './client') fail('metadata.entrypoints must point to package exports . and ./client');
+  return root;
+}
+
+export const PERSONAL_ASSISTANT_MANIFEST_FORMAT = FORMAT;

package/src/schedule-manager.mjs

@@ -0,0 +1,88 @@
+/**
+ * Small deterministic schedule manager owned by one assistant profile.
+ *
+ * It stores schedule metadata and asks the host to run a callback at a future
+ * time. Durable persistence is supplied by the runtime image's state path;
+ * this class deliberately has no process-wide timers or cross-user state.
+ */
+export const PERSONAL_ASSISTANT_SCHEDULE_CAPABILITY = 'personal-assistant-schedule-manager/v1';
+
+const ID = /^[a-z][a-z0-9._:-]{0,127}$/u;
+function identifier(value, field) {
+  const result = String(value ?? '').trim();
+  if (!ID.test(result)) throw new TypeError(`${field} has an invalid format`);
+  return result;
+}
+function at(value) {
+  const time = value instanceof Date ? value.getTime() : Number(value);
+  if (!Number.isSafeInteger(time) || time < 0) throw new TypeError('runAt must be a non-negative timestamp');
+  return time;
+}
+
+/**
+ * In-memory scheduler with stable nextRunAt/cancel semantics. A host can
+ * persist `snapshot()` and restore it on restart before scheduling callbacks.
+ */
+export class ScheduleManager {
+  constructor({ now = () => Date.now(), setTimeoutFn = setTimeout, clearTimeoutFn = clearTimeout } = {}) {
+    this.now = now;
+    this.setTimeoutFn = setTimeoutFn;
+    this.clearTimeoutFn = clearTimeoutFn;
+    this.schedules = new Map();
+  }
+
+  scheduleOnce({ scheduleId, runAt, task, metadata = {} } = {}) {
+    const id = identifier(scheduleId, 'scheduleId');
+    if (typeof task !== 'function') throw new TypeError('task must be a function');
+    const nextRunAt = at(runAt);
+    if (nextRunAt <= this.now()) throw new RangeError('runAt must be in the future');
+    this.cancel(id);
+    const record = { scheduleId: id, nextRunAt, metadata: Object.freeze({ ...metadata }), timer: null };
+    const delay = Math.max(1, nextRunAt - this.now());
+    record.timer = this.setTimeoutFn(async () => {
+      this.schedules.delete(id);
+      await task({ scheduleId: id, scheduledAt: nextRunAt });
+    }, delay);
+    record.timer?.unref?.();
+    this.schedules.set(id, record);
+    return this.describe(id);
+  }
+
+  cancel(scheduleId) {
+    const id = identifier(scheduleId, 'scheduleId');
+    const record = this.schedules.get(id);
+    if (!record) return false;
+    this.clearTimeoutFn(record.timer);
+    this.schedules.delete(id);
+    return true;
+  }
+
+  nextRunAt(scheduleId) {
+    const id = identifier(scheduleId, 'scheduleId');
+    return this.schedules.get(id)?.nextRunAt;
+  }
+
+  describe(scheduleId) {
+    const id = identifier(scheduleId, 'scheduleId');
+    const record = this.schedules.get(id);
+    if (!record) return undefined;
+    return Object.freeze({ scheduleId: record.scheduleId, nextRunAt: record.nextRunAt, metadata: record.metadata });
+  }
+
+  snapshot() {
+    return Object.freeze([...this.schedules.values()].map(record => ({
+      scheduleId: record.scheduleId,
+      nextRunAt: record.nextRunAt,
+      metadata: { ...record.metadata },
+    })));
+  }
+
+  dispose() {
+    for (const record of this.schedules.values()) this.clearTimeoutFn(record.timer);
+    this.schedules.clear();
+  }
+}
+
+export function createScheduleManager(options) {
+  return new ScheduleManager(options);
+}

package/src/system-fetch.mjs

@@ -0,0 +1,72 @@
+/**
+ * 带系统信任链的 fetch。
+ *
+ * 预发/内网网关（`pa-desktop-dev.agent-pre.kspmas.ksyun.com` 等）用的是内网 CA 签发的证书：
+ * macOS 钥匙串信任它，但 Node 自带的 CA 库不信任，于是 `fetch` 直接抛
+ * `TypeError: fetch failed`（cause: self-signed certificate in certificate chain），
+ * 面板就表现为「检查失败 · fetch failed」「暂时无法读取助理列表」。
+ *
+ * 这里用 `node:https` + `tls.getCACertificates('system')`（Node ≥ 22.15）把系统证书并入
+ * 信任链；只有 https 才走这条路径，plain http 与 data/相对 URL 仍交给全局 fetch。
+ */
+import https from 'node:https';
+import tls from 'node:tls';
+
+let cachedCA;
+
+/** 系统信任链 + Node 内置根证书；取不到系统证书时退回内置根证书。 */
+export function trustedCAs() {
+  if (cachedCA !== undefined) return cachedCA;
+  const bundled = Array.isArray(tls.rootCertificates) ? tls.rootCertificates : [];
+  let system = [];
+  try {
+    if (typeof tls.getCACertificates === 'function') system = tls.getCACertificates('system');
+  } catch { system = []; }
+  cachedCA = [...bundled, ...(Array.isArray(system) ? system : [])];
+  return cachedCA;
+}
+
+/** HEADERS 输入可能是 Headers / 数组 / 普通对象，统一成普通对象交给 https.request。 */
+function headerObject(input) {
+  if (!input) return {};
+  if (typeof Headers === 'function' && input instanceof Headers) return Object.fromEntries(input.entries());
+  if (Array.isArray(input)) return Object.fromEntries(input);
+  return { ...input };
+}
+
+/**
+ * 构造一个与全局 fetch 形状兼容、但对 https 使用系统信任链的实现。
+ * @param {typeof fetch} [fallback] 非 https 请求的兜底实现，默认全局 fetch。
+ * @returns {typeof fetch} fetch 兼容函数
+ */
+export function createSystemFetch(fallback = globalThis.fetch) {
+  return async function systemFetch(input, init = {}) {
+    const raw = typeof input === 'string' || input instanceof URL ? String(input) : String(input?.url ?? input);
+    let url;
+    try { url = new URL(raw); } catch { return fallback(input, init); }
+    if (url.protocol !== 'https:') return fallback(input, init);
+    return new Promise((resolve, reject) => {
+      const request = https.request(url, {
+        method: init.method ?? 'GET',
+        headers: headerObject(init.headers),
+        ca: trustedCAs(),
+        signal: init.signal ?? undefined,
+        rejectUnauthorized: true,
+      }, response => {
+        const chunks = [];
+        response.on('data', chunk => chunks.push(chunk));
+        response.on('end', () => {
+          const body = Buffer.concat(chunks);
+          resolve(new Response(body, { status: response.statusCode ?? 500, statusText: response.statusMessage ?? '', headers: headerObject(response.headers) }));
+        });
+        response.on('error', reject);
+      });
+      request.on('error', reject);
+      const body = init.body;
+      if (body === undefined || body === null) request.end();
+      else if (typeof body === 'string' || Buffer.isBuffer(body)) request.end(body);
+      else if (typeof body === 'object' && typeof body.pipe === 'function') body.pipe(request);
+      else request.end(String(body));
+    });
+  };
+}

package/src/workspace-tools.mjs

@@ -0,0 +1,22 @@
+// 文件和技能均由电脑上的相同 Landlock/租约链执行，不读取 Runtime 私有目录。
+export function createWorkspaceTool({ action } = {}) {
+  return {
+    name: 'cloud_workspace',
+    description: 'List/read/write files in the shared cloud workspace, discover skill SKILL.md files, or read a chosen skill before running its commands with cloud_bash. Paths must be relative to the workspace. Text read/write is bounded to 64 KiB. Deliver generated files with a Markdown link [下载文件](cloud-file:URL_ENCODED_RELATIVE_PATH); downloads are limited to 512 KiB per file. Internet is available by default for installing public dependencies and skills.',
+    parameters: { type: 'object', required: ['action'], additionalProperties: false, properties: {
+      action: { type: 'string', enum: ['list', 'read', 'write', 'skills'] }, path: { type: 'string' }, text: { type: 'string' },
+    } },
+    output: { schema: { type: 'object', required: ['result'], properties: { result: { type: 'string' } } }, render: (_args, value) => [{ type: 'text', text: value.result }] },
+    async execute(args, execution) {
+      if (!['list', 'read', 'write', 'skills'].includes(args.action)) throw new TypeError('unsupported workspace action');
+      const path = String(args.path || '.');
+      if (path.startsWith('/') || path.split(/[\\/]/u).includes('..') || /[\u0000-\u001f]/u.test(path) || path.length > 2048) throw new TypeError('path must stay inside the cloud workspace');
+      if (args.action === 'write' && (typeof args.text !== 'string' || Buffer.byteLength(args.text) > 65536)) throw new TypeError('text exceeds 64 KiB');
+      const request = JSON.stringify({ ...args, path });
+      const code = `import json,pathlib,os\na=json.loads(${JSON.stringify(request)})\np=pathlib.Path(a['path'])\nroot=pathlib.Path.cwd().resolve()\np=p.resolve()\nassert p==root or root in p.parents,'path escapes workspace'\nif a['action']=='skills':\n rows=[]\n for folder,dirs,files in os.walk(root/'skills',followlinks=False):\n  dirs[:]=[d for d in dirs if not pathlib.Path(folder,d).is_symlink()][:128]\n  if 'SKILL.md' in files:\n   rows.append(str(pathlib.Path(folder,'SKILL.md').relative_to(root)))\n  if len(rows)>=100: break\n print(json.dumps({'skills':rows},ensure_ascii=False))\nelif a['action']=='list':\n print(json.dumps({'files':[{'name':q.name,'directory':q.is_dir()} for q in sorted(p.iterdir())[:200]]},ensure_ascii=False))\nelif a['action']=='read':\n with p.open('rb') as f: data=f.read(65537)\n assert len(data)<=65536,'file exceeds 64 KiB; use cloud_bash for bounded processing'\n print(json.dumps({'path':str(p.relative_to(root)),'text':data.decode('utf-8')},ensure_ascii=False))\nelse:\n p.parent.mkdir(parents=True,exist_ok=True)\n p.write_text(a['text'],encoding='utf-8')\n print(json.dumps({'path':str(p.relative_to(root)),'bytes':len(a['text'].encode())}))`;
+      const result = await action('terminal.exec', { language: 'python', code }, execution);
+      if (result.exitCode !== 0) throw new Error(result.stderr || 'cloud workspace operation failed');
+      return { result: result.stdout.trim() };
+    },
+  };
+}

package/src/workspace.mjs

@@ -0,0 +1,22 @@
+/** Workspace contract shared by runtime tools and the computer broker. */
+export const PERSONAL_ASSISTANT_WORKSPACE_CAPABILITY = 'personal-assistant-workspace-managed/v1';
+export const WORKSPACE_PATH_ENV = 'WORKSPACE_PATH';
+
+import { isAbsolute, resolve } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+export function workspaceDir(value = process.env.WORKSPACE_PATH ?? '/workspace') {
+  const result = String(value).trim();
+  if (!isAbsolute(result)) throw new TypeError('workspace path must be absolute');
+  return resolve(result);
+}
+
+export async function ensureWorkspace(value) {
+  const directory = workspaceDir(value);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  return directory;
+}
+
+export function workspaceMount({ path = process.env.WORKSPACE_PATH, readOnly = false } = {}) {
+  return Object.freeze({ path: workspaceDir(path), readOnly: Boolean(readOnly) });
+}