@piagent/platform 1.7.1 → 1.9.0

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

@@ -0,0 +1,243 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { developerTools, managedGit, searchToolPath, userToolchains } from './toolchain.mjs';
+
+const TOOL_NAMES = Object.freeze(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls']);
+const MAX_WIRE_BYTES = 12 * 1024 * 1024;
+const workerPath = fileURLToPath(new URL('./tool-worker.mjs', import.meta.url));
+const hash = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+function literal(value) {
+  if (typeof value !== 'string' || !path.isAbsolute(value) || /[\x00-\x1f\x7f]/.test(value)) throw new Error('managed-path-invalid');
+  return JSON.stringify(value);
+}
+function inside(file, root) { return file === root || file.startsWith(root + path.sep); }
+
+export function managedSeatbelt({ cwd, sdkRoot, runtimeRoot, temporary, node, denied = [], readOnly = false, repository = [], gitDirs = [], toolchains = [], developer = [], network = false }) {
+  // Default-deny protects Keychain/SSH agent/Watch IPC and process inspection.
+  // System libraries/toolchains are read-only. Writes stay in this project and
+  // a fresh temporary directory. No network exception or unsandboxed fallback.
+  // A project inside a larger repository reads that repository (monorepo)
+  // and, when writable, its git directories so commits work. Also readable,
+  // as on any Mac: installer-based Python/JDKs, the Rosetta runtime (x86_64
+  // tools on Apple Silicon) and the time zone database.
+  const system = ['/Library/Frameworks', '/Library/Java', '/Library/Apple', '/private/var/db/oah', '/private/var/db/timezone'];
+  const readRoots = ['/System', '/usr', '/bin', '/sbin', '/Library/Developer', '/Applications/Xcode.app', '/opt/homebrew', ...system, ...developer, sdkRoot, runtimeRoot, cwd, temporary, ...repository, ...gitDirs, ...toolchains];
+  const filters = readRoots.map(root => `(subpath ${literal(root)})`).join(' ');
+  const writeRoots = [temporary, ...(!readOnly ? [cwd, ...gitDirs] : [])];
+  // Signals reach only processes of this sandbox: a search stops ripgrep at
+  // its limit and a cancelled command stops its children, while nothing
+  // outside (Agent Watch, the member's apps) can be signalled.
+  return `(version 1)
+(deny default)
+(allow process-fork process-exec)
+(allow signal (target same-sandbox))
+(allow sysctl-read)
+(allow mach-lookup (global-name "com.apple.system.logger") (global-name "com.apple.system.opendirectoryd"))
+(allow file-read-metadata)
+(allow file-read* (literal "/") ${filters} (literal ${literal(node)}) (subpath "/private/etc") (subpath "/dev"))
+(allow file-write* ${writeRoots.map(root => `(subpath ${literal(root)})`).join(' ')} (literal "/dev/null") (literal "/dev/tty"))
+${network ? `(allow network-outbound (remote ip))
+(allow network-outbound (literal "/private/var/run/mDNSResponder"))
+(allow system-socket)
+(allow mach-lookup (global-name "com.apple.dnssd.service") (global-name "com.apple.trustd.agent") (global-name "com.apple.SystemConfiguration.configd"))` : ''}
+${denied.map(root => `(deny file-read* file-write* (subpath ${literal(root)}))`).join('\n')}
+(deny file-read* file-write* (regex #"(^|/)(\\.env([./]|$)|auth\\.json$|credentials([./]|$)|\\.npmrc$|\\.netrc$)"))
+`;
+}
+
+// Toolchains from the pinned node/git and Homebrew, compilers and SDK; the
+// git identity this project gets on the user's machine (name and email only)
+// so commits work. Without network, package managers fail fast instead of
+// retrying for minutes.
+function toolEnvironment({ git, node, home, temporary, toolchains, developer, identity, scope }) {
+  const PATH = [...new Set([path.dirname(node), ...toolchains.bins, '/opt/homebrew/bin', '/opt/homebrew/sbin', '/usr/local/bin', ...developer.bins, path.dirname(git), '/usr/bin', '/bin', '/usr/sbin', '/sbin'])].join(':');
+  const network = { ...toolchains.env, ...developer.env, PATH, HOME: home, TMPDIR: temporary, PIAGENT_TOOL_SCOPE: scope, LANG: 'en_US.UTF-8', LC_ALL: 'en_US.UTF-8', RIPGREP_CONFIG_PATH: path.join(home, '.ripgreprc'),
+    ...(identity ? { GIT_AUTHOR_NAME: identity.name, GIT_AUTHOR_EMAIL: identity.email, GIT_COMMITTER_NAME: identity.name, GIT_COMMITTER_EMAIL: identity.email } : {}) };
+  return { network, offline: { ...network, npm_config_fetch_retries: '0', npm_config_fetch_timeout: '5000', PIP_RETRIES: '0', PIP_TIMEOUT: '5' } };
+}
+// Effective config for this project, as the user's own git would see it:
+// global and XDG files, includeIf (e.g. a work email for ~/work) and the
+// repository's own settings. `git config --get` runs no hooks or helpers.
+function gitIdentity(git, cwd) {
+  const read = key => { try { return execFileSync(git, ['-C', cwd, 'config', '--get', key], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: { HOME: os.homedir(), PATH: '/usr/bin:/bin' } }).trim(); } catch { return ''; } };
+  const name = read('user.name'), email = read('user.email');
+  return name && email && name.length <= 200 && email.length <= 200 && !/[\x00-\x1f]/.test(name + email) ? { name, email } : null;
+}
+// The trusted runtime resolves the repository before any tool runs.
+function repositoryRoots(git, cwd, temporary) {
+  try {
+    const [top, gitDir, commonDir] = execFileSync(git, ['-C', cwd, 'rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-common-dir'],
+      { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'], env: { HOME: temporary, PATH: '/usr/bin:/bin', GIT_CONFIG_NOSYSTEM: '1' } }).trim().split('\n');
+    return { top: fs.realpathSync(top), gitDir: fs.realpathSync(gitDir), commonDir: fs.realpathSync(path.resolve(cwd, commonDir)) };
+  } catch { return null; }
+}
+// Pi's grep/find need ripgrep and fd and would download them, which the
+// sandbox forbids. Copy installed binaries into the sandbox home instead.
+function provisionSearchTools(home, userHome) {
+  // Credential files are unreadable here; ripgrep skips them instead of
+  // failing the whole search with a permission error.
+  fs.writeFileSync(path.join(home, '.ripgreprc'), ['.env', '.env.*', '.env/**', 'auth.json', 'credentials', 'credentials.*', 'credentials/**', '.npmrc', '.netrc']
+    .map(glob => `--glob=!${glob}`).join('\n') + '\n', { mode: 0o600 });
+  const bin = path.join(home, '.pi/agent/bin');
+  fs.mkdirSync(bin, { recursive: true, mode: 0o700 });
+  // Without a copy here the worker uses the built-in search (search-fallback.mjs).
+  for (const name of ['rg', 'fd']) {
+    const source = searchToolPath(name, userHome);
+    if (source) { fs.copyFileSync(source, path.join(bin, name)); fs.chmodSync(path.join(bin, name), 0o755); }
+  }
+}
+
+export class ManagedToolBoundary {
+  #tail = Promise.resolve();
+  #children = new Set();
+  #closed = false;
+  constructor({ cwd, sdkRoot, protectedRoots = [], readOnly = false, node = process.execPath, identity, userHome: home, searchTools = true }) {
+    if (process.platform !== 'darwin') throw new Error('managed-sandbox-unavailable');
+    this.cwd = fs.realpathSync(cwd); this.sdkRoot = fs.realpathSync(sdkRoot);
+    this.node = fs.realpathSync(node);
+    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));
+    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)
+      || [this.sdkRoot,this.runtimeRoot,this.node,this.git,...['/opt/homebrew/bin/gh','/usr/local/bin/gh'].filter(p=>fs.existsSync(p)).map(p=>fs.realpathSync(p))].some(p=>inside(p,this.cwd))) throw new Error('managed-project-overlaps-runtime');
+    this.temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'piagent-tools-')));
+    fs.chmodSync(this.temporary, 0o700);
+    this.home = path.join(this.temporary, 'home'); fs.mkdirSync(this.home, { mode: 0o700 });
+    const denied = [path.join(userHome, '.ssh'), path.join(userHome, '.aws'), path.join(userHome, '.config'),
+      path.join(userHome, '.pi'), path.join(userHome, '.codex'), path.join(userHome, '.claude'),
+      path.join(userHome, 'Library/Keychains'), path.join(userHome, 'Library/Application Support/AgentWatch'),
+      ...protectedRoots.map(p => path.resolve(p))];
+    // A pinned SDK may itself be installed under ~/.pi; grant that code only,
+    // while keeping the adjacent personal auth/config subtree inaccessible.
+    const narrowed = denied.filter(root => !inside(this.sdkRoot, root));
+    if (inside(this.sdkRoot, path.join(userHome, '.pi'))) narrowed.push(path.join(userHome, '.pi/agent'));
+    const repo = repositoryRoots(this.git, this.cwd, this.temporary);
+    const allowedRoot = root => root !== '/' && !inside(userHome, root) && !inside(this.sdkRoot, root) && !inside(this.runtimeRoot, root);
+    const repository = repo && repo.top !== this.cwd && allowedRoot(repo.top) ? [repo.top] : [];
+    this.repositoryTop = repository[0] ?? this.cwd;
+    // A repository above the home folder (a dotfiles repo) is never opened:
+    // neither read as a monorepo nor writable through its git directory.
+    const gitDirs = repo && (repo.top === this.cwd || allowedRoot(repo.top)) ? [...new Set([repo.gitDir, repo.commonDir])].filter(dir => !inside(dir, this.cwd) && allowedRoot(dir)) : [];
+    const toolchains = userToolchains(userHome, this.node), developer = developerTools();
+    const base = { cwd: this.cwd, sdkRoot: this.sdkRoot, runtimeRoot: this.runtimeRoot, temporary: this.temporary, node: this.node,
+      denied: narrowed, readOnly, repository, gitDirs, toolchains: toolchains.roots, developer: developer.roots };
+    this.profile = managedSeatbelt(base);
+    // Only for commands the user approved (run_with_network); credentials stay denied.
+    this.networkProfile = readOnly ? null : managedSeatbelt({ ...base, network: true });
+    // Every process a command starts carries this marker, also one it detaches.
+    this.scope = randomUUID();
+    this.environment = toolEnvironment({ git: this.git, node: this.node, home: this.home, temporary: this.temporary, toolchains, developer, scope: this.scope,
+      identity: identity !== undefined ? identity : gitIdentity(this.git, this.cwd) });
+    if (searchTools) provisionSearchTools(this.home, userHome);
+    else fs.writeFileSync(path.join(this.home, '.ripgreprc'), '', { mode: 0o600 });
+    this.allowed = readOnly ? TOOL_NAMES.filter(name => !['write', 'edit', 'bash'].includes(name)) : [...TOOL_NAMES];
+  }
+  tools(api) {
+    const factories = { read: api.createReadToolDefinition, write: api.createWriteToolDefinition,
+      edit: api.createEditToolDefinition, bash: api.createBashToolDefinition,
+      grep: api.createGrepToolDefinition, find: api.createFindToolDefinition, ls: api.createLsToolDefinition };
+    return this.allowed.map(name => ({ ...factories[name](this.cwd), execute: (_id, args, signal, onUpdate, context) => {
+      // One queue spans read and all mutations so two concurrent edit requests
+      // observe a deterministic order. Helpers use separate read-only workers.
+      const run = this.#tail.then(() => this.invoke(name, args, signal, onUpdate, context?.model));
+      this.#tail = run.catch(() => {}); return run;
+    } }));
+  }
+  async invoke(name, args, signal, onUpdate, model, { network = false } = {}) {
+    if (this.#closed || !this.allowed.includes(name) || network && (name !== 'bash' || !this.networkProfile)) throw new Error('managed-tool-unavailable');
+    if (signal?.aborted) throw new Error('managed-tool-cancelled');
+    for (const [file, digest] of this.pins) if (hash(file) !== digest) throw new Error('managed-runtime-changed');
+    const message = JSON.stringify({ name, args, ...(network ? { network: true } : {}), model: model ? { input: model.input, inputLimits: model.inputLimits } : undefined }) + '\n';
+    if (Buffer.byteLength(message) > MAX_WIRE_BYTES) throw new Error('managed-tool-input-too-large');
+    return await new Promise((resolve, reject) => {
+      const child = spawn('/usr/bin/sandbox-exec', ['-p', network ? this.networkProfile : this.profile, this.node, workerPath, this.sdkPath, this.cwd], {
+        cwd: this.cwd, detached: true, stdio: ['pipe', 'pipe', 'pipe'],
+        env: network ? this.environment.network : this.environment.offline,
+      });
+      this.#children.add(child);
+      const decoder = new StringDecoder('utf8');
+      let pending = '', bytes = 0, result, failure, terminated = false, hardStop;
+      const terminate = () => {
+        if (terminated) return; terminated = true;
+        child.stdin.write('{"cancel":true}\n');
+        // bash descendants may use separate process groups. Native bash abort
+        // handles those first; a hard stop is the last resort, never a refund.
+        hardStop = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 1000);
+        hardStop.unref();
+      };
+      const abort = () => { failure = new Error('managed-tool-cancelled'); terminate(); };
+      child.managedCancel = abort;
+      const deadline = setTimeout(() => { failure = new Error('managed-tool-timeout'); terminate(); }, name === 'bash' ? 600000 : 30000);
+      deadline.unref();
+      signal?.addEventListener('abort', abort, { once: true });
+      child.stdin.on('error', () => {});
+      child.stdout.on('data', chunk => {
+        bytes += chunk.length;
+        if (bytes > MAX_WIRE_BYTES) { failure = new Error('managed-tool-output-too-large'); terminate(); return; }
+        pending += decoder.write(chunk);
+        for (;;) {
+          const newline = pending.indexOf('\n'); if (newline < 0) break;
+          const line = pending.slice(0, newline); pending = pending.slice(newline + 1);
+          try {
+            const value = JSON.parse(line);
+            if (value.update) onUpdate?.(value.update);
+            // A cancel or timeout asked for first stays the reason: the worker
+            // then reports how its command ended ("Command aborted").
+            else if (value.error) failure ??= new Error(String(value.error).slice(0, 1000));
+            else if (value.result) result = value.result;
+            else throw new Error('managed-worker-invalid-response');
+          } catch { failure = new Error('managed-worker-invalid-response'); terminate(); }
+        }
+      });
+      // Do not relay raw startup diagnostics into model context (paths/env may
+      // contain sensitive material). The UI can show this stable failure code.
+      child.stderr.on('data', () => {});
+      child.on('error', () => { failure = new Error('managed-worker-start-failed'); });
+      child.on('close', code => {
+        clearTimeout(deadline); if (hardStop) clearTimeout(hardStop);
+        this.#children.delete(child); signal?.removeEventListener('abort', abort);
+        if (failure) reject(failure);
+        else if (code !== 0 || !result || pending) reject(new Error('managed-worker-failed'));
+        else resolve(result);
+      });
+      child.stdin.write(message);
+      if (signal?.aborted) abort();
+    });
+  }
+  // Processes a command left running (`nohup … &`, a detached child) outlive
+  // it with the marker in their environment. They are stopped when a turn ends
+  // and when the boundary closes; nothing outside this boundary has the marker.
+  async stopStrays() {
+    if (this.#children.size) 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;
+  }
+  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();
+    fs.rmSync(this.temporary, { recursive: true, force: true });
+  }
+}

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

@@ -0,0 +1,36 @@
+import { sandboxDiagnostic } from './sandbox-diagnostic.mjs';
+import { fallbackFind, fallbackGrep } from './search-fallback.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { pathToFileURL } from 'node:url';
+// A dedicated, credential-free process already inside Seatbelt. The launch
+// profile and environment are supplied by the trusted runtime, never the LLM.
+const [sdkPath, cwd] = process.argv.slice(2);
+const api = await import(pathToFileURL(sdkPath).href);
+const factories = { read: api.createReadToolDefinition, write: api.createWriteToolDefinition,
+  edit: api.createEditToolDefinition, bash: api.createBashToolDefinition,
+  grep: api.createGrepToolDefinition, find: api.createFindToolDefinition, ls: api.createLsToolDefinition };
+let active = false, controller, network = false;
+const emit = value => process.stdout.write(JSON.stringify(value) + '\n');
+const input = createInterface({ input: process.stdin });
+input.on('line', async line => {
+  try {
+    const message = JSON.parse(line);
+    if (message.cancel === true) { controller?.abort(); return; }
+    if (active || !Object.hasOwn(factories, message.name)) throw new Error('managed-worker-request-invalid');
+    active = true; controller = new AbortController(); network = message.network === true;
+    const options = message.name === 'bash' ? { shellPath: '/bin/bash', exposeSessionEnvironment: false } : undefined;
+    // The runtime copies ripgrep/fd here when the machine has or can fetch them.
+    const provided = name => fs.existsSync(path.join(process.env.HOME ?? '', '.pi/agent/bin', name));
+    const result = message.name === 'grep' && !provided('rg') ? fallbackGrep(cwd, message.args)
+      : message.name === 'find' && !provided('fd') ? fallbackFind(cwd, message.args)
+      : 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).
+    emit({ result });
+  } catch (error) { emit({ error: sandboxDiagnostic(error instanceof Error ? error.message : 'managed-worker-failed', { network }) }); }
+  finally { if (active) { input.close(); process.stdin.destroy(); } }
+});
+process.stdin.on('end', () => controller?.abort());

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

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const CLT = '/Library/Developer/CommandLineTools';
+const executable = file => { try { fs.accessSync(file, fs.constants.X_OK); return fs.statSync(file).isFile(); } catch { return false; } };
+// The developer directory chosen by xcode-select (any Xcode name or location).
+function selectedDeveloperDir() {
+  try { return fs.realpathSync('/private/var/db/xcode_select_link'); } catch { return null; }
+}
+
+// /usr/bin/git is a macOS developer-tools launcher. Inside Seatbelt it may
+// misreport an unaccepted Xcode license when its preference lookup is denied.
+// Pin the actual installed binary; never widen access to user preferences.
+export function managedGit() {
+  const selected = selectedDeveloperDir();
+  for (const candidate of [`${CLT}/usr/bin/git`, ...(selected ? [path.join(selected, 'usr/bin/git')] : []), '/Applications/Xcode.app/Contents/Developer/usr/bin/git', '/opt/homebrew/bin/git', '/usr/local/bin/git']) {
+    if (executable(candidate)) return fs.realpathSync(candidate);
+  }
+  throw Error('managed-git-unavailable');
+}
+
+// Compilers without the /usr/bin shims: inside Seatbelt, xcrun cannot read
+// the Xcode license record and xcodebuild aborts, so cc/c++/make (and so Rust,
+// cgo and node-gyp builds) would fail on machines that select Xcode.app while
+// working on machines with only the Command Line Tools. Resolve the tools and
+// SDK here, outside the sandbox, the same way on every machine: the Command
+// Line Tools when installed, otherwise the selected Xcode.
+let developer;
+export function developerTools() {
+  if (developer) return developer;
+  const selected = selectedDeveloperDir();
+  const dir = executable(`${CLT}/usr/bin/clang`) ? CLT
+    : [selected, '/Applications/Xcode.app/Contents/Developer'].find(dev => dev && executable(path.join(dev, 'Toolchains/XcodeDefault.xctoolchain/usr/bin/clang')));
+  if (!dir) return (developer = { roots: [], bins: [], env: {} });
+  let sdk = '';
+  try {
+    sdk = execFileSync('/usr/bin/xcrun', ['--sdk', 'macosx', '--show-sdk-path'], { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'ignore'], env: { PATH: '/usr/bin:/bin', DEVELOPER_DIR: dir } }).trim();
+    sdk = fs.realpathSync(sdk);
+  } catch { sdk = dir === CLT && fs.existsSync(`${CLT}/SDKs/MacOSX.sdk`) ? fs.realpathSync(`${CLT}/SDKs/MacOSX.sdk`) : ''; }
+  const bins = dir === CLT ? [`${CLT}/usr/bin`] : [path.join(dir, 'Toolchains/XcodeDefault.xctoolchain/usr/bin'), path.join(dir, 'usr/bin')];
+  const app = dir.match(/^(.+?\.app)\/Contents\/Developer$/)?.[1];
+  return (developer = { roots: [...new Set([app ?? dir, ...(sdk ? [sdk] : [])])], bins, env: { DEVELOPER_DIR: dir, ...(sdk ? { SDKROOT: sdk } : {}) } });
+}
+
+// Certificates the Mac trusts beyond Node's bundled roots (a company CA, a
+// TLS-inspecting network) are trusted here too, so Studio and web pages load
+// wherever Agent Watch (which uses the system trust store) can connect.
+let systemTrust = false;
+export async function trustSystemCertificates() {
+  if (systemTrust) return; systemTrust = true;
+  try {
+    const tls = await import('node:tls');
+    const system = tls.getCACertificates('system');
+    if (system.length) tls.setDefaultCACertificates([...new Set([...tls.getCACertificates('default'), ...system])]);
+  } catch { /* older Node: bundled roots only */ }
+}
+
+const downloaded = new Map();
+
+// ripgrep and fd for Pi's grep/find, on any member machine: an installed copy,
+// else Pi's own downloader run here (outside the sandbox, like personal Pi).
+export function searchToolPath(name, userHome = os.homedir()) {
+  for (const candidate of [downloaded.get(name), `/opt/homebrew/bin/${name}`, `/usr/local/bin/${name}`, path.join(userHome, '.pi/agent/bin', name)]) {
+    if (candidate && executable(candidate)) return fs.realpathSync(candidate);
+  }
+  return null;
+}
+export async function ensureSearchTools(sdkRoot, userHome = os.homedir(), timeoutMs = 60_000) {
+  const missing = ['rg', 'fd'].filter(name => !searchToolPath(name, userHome));
+  if (!missing.length) return;
+  let manager;
+  try { manager = await import(pathToFileURL(path.join(sdkRoot, 'dist/utils/tools-manager.js')).href); } catch { return; }
+  await Promise.all(missing.map(async name => {
+    try {
+      const found = await Promise.race([manager.ensureTool(name, true), new Promise(resolve => setTimeout(resolve, timeoutMs).unref())]);
+      if (typeof found === 'string' && path.isAbsolute(found) && executable(found)) downloaded.set(name, found);
+    } catch { /* grep/find fall back to the built-in search */ }
+  }));
+}
+
+// Version managers and user-level toolchains the sandbox may read (never
+// write): only folders that exist on this machine, with their bin folders on
+// PATH and the variables their shims need. Credentials inside stay denied by
+// the profile's credential rules.
+const TOOLCHAINS = [
+  { dir: '.nvm' }, { dir: '.fnm' }, { dir: '.local/share/fnm' },
+  { dir: '.volta', bin: ['bin'], env: 'VOLTA_HOME' },
+  { dir: 'Library/pnpm', bin: [''], env: 'PNPM_HOME' }, { dir: '.local/share/pnpm', bin: [''] },
+  { dir: '.bun', bin: ['bin'], env: 'BUN_INSTALL' }, { dir: '.deno', bin: ['bin'] },
+  { dir: '.cargo', bin: ['bin'], env: 'CARGO_HOME' }, { dir: '.rustup', env: 'RUSTUP_HOME' },
+  { dir: '.pyenv', bin: ['shims', 'bin'], env: 'PYENV_ROOT' }, { dir: '.rbenv', bin: ['shims', 'bin'], env: 'RBENV_ROOT' },
+  { dir: 'go', bin: ['bin'], env: 'GOPATH' }, { dir: '.sdkman/candidates', bin: ['java/current/bin', 'gradle/current/bin', 'maven/current/bin'] },
+  { dir: '.local/share/mise', bin: ['shims'], env: 'MISE_DATA_DIR' }, { dir: '.asdf', bin: ['shims', 'bin'], env: 'ASDF_DATA_DIR' },
+  { dir: '.nodenv', bin: ['shims', 'bin'], env: 'NODENV_ROOT' }, { dir: '.goenv', bin: ['shims', 'bin'], env: 'GOENV_ROOT' },
+  { dir: '.jenv', bin: ['shims', 'bin'] }, { dir: '.rvm', bin: ['bin'] },
+  { dir: 'miniconda3', bin: ['bin', 'condabin'] }, { dir: 'miniforge3', bin: ['bin', 'condabin'] }, { dir: 'anaconda3', bin: ['bin', 'condabin'] },
+  { dir: '.dotnet', bin: [''], env: 'DOTNET_ROOT' }, { dir: '.yarn', bin: ['bin'] },
+  { dir: '.npm-global', bin: ['bin'] }, { dir: '.npm-packages', bin: ['bin'] },
+  { dir: '.local/bin', bin: [''] },
+];
+export function userToolchains(userHome = os.homedir(), node = process.execPath) {
+  const roots = [], bins = [], env = {};
+  for (const tool of TOOLCHAINS) {
+    const root = path.join(userHome, tool.dir);
+    let real;
+    try { real = fs.realpathSync(root); if (!fs.statSync(real).isDirectory()) continue; } catch { continue; }
+    roots.push(real);
+    for (const bin of tool.bin ?? []) { const dir = path.join(real, bin); if (fs.existsSync(dir)) bins.push(dir); }
+    if (tool.env) env[tool.env] = real;
+  }
+  if (env.GOPATH) env.GOMODCACHE = path.join(env.GOPATH, 'pkg/mod');
+  // npm/npx of the pinned node live in its install prefix (nvm, volta, fnm, a
+  // tarball install), which may sit outside the system folders.
+  const prefix = path.dirname(path.dirname(fs.realpathSync(node)));
+  if (prefix !== userHome && prefix !== '/' && fs.existsSync(path.join(prefix, 'lib/node_modules'))) roots.push(prefix);
+  return { roots: [...new Set(roots)], bins, env };
+}

package/packages/piagent-core/managed/web-fetch.mjs

@@ -0,0 +1,105 @@
+import dns from 'node:dns/promises';
+import https from 'node:https';
+import net from 'node:net';
+import zlib from 'node:zlib';
+
+// Reads one public https page for the company session, from the runtime
+// process (tools in the sandbox have no network). GET only, no cookies or
+// credentials, public addresses only (checked per redirect and pinned for the
+// connection so DNS cannot rebind to a private address), bounded size/time.
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const TEXT = /^(text\/|application\/(json|xml|xhtml\+xml|javascript|x-yaml|yaml|ld\+json|rss\+xml|atom\+xml))/i;
+
+function v4Private(address) {
+  const [a, b] = address.split('.').map(Number);
+  return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
+    || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19));
+}
+export function privateAddress(address) {
+  if (net.isIPv4(address)) return v4Private(address);
+  if (!net.isIPv6(address)) return true;
+  const value = address.toLowerCase();
+  const mapped = value.match(/^(?:0*:)*:ffff:(\d+\.\d+\.\d+\.\d+)$/) ?? value.match(/^64:ff9b::(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return v4Private(mapped[1]);
+  return value === '::' || value === '::1' || /^f[cd]/.test(value) || /^fe[89ab]/.test(value) || /^ff/.test(value) || value.startsWith('2001:db8');
+}
+
+async function publicTarget(url, resolve) {
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error('web-fetch-url-not-allowed');
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (/^(localhost|.*\.local|.*\.internal|.*\.localhost)$/i.test(host)) throw new Error('web-fetch-private-address');
+  const addresses = net.isIP(host) ? [{ address: host, family: net.isIP(host) }] : await resolve(host);
+  if (!addresses.length || addresses.some((entry) => privateAddress(entry.address))) throw new Error('web-fetch-private-address');
+  return addresses[0];
+}
+
+export function htmlToText(html) {
+  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? '';
+  const body = html.replace(/<(script|style|noscript|svg|template|iframe|title)[\s\S]*?<\/\1>/gi, ' ').replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<(br|hr)\b[^>]*>/gi, '\n').replace(/<\/(p|div|section|article|li|tr|h[1-6]|pre|blockquote|table|ul|ol)>/gi, '\n')
+    .replace(/<h([1-6])[^>]*>/gi, (_, level) => '\n' + '#'.repeat(Number(level)) + ' ').replace(/<li[^>]*>/gi, '- ').replace(/<[^>]+>/g, ' ');
+  const decode = (text) => text.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|nbsp|#39);/gi, (entity, code) => {
+    const lower = code.toLowerCase();
+    if (lower.startsWith('#x')) return String.fromCodePoint(parseInt(lower.slice(2), 16) || 32);
+    if (lower.startsWith('#')) return String.fromCodePoint(Number(lower.slice(1)) || 32);
+    return { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' }[lower] ?? entity;
+  });
+  const text = decode(body).split('\n').map((line) => line.replace(/[ \t\f\v ]+/g, ' ').trim()).filter(Boolean).join('\n');
+  return { title: decode(title).replace(/\s+/g, ' ').trim(), text };
+}
+
+// Connect only to the checked address. Node (autoSelectFamily, default since
+// Node 20) asks for every address at once ({all: true}) and rejects a single
+// address with "Invalid IP address", so answer in the shape requested.
+export function pinnedLookup(target) {
+  return (_host, options, callback) => options?.all
+    ? callback(null, [{ address: target.address, family: target.family }])
+    : callback(null, target.address, target.family);
+}
+
+function request(url, target, signal) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(url, { method: 'GET', signal, servername: net.isIP(url.hostname) ? undefined : url.hostname,
+      lookup: pinnedLookup(target),
+      headers: { 'User-Agent': 'Piagent-company-web-fetch/1', Accept: 'text/html,text/plain,application/json;q=0.9,*/*;q=0.1', 'Accept-Encoding': 'gzip, deflate, br' } }, resolve);
+    req.once('error', reject); req.end();
+  });
+}
+
+async function body(response) {
+  const encoding = String(response.headers['content-encoding'] ?? '').toLowerCase();
+  const stream = encoding === 'gzip' ? response.pipe(zlib.createGunzip()) : encoding === 'deflate' ? response.pipe(zlib.createInflate())
+    : encoding === 'br' ? response.pipe(zlib.createBrotliDecompress()) : response;
+  const chunks = []; let size = 0;
+  for await (const chunk of stream) {
+    size += chunk.length;
+    if (size > MAX_BYTES) { response.destroy(); throw new Error('web-fetch-too-large'); }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// `requestForTest` replaces only the connection; address checks still apply.
+export async function fetchPublicPage(input, { maxChars = 30_000, signal, resolve = (host) => dns.lookup(host, { all: true, verbatim: true }), requestForTest } = {}) {
+  let url;
+  try { url = new URL(String(input)); } catch { throw new Error('web-fetch-url-invalid'); }
+  const limit = Math.max(1_000, Math.min(100_000, Number(maxChars) || 30_000));
+  const timeout = AbortSignal.timeout(20_000), combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  for (let hop = 0; ; hop += 1) {
+    const target = await publicTarget(url, resolve);
+    const response = requestForTest ? await requestForTest(url) : await request(url, target, combined);
+    const status = response.statusCode ?? 0;
+    if (status >= 300 && status < 400 && response.headers.location) {
+      response.resume();
+      if (hop >= MAX_REDIRECTS) throw new Error('web-fetch-too-many-redirects');
+      url = new URL(response.headers.location, url); continue;
+    }
+    const type = String(response.headers['content-type'] ?? '');
+    if (type && !TEXT.test(type)) { response.destroy(); return { url: url.href, status, text: `Unsupported content type: ${type.split(';')[0]}` }; }
+    const raw = await body(response);
+    const page = /html/i.test(type) || /^\s*<(!doctype html|html)/i.test(raw) ? htmlToText(raw) : { title: '', text: raw };
+    const truncated = page.text.length > limit;
+    return { url: url.href, status, title: page.title, text: truncated ? page.text.slice(0, limit) + `\n[Truncated at ${limit} characters.]` : page.text };
+  }
+}

package/packages/piagent-core/managed/web-search.mjs

@@ -0,0 +1,96 @@
+// Web search for company sessions: the provider's own search tool (Codex
+// `web_search`, Claude `web_search_20250305`) through Studio with the current
+// run token, so queries stay with the company accounts and are metered like
+// any other request. The request carries the grant's model and effort, which
+// Studio requires to match.
+const INSTRUCTIONS = 'Search the web for the request. Answer concisely with the facts found and cite every source URL. Prefer official documentation and primary sources.';
+
+function sourceList(sources) {
+  const seen = new Set(), out = [];
+  for (const source of sources) {
+    if (typeof source?.url !== 'string' || !/^https?:\/\//.test(source.url)) continue;
+    const url = source.url.replace(/[?&]utm_source=openai$/, '');
+    if (seen.has(url)) continue;
+    seen.add(url); out.push({ title: typeof source.title === 'string' && source.title.trim() ? source.title.trim() : url, url });
+  }
+  return out.slice(0, 20);
+}
+
+function* events(text) {
+  for (const line of text.split('\n')) {
+    if (!line.startsWith('data:')) continue;
+    const data = line.slice(5).trim();
+    if (!data || data === '[DONE]') continue;
+    try { yield JSON.parse(data); } catch { /* skip keep-alives */ }
+  }
+}
+
+function parseCodex(text) {
+  let output = [];
+  const items = [];
+  for (const event of events(text)) {
+    if (event.type === 'response.output_item.done' && event.item) items.push(event.item);
+    if ((event.type === 'response.completed' || event.type === 'response.done') && Array.isArray(event.response?.output)) output = event.response.output;
+  }
+  if (!output.length) output = items;
+  // Sources the answer cites come first, then the other pages searched.
+  const answer = [], cited = [], searched = [];
+  for (const item of output) {
+    if (item?.type === 'message') for (const part of item.content ?? []) {
+      if (typeof part?.text === 'string') answer.push(part.text);
+      for (const note of part?.annotations ?? []) if (note?.type === 'url_citation') cited.push(note);
+    }
+    if (item?.type === 'web_search_call') for (const group of [item.action?.sources, item.sources, item.results]) {
+      for (const source of Array.isArray(group) ? group : []) searched.push({ url: source?.url, title: source?.title });
+    }
+  }
+  return { answer: answer.join('\n').trim(), sources: sourceList([...cited, ...searched]) };
+}
+
+function parseClaude(text) {
+  const blocks = [], sources = [];
+  let current = null;
+  for (const event of events(text)) {
+    if (event.type === 'content_block_start') {
+      current = event.content_block ?? null;
+      if (current?.type === 'text') blocks.push(current.text ?? '');
+      if (current?.type === 'web_search_tool_result' && Array.isArray(current.content)) for (const result of current.content) sources.push(result);
+    }
+    if (event.type === 'content_block_delta') {
+      if (event.delta?.type === 'text_delta' && current?.type === 'text') blocks[blocks.length - 1] += event.delta.text ?? '';
+      if (event.delta?.type === 'citations_delta') sources.push(event.delta.citation);
+    }
+  }
+  return { answer: blocks.join('').trim(), sources: sourceList(sources) };
+}
+
+export async function searchThroughStudio({ provider, origin, token, roleId, model, effort, query, domains, signal, fetchImpl = fetch }) {
+  if (typeof query !== 'string' || !query.trim() || query.length > 2000) throw new Error('web-search-query-invalid');
+  const allowed = Array.isArray(domains) ? domains.filter((domain) => typeof domain === 'string' && /^[a-z0-9.-]{1,253}$/i.test(domain)).slice(0, 20) : [];
+  const claude = provider === 'claude';
+  const body = claude
+    ? { model, max_tokens: 4096, system: INSTRUCTIONS, stream: true, messages: [{ role: 'user', content: query }],
+        tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: 5, ...(allowed.length ? { allowed_domains: allowed } : {}) }],
+        ...(effort ? { thinking: { type: 'adaptive' }, output_config: { effort } } : {}) }
+    : { model, instructions: INSTRUCTIONS, stream: true, store: false, input: [{ role: 'user', content: [{ type: 'input_text', text: query }] }],
+        tools: [{ type: 'web_search', ...(allowed.length ? { filters: { allowed_domains: allowed } } : {}) }],
+        include: ['web_search_call.action.sources'], tool_choice: 'required', ...(effort ? { reasoning: { effort } } : {}) };
+  const response = await fetchImpl(`${origin}${claude ? '/claude/v1/messages' : '/v1/responses'}`, {
+    method: 'POST', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(120_000)]) : AbortSignal.timeout(120_000),
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'text/event-stream', 'X-Session-Id': roleId,
+      ...(claude ? { 'anthropic-version': '2023-06-01' } : {}) },
+    body: JSON.stringify(body) });
+  const text = await response.text();
+  if (!response.ok) {
+    let code = `http-${response.status}`;
+    try { code = JSON.parse(text)?.error?.code ?? code; } catch { /* not JSON */ }
+    throw new Error(`web-search-failed: ${String(code).slice(0, 80)}`);
+  }
+  const result = claude ? parseClaude(text) : parseCodex(text);
+  if (!result.answer && !result.sources.length) throw new Error('web-search-empty');
+  return result;
+}
+
+export function searchResultText({ answer, sources }) {
+  return [answer || 'No summary returned.', sources.length ? 'Sources:\n' + sources.map((source, index) => `${index + 1}. ${source.title} — ${source.url}`).join('\n') : ''].filter(Boolean).join('\n\n');
+}