@piagent/platform 1.24.0 → 1.26.0

package/docs-site/workflows.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.24.0 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.26.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/workflows" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/workflows" hreflang="en" lang="en">EN</a>

package/evals/private-holdout-v1/public-exposure.v2.json

@@ -256,8 +256,8 @@
     },
     {
       "path": "tests",
-      "fileCount": 539,
-      "sha256": "3d6f3ab397c5b5e9d2709c5b22e56bbd1dd93537e2f52146b26239fe7a3cd2b7"
+      "fileCount": 547,
+      "sha256": "845f7c2abbea50453be655a8c88710ca49a8f62f2e58d0a02e29ab5c7319f92e"
     }
   ],
   "custodianComparisonRules": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/managed/background-process.mjs

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { redactedText } from '../runtime/managed-failure.mjs';
+
+// Processes the agent keeps running across turns: a dev server, a watcher, a
+// local service the tests need. A bash command stops after 10 minutes and what
+// it leaves running stops when the turn ends; these run in the same sandbox,
+// without network, until the agent stops them, the conversation closes or
+// they reach their lifetime.
+export const MAX_PROCESSES = 4;
+export const LIFETIME_MS = 4 * 60 * 60 * 1000;
+const BUFFER = 64 * 1024, MAX_WAIT_SECONDS = 60;
+
+export class BackgroundProcesses {
+  #entries = new Map(); #next = 1;
+  constructor(boundary, { lifetime = LIFETIME_MS, poll = 200 } = {}) { Object.assign(this, { boundary, lifetime, poll }); }
+  running() { return [...this.#entries.values()].filter(entry => entry.status === 'running'); }
+  async start(command, name) {
+    if (this.running().length >= MAX_PROCESSES) throw new Error(`managed-process-limit: ${MAX_PROCESSES} background processes already run in this conversation (${this.running().map(e => e.id).join(', ')}). Stop one with stop_process first.`);
+    const key = randomUUID(), id = `p${this.#next++}`;
+    const { child, isolated } = await this.boundary.spawnBackground(command, key);
+    const entry = { id, key, name: String(name || command).slice(0, 80), command, child, status: 'running', code: null, text: '', dropped: 0, total: 0, read: 0, started: Date.now(), isolated };
+    const append = chunk => {
+      entry.text += chunk.toString('utf8'); entry.total += chunk.length;
+      if (entry.text.length > BUFFER) { entry.dropped += entry.text.length - BUFFER; entry.text = entry.text.slice(-BUFFER); }
+    };
+    child.stdout.on('data', append); child.stderr.on('data', append);
+    child.on('close', code => { if (entry.status === 'running') { entry.status = 'exited'; entry.code = code; } clearTimeout(entry.timer); });
+    child.on('error', () => { entry.status = 'exited'; entry.code = -1; });
+    entry.timer = setTimeout(() => this.stop(id, 'its 4-hour lifetime ended').catch(() => {}), this.lifetime); entry.timer.unref?.();
+    this.#entries.set(id, entry);
+    return entry;
+  }
+  get(id) {
+    const entry = this.#entries.get(String(id));
+    if (!entry) throw new Error(`managed-process-unknown: no background process ${id} in this conversation${this.#entries.size ? ` (known: ${[...this.#entries.keys()].join(', ')})` : ''}.`);
+    return entry;
+  }
+  // New output since the last read; waits up to `waitSeconds` for `until` to
+  // appear in it (a server's "ready" line) or for the process to end.
+  async output(id, { waitSeconds = 0, until, signal } = {}) {
+    const entry = this.get(id), deadline = Date.now() + Math.min(Math.max(Number(waitSeconds) || 0, 0), MAX_WAIT_SECONDS) * 1000;
+    const fresh = () => entry.text.slice(Math.max(0, entry.read - entry.dropped));
+    while (Date.now() < deadline && entry.status === 'running' && !signal?.aborted && !(until && fresh().includes(until)))
+      await new Promise(resolve => setTimeout(resolve, this.poll));
+    const skipped = Math.max(0, entry.dropped - entry.read), text = fresh();
+    entry.read = entry.dropped + entry.text.length;
+    return { entry, text: redactedText((skipped ? `[… ${skipped} characters not read …]\n` : '') + text), matched: until ? text.includes(until) : null };
+  }
+  async stop(id, reason = 'the agent stopped it') {
+    const entry = this.get(id);
+    if (entry.status !== 'running') return entry;
+    entry.status = 'stopped'; entry.reason = reason; clearTimeout(entry.timer);
+    // Its process group, what it started (found by parent, since ps cannot
+    // read the environment of Apple's own binaries), then its marker.
+    const tree = descendants(entry.child.pid);
+    for (const pid of [-entry.child.pid, ...tree]) try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+    await this.boundary.stopBackground(entry.key);
+    for (const pid of tree) try { process.kill(pid, 'SIGKILL'); } catch { /* stopped */ }
+    return entry;
+  }
+  async dispose() { await Promise.all(this.running().map(entry => this.stop(entry.id, 'the conversation closed'))); }
+}
+
+function descendants(root) {
+  let rows = [];
+  try { rows = execFileSync('/bin/ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', timeout: 5000 }).trim().split('\n').map(row => row.trim().split(/\s+/).map(Number)); } catch { return []; }
+  const out = [], queue = [root];
+  while (queue.length) { const parent = queue.shift(); for (const [pid, ppid] of rows) if (ppid === parent && !out.includes(pid)) { out.push(pid); queue.push(pid); } }
+  return out;
+}
+
+const describe = entry => `${entry.id} (${entry.name}): ${entry.status === 'running' ? `running for ${Math.round((Date.now() - entry.started) / 1000)} s`
+  : entry.status === 'exited' ? `exited with code ${entry.code}` : `stopped (${entry.reason})`}`;
+const result = text => ({ content: [{ type: 'text', text }], details: {} });
+
+export function processTools(self) {
+  if (process.platform !== 'darwin') return [];
+  // The boundary closes with the conversation and stops them then.
+  const manager = () => (self.background ??= self.boundary.background = new BackgroundProcesses(self.boundary));
+  return [
+    { name: 'start_process', label: 'Start background process',
+      description: 'Start a long-running command in the background and keep it running across turns: a dev server (npm run dev), a file watcher, a local service the tests call. It runs in the same sandbox as bash, without network, and keeps running until stop_process, the end of the conversation or 4 hours. Read its output with process_output (wait for a line such as "ready" there). Do not use it for tests or builds: run those with bash. At most 4 at once.',
+      parameters: { type: 'object', properties: { command: { type: 'string', minLength: 1, maxLength: 4000 }, name: { type: 'string', minLength: 1, maxLength: 80 } }, required: ['command'], additionalProperties: false },
+      execute: async (_id, args) => {
+        const entry = await manager().start(args.command, args.name);
+        return result(`Started ${entry.id} (${entry.name}). It keeps running across turns; read its output with process_output and stop it with stop_process.${entry.isolated ? ' A local proxy listens on this Mac, so other localhost servers are out of its reach.' : ''}`);
+      } },
+    { name: 'process_output', label: 'Background process output',
+      description: 'Read what a background process started with start_process printed since the last read, and whether it still runs. wait_seconds (up to 60) waits for more output; with until, it returns as soon as that text appears (a server\'s ready line).',
+      parameters: { type: 'object', properties: { id: { type: 'string', minLength: 1, maxLength: 20 }, wait_seconds: { type: 'number', minimum: 0, maximum: MAX_WAIT_SECONDS }, until: { type: 'string', minLength: 1, maxLength: 200 } }, required: ['id'], additionalProperties: false },
+      execute: async (_id, args, signal) => {
+        const { entry, text, matched } = await manager().output(args.id, { waitSeconds: args.wait_seconds, until: args.until, signal });
+        return result(`${describe(entry)}${matched === false ? `; "${args.until}" has not appeared yet` : ''}\n${text || '(no new output)'}`);
+      } },
+    { name: 'stop_process', label: 'Stop background process',
+      description: 'Stop a background process started with start_process, with everything it started.',
+      parameters: { type: 'object', properties: { id: { type: 'string', minLength: 1, maxLength: 20 } }, required: ['id'], additionalProperties: false },
+      execute: async (_id, args) => result(describe(await manager().stop(args.id))) },
+  ];
+}

package/packages/piagent-core/managed/checkpoints.mjs

@@ -0,0 +1,69 @@
+// Turn checkpoints and /undo for company conversations in a git repository.
+// Before a run first changes files, the working tree (tracked and untracked,
+// .gitignore honoured) is written as a git tree through a private index; when
+// the run ends, the tree after it. /undo puts back the files the last turn
+// changed, and refuses when one of them changed again since (the member's own
+// edit is never overwritten). The member's index, HEAD and commits are not
+// touched: a commit made in the turn stays. The private index is copied with
+// its time kept, so git still re-reads a file changed within the same second
+// at the same size. Commands run in the command sandbox.
+const SNAPSHOT = `set -e; git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo NOREPO; exit 0; }
+top=$(git rev-parse --show-toplevel); cd "$top"; idx="$TMPDIR/piagent-checkpoint-$$"
+real=$(git rev-parse --git-path index); if [ -f "$real" ]; then cp -p "$real" "$idx"; fi
+GIT_INDEX_FILE="$idx" git add -A >/dev/null 2>&1; tree=$(GIT_INDEX_FILE="$idx" git write-tree); rm -f "$idx"; echo "TREE $tree"`;
+const b64 = list => Buffer.from(list.map(p => p + '\0').join(''), 'utf8').toString('base64');
+
+export class TurnCheckpoints {
+  #stack = [];
+  constructor(managed) { this.managed = managed; }
+  async #bash(command) {
+    const result = await this.managed.boundary.invoke('bash', { command, timeout: 120 });
+    return (result.content ?? []).map(part => part.text ?? '').join('');
+  }
+  async #tree() {
+    const out = await this.#bash(SNAPSHOT);
+    return out.match(/^TREE ([0-9a-f]{40,64})$/m)?.[1] ?? null;
+  }
+  // Before the first change of a run; once per run.
+  async take(run = this.managed.run) {
+    if (!run || run.checkpoint !== undefined) return;
+    run.checkpoint = null;
+    try { const before = await this.#tree(); if (before) { run.checkpoint = { before, after: null, at: Date.now() }; } } catch { /* no checkpoint: /undo says so */ }
+  }
+  // When the run ends: the tree after it, kept when the run changed something.
+  async finish(run = this.managed.run) {
+    const point = run?.checkpoint;
+    if (!point) return;
+    try { point.after = await this.#tree(); } catch { return; }
+    if (point.after && point.after !== point.before) this.#stack.push(point);
+  }
+  async #changed(from, to) {
+    const out = await this.#bash(`top=$(git rev-parse --show-toplevel) && cd "$top" && git diff --no-renames --name-status -z ${from} ${to}`);
+    const parts = out.split('\0').filter(Boolean), files = [];
+    for (let i = 0; i + 1 < parts.length; i += 2) files.push({ status: parts[i].trim(), path: parts[i + 1] });
+    return files;
+  }
+  // Puts back what the last turn changed: { result, restored, removed, files }
+  // for the WebUI note (phase "undo") and `text`, the sentence for the member.
+  async undo() {
+    const answer = (undo, text) => ({ ...undo, text });
+    if (this.managed.activePrompt) return answer({ result: 'busy', restored: 0, removed: 0, files: [] }, 'Đang có một lượt chạy: chờ nó xong (hoặc dừng nó) rồi /undo.');
+    const point = this.#stack.at(-1);
+    if (!point) return answer({ result: 'none', restored: 0, removed: 0, files: [] }, 'Không có lượt nào để hoàn tác trong cuộc trò chuyện này (chỉ áp dụng cho project là git repository; checkpoint có từ khi mở cuộc trò chuyện).');
+    const now = await this.#tree();
+    if (!now) return answer({ result: 'failed', restored: 0, removed: 0, files: [] }, 'Không đọc được trạng thái hiện tại của project; không hoàn tác.');
+    const turn = await this.#changed(point.before, point.after), since = new Set((await this.#changed(point.after, now)).map(f => f.path));
+    const touched = turn.filter(f => since.has(f.path)).map(f => f.path);
+    if (touched.length) return answer({ result: 'refused', restored: 0, removed: 0, files: touched.slice(0, 5) },
+      `Không hoàn tác: ${touched.length} file lượt trước đã sửa lại thay đổi sau đó (${touched.slice(0, 5).join(', ')}${touched.length > 5 ? ', …' : ''}). Hoàn tác sẽ ghi đè thay đổi đó.`);
+    const restore = turn.filter(f => f.status !== 'A').map(f => f.path), remove = turn.filter(f => f.status === 'A').map(f => f.path);
+    const steps = ['set -e', 'top=$(git rev-parse --show-toplevel); cd "$top"; idx="$TMPDIR/piagent-undo-$$"'];
+    if (restore.length) steps.push(`GIT_INDEX_FILE="$idx" git read-tree ${point.before}`, `printf %s ${b64(restore)} | base64 --decode | GIT_INDEX_FILE="$idx" git checkout-index -f -z --stdin`, 'rm -f "$idx"');
+    if (remove.length) steps.push(`printf %s ${b64(remove)} | base64 --decode | xargs -0 rm -f --`);
+    await this.#bash(steps.join('\n'));
+    this.#stack.pop();
+    return answer({ result: 'done', restored: restore.length, removed: remove.length, files: [...restore, ...remove].slice(0, 5), more: this.#stack.length > 0 },
+      `Đã hoàn tác lượt trước: ${restore.length} file trả về như trước lượt đó, ${remove.length} file lượt đó tạo đã xoá.${this.#stack.length ? ' /undo lần nữa để hoàn tác lượt trước nữa.' : ''} Commit tạo trong lượt đó (nếu có) vẫn giữ nguyên.`);
+  }
+}
+export const checkpointsOf = managed => (managed.checkpoints ??= new TurnCheckpoints(managed));

package/packages/piagent-core/managed/command-tools.mjs

@@ -1,17 +1,23 @@
+import { spawn } from 'node:child_process';
 import { networkConfirmation } from './permission.mjs';
+import { engineAlive, engineLauncher } from './container-engine.mjs';
+import { MEMBER_ONLY, memberOnlyReason, runHostCommand } from './host-command.mjs';
+import { processTools } from './background-process.mjs';
+import { checkpointsOf } from './checkpoints.mjs';
 
 // Commands that leave the plain sandbox, each after the member approves that
-// exact command: run_with_network (internet, a local server or browser) and,
-// when this machine has a Docker engine, run_with_docker (the same plus the
-// engine's socket). Bypass runs both without asking (owner, 2026-10-09),
-// except what must be confirmed for any command (bypass-policy.mjs: pushes,
-// deploys, registry logins, deletes known only at run time).
+// exact command: run_with_network (internet, a local server or browser),
+// run_with_docker when this machine has Docker (the same plus the engine's
+// socket) and run_on_host (on the member's machine, outside the sandbox).
+// Bypass runs the first two without asking (owner, 2026-10-09), except what
+// must be confirmed for any command (bypass-policy.mjs: pushes, deploys,
+// registry logins, deletes known only at run time); run_on_host always asks.
 const PARAMETERS = { type: 'object', properties: { command: { type: 'string', minLength: 1, maxLength: 4000 }, reason: { type: 'string', minLength: 1, maxLength: 300 }, timeout: { type: 'number', minimum: 1, maximum: 1800 } }, required: ['command', 'reason'], additionalProperties: false };
 
 const KINDS = {
   network: {
     name: 'run_with_network', label: 'Run with network', scope: 'network-command-once', provider: 'network', riskClass: 'medium',
-    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command. Normal bash has no network and cannot listen on a port. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
+    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command. Normal bash has no internet; on macOS it reaches servers on this Mac and runs Playwright\'s Chromium against them, except while a local proxy listens. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
     allow: 'Run this exact command once, with internet access; a server it starts accepts connections while it runs.',
     title: 'Chạy lệnh có internet', allowText: 'chạy đúng lệnh này một lần, có internet; server nó mở nhận kết nối trong lúc chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
@@ -23,34 +29,99 @@ const KINDS = {
     title: 'Chạy lệnh dùng Docker', allowText: 'chạy đúng lệnh này một lần, có internet và Docker; container nó tạo có thể đọc thư mục Docker được chia sẻ trên máy và có thể tiếp tục chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
   },
+  host: {
+    name: 'run_on_host', label: 'Run on this machine', scope: 'host-command-once', provider: 'host', riskClass: 'high',
+    description: 'Run one shell command on the member\'s machine, outside the sandbox, as the member, after they approve that exact command. Use it when the sandbox blocks what the task needs and no other tool covers it: install a runtime or tool the project needs (brew install openjdk@21, brew install node@22, sdk install java…), git pull or git push with the member\'s sign-in, a private registry, a file outside the project. It has the member\'s files, Keychain and sign-ins, so ask only for what the task needs and say why in reason. No input can be typed: commands that need the member\'s password (sudo, a .pkg installer) or an interactive sign-in are refused; ask the member with ask_user for those.',
+    allow: 'Run this exact command once on this machine, outside the sandbox, as you: it can read and change your files and use your sign-ins.',
+    title: 'Chạy lệnh trên máy (ngoài sandbox)', allowText: 'chạy đúng lệnh này một lần trên máy bạn, ngoài sandbox, bằng quyền của bạn: lệnh đọc/sửa được file và dùng được tài khoản đã đăng nhập trên máy.',
+    // Bypass does not cover it: the member approves each command (with what
+    // Bypass would still have asked about, when there is something).
+    confirm: async (self, command) => await networkConfirmation(self, command) ?? 'ask',
+  },
 };
 
+// The engine answers, looked up again when it did not (started since).
+async function engineReady(boundary) {
+  if (boundary.engine && await engineAlive(boundary.engine.socket)) return true;
+  return boundary.refreshEnvironment() && engineAlive(boundary.engine.socket);
+}
+const DOCKER_STOPPED = 'managed-docker-unreachable: Docker engine trên máy không chạy. Gọi start_docker để xin member duyệt mở Docker, rồi chạy lại đúng lệnh này bằng run_with_docker.';
+
+// One approval of the member (the dashboard card, else the Terminal).
+async function approve(self, id, signal, ctx, action, { title, body }) {
+  const { piApprovalBroker } = await import('../runtime/inspection/approval-broker.ts');
+  const decision = await piApprovalBroker.request({ cwd: self.cwd, rawSessionId: self.session.sessionManager.getSessionId(), toolCallId: id,
+    action: { kind: 'external-provider-action', preconditionClass: 'runtime-only', targetPaths: [self.cwd], urlOrigin: null, ...action },
+    terminalConfirm: () => ctx?.ui?.confirm?.(title, body) ?? Promise.resolve(false),
+    unavailableFallback: 'terminal-confirm', recheck: () => !signal?.aborted && Boolean(self.grant) });
+  if (!decision.allowed || !decision.consume() || signal?.aborted) throw Error('managed-operation-denied');
+}
+
 function commandTool(self, kind) {
   const spec = KINDS[kind];
   return { name: spec.name, label: spec.label, description: spec.description, parameters: PARAMETERS,
     execute: async (id, args, signal, onUpdate, ctx) => {
+      if (kind === 'docker' && !await engineReady(self.boundary)) throw Error(DOCKER_STOPPED);
+      const memberOnly = kind === 'host' ? memberOnlyReason(args.command) : null;
+      if (memberOnly) throw Error(MEMBER_ONLY(memberOnly));
       const confirm = await spec.confirm(self, args.command);
-      const decision = confirm === null ? { allowed: true, consume: () => true } : await (await import('../runtime/inspection/approval-broker.ts')).piApprovalBroker.request({ cwd: self.cwd, rawSessionId: self.session.sessionManager.getSessionId(), toolCallId: id,
-        action: { kind: 'external-provider-action', preconditionClass: 'runtime-only', toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
-          targetPaths: [self.cwd], provider: spec.provider, urlOrigin: null, requestedScope: spec.scope, reason: (confirm === 'ask' ? String(args.reason) : `Bypass still asks: ${confirm}. ${args.reason}`).slice(0, 300), riskClass: spec.riskClass,
-          allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
-        terminalConfirm: () => ctx?.ui?.confirm?.(spec.title, `${args.command}\n\nLý do: ${args.reason}${confirm === 'ask' ? '' : `\nBypass vẫn hỏi: ${confirm}`}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.`) ?? Promise.resolve(false),
-        unavailableFallback: 'terminal-confirm', recheck: () => !signal?.aborted && Boolean(self.grant) });
-      if (!decision.allowed || !decision.consume() || signal?.aborted) throw Error('managed-operation-denied');
+      if (confirm !== null) await approve(self, id, signal, ctx, { toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
+        provider: spec.provider, requestedScope: spec.scope, reason: (confirm === 'ask' ? String(args.reason) : `Bypass still asks: ${confirm}. ${args.reason}`).slice(0, 300), riskClass: spec.riskClass,
+        allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
+      { title: spec.title, body: `${args.command}\n\nLý do: ${args.reason}${confirm === 'ask' ? '' : `\nBypass vẫn hỏi: ${confirm}`}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.` });
       let ok = false;
+      if (self.run) await checkpointsOf(self).take();
       const before = await self.changedFiles();
-      try { const result = await self.boundary.invoke('bash', { command: args.command, ...(args.timeout ? { timeout: args.timeout } : {}) }, signal, onUpdate, ctx?.model, kind === 'docker' ? { docker: true } : { network: true }); ok = !result?.isError; return result; }
-      finally { await self.claimChanges(before); await self.run?.afterTool('bash', args, ok, () => self.digest()); await self.refreshReview(); }
+      try {
+        const result = kind === 'host' ? await runHostCommand({ command: args.command, cwd: self.cwd, userHome: self.boundary.userHome, timeout: args.timeout, signal, onUpdate })
+          : await self.boundary.invoke('bash', { command: args.command, ...(args.timeout ? { timeout: args.timeout } : {}) }, signal, onUpdate, ctx?.model, kind === 'docker' ? { docker: true } : { network: true });
+        ok = !result?.isError; return result;
+      } finally {
+        // What the command installed (a JDK, Node) is there for the next one.
+        if (kind === 'host') self.boundary.refreshEnvironment();
+        await self.claimChanges(before); await self.run?.afterTool('bash', args, ok, () => self.digest()); await self.refreshReview();
+      }
+    } };
+}
+
+// start_docker: the engine the member installed, started after they approve
+// (Bypass starts it without asking: local and reversible), then waited for.
+const textResult = text => ({ content: [{ type: 'text', text }], details: {} });
+function startDockerTool(self, { wait = 180_000, every = 2000, launcher: found = engineLauncher, spawnImpl = spawn } = {}) {
+  return { name: 'start_docker', label: 'Start Docker',
+    description: 'Start the Docker engine installed on this machine (Docker Desktop, OrbStack, Colima, rootless Docker) after the member approves, and wait until it answers; run_with_docker works right after, in this conversation. Use it when a command reports that Docker is not running.',
+    parameters: { type: 'object', properties: { reason: { type: 'string', minLength: 1, maxLength: 300 } }, required: ['reason'], additionalProperties: false },
+    execute: async (id, args, signal, _onUpdate, ctx) => {
+      if (await engineReady(self.boundary)) return textResult('The Docker engine is running: use run_with_docker.');
+      const launcher = found({ userHome: self.boundary.userHome });
+      if (!launcher) throw Error(self.boundary.dockerCli ? MEMBER_ONLY("starting this machine's Docker service needs the member's password")
+        : 'managed-docker-not-installed: Máy chưa cài Docker. Hỏi member bằng ask_user: cài Docker Desktop hoặc OrbStack (trình cài cần mật khẩu nên member tự cài; máy có Homebrew thì có thể xin run_on_host "brew install colima docker"), hay chạy check theo cách khác.');
+      const preview = `${launcher.command} ${launcher.args.join(' ')}`;
+      if (self.permission !== 'trusted-full-access') await approve(self, id, signal, ctx, { toolName: 'start_docker', rawAction: { launcher: launcher.label }, commandPreview: preview,
+        provider: 'docker', requestedScope: 'start-docker-once', reason: String(args.reason).slice(0, 300), riskClass: 'medium',
+        allowConsequence: `Start ${launcher.label} on this machine; it keeps running after the conversation.`, denyConsequence: 'Docker is not started; the agent is told you declined.' },
+      { title: `Mở ${launcher.label}`, body: `${preview}\n\nLý do: ${args.reason}\n\nĐồng ý: mở ${launcher.label} trên máy; nó vẫn chạy sau cuộc trò chuyện.\nTừ chối: không mở Docker, agent được báo bạn đã từ chối.` });
+      try { spawnImpl(launcher.command, launcher.args, { detached: true, stdio: 'ignore', env: { HOME: self.boundary.userHome, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin', USER: process.env.USER ?? '', LANG: 'en_US.UTF-8' } }).on('error', () => {}).unref(); } catch { /* waited for below */ }
+      for (const until = Date.now() + wait; Date.now() < until;) {
+        if (signal?.aborted) throw Error('managed-tool-cancelled');
+        await new Promise(resolve => setTimeout(resolve, every));
+        if (await engineReady(self.boundary)) return textResult(`${launcher.label} is running. Run the Docker command again with run_with_docker.`);
+      }
+      throw Error(`managed-docker-start-timeout: ${launcher.label} đã được mở nhưng engine chưa trả lời sau ${Math.round(wait / 60000)} phút (lần đầu mở app có thể chờ member bấm đồng ý điều khoản hoặc đăng nhập trong cửa sổ Docker). Hỏi member bằng ask_user, kèm lựa chọn "Docker đã chạy, thử lại" và "Bỏ qua bước này".`);
     } };
 }
 
-export function commandTools(self) {
-  return [commandTool(self, 'network'), ...(self.boundary.engine ? [commandTool(self, 'docker')] : [])];
+export function commandTools(self, options) {
+  const docker = self.boundary.engine || self.boundary.dockerCli;
+  return [commandTool(self, 'network'), ...(docker ? [commandTool(self, 'docker')] : []), startDockerTool(self, options), commandTool(self, 'host'), ...processTools(self)];
 }
 
-// What the system prompt says about services: Docker when the machine has an
-// engine (run_with_docker), else the member starts them.
+// What the system prompt says about services and what the sandbox blocks: it
+// is read for every request, so a Docker started since shows up.
+const HOST_PROMPT = ' When the sandbox blocks something the task needs (a missing runtime such as a JDK or a Node version, the member\'s sign-in for git pull or git push or a private registry, a file outside the project), do not stop and do not tell the member to run it: request run_on_host with the exact command; it runs on the member\'s machine once they approve. Only what needs the member themselves (their password for sudo or an installer, an interactive sign-in, a window to click) goes to ask_user, with the exact steps and the options to continue or skip; after their answer, check and carry on.';
 export function servicesPrompt(boundary) {
-  if (boundary.engine) return ' Docker is available through run_with_docker (the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. Stop what you started when done unless the member wants it kept. The iOS Simulator is not available in the sandbox: ask the member to run those tests.';
-  return ' Docker is not running on this machine and the iOS Simulator is not available in the sandbox: ask the member to start those services (or Docker, after which a new conversation has run_with_docker) or run those tests.';
+  const simulator = ' The iOS Simulator is not available in the sandbox: ask the member with ask_user to run those tests.';
+  if (boundary.engine) return ' Docker is available through run_with_docker (the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. If the engine stops answering, start_docker asks the member to start it. Stop what you started when done unless the member wants it kept.' + simulator + HOST_PROMPT;
+  if (boundary.dockerCli) return ' Docker is installed but not running: when the task needs it, call start_docker (the member approves), then run_with_docker.' + simulator + HOST_PROMPT;
+  return ' Docker is not installed on this machine: when the task needs it, ask the member with ask_user (install it, or check another way).' + simulator + HOST_PROMPT;
 }

package/packages/piagent-core/managed/container-engine.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import net from 'node:net';
 import path from 'node:path';
 
 // The Docker engine a company command may use once the member approves it
@@ -66,3 +67,42 @@ export function engineEnvironment(engine, home) {
     ...(process.platform === 'darwin' ? { TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE: '/var/run/docker.sock' } : {}),
   };
 }
+
+// The Docker CLI on this machine, engine running or not.
+export const dockerCli = (paths = ['/usr/local/bin', '/opt/homebrew/bin', '/usr/bin', '/Applications/Docker.app/Contents/Resources/bin']) =>
+  paths.map(dir => real(path.join(dir, 'docker'))).find(Boolean) ?? null;
+
+// Whether the engine behind a socket answers (Docker Desktop leaves its
+// socket file in place when it quits).
+export function engineAlive(socket, timeoutMs = 2000) {
+  return new Promise(resolve => {
+    let reply = '';
+    const done = value => { clearTimeout(timer); connection.destroy(); resolve(value); };
+    const connection = net.createConnection(socket, () => connection.write('GET /_ping HTTP/1.0\r\nHost: docker\r\n\r\n'));
+    const timer = setTimeout(() => done(false), timeoutMs);
+    connection.on('data', chunk => { reply += chunk; if (/\r\n\r\nOK/.test(reply)) done(true); });
+    connection.on('error', () => done(false)); connection.on('end', () => done(/\r\n\r\nOK/.test(reply)));
+  });
+}
+
+// How start_docker starts an engine the member installed: the app (Docker
+// Desktop, OrbStack, Rancher Desktop) or Colima on macOS, the user service on
+// Linux. Null when none is installed, or only the system service is (that
+// needs the member's password).
+export function engineLauncher({ userHome, platform = process.platform, exists = fs.existsSync } = {}) {
+  if (platform === 'darwin') {
+    for (const app of ['Docker', 'OrbStack', 'Rancher Desktop']) {
+      const bundle = [`/Applications/${app}.app`, path.join(userHome, `Applications/${app}.app`)].find(exists);
+      if (bundle) return { label: app === 'Docker' ? 'Docker Desktop' : app, command: '/usr/bin/open', args: ['-g', '-a', bundle] };
+    }
+    const colima = ['/opt/homebrew/bin/colima', '/usr/local/bin/colima'].find(exists);
+    return colima ? { label: 'Colima', command: colima, args: ['start'] } : null;
+  }
+  // WSL2: Docker Desktop is a Windows app that serves this distribution.
+  const desktop = '/mnt/c/Program Files/Docker/Docker/Docker Desktop.exe';
+  if (exists('/proc/sys/fs/binfmt_misc/WSLInterop') && exists(desktop))
+    return { label: 'Docker Desktop', command: '/mnt/c/Windows/System32/cmd.exe', args: ['/c', 'start', '""', 'C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe'] };
+  const units = [path.join(userHome, '.config/systemd/user/docker.service'), '/usr/lib/systemd/user/docker.service', '/usr/lib/systemd/user/podman.socket'];
+  const unit = units.find(exists);
+  return unit ? { label: unit.endsWith('podman.socket') ? 'Podman' : 'Docker (rootless)', command: '/usr/bin/systemctl', args: ['--user', 'start', path.basename(unit)] } : null;
+}

package/packages/piagent-core/managed/continuation.mjs

@@ -1,3 +1,4 @@
+import { checkpointsOf } from './checkpoints.mjs';
 import { unfinished, planText, currentPlan, workflowPolicy } from './workflow.mjs';
 import { failureCode } from '../runtime/managed-failure.mjs';
 
@@ -77,6 +78,13 @@ const fresh = (self, manager, text) => {
 };
 
 export async function memberTurn(self, { manager, prompt, runRound }, text, deliver) {
+  // /undo from the WebUI (the Terminal has its own command): the last turn's
+  // files go back, said in a note, with no model request (checkpoints.mjs).
+  if (/^\s*\/undo\s*$/.test(text)) {
+    const { text: content, ...undo } = await checkpointsOf(self).undo();
+    await self.session.sendCustomMessage({ customType: 'agent-watch-process', content, display: true, details: { phase: 'undo', undo } }, { triggerTurn: false });
+    return;
+  }
   let continuation = fresh(self, manager, text), result, waiting = null, ended = null;
   self.stopRequested = false; self.queued = [];
   try {

package/packages/piagent-core/managed/doctor.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { ManagedToolBoundary } from './tool-boundary.mjs';
+import { ManagedToolBoundary, PI_HOST_VERSION, hostPackage } from './tool-boundary.mjs';
 import { ensureSearchTools } from './toolchain.mjs';
 import { nativeManagedModel, piProvider } from './native-catalog.mjs';
 import { fetchPublicPage } from './web-fetch.mjs';
@@ -28,9 +28,9 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
     catch (error) { results.push({ label, required, ok: false, detail: first(error?.message ?? error) }); }
   };
   const sdk = fs.realpathSync(sdkRoot);
-  await check('Pi host 0.87.1', true, () => {
+  await check(`Pi host ${PI_HOST_VERSION}`, true, () => {
     const version = JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'), 'utf8')).version;
-    if (version !== '0.87.1') throw Error(`found ${version}; company sessions need 0.87.1`);
+    if (version !== PI_HOST_VERSION) throw Error(`found ${version}; company sessions need ${PI_HOST_VERSION}`);
     return sdk;
   });
   await check('search tools (ripgrep, fd)', true, async () => { await ensureSearchTools(sdk); return 'ready'; });
@@ -115,7 +115,7 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
       return `key "${manifest.key_label ?? manifest.key_id}"`;
     });
     if (manifest) await check('this Piagent knows every harness model', true, async () => {
-      const api = await import(pathToFileURL(path.join(sdk, 'dist/index.js'))), ai = await import(pathToFileURL(path.join(sdk, 'node_modules/@earendil-works/pi-ai/dist/index.js')));
+      const api = await import(pathToFileURL(path.join(sdk, 'dist/index.js'))), ai = await import(pathToFileURL(path.join(hostPackage(sdk, '@earendil-works/pi-ai'), 'dist/index.js')));
       const runtime = await api.ModelRuntime.create({ credentials: new ai.InMemoryCredentialStore(), modelsPath: null, allowModelNetwork: false, refreshOnCreate: false });
       const roles = Object.entries(manifest.harness.configuration ?? {}).filter(([, role]) => role?.model_ids?.length);
       for (const [role, value] of roles) for (const id of value.model_ids) {

package/packages/piagent-core/managed/host-command.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { redactedText } from '../runtime/managed-failure.mjs';
+
+// Commands the member approved to run on their machine, outside the sandbox
+// (run_on_host, start_docker): installing a runtime the project needs, git
+// with the member's own sign-in, a file outside the project (owner,
+// 2026-10-13: once the member approves, it runs; only what needs the member
+// themselves goes back to them).
+
+// What only the member can do: type their password, sign in interactively.
+const PASSWORD = new Set(['sudo', 'doas', 'su', 'pkexec', 'passwd']);
+const SIGN_IN = [/^gh auth (login|refresh)\b/, /^(npm|pnpm) (login|adduser)\b/, /^yarn npm login\b/, /^docker login\b(?!.*--password-stdin)/, /^az login\b/,
+  /^gcloud auth (login|application-default login)\b/, /^aws (configure\s*$|sso login\b)/, /^(firebase|vercel|wrangler|heroku|netlify) login\b/];
+const WRAPPERS = new Set(['env', 'command', 'exec', 'time', 'nohup']);
+export function memberOnlyReason(command) {
+  for (const part of String(command).split(/&&|\|\||;|\||\n/)) {
+    const words = part.trim().split(/\s+/).filter(Boolean);
+    while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || WRAPPERS.has(words[0]))) words.shift();
+    const name = words[0]?.split('/').pop(), rest = words.join(' ');
+    if (PASSWORD.has(name)) return `${name} needs the member's password`;
+    if (name === 'installer' || name === 'softwareupdate') return `${name} needs the member's password`;
+    if (SIGN_IN.some(rule => rule.test(rest))) return 'an interactive sign-in needs the member';
+  }
+  return null;
+}
+// What a command printed when it stopped to ask for a password or a terminal.
+export const NEEDS_MEMBER = /sudo: a (terminal|password) is required|no tty present|askpass|Password:\s*$|must be run from a terminal|Inappropriate ioctl for device/im;
+
+export const MEMBER_ONLY = reason => `managed-host-member-only: ${reason}. Lệnh này member phải tự làm (nhập mật khẩu máy hoặc đăng nhập tương tác). Dùng ask_user: đưa đúng lệnh hoặc các bước, nói vì sao cần, kèm lựa chọn "Tôi đã làm xong" và "Bỏ qua bước này"; member trả lời xong thì kiểm tra lại và làm tiếp.`;
+
+const TAIL = 50 * 1024;
+const tail = text => text.length > TAIL ? `[… ${text.length - TAIL} characters before …]\n${text.slice(-TAIL)}` : text;
+const shell = () => process.platform === 'darwin' ? '/bin/zsh' : fs.existsSync('/bin/bash') ? '/bin/bash' : '/bin/sh';
+
+// Runs one command as the member, in a login shell (Homebrew, SDKMAN… on
+// PATH as in their Terminal). Nothing of Piagent's own environment (Studio
+// tokens) is passed; no input, so a prompt ends the command instead of hanging.
+export function runHostCommand({ command, cwd, userHome = os.homedir(), timeout = 600, signal, onUpdate, spawnImpl = spawn }) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(Error('Command aborted'));
+    const login = shell(), user = os.userInfo().username;
+    const child = spawnImpl(login, ['-lc', command], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+      env: { HOME: userHome, USER: user, LOGNAME: user, SHELL: login, PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin', LANG: 'en_US.UTF-8', TERM: 'dumb',
+        GIT_TERMINAL_PROMPT: '0', NONINTERACTIVE: '1', HOMEBREW_NO_ENV_HINTS: '1', DEBIAN_FRONTEND: 'noninteractive' } });
+    let output = '', ended = null, last = 0;
+    const kill = why => { ended ??= why; try { process.kill(-child.pid, 'SIGTERM'); } catch {} setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 2000).unref(); };
+    const seconds = Math.min(Math.max(Number(timeout) || 600, 1), 1800);
+    const timer = setTimeout(() => kill(`Command timed out after ${seconds} seconds`), seconds * 1000); timer.unref();
+    const abort = () => kill('Command aborted'); signal?.addEventListener('abort', abort, { once: true });
+    const take = chunk => {
+      output += chunk; if (output.length > 4 * TAIL) output = output.slice(-2 * TAIL);
+      if (onUpdate && Date.now() - last > 250) { last = Date.now(); onUpdate({ content: [{ type: 'text', text: redactedText(tail(output)) }], details: { host: true } }); }
+    };
+    child.stdout.on('data', take); child.stderr.on('data', take);
+    child.on('error', () => { ended ??= 'managed-host-command-failed: the shell did not start'; });
+    child.on('close', code => {
+      clearTimeout(timer); signal?.removeEventListener('abort', abort);
+      const text = redactedText(tail(output.trimEnd()));
+      if (ended) return reject(Error(`${text}${text ? '\n\n' : ''}${ended}`));
+      if (code === 0) return resolve({ content: [{ type: 'text', text: text || '(no output)' }], details: { host: true, exitCode: 0 } });
+      const member = NEEDS_MEMBER.test(output) ? `\n\n${MEMBER_ONLY('the command stopped to ask for a password or a terminal')}` : '';
+      reject(Error(`${text}${member}\n\nCommand exited with code ${code}`));
+    });
+  });
+}

package/packages/piagent-core/managed/language-environment.mjs

@@ -43,8 +43,14 @@ function javaHome(userHome) {
   }
   try {
     const home = execFileSync('/usr/libexec/java_home', [], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: { HOME: userHome, PATH: '/usr/bin:/bin' } }).trim();
-    return existing(home);
-  } catch { return null; }
+    if (existing(home)) return existing(home);
+  } catch { /* none registered with macOS */ }
+  // A JDK macOS does not list: Homebrew's openjdk formulas (keg-only, what
+  // run_on_host installs without a password), SDKMAN's current Java.
+  const kegs = ['/opt/homebrew/opt', '/usr/local/opt'].flatMap(dir => {
+    try { return fs.readdirSync(dir).filter(name => /^openjdk(@\d+)?$/.test(name)).map(name => path.join(dir, name, 'libexec/openjdk.jdk/Contents/Home')); } catch { return []; }
+  }).sort((a, b) => (/openjdk\//.test(b) - /openjdk\//.test(a)) || Number(/@(\d+)/.exec(b)?.[1] ?? 0) - Number(/@(\d+)/.exec(a)?.[1] ?? 0));
+  return [...kegs, path.join(userHome, '.sdkman/candidates/java/current')].map(existing).find(Boolean) ?? null;
 }
 
 // SwiftPM and xcodebuild start sandbox-exec for package manifests and

package/packages/piagent-core/managed/pi-host.mjs

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The Pi host company sessions are qualified on: the package's peer
+// dependency, which piagent-setup installs and CI tests. One place, so moving
+// to a new host is one change (scripts/verify-release-identity.mjs keeps its
+// own copy on purpose, to catch a pin moved by accident).
+export const PI_HOST_VERSION = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).peerDependencies['@earendil-works/pi-coding-agent'];
+
+// A package the host depends on (@earendil-works/pi-ai), found the way Node
+// finds it from the host: in its own node_modules (0.87.1 shipped a
+// shrinkwrap that nested it there), else in a parent's (1.x hoists it).
+export function hostPackage(sdk, name) {
+  for (let dir = sdk; ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, 'node_modules', ...name.split('/'));
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
+    if (path.dirname(dir) === dir) throw new Error(`managed-sdk-dependency-missing: ${name}`);
+  }
+}