@piagent/platform 1.25.0 → 1.26.0

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

@@ -2,6 +2,8 @@ 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),
@@ -15,7 +17,7 @@ const PARAMETERS = { type: 'object', properties: { command: { type: 'string', mi
 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),
@@ -68,6 +70,7 @@ function commandTool(self, kind) {
         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 = kind === 'host' ? await runHostCommand({ command: args.command, cwd: self.cwd, userHome: self.boundary.userHome, timeout: args.timeout, signal, onUpdate })
@@ -110,7 +113,7 @@ function startDockerTool(self, { wait = 180_000, every = 2000, launcher: found =
 
 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')];
+  return [commandTool(self, 'network'), ...(docker ? [commandTool(self, 'docker')] : []), startDockerTool(self, options), commandTool(self, 'host'), ...processTools(self)];
 }
 
 // What the system prompt says about services and what the sandbox blocks: it

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/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}`);
+  }
+}

package/packages/piagent-core/managed/sandbox-diagnostic.mjs

@@ -11,6 +11,8 @@ const OFFLINE = /ENOTFOUND|EAI_AGAIN|Could not resolve host|getaddrinfo|npm erro
 // name that does not resolve is the machine's network, not the sandbox.
 // `isolated`: a proxy listens on this Mac, so without approval a command does
 // not reach this Mac's own servers either (tool-boundary.mjs).
+// Node's fetch reports that refusal as a bare "fetch failed" when a test
+// runner prints the error without its cause (node --test on Node 22).
 // `docker`: the command ran with the Docker engine (run_with_docker);
 // `engine`: one is there for run_with_docker, but this command ran without it.
 const DOCKER_DAEMON = /Cannot connect to the Docker daemon|connect to the docker API|docker\.sock|Is the docker daemon running|Could not find a valid Docker environment/i;
@@ -18,7 +20,7 @@ const DOCKER_DAEMON = /Cannot connect to the Docker daemon|connect to the docker
 // version the project asks for).
 const TOOLCHAIN = /Unable to locate a Java Runtime|No Java runtime present|JAVA_HOME is not (?:set|defined correctly)|(?:^|\n)\S*?(?:ba|z)?sh: (?:line \d+: )?[\w.+-]+: command not found|zsh: command not found: [\w.+-]+|xcrun: error: (?:unable to find utility|invalid active developer path)|env: '?[\w.+-]+'?: No such file or directory|Unsupported class file major version|invalid target release: \d+|release version \d+ not supported|requires? (?:at least )?Java \d+|The engine "node" is incompatible|Unsupported engine/i;
 // The member's sign-in, which the sandbox does not have.
-const SIGN_IN = /could not read (?:Username|Password) for|terminal prompts disabled|Authentication failed for|Permission denied \(publickey|Host key verification failed|\bENEEDAUTH\b|\bE401\b|\b401 Unauthorized|requires authentication|denied: requested access to the resource is denied|pull access denied/i;
+const SIGN_IN = /could not read (?:Username|Password) for|terminal prompts disabled|Authentication failed for|Permission denied \(publickey|Host key verification failed|not logged into any GitHub hosts|please run:\s+gh auth login|Could not open a connection to your authentication agent|\bENEEDAUTH\b|\bE401\b|\b401 Unauthorized|requires authentication|denied: requested access to the resource is denied|pull access denied/i;
 
 export function sandboxDiagnostic(message, { network = false, isolated = false, docker = false, engine = false } = {}) {
   const text=String(message);
@@ -26,7 +28,7 @@ export function sandboxDiagnostic(message, { network = false, isolated = false,
   if(!docker&&DOCKER_DAEMON.test(text))return (engine?'managed-docker-blocked: Lệnh bash thường không dùng được Docker trong chế độ công ty. Lệnh docker, docker compose, hoặc test cần Docker (Testcontainers) chạy qua run_with_docker để người dùng duyệt đúng lệnh đó.\n':'managed-docker-unavailable: Docker engine trên máy chưa chạy. Gọi start_docker để xin member duyệt mở Docker, rồi chạy lệnh bằng run_with_docker.\n')+text;
   if(TOOLCHAIN.test(text))return 'managed-toolchain-missing: Máy thiếu runtime/công cụ mà lệnh cần, hoặc sai version project yêu cầu. Đừng dừng ở đây: xem project cần gì (pom.xml, build.gradle, .nvmrc, .tool-versions, package.json engines…) rồi dùng run_on_host để xin member duyệt cài trên máy (ví dụ brew install openjdk@21, brew install node@22, sdk install java 21-tem), sau đó chạy lại lệnh. Nếu project build được trong Docker thì có thể đề xuất run_with_docker. Trình cài cần mật khẩu (sudo, file .pkg) thì hỏi member bằng ask_user.\n'+text;
   if(SIGN_IN.test(text))return 'managed-credentials-unavailable: Lệnh cần tài khoản đăng nhập của member (git qua HTTPS/SSH, registry riêng, image riêng), sandbox không có. git fetch dùng fetch_origin; git pull, git push, cài từ registry riêng hoặc pull image riêng thì dùng run_on_host để member duyệt chạy đúng lệnh đó trên máy bằng tài khoản của họ.\n'+text;
-  if(isolated&&!/CONNECT tunnel failed|tunneling socket|statusCode=403|response 403/i.test(text)&&/ECONNREFUSED|EPERM|connect|Connection refused|could not connect/i.test(text))return 'managed-loopback-blocked: Máy đang chạy một proxy cục bộ, nên lệnh không có mạng cũng không được kết nối tới server trên localhost (proxy có thể đưa lệnh ra internet). Test cần server hoặc database trên localhost: dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
+  if(isolated&&!/CONNECT tunnel failed|tunneling socket|statusCode=403|response 403/i.test(text)&&/ECONNREFUSED|EPERM|connect|Connection refused|could not connect|fetch failed/i.test(text))return 'managed-loopback-blocked: Máy đang chạy một proxy cục bộ, nên lệnh không có mạng cũng không được kết nối tới server trên localhost (proxy có thể đưa lệnh ra internet). Test cần server hoặc database trên localhost: dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
   if(network&&!DENIAL.test(text)&&OFFLINE.test(text))return 'managed-network-unreachable: Lệnh đã được duyệt và chạy có mạng nhưng không tới được host (máy offline, cần VPN/proxy công ty, hoặc sai tên host). Hỏi member bằng ask_user, kèm lựa chọn "Đã kết nối mạng/VPN, chạy lại" và "Bỏ qua bước này"; member trả lời xong thì làm theo.\n'+text;
   if(!DENIAL.test(text)&&OFFLINE.test(text))return 'managed-network-blocked: Lệnh bash thường không có mạng trong chế độ công ty. Nếu lệnh thật sự cần mạng (cài package, tải dữ liệu), dùng run_with_network để người dùng duyệt đúng lệnh đó.\n'+text;
   if(!DENIAL.test(text))return text;

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

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { ManagedToolBoundary } from './tool-boundary.mjs';
+import { ManagedToolBoundary, PI_HOST_VERSION, hostPackage } from './tool-boundary.mjs';
 import { ensureSearchTools, trustSystemCertificates } from './toolchain.mjs';
 import { inlineExtensions, managedResourceLoader, projectInstructions } from './resource-loader.mjs';
 import { fetchPublicPage, fetchLimits } from './web-fetch.mjs';
@@ -91,10 +91,10 @@ export class ManagedSession {
   // the conversation enrolls again before its next run.
   static async create({ sdkRoot, cwd, origin, broker, protectedRoots = [], agentDir, sessionManager, renewBroker = null, bindingRevision = null, terminalExtensions = [] }) {
     const sdk = fs.realpathSync(sdkRoot);
-    if (JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'))).version !== '0.87.1') throw Error('managed-sdk-version-unqualified');
+    if (JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'))).version !== PI_HOST_VERSION) throw Error('managed-sdk-version-unqualified');
     await trustSystemCertificates();
     const api = await import(pathToFileURL(path.join(sdk, 'dist/index.js')));
-    const ai = await import(pathToFileURL(path.join(sdk, 'node_modules/@earendil-works/pi-ai/dist/index.js')));
+    const ai = await import(pathToFileURL(path.join(hostPackage(sdk, '@earendil-works/pi-ai'), 'dist/index.js')));
     const manifest = usable(await patiently(() => broker.request('config'), 3));
     const self = new ManagedSession(); Object.assign(self, { sdk, cwd: fs.realpathSync(cwd), origin: safeOrigin(origin), broker, api, ai, manifest, protectedRoots, helpers: new Map(), helperCalls: new Map(), ownPaths: new Set(), listeners: new Set(), capacityWaits: new Set(), routes: new WeakMap(), grant: null,
       renewBroker, bindingRevision, bindingSeen: bindingRevision?.() ?? null, preflight: null, blocked: null });

package/packages/piagent-core/managed/tool-boundary.mjs

@@ -8,6 +8,8 @@ import { createHash, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { developerLicense, developerTools, managedGit, searchToolPath, userToolchains } from './toolchain.mjs';
 import { languageEnvironment } from './language-environment.mjs';
+import { PI_HOST_VERSION, hostPackage } from './pi-host.mjs';
+export { PI_HOST_VERSION, hostPackage };
 import { containerEngine, dockerCli, engineEnvironment } from './container-engine.mjs';
 import { DEFAULT_DOMAINS, PackageProxy, mavenSettings, memberDomains, proxyEnvironment } from './package-proxy.mjs';
 import { BWRAP, bubblewrapArgs, credentialFiles, referenceFolders } from './linux-sandbox.mjs';
@@ -205,8 +207,8 @@ export class ManagedToolBoundary {
     this.runtimeRoot = fs.realpathSync(path.dirname(workerPath));
     this.sdkPath = path.join(this.sdkRoot, 'dist/index.js');
     this.git = managedGit();
-    if (JSON.parse(fs.readFileSync(path.join(this.sdkRoot, 'package.json'), 'utf8')).version !== '0.87.1') throw new Error('managed-sdk-version-unqualified');
-    const workerModules = ['search-fallback.mjs', 'sandbox-diagnostic.mjs'].map(name => path.join(this.runtimeRoot, name));
+    if (JSON.parse(fs.readFileSync(path.join(this.sdkRoot, 'package.json'), 'utf8')).version !== PI_HOST_VERSION) throw new Error('managed-sdk-version-unqualified');
+    const workerModules = ['search-fallback.mjs', 'sandbox-diagnostic.mjs', 'ts-diagnostics-server.mjs'].map(name => path.join(this.runtimeRoot, name));
     this.pins = new Map([this.node, this.git, workerPath, ...workerModules, this.sdkPath].map(file => [file, hash(file)]));
     const userHome = fs.realpathSync(home ?? os.homedir());
     if ([userHome, '/', this.sdkRoot, this.runtimeRoot].includes(this.cwd)
@@ -270,7 +272,10 @@ export class ManagedToolBoundary {
     // The Docker engine, for commands the member approves (run_with_docker).
     this.engine = readOnly ? null : containerEngine({ userHome });
     this.dockerCli = readOnly ? null : this.engine?.cli ?? dockerCli();
-    const base = this.base = { cwd: this.cwd, sdkRoot: this.sdkRoot, runtimeRoot: this.runtimeRoot, temporary: this.temporary, node: this.node,
+    // What the host loads: its own folder, and the node_modules its
+    // dependencies were hoisted to when they are not nested in it (Pi 1.x).
+    const ai = hostPackage(this.sdkRoot, '@earendil-works/pi-ai'), hostRoot = inside(fs.realpathSync(ai), this.sdkRoot) ? this.sdkRoot : fs.realpathSync(path.dirname(path.dirname(ai)));
+    const base = this.base = { cwd: this.cwd, sdkRoot: hostRoot, runtimeRoot: this.runtimeRoot, temporary: this.temporary, node: this.node,
       denied: narrowed, readOnly, repository, gitDirs, toolchains: [...toolchains.roots, ...languages.readRoots], developer: developer.roots,
       browsers: browsers ? [browsers] : [], skills, caches: languages.writeRoots, license: developerLicense() };
     if (this.linux) this.linuxBase = { ...base, toolchains: [...base.toolchains, ...base.browsers], references: this.references, empty: this.empty, engineRoots: this.engine?.readRoots ?? [] };
@@ -436,28 +441,50 @@ export class ManagedToolBoundary {
   async stopStrays() {
     // On Linux a command's processes end with it (its own PID namespace).
     if (this.#children.size || this.linux) return 0;
-    const marker = `PIAGENT_TOOL_SCOPE=${this.scope}`, find = () => {
-      try {
-        return execFileSync('/bin/ps', ['-axwwE', '-o', 'pid=,command='], { encoding: 'utf8', maxBuffer: 64 << 20, timeout: 5000 }).split('\n')
-          .filter(row => row.includes(marker)).map(row => Number(row.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid);
-      } catch { return []; }
-    };
-    const strays = find();
-    for (const pid of strays) try { process.kill(pid, 'SIGTERM'); } catch {}
-    for (let waited = 0; strays.length && waited < 2000; waited += 100) {
-      await new Promise(resolve => setTimeout(resolve, 100));
-      if (!find().length) break;
-    }
-    for (const pid of find()) try { process.kill(pid, 'SIGKILL'); } catch {}
-    return strays.length;
+    return stopMarked(`PIAGENT_TOOL_SCOPE=${this.scope}`);
+  }
+  // A process the agent keeps running across turns (background-process.mjs):
+  // the plain command sandbox and environment, marked as this conversation's
+  // background process instead of the turn's, so stopStrays leaves it.
+  async spawnBackground(command, key) { return this.spawnSandboxed(['/bin/bash', '-c', command], key); }
+  // `argv` in the plain command sandbox; stdin 'pipe' for a process that
+  // answers requests (ts-diagnostics.mjs).
+  async spawnSandboxed(argv, key, { stdin = 'ignore' } = {}) {
+    if (this.#closed || this.linux || !this.allowed.includes('bash') || !/^[0-9a-f-]{36}$/.test(key)) throw new Error('managed-tool-unavailable');
+    for (const [file, digest] of this.pins) if (hash(file) !== digest) throw new Error('managed-runtime-changed');
+    if (Date.now() - this.proxyCheck.at > 5000) this.proxyCheck = { at: Date.now(), listening: localProxyListening(this.proxyPorts) };
+    const isolated = await this.proxyCheck.listening, { PIAGENT_TOOL_SCOPE: _turn, ...env } = this.environment.offline;
+    const child = spawn('/usr/bin/sandbox-exec', ['-p', isolated ? this.isolatedProfile : this.profile, ...argv],
+      { cwd: this.cwd, detached: true, stdio: [stdin, 'pipe', 'pipe'], env: { ...env, PIAGENT_PROCESS_SCOPE: `${this.scope}:${key}` } });
+    return { child, isolated };
   }
+  stopBackground(key) { return stopMarked(`PIAGENT_PROCESS_SCOPE=${this.scope}:${key}`); }
   async dispose() {
     this.#closed = true;
     const stopping = [...this.#children].map(child => new Promise(resolve => { child.once('close', resolve); child.managedCancel(); }));
     await Promise.all(stopping); await this.#tail;
-    await this.stopStrays();
+    await this.background?.dispose(); await this.stopStrays(); if (!this.linux) await stopMarked(`PIAGENT_PROCESS_SCOPE=${this.scope}:`);
     await this.proxyReady; await this.proxy?.close().catch(() => {});
     if (this.proxySocket) fs.rmSync(this.proxySocket, { force: true });
     fs.rmSync(this.temporary, { recursive: true, force: true });
   }
 }
+
+// Stops every process whose environment carries `marker` (ps -E), then
+// whatever is left after two seconds.
+async function stopMarked(marker) {
+  const find = () => {
+    try {
+      return execFileSync('/bin/ps', ['-axwwE', '-o', 'pid=,command='], { encoding: 'utf8', maxBuffer: 64 << 20, timeout: 5000 }).split('\n')
+        .filter(row => row.includes(marker)).map(row => Number(row.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid);
+    } catch { return []; }
+  };
+  const found = find();
+  for (const pid of found) try { process.kill(pid, 'SIGTERM'); } catch {}
+  for (let waited = 0; found.length && waited < 2000; waited += 100) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    if (!find().length) break;
+  }
+  for (const pid of find()) try { process.kill(pid, 'SIGKILL'); } catch {}
+  return found.length;
+}

package/packages/piagent-core/managed/tool-worker.mjs

@@ -43,7 +43,9 @@ input.on('line', async line => {
       : await factories[message.name](cwd, options).execute('managed-tool', message.args, controller.signal,
         update => emit({ update }), { cwd, model: message.model });
     // Successful output is returned verbatim; the sandbox note is only added to
-    // failures (Pi tools throw on denial and on a non-zero shell exit).
+    // failures. Pi 0.87 throws on denial and on a non-zero shell exit; Pi 1.x
+    // returns an isError result with the same text instead: read as the throw.
+    if (result?.isError === true) throw new Error((result.content ?? []).filter(part => part.type === 'text').map(part => part.text).join('\n') || 'managed-worker-failed');
     emit({ result });
   } catch (error) { emit({ error: sandboxDiagnostic(error instanceof Error ? error.message : 'managed-worker-failed', { network, isolated, docker, engine }) }); }
   finally { if (active) { input.close(); process.stdin.destroy(); } }

package/packages/piagent-core/managed/ts-diagnostics-server.mjs

@@ -0,0 +1,102 @@
+// Runs inside the command sandbox (ts-diagnostics.mjs starts it): the
+// project's own TypeScript reports the errors of one file, one request per
+// line on stdin ({id, file}), one answer per line on stdout. TypeScript 5 and
+// 6 keep a language service per tsconfig/jsconfig; TypeScript 7 (the native
+// compiler, which has no such JavaScript API) checks the project with its own
+// tsc, fast enough to run on each change.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+
+const [cwd] = process.argv.slice(2);
+const services = new Map();
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); };
+const version = file => { try { const stat = fs.statSync(file); return `${stat.mtimeMs}:${stat.size}`; } catch { return '0'; } };
+
+// The nearest tsconfig.json, else jsconfig.json, inside the project.
+function configFor(file) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    for (let dir = path.dirname(file); inside(cwd, dir); dir = path.dirname(dir)) {
+      if (fs.existsSync(path.join(dir, name))) return path.join(dir, name);
+      if (dir === cwd) break;
+    }
+  }
+  return null;
+}
+
+function serviceFor(file) {
+  let manifest;
+  try { manifest = createRequire(file).resolve('typescript/package.json'); } catch { return { reason: 'no-typescript' }; }
+  const config = configFor(file);
+  if (!config) return { reason: 'no-config' };
+  if (services.has(config)) return services.get(config);
+  const major = Number.parseInt(JSON.parse(fs.readFileSync(manifest, 'utf8')).version, 10);
+  if (major >= 7) {
+    const entry = { native: path.join(path.dirname(manifest), 'bin/tsc'), config };
+    services.set(config, entry); return entry;
+  }
+  const ts = createRequire(file)(path.dirname(manifest));
+  const parsed = ts.getParsedCommandLineOfConfigFile(config, {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} });
+  if (!parsed) return { reason: 'no-config' };
+  const extra = new Set();
+  const host = {
+    getScriptFileNames: () => [...new Set([...parsed.fileNames, ...extra])],
+    getScriptVersion: version,
+    getScriptSnapshot: name => fs.existsSync(name) ? ts.ScriptSnapshot.fromString(fs.readFileSync(name, 'utf8')) : undefined,
+    getCurrentDirectory: () => path.dirname(config),
+    getCompilationSettings: () => parsed.options,
+    getDefaultLibFileName: options => ts.getDefaultLibFilePath(options),
+    fileExists: ts.sys.fileExists, readFile: ts.sys.readFile, readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists, getDirectories: ts.sys.getDirectories,
+  };
+  const entry = { ts, config, extra, service: ts.createLanguageService(host, ts.createDocumentRegistry()) };
+  services.set(config, entry);
+  return entry;
+}
+
+// tsc --pretty false prints "file(line,col): error TS1234: message".
+function nativeDiagnostics({ native, config }, file) {
+  let output;
+  try { output = execFileSync(process.execPath, [native, '--noEmit', '--pretty', 'false', '-p', config], { cwd: path.dirname(config), encoding: 'utf8', timeout: 30000, maxBuffer: 16 << 20, stdio: ['ignore', 'pipe', 'pipe'] }); }
+  catch (error) { output = String(error.stdout ?? ''); }
+  const found = [], elsewhere = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(/^(.+?)\((\d+),(\d+)\): error TS(\d+): (.*)$/);
+    if (!match) continue;
+    const at = path.resolve(path.dirname(config), match[1]), item = { line: Number(match[2]), column: Number(match[3]), code: Number(match[4]), message: match[5].slice(0, 400) };
+    if (at === file) found.push(item); else elsewhere.push({ ...item, file: path.relative(cwd, at) });
+  }
+  // A syntax error anywhere stops tsc before it checks types: say so rather
+  // than let silence read as a clean file.
+  const syntax = elsewhere.filter(item => item.code >= 1000 && item.code < 2000);
+  return found.length || !syntax.length ? { diagnostics: found } : { diagnostics: [], uncheckedBecause: syntax.slice(0, 3) };
+}
+
+function diagnostics(file) {
+  const entry = serviceFor(file);
+  if (entry.reason) return { reason: entry.reason };
+  if (entry.native) return { config: path.relative(cwd, entry.config), ...nativeDiagnostics(entry, file) };
+  const { ts, service, extra, config } = entry;
+  extra.add(file);
+  const found = [...service.getSyntacticDiagnostics(file), ...service.getSemanticDiagnostics(file)]
+    .filter(d => d.category === ts.DiagnosticCategory.Error)
+    .map(d => {
+      const at = d.file && d.start !== undefined ? d.file.getLineAndCharacterOfPosition(d.start) : { line: 0, character: 0 };
+      return { line: at.line + 1, column: at.character + 1, code: d.code, message: ts.flattenDiagnosticMessageText(d.messageText, ' ').slice(0, 400) };
+    });
+  return { config: path.relative(cwd, config), diagnostics: found };
+}
+
+const input = createInterface({ input: process.stdin });
+input.on('line', line => {
+  let id = null;
+  try {
+    const request = JSON.parse(line); id = request.id;
+    const file = path.resolve(cwd, String(request.file));
+    if (!inside(cwd, file)) throw new Error('outside the project');
+    process.stdout.write(JSON.stringify({ id, ...diagnostics(file) }) + '\n');
+  } catch (error) { process.stdout.write(JSON.stringify({ id, error: String(error?.message ?? error).slice(0, 300) }) + '\n'); }
+});
+input.on('close', () => process.exit(0));

package/packages/piagent-core/managed/ts-diagnostics.mjs

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// TypeScript and JavaScript errors of a file right after the agent writes or
+// edits it, from the project's own TypeScript (ts-diagnostics-server.mjs, in
+// the command sandbox). A file without errors adds nothing; a project without
+// TypeScript or a tsconfig/jsconfig adds nothing; a slow first answer (a large
+// program loading) adds nothing rather than holding the edit.
+const SERVER = fileURLToPath(new URL('./ts-diagnostics-server.mjs', import.meta.url));
+const EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+const SHOWN = 10, RESTARTS = 3;
+
+export class TsDiagnostics {
+  #child = null; #pending = new Map(); #next = 1; #buffer = ''; #starts = 0; #off = false;
+  constructor(boundary, { timeout = 8000 } = {}) { Object.assign(this, { boundary, timeout }); }
+  applies(file) {
+    return !this.#off && process.platform === 'darwin' && typeof file === 'string' && EXTENSIONS.has(path.extname(file)) && !/(^|[\\/])node_modules[\\/]/.test(file);
+  }
+  async #server() {
+    if (this.#child) return this.#child;
+    if (this.#starts >= RESTARTS) { this.#off = true; return null; }
+    this.#starts += 1;
+    const { child } = await this.boundary.spawnSandboxed([this.boundary.node, SERVER, this.boundary.cwd], randomUUID(), { stdin: 'pipe' });
+    child.stdout.on('data', chunk => {
+      this.#buffer += chunk.toString('utf8');
+      for (let at; (at = this.#buffer.indexOf('\n')) >= 0;) {
+        const line = this.#buffer.slice(0, at); this.#buffer = this.#buffer.slice(at + 1);
+        try { const answer = JSON.parse(line); this.#pending.get(answer.id)?.(answer); } catch { /* not an answer */ }
+      }
+    });
+    child.stderr.on('data', () => {});
+    child.stdin.on('error', () => {});
+    child.on('close', () => { if (this.#child === child) this.#child = null; for (const resolve of this.#pending.values()) resolve(null); this.#pending.clear(); });
+    this.#child = child;
+    return child;
+  }
+  // A note for the agent, or '' when there is nothing to say.
+  async check(file) {
+    if (!this.applies(file)) return '';
+    try {
+      const child = await this.#server();
+      if (!child) return '';
+      const id = this.#next++;
+      const answer = await new Promise(resolve => {
+        const timer = setTimeout(() => { this.#pending.delete(id); resolve(null); }, this.timeout); timer.unref?.();
+        this.#pending.set(id, value => { clearTimeout(timer); this.#pending.delete(id); resolve(value); });
+        child.stdin.write(JSON.stringify({ id, file }) + '\n');
+      });
+      const found = answer?.diagnostics, name = path.relative(this.boundary.cwd, path.resolve(this.boundary.cwd, file));
+      if (Array.isArray(answer?.uncheckedBecause) && answer.uncheckedBecause.length)
+        return `\n[TypeScript, ${answer.config}] ${name} was not type-checked: tsc stops at syntax errors elsewhere in the project:\n${answer.uncheckedBecause.map(d => `${d.file}:${d.line}:${d.column} TS${d.code} ${d.message}`).join('\n')}`;
+      if (!Array.isArray(found) || !found.length) return '';
+      const lines = found.slice(0, SHOWN).map(d => `${name}:${d.line}:${d.column} TS${d.code} ${d.message}`);
+      return `\n[TypeScript, ${answer.config}] ${found.length} error(s) in ${name} after this change:\n${lines.join('\n')}${found.length > SHOWN ? `\n… and ${found.length - SHOWN} more` : ''}`;
+    } catch { return ''; }
+  }
+  dispose() { this.#off = true; try { this.#child?.stdin.end(); } catch { /* gone */ } }
+}