@piagent/platform 1.18.0 → 1.20.0

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

@@ -0,0 +1,131 @@
+import { unfinished, planText, currentPlan, workflowPolicy } from './workflow.mjs';
+import { failureCode } from '../runtime/managed-failure.mjs';
+
+// A main agent often ends its turn between the steps of its own checklist
+// ("STEP06 done, STEP07 next"), though the member asked for all of them.
+// Under plan "require" the harness sends it back to the next open step, as a
+// new run (as if the member had sent "continue": each round gets its own
+// helpers, checks and review), until the checklist is done, the member stops
+// it, a round fails, or IDLE_ROUNDS rounds in a row change nothing.
+export const IDLE_ROUNDS = 2;
+// A checklist holds at most 30 steps: one round per step at most.
+export const MAX_ROUNDS = 30;
+// How the member's message ended, shown under the last answer.
+export const TURN_END_ENTRY = 'agent-watch-turn-end';
+export const TURN_END_STATES = ['done', 'midway', 'failed', 'cancelled'];
+
+const completed = plan => plan?.plan?.filter(p => p.status === 'completed').length ?? 0;
+const deferred = plan => plan?.plan?.filter(p => p.status === 'deferred').length ?? 0;
+
+export class Continuation {
+  constructor(policy) {
+    Object.assign(this, { policy, rounds: 0, idle: 0, touched: false, reason: null, startDone: 0 });
+  }
+  // A round is about to start: what its progress is measured from.
+  begin(plan) { this.startDone = completed(plan); }
+  // A round ended (its run closed). The message that starts the next round,
+  // or null: then `reason` says why the harness stopped sending it back.
+  next({ plan, planUpdated, changed, stopped, failed }) {
+    if (planUpdated) this.touched = true;
+    if (stopped) { this.reason = 'stopped'; return null; }
+    if (failed) { this.reason = 'failed'; return null; }
+    if (!this.touched || !unfinished(plan)) { this.reason = null; return null; }
+    if (this.policy.plan !== 'require') { this.reason = 'policy'; return null; }
+    // The member's own round always gets one round back; a harness round
+    // that neither completed a step nor changed code counts as idle.
+    if (this.rounds > 0) this.idle = completed(plan) > this.startDone || changed ? 0 : this.idle + 1;
+    if (this.idle >= IDLE_ROUNDS) { this.reason = 'idle'; return null; }
+    if (this.rounds >= MAX_ROUNDS) { this.reason = 'limit'; return null; }
+    this.rounds += 1;
+    const steps = plan.plan.length, done = completed(plan), open = steps - done - deferred(plan);
+    return { customType: 'agent-watch-process', display: true,
+      content: `Harness: your checklist still has ${open} open step(s) (${done}/${steps} completed):\n${planText(plan)}\nThe member asked for all of it, unless they told you to stop at this point. Continue with the next open step now and keep going until every step is completed; update the checklist with update_plan as you go. Do not stop to report progress between steps. If the member asked you to stop here (to review a plan before any change, for example) or you cannot go on without them (a decision, access, a service that is not running), ask with ask_user instead of going on. If a step is no longer needed, take it out of the checklist and say why in your final answer.`,
+      details: { phase: 'continue', round: this.rounds, maxRounds: MAX_ROUNDS, planOpen: open, planDone: done, planSteps: steps, ...(this.idle ? { idle: this.idle } : {}) } };
+  }
+}
+
+// How a member's message ended: every step done (or answered without a
+// checklist), stopped with steps open (and why the harness did not go on),
+// failed (which role, which kind) or stopped by the member.
+export function turnEnd(continuation, plan, { stopped, failure }) {
+  const steps = continuation.touched ? plan?.plan?.length ?? 0 : 0, done = continuation.touched ? completed(plan) : 0;
+  const state = stopped ? 'cancelled' : failure ? 'failed' : continuation.touched && unfinished(plan) ? 'midway' : 'done';
+  const later = continuation.touched ? deferred(plan) : 0;
+  return { state, planSteps: steps, planDone: done, ...(later ? { planDeferred: later } : {}), rounds: continuation.rounds,
+    ...(state === 'midway' && continuation.reason ? { reason: continuation.reason } : {}),
+    ...(state === 'failed' ? { role: failure.role ?? 'main', code: String(failure.code || 'unknown').toLowerCase().replace(/[^a-z0-9_]+/g, '_').slice(0, 64) } : {}),
+    at: new Date().toISOString() };
+}
+
+// One member message: its round, then the rounds the harness adds while the
+// checklist has open steps. `runRound(text, deliver)` runs one Studio run and
+// returns { result, preflight, planUpdated, changed, closeFailed }. A message the member
+// sends while a round closes (no model runs then) becomes the next round;
+// Stop ends the turn. Listeners hear "settled" once, after the last round.
+// "tiếp tục", "continue", the dashboard's Continue button: the member asks
+// for the open checklist, so it is this message's work even before the agent
+// touches it again.
+const CONTINUE = /^(tiep tuc|lam tiep|lam not|continue|go on|keep going|resume)\b/;
+export function asksToContinue(text) {
+  const normal = String(text ?? '').normalize('NFD').replace(/\p{M}/gu, '').replace(/[đĐ]/g, 'd').toLowerCase().trim();
+  return normal.length <= 60 && CONTINUE.test(normal);
+}
+const fresh = (self, manager, text) => {
+  const continuation = new Continuation(workflowPolicy(self.manifest));
+  if (asksToContinue(text) && unfinished(currentPlan(manager))) continuation.touched = true;
+  return continuation;
+};
+
+export async function memberTurn(self, { manager, prompt, runRound }, text, deliver) {
+  let continuation = fresh(self, manager, text), result, waiting = null, ended = null;
+  self.stopRequested = false; self.queued = [];
+  try {
+    for (let first = true; ; first = false) {
+      continuation.begin(currentPlan(manager));
+      self.between = false;
+      let round;
+      try { round = await runRound(text, deliver); }
+      catch (error) { waiting?.reject(error); waiting = null; throw error; }
+      if (first) result = round.result; else waiting?.resolve(round.result);
+      waiting = null;
+      const last = self.session.messages.findLast(m => m.role === 'assistant');
+      const stopped = self.stopRequested || last?.stopReason === 'aborted';
+      const failure = round.preflight || last?.stopReason === 'error' ? { role: 'main', code: failureCode(last?.errorMessage ?? '') }
+        : round.closeFailed ? { role: 'main', code: round.closeFailed } : null;
+      const plan = currentPlan(manager), message = continuation.next({ plan, planUpdated: round.planUpdated, changed: round.changed, stopped, failed: !!failure });
+      if (self.queued.length) {
+        // The member wrote while the round closed: theirs is the next round,
+        // a new request (Stop before it applied to the round before).
+        waiting = self.queued.shift(); self.stopRequested = false;
+        const next = waiting; text = next.text;
+        deliver = () => prompt(next.text, { ...next.options, expandPromptTemplates: false });
+        continuation = fresh(self, manager, next.text);
+      } else if (message) {
+        text = message.content;
+        deliver = () => { self.nextPurpose = 'continue'; return self.session.sendCustomMessage(message, { triggerTurn: true }); };
+      } else { ended = turnEnd(continuation, plan, { stopped, failure }); break; }
+    }
+  } finally {
+    self.between = false;
+    for (const queued of self.queued.splice(0)) queued.reject(Error('managed-turn-stopped'));
+    // How the member's message ended: an entry of the conversation (not a
+    // message: the model never reads it), shown under the last answer, and
+    // told to listeners (the company Terminal).
+    if (ended) {
+      try { manager.appendCustomEntry(TURN_END_ENTRY, ended); } catch { /* the answer stands */ }
+      self.notify({ type: 'managed_turn_end', end: ended, text: turnEndText(ended) });
+    }
+    self.activePrompt = false;
+    self.notify({ type: 'agent_settled' });
+  }
+  return result;
+}
+
+// The plain text of a turn's end (the Terminal shows it; the WebUI reads details).
+export function turnEndText(end) {
+  if (end.state === 'cancelled') return 'Turn stopped by the member.';
+  if (end.state === 'failed') return `Turn failed: ${end.role} agent, ${end.code}. Send "continue" to go on.`;
+  if (end.state === 'midway') return `Turn ended with ${end.planSteps - end.planDone - (end.planDeferred ?? 0)} of ${end.planSteps} checklist step(s) open${end.reason === 'idle' ? `: the agent stopped ${IDLE_ROUNDS} times in a row without progress` : end.reason === 'limit' ? `: ${MAX_ROUNDS} rounds reached` : ''}. Send "continue" to go on.`;
+  if (end.planDeferred) return `Done: ${end.planDone} of ${end.planSteps} checklist steps completed, ${end.planDeferred} left for later.`;
+  return end.planSteps ? `Done: all ${end.planSteps} checklist steps completed.` : 'Done.';
+}

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

@@ -66,6 +66,11 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
       let refused = false; try { await bash('curl -sS -m 5 https://example.com/ >/dev/null'); } catch { refused = true; }
       if (!refused) throw Error('a command reached the internet without approval'); return 'blocked';
     });
+    // Package registries through the runtime's proxy (package-proxy.mjs).
+    if (network) await check('package registries without approval (npm through the proxy)', false, async () => {
+      const status = await bash('curl -sS -m 15 -o /dev/null -w "%{http_code}" https://registry.npmjs.org/');
+      if (status !== '200') throw Error(`HTTP ${status}`); return 'registry.npmjs.org';
+    });
     await check('git', true, () => bash('git --version'));
     await check('git commit with the member\'s identity', false, async () => {
       await bash('git init -q . && git add -A');
@@ -86,6 +91,13 @@ export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
       try { return await bash('node loopback.mjs'); }
       catch (error) { throw Error(/loopback-blocked/.test(String(error?.message)) ? 'a local proxy listens on this Mac: tests that use localhost need run_with_network' : first(String(error?.message))); }
     });
+    // run_with_docker: the engine answers through its socket, and only there.
+    await check('Docker for approved commands (run_with_docker)', false, async () => {
+      if (!boundary.engine) throw Error('no Docker engine running (Docker Desktop, Colima, OrbStack…): start it, then open a new conversation');
+      let refused = false; try { await bash('docker version --format "{{.Server.Version}}"'); } catch { refused = true; }
+      if (!refused) throw Error('a plain command reached the Docker engine');
+      return `engine ${await bash('docker version --format "{{.Server.Version}}"', { docker: true })}`;
+    });
     await check('package caches kept for the project', false, async () => { await bash('mkdir -p "$npm_config_cache" && touch "$npm_config_cache/.piagent-doctor"'); return boundary.packageCache; });
     // The languages installed on this Mac, each started once in the sandbox.
     // (macOS ships stubs for some, such as javac without a JDK: a probe decides.)

package/packages/piagent-core/managed/helper-roles.mjs

@@ -34,7 +34,7 @@ const HELPER_USES = {
   research: roles => roles.includes('scout') ? 'research: anything on the web (current information, news, library or API documentation, releases, error messages), with the code when needed. It searches and reads the pages; you get its summary with sources.'
     : 'research: anything on the web (current information, news, documentation; it searches and reads the pages, you get its summary with sources), and before changing an area you do not know that spans more files than you can read in a few batches (where something is computed and every caller, how a flow crosses modules); your own context stays free for the change.',
   verify: () => 'verify: an independent check of a result: it runs the repository checks on the current code (offline, and the project is read-only for its commands) and confirms claims, yours or a helper\'s, against the code and primary sources. It answers pass, fail or unverifiable per claim, with evidence.',
-  review: () => 'review: an independent review of the current patch.',
+  review: () => 'review: an independent review of the current patch (this turn\'s changes, commits made in the turn included). To review work committed in earlier turns, pass since: the commit, branch or HEAD~N it started from; when this turn changed nothing, it reviews the branch\'s commits since it left the default branch.',
 };
 export function delegateDescription(roles) {
   return `Hand work to a helper with its own context. Helpers read the project but cannot change files or call helpers. ${roles.map(role => HELPER_USES[role](roles)).join(' ')} A lookup that one grep or read answers stays with you. Write the task as a brief the helper can act on alone: the goal, what to find or check, where to start and what you already know or ruled out, and the answer you need (file:line facts). One call per helper runs at a time; each can be called again, up to ${HELPER_CALLS} times per user message, for example a second review after fixing what the first one found.`;

package/packages/piagent-core/managed/helper-run.mjs

@@ -8,7 +8,7 @@ import { ManagedToolBoundary } from './tool-boundary.mjs';
 import { managedResourceLoader } from './resource-loader.mjs';
 import { shareGrant, releaseGrant } from './grant-share.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
-import { reviewParts, mergeReviews, REVIEW_PARALLEL } from './patch-snapshot.mjs';
+import { reviewParts, mergeReviews, REVIEW_PARALLEL, emptySnapshot, readBranchBase, readPatchDigest, readPatchSnapshot, resolveReviewBase } from './patch-snapshot.mjs';
 import { reviewFindings, briefIssues } from './workflow.mjs';
 import { anchorText, relayObjection, recordVerdicts } from './objections.mjs';
 import { HELPER_CALLS, HELPER_SETUP, READ_TOOLS, countedCheck } from './helper-roles.mjs';
@@ -21,8 +21,24 @@ const textContent = result => result.content?.filter(p => p.type === 'text').map
 const HELPER_SWITCH = new Set(['upstream_rate_limited', 'session_account_not_ready_retry_later', 'session_account_unavailable_start_new_session', 'account_capacity_unavailable', 'execution_capability_unavailable']);
 const HELPER_ATTEMPTS = 2;
 
-export async function runHelper(managed, role, task, signal, harness, { verifyGrant, patiently, title }) {
-  const snapshot = role === 'review' ? await managed.patchSnapshot() : null, parts = snapshot ? reviewParts(snapshot) : null;
+// The patch a review reads: this turn's change; the commits since `since`
+// (a commit before HEAD the main agent names); or, when the turn changed
+// nothing and the main agent asked (a review of work committed in earlier
+// turns), the branch's commits since it left the default branch.
+async function reviewSnapshot(managed, harness, since) {
+  if (since) {
+    const base = await resolveReviewBase(managed.boundary, since);
+    if (!base) throw Error(`managed-review-base-unknown: "${String(since).slice(0, 80)}" is not a commit HEAD descends from in this repository; name a commit, a branch or HEAD~N`);
+    return Object.assign(await readPatchSnapshot(managed.boundary, null, base), { from: { kind: 'since', ref: since, base } });
+  }
+  const snapshot = await managed.patchSnapshot();
+  if (harness || !emptySnapshot(snapshot)) return snapshot;
+  const branch = await readBranchBase(managed.boundary);
+  return branch ? Object.assign(await readPatchSnapshot(managed.boundary, null, branch.base), { from: { kind: 'branch', ref: branch.ref, base: branch.base } }) : snapshot;
+}
+
+export async function runHelper(managed, role, task, signal, harness, { verifyGrant, patiently, title, since }) {
+  const snapshot = role === 'review' ? await reviewSnapshot(managed, harness, since) : null, parts = snapshot ? reviewParts(snapshot) : null;
   // A helper whose company model account is out of usage, or resting after
   // a refusal, starts once more: Studio then gives the new helper the next
   // model of its role that serves (an auto role's list). Helpers read and
@@ -98,15 +114,17 @@ async function helperAttempt(managed, role, task, signal, harness, snapshot, par
       review = mergeReviews(parts, answers, { findingsOf: reviewFindings, issuesOf: briefIssues });
       ({ reply, usage } = review);
     }
-    const stale = snapshot ? (await managed.patchDigest()) !== snapshot.digest : false;
-    const details = { role, runID: grant.run_id, tokens: usage, patchDigest: snapshot?.digest, stale };
+    const from = snapshot?.from ?? null;
+    const stale = snapshot ? (await (from ? readPatchDigest(managed.boundary, null, from.base) : managed.patchDigest())) !== snapshot.digest : false;
+    const details = { role, runID: grant.run_id, tokens: usage, patchDigest: snapshot?.digest, stale, ...(from ? { since: { kind: from.kind, ref: from.ref, base: from.base } } : {}) };
     if (snapshot) {
       // Severity-graded findings decide whether the harness sends the agent back.
       const findings = review ? review.findings : reviewFindings(reply);
       Object.assign(details, { parsed: review ? review.parsed : !!findings, findings: (findings ?? []).slice(0, 40), blocking: findings?.filter(f => f.severity === 'blocking').length ?? 0 });
       if (review) Object.assign(details, { parts: parts.parts.length, unread: parts.omitted.map(o => o.path).slice(0, 50) });
       if (managed.run) { managed.run.reviews += 1; managed.run.blocking += details.blocking; }
-      managed.review = details;
+      // A review of earlier commits is not the review of this turn's change.
+      if (!from) managed.review = details;
       managed.session.sessionManager.appendCustomEntry('agent-watch-review', details);
     }
     const verdicts = role === 'verify' ? recordVerdicts(managed.run, reply, harness, details) : '';

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

@@ -10,6 +10,10 @@ import { execFileSync } from 'node:child_process';
 //   network (run_with_network), later runs work offline;
 // - the member's own dependency caches as read-only seeds, where the tool can
 //   layer one (Go, Gradle, Maven), so what is already downloaded is reused;
+// - the distributions the Maven Wrapper (./mvnw) and the Gradle Wrapper
+//   (./gradlew) already unpacked on this Mac, linked read-only into the
+//   project's cache, so they run without asking for network; one they have
+//   to download stays in the cache;
 // - runtimes installed in places the sandbox otherwise keeps closed (JDKs
 //   under ~/Library/Java, the Android SDK, the system gem folder, MacPorts);
 // - SwiftPM and xcodebuild, which cannot start their own sandbox inside this
@@ -62,6 +66,50 @@ case "$(basename "$0"):$1" in
 esac
 `;
 
+// Each <name>/<hash> distribution folder of the member's Maven Wrapper as a
+// link in the project's cache; one already there (linked, or downloaded by an
+// approved command) is kept.
+function linkDistributions(source, target) {
+  let names = [];
+  try { names = fs.readdirSync(source, { withFileTypes: true }).filter(entry => entry.isDirectory()); } catch { return; }
+  for (const name of names) {
+    let hashes = [];
+    try { hashes = fs.readdirSync(path.join(source, name.name), { withFileTypes: true }).filter(entry => entry.isDirectory()); } catch { continue; }
+    for (const hash of hashes) {
+      const link = path.join(target, name.name, hash.name);
+      try { fs.lstatSync(link); continue; } catch { /* not there yet */ }
+      try { fs.mkdirSync(path.dirname(link), { recursive: true, mode: 0o700 }); fs.symlinkSync(path.join(source, name.name, hash.name), link); } catch { /* best effort */ }
+    }
+  }
+}
+
+// The Gradle Wrapper locks <hash>/<zip>.lck and checks <zip>.ok before it
+// uses a distribution, so each <name>/<hash> is a folder of the cache with
+// the marker copied and the unpacked distribution linked.
+function linkGradleDistributions(source, target) {
+  let names = [];
+  try { names = fs.readdirSync(source, { withFileTypes: true }).filter(entry => entry.isDirectory()); } catch { return; }
+  for (const name of names) {
+    let hashes = [];
+    try { hashes = fs.readdirSync(path.join(source, name.name), { withFileTypes: true }).filter(entry => entry.isDirectory()); } catch { continue; }
+    for (const hash of hashes) {
+      const from = path.join(source, name.name, hash.name), to = path.join(target, name.name, hash.name);
+      let entries = [];
+      try { entries = fs.readdirSync(from, { withFileTypes: true }); } catch { continue; }
+      if (!entries.some(entry => entry.name.endsWith('.ok'))) continue; // not fully unpacked
+      try { fs.mkdirSync(to, { recursive: true, mode: 0o700 }); } catch { continue; }
+      for (const entry of entries) {
+        const link = path.join(to, entry.name);
+        try { fs.lstatSync(link); continue; } catch { /* not there yet */ }
+        try {
+          if (entry.isDirectory()) fs.symlinkSync(path.join(from, entry.name), link);
+          else if (entry.name.endsWith('.ok')) fs.writeFileSync(link, '', { mode: 0o600 });
+        } catch { /* best effort */ }
+      }
+    }
+  }
+}
+
 export function languageEnvironment({ userHome, repositoryTop, home }) {
   const linux = process.platform === 'linux';
   const root = linux ? path.join(process.env.XDG_CACHE_HOME || path.join(userHome, '.cache'), 'piagent/sandbox') : path.join(userHome, 'Library/Caches/Piagent/sandbox');
@@ -80,11 +128,19 @@ export function languageEnvironment({ userHome, repositoryTop, home }) {
     // .NET restores over TLS through the macOS Security framework, closed
     // here: packages the member restored are read from their own folder.
     nuget: existing(path.join(userHome, '.nuget/packages')),
+    mavenWrapper: existing(path.join(userHome, '.m2/wrapper/dists')),
+    gradleWrapper: existing(path.join(userHome, '.gradle/wrapper/dists')),
   };
   const java = javaHome(userHome), android = existing(path.join(userHome, linux ? 'Android/Sdk' : 'Library/Android/sdk'));
   const readRoots = [...new Set([...Object.values(seeds), java, android, existing(path.join(userHome, 'Library/Java/JavaVirtualMachines')),
     existing('/Library/Ruby'), existing('/opt/local')].filter(Boolean))];
 
+  // ./mvnw looks for its distribution in MAVEN_USER_HOME/wrapper/dists/<name>/<hash>
+  // (the sandbox's HOME is an empty folder per conversation).
+  if (seeds.mavenWrapper) linkDistributions(seeds.mavenWrapper, at('m2/wrapper/dists'));
+  // ./gradlew: GRADLE_USER_HOME/wrapper/dists/<name>/<hash>.
+  if (seeds.gradleWrapper) linkGradleDistributions(seeds.gradleWrapper, at('gradle/wrapper/dists'));
+
   const bin = path.join(home, '.piagent/bin');
   fs.mkdirSync(bin, { recursive: true, mode: 0o700 });
   // (Only macOS: SwiftPM on Linux starts no sandbox of its own.)
@@ -102,6 +158,7 @@ export function languageEnvironment({ userHome, repositoryTop, home }) {
     CARGO_HOME: at('cargo'), GRADLE_USER_HOME: at('gradle'), NUGET_PACKAGES: at('nuget'), COMPOSER_CACHE_DIR: at('composer'),
     PUB_CACHE: at('pub'), GEM_HOME: at('gem'), BUNDLE_PATH: at('bundle'), CP_HOME_DIR: at('cocoapods'), PIAGENT_DERIVED_DATA: at('DerivedData'),
     DOTNET_CLI_TELEMETRY_OPTOUT: '1', DOTNET_NOLOGO: '1', DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1',
+    MAVEN_USER_HOME: at('m2'),
     MAVEN_OPTS: [`-Dmaven.repo.local=${at('m2/repository')}`, ...(seeds.maven ? [`-Dmaven.repo.local.tail=${seeds.maven}`] : [])].join(' '),
     ...(seeds.gradle ? { GRADLE_RO_DEP_CACHE: seeds.gradle } : {}),
     ...(seeds.nuget ? { NUGET_FALLBACK_PACKAGES: seeds.nuget } : {}),

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

@@ -52,7 +52,7 @@ export function credentialFiles(roots, { limit = SCAN_ENTRIES } = {}) {
 }
 
 const depth = file => file.split('/').length;
-export function bubblewrapArgs({ cwd, sdkRoot, runtimeRoot, temporary, empty, node, readOnly = false, repository = [], gitDirs = [], toolchains = [], skills = [], caches = [], references = [], network = false, credentials = [] }) {
+export function bubblewrapArgs({ cwd, sdkRoot, runtimeRoot, temporary, empty, node, readOnly = false, repository = [], gitDirs = [], toolchains = [], skills = [], caches = [], references = [], network = false, credentials = [], docker = null, proxySocket = null }) {
   const exists = file => { try { fs.statSync(file); return true; } catch { return false; } };
   const readable = [...new Set([sdkRoot, runtimeRoot, path.dirname(node), ...repository, ...toolchains, ...skills, ...references, ...(readOnly ? [cwd, ...gitDirs] : [])])].filter(exists);
   const writable = [...new Set([...caches, ...(readOnly ? [] : [cwd, ...gitDirs])])].filter(exists);
@@ -66,6 +66,11 @@ export function bubblewrapArgs({ cwd, sdkRoot, runtimeRoot, temporary, empty, no
     '--proc', '/proc', '--dev', '/dev', '--tmpfs', '/tmp', '--bind', temporary, temporary,
     ...mounts.flatMap(([kind, dir]) => [kind, dir, dir]),
     ...credentials.filter(item => exists(item.path)).flatMap(item => item.directory ? ['--tmpfs', item.path] : ['--ro-bind', empty, item.path]),
+    // An approved Docker command reaches the engine's socket (run_with_docker).
+    ...(docker && exists(docker) ? ['--bind', docker, docker] : []),
+    // A command without network reaches the package proxy (package-proxy.mjs)
+    // through this socket; the worker forwards 127.0.0.1:3128 to it.
+    ...(proxySocket && exists(proxySocket) ? ['--bind', proxySocket, '/run/piagent-proxy.sock'] : []),
     '--remount-ro', '/', '--chdir', cwd,
   ];
 }

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

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { lookup } from 'node:dns/promises';
+
+// The package registries a company command reaches without asking: plain
+// bash has no network, except through this proxy, which the trusted runtime
+// runs outside the sandbox. It tunnels HTTPS (CONNECT) and forwards plain
+// HTTP to the hosts below and the member's own additions, on ports 443 and
+// 80 only, never to an IP literal or a name that resolves to this machine or
+// a private network (DNS rebinding), and connects to the address it checked.
+// Everything else is refused with 403 and remembered, so the command's
+// failure names the host and run_with_network (the member approves it).
+// Registries (and GitHub) take no upload without a token, and tokens stay
+// out of the sandbox (.npmrc, ~/.m2/settings.xml, git credentials).
+export const DEFAULT_DOMAINS = Object.freeze([
+  // JavaScript
+  'registry.npmjs.org', 'registry.yarnpkg.com', 'repo.yarnpkg.com', 'registry.npmmirror.com', 'jsr.io', 'npm.jsr.io', 'deno.land',
+  // Python
+  'pypi.org', 'files.pythonhosted.org',
+  // Go
+  'proxy.golang.org', 'sum.golang.org', 'index.golang.org',
+  // Rust
+  'crates.io', 'index.crates.io', 'static.crates.io', 'static.rust-lang.org',
+  // JVM
+  'repo.maven.apache.org', 'repo1.maven.org', 'maven.google.com', 'dl.google.com', 'plugins.gradle.org', 'plugins-artifacts.gradle.org',
+  'services.gradle.org', 'downloads.gradle.org', 'repo.spring.io', 'jitpack.io',
+  // .NET, Ruby, PHP, Dart, Swift/CocoaPods, Elixir
+  'api.nuget.org', 'globalcdn.nuget.org', 'rubygems.org', 'index.rubygems.org', 'packagist.org', 'repo.packagist.org',
+  'pub.dev', 'cdn.cocoapods.org', 'repo.hex.pm', 'builds.hex.pm',
+  // Public GitHub downloads: release assets (the Gradle Wrapper's
+  // distributions redirect there), git dependencies and archives. Nothing
+  // is pushed or uploaded without a token, and none reaches the sandbox.
+  'github.com', 'codeload.github.com', 'objects.githubusercontent.com', 'release-assets.githubusercontent.com',
+]);
+const PORTS = new Set([80, 443]);
+
+// One host name per line in the member's file (# comments); "*.example.com"
+// covers its subdomains. Read by the trusted runtime: the sandbox cannot.
+export function memberDomains(userHome, file = path.join(userHome, '.piagent/sandbox-domains')) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  return text.split('\n').map(line => line.replace(/#.*/, '').trim().toLowerCase()).filter(name => /^(\*\.)?[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(name)).slice(0, 200);
+}
+
+export function domainAllowed(host, domains) {
+  const name = String(host).toLowerCase().replace(/\.$/, '');
+  if (!/^[a-z0-9.-]+$/.test(name) || net.isIP(name)) return false;
+  return domains.some(rule => rule.startsWith('*.') ? name.endsWith(rule.slice(1)) && name.length > rule.length - 1 : name === rule);
+}
+
+// Addresses that are this machine, a private network or not routable.
+export function privateAddress(address) {
+  if (net.isIPv4(address)) {
+    const [a, b] = address.split('.').map(Number);
+    return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b < 128) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b < 32)
+      || (a === 192 && b === 168) || (a === 198 && (b === 18 || b === 19)) || a >= 224;
+  }
+  const v6 = address.toLowerCase();
+  if (v6.startsWith('::ffff:')) return privateAddress(v6.slice(7));
+  return v6 === '::' || v6 === '::1' || /^f[cd]/.test(v6) || /^fe[89ab]/.test(v6) || v6.startsWith('ff');
+}
+
+function upstreamProxy(env) {
+  for (const name of ['HTTPS_PROXY', 'https_proxy']) {
+    try { const url = new URL(env[name]); if (url.protocol === 'http:' && url.hostname && !url.username) return { host: url.hostname, port: Number(url.port) || 80 }; } catch { /* unset */ }
+  }
+  return null;
+}
+
+export class PackageProxy {
+  #server; #sockets = new Set();
+  // (`ports` and `isPrivate` are for tests.)
+  constructor({ domains = DEFAULT_DOMAINS, resolve = name => lookup(name, { all: true }), env = process.env, maxDenied = 200, ports = PORTS, isPrivate = privateAddress } = {}) {
+    this.domains = [...new Set(domains.map(name => name.toLowerCase()))];
+    this.resolve = resolve; this.upstream = upstreamProxy(env); this.maxDenied = maxDenied; this.ports = new Set(ports); this.isPrivate = isPrivate;
+    this.log = []; this.deniedCount = 0;
+    this.#server = http.createServer((request, response) => this.#forward(request, response));
+    this.#server.on('connect', (request, socket, head) => this.#tunnel(request, socket, head));
+    this.#server.on('connection', socket => { this.#sockets.add(socket); socket.once('close', () => this.#sockets.delete(socket)); });
+    this.#server.on('clientError', (_error, socket) => socket.destroy());
+  }
+  // A TCP port on loopback (macOS) or a Unix socket (Linux).
+  listen(where) {
+    return new Promise((resolve, reject) => {
+      this.#server.once('error', reject);
+      const done = () => { this.#server.off('error', reject); resolve(this.#server.address()); };
+      if (typeof where === 'string') this.#server.listen(where, done); else this.#server.listen(0, '127.0.0.1', done);
+    });
+  }
+  #deny(host) {
+    this.deniedCount += 1;
+    this.log.push(String(host).slice(0, 253)); if (this.log.length > this.maxDenied) this.log.shift();
+  }
+  // The hosts refused since the count was `before` (at most the last few).
+  deniedSince(before) {
+    const count = Math.min(this.deniedCount - before, this.log.length);
+    return count > 0 ? [...new Set(this.log.slice(-count))].slice(-5) : [];
+  }
+  // The checked public address of an allowed host, or null.
+  async #target(host, port) {
+    if (!this.ports.has(port) || !domainAllowed(host, this.domains)) { this.#deny(host); return null; }
+    if (this.upstream) return { host, port };
+    try {
+      const addresses = await this.resolve(host);
+      if (!addresses.length || addresses.some(entry => this.isPrivate(entry.address))) { this.#deny(host); return null; }
+      return { host: addresses[0].address, port };
+    } catch { this.#deny(host); return null; }
+  }
+  async #tunnel(request, socket, head) {
+    socket.on('error', () => {});
+    const match = /^([^:[\]]+|\[[^\]]+\]):(\d+)$/.exec(request.url ?? '');
+    const target = match ? await this.#target(match[1], Number(match[2])) : (this.#deny(request.url ?? ''), null);
+    if (!target) { socket.end('HTTP/1.1 403 Forbidden\r\nX-Piagent-Proxy: domain-not-allowed\r\nContent-Length: 0\r\n\r\n'); return; }
+    const upstream = this.upstream ? net.connect(this.upstream.port, this.upstream.host) : net.connect(target.port, target.host);
+    upstream.setTimeout(10 * 60_000, () => upstream.destroy());
+    upstream.once('connect', () => {
+      if (this.upstream) {
+        upstream.write(`CONNECT ${match[1]}:${match[2]} HTTP/1.1\r\nHost: ${match[1]}:${match[2]}\r\n\r\n`);
+        let reply = Buffer.alloc(0);
+        const onData = chunk => {
+          reply = Buffer.concat([reply, chunk]);
+          const end = reply.indexOf('\r\n\r\n'); if (end < 0) { if (reply.length > 16384) upstream.destroy(); return; }
+          upstream.off('data', onData);
+          if (!/^HTTP\/1\.[01] 2\d\d/.test(reply.subarray(0, end).toString('latin1'))) { socket.end('HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n\r\n'); upstream.destroy(); return; }
+          socket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); if (reply.length > end + 4) socket.write(reply.subarray(end + 4)); if (head?.length) upstream.write(head);
+          upstream.pipe(socket); socket.pipe(upstream);
+        };
+        upstream.on('data', onData);
+        return;
+      }
+      socket.write('HTTP/1.1 200 Connection Established\r\n\r\n');
+      if (head?.length) upstream.write(head);
+      upstream.pipe(socket); socket.pipe(upstream);
+    });
+    upstream.on('error', () => { if (socket.writable) socket.end('HTTP/1.1 502 Bad Gateway\r\nContent-Length: 0\r\n\r\n'); });
+    socket.on('close', () => upstream.destroy());
+  }
+  async #forward(request, response) {
+    let url;
+    try { url = new URL(request.url); } catch { response.writeHead(400).end(); return; }
+    if (url.protocol !== 'http:') { response.writeHead(400).end(); return; }
+    const target = await this.#target(url.hostname, Number(url.port) || 80);
+    if (!target) { response.writeHead(403, { 'X-Piagent-Proxy': 'domain-not-allowed', 'Content-Type': 'text/plain; charset=utf-8' }).end(`piagent: ${url.hostname} is not an allowed package registry\n`); return; }
+    const headers = { ...request.headers, host: url.host }; delete headers['proxy-connection']; delete headers['proxy-authorization'];
+    const outgoing = http.request(this.upstream
+      ? { host: this.upstream.host, port: this.upstream.port, path: url.href, method: request.method, headers }
+      : { host: target.host, port: target.port, path: url.pathname + url.search, method: request.method, headers, servername: url.hostname }, incoming => {
+      response.writeHead(incoming.statusCode ?? 502, incoming.headers); incoming.pipe(response);
+    });
+    outgoing.on('error', () => { if (!response.headersSent) response.writeHead(502); response.end(); });
+    request.pipe(outgoing);
+  }
+  async close() {
+    for (const socket of this.#sockets) socket.destroy();
+    await new Promise(resolve => this.#server.close(() => resolve()));
+  }
+}
+
+// Maven reads its proxy only from settings.xml (not the JVM's properties):
+// a settings file in the sandbox's own home, which Maven reads as the user's
+// once MAVEN_OPTS names that home (Java takes user.home from the account,
+// not from HOME, and the member's ~/.m2 is closed here).
+export function mavenSettings(url) {
+  const { hostname, port } = new URL(url);
+  const proxy = protocol => `<proxy><id>piagent-${protocol}</id><active>true</active><protocol>${protocol}</protocol><host>${hostname}</host><port>${port}</port><nonProxyHosts>localhost|127.0.0.1</nonProxyHosts></proxy>`;
+  return `<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"><proxies>${proxy('https')}${proxy('http')}</proxies></settings>\n`;
+}
+
+// Environment a command gets for the proxy at this URL: the variables
+// package managers read, and the JVM's (Gradle), which ignores them.
+export function proxyEnvironment(url, { mavenOpts = '', gradleOpts = '', mavenHome = null } = {}) {
+  const { hostname, port } = new URL(url);
+  const jvm = `-Dhttp.proxyHost=${hostname} -Dhttp.proxyPort=${port} -Dhttps.proxyHost=${hostname} -Dhttps.proxyPort=${port} -Dhttp.nonProxyHosts=localhost|127.0.0.1|::1`;
+  return {
+    HTTP_PROXY: url, HTTPS_PROXY: url, http_proxy: url, https_proxy: url, NO_PROXY: 'localhost,127.0.0.1,::1', no_proxy: 'localhost,127.0.0.1,::1',
+    npm_config_proxy: url, npm_config_https_proxy: url,
+    MAVEN_OPTS: [mavenOpts, jvm, mavenHome && `-Duser.home=${mavenHome}`].filter(Boolean).join(' '), GRADLE_OPTS: [gradleOpts, jvm].filter(Boolean).join(' '),
+  };
+}