@piagent/platform 1.17.0 → 1.19.0

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

@@ -11,19 +11,21 @@ import { searchForRole } from './web-search.mjs';
 import { shareGrant, releaseGrant } from './grant-share.mjs';
 import { managedThinkingLevels, nearestLevel } from './capabilities.mjs';
 import { nativeManagedModel, isVendor, piProvider, studioAPI, studioPath } from './native-catalog.mjs';
-import { repositoryFetchPlan, executeRepositoryFetch } from './repository-operation.mjs';
+import { fetchOriginTool } from './repository-operation.mjs';
 import { describeFailure, failureCode, failureText } from '../runtime/managed-failure.mjs';
-import { wrapRoleStreams } from './request-stream.mjs';
+import { enableCompanyTurnRetry, wrapRoleStreams } from './request-stream.mjs';
 import { runHelper } from './helper-run.mjs';
 import { askTool } from './member-questions.mjs';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { stageCompaction, compactEarly, backOffFailedCompaction } from './compaction.mjs';
-import { readPatchDigest, readPatchSnapshot, readChangedFiles } from './patch-snapshot.mjs';
-import { workflowPolicy, repositoryChecks, planTool, currentPlan, PLAN_ENTRY, workflowPrompt, RunProcess, completionGate, pendingBaseline, pendingPaths, processEditTools } from './workflow.mjs';
+import { readPatchDigest, readPatchSnapshot, readChangedFiles, readHead } from './patch-snapshot.mjs';
+import { memberTurn } from './continuation.mjs';
+import { workflowPolicy, repositoryChecks, planTool, currentPlan, PLAN_ENTRY, workflowPrompt, RunProcess, completionGate, pendingBaseline, pendingPaths, pendingHead, processEditTools } from './workflow.mjs';
 import { beforeDelegate } from './objections.mjs';
 import { HELPER_CALLS, HELPER_ROLES, helperRoles, helperPrompt, webPrompt, delegateDescription } from './helper-roles.mjs';
 import { loadAgentResources } from './agent-skills.mjs';
-import { restorePermission, permissionSetter, networkConfirmation } from './permission.mjs';
+import { restorePermission, permissionSetter } from './permission.mjs';
+import { commandTools, servicesPrompt } from './command-tools.mjs';
 
 const PROVIDER = 'agent_watch_managed';
 // Who the agent is: the model account may put another product's name in an
@@ -33,10 +35,10 @@ const BASE_PROMPT = 'You are Piagent, the company coding assistant. If an earlie
 // they name) are readable for reference; the sandbox keeps them read-only.
 const referencePrompt = home => ` The member may point you to folders outside the project for reference (an @path mention or a folder they name): read them with read, ls, grep and find. They are read-only: changes go in the project only. In those tools ~ is the member's home folder (${home}); in bash ~ is a private empty folder, so use absolute paths there.`;
 // Tests in the sandbox (tool-boundary.mjs, language-environment.mjs).
-const TEST_PROMPT = ' To run unit and integration tests, use bash. Installing packages (npm, pnpm, pip, uv, go, cargo, gradle, maven…) needs run_with_network once; the project\'s package caches are kept, so later runs work offline. '
+const TEST_PROMPT = ' To run unit and integration tests, use bash. Installing packages (npm, pnpm, pip, uv, go, cargo, gradle, maven…) needs run_with_network once; the project\'s package caches are kept, so later runs work offline. ./mvnw and ./gradlew reuse the Maven and Gradle they already unpacked on this Mac; Maven\'s files are under $MAVEN_USER_HOME and $GRADLE_USER_HOME, not ~/.m2 or ~/.gradle (closed here). '
   + (process.platform === 'linux'
-    ? 'A command without network reaches only the servers it starts itself, which end with it: start a test server and run the tests in one command; a database or service already running on this machine needs run_with_network. Docker is not available in the sandbox: ask the member to start those services.'
-    : 'Servers on localhost (a test\'s own server, a local database) are reachable, except while a local proxy runs (the error says so: then use run_with_network). Docker and the iOS Simulator are not available in the sandbox: ask the member to start those services or run those tests.');
+    ? 'A command without network reaches only the servers it starts itself, which end with it: start a test server and run the tests in one command; a database or service already running on this machine needs run_with_network.'
+    : 'Servers on localhost (a test\'s own server, a local database) are reachable, except while a local proxy runs (the error says so: then use run_with_network).');
 const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
 export function taskClass(text) {
   // Advisory hint only. Studio owns allowed models, budgets and run authority.
@@ -106,41 +108,12 @@ export class ManagedSession {
     const model = self.installModel(self.modelRuntime, preview);
     self.wrapStreams(self.modelRuntime, 'main');
     const customTools = processEditTools(self, self.boundary.tools(api));
-    customTools.push({name:'fetch_origin',label:'Fetch origin',description:'Request one approved GitHub origin fetch. Refreshes origin branches without changing working files. Does not expose credentials or allow arbitrary network commands.',
-      parameters:{type:'object',properties:{},additionalProperties:false},
-      execute:async(id,_args,signal,_update,ctx)=>{
-        const plan=await repositoryFetchPlan(self.boundary);
-        if(self.permission==='trusted-full-access'&&!signal?.aborted)return executeRepositoryFetch(self.boundary,plan,signal);
-        const {piApprovalBroker}=await import('../runtime/inspection/approval-broker.ts');
-        const decision=await piApprovalBroker.request({cwd:self.cwd,rawSessionId:self.session.sessionManager.getSessionId(),toolCallId:id,
-          action:{kind:'external-provider-action',preconditionClass:'runtime-only',toolName:'fetch_origin',rawAction:plan,
-            targetPaths:[self.cwd],provider:'github',urlOrigin:'https://github.com',requestedScope:'fetch-origin-once',
-            reason:`Fetch origin branches from ${plan.repository}`,riskClass:'low',allowConsequence:'Download origin branches once; keep the current branch and working files unchanged.',denyConsequence:'No network request or credential read.'},
-          terminalConfirm:()=>ctx?.ui?.confirm?.('Tải nhánh từ origin',`Tải các nhánh của ${plan.repository} về ${self.cwd} một lần.\n\nĐồng ý: chỉ tải nhánh; nhánh hiện tại và file đang làm không đổi.\nTừ chối: không gửi request mạng, không đọc thông tin đăng nhập.`)??Promise.resolve(false),
-          unavailableFallback:'terminal-confirm',recheck:()=>!signal?.aborted&&Boolean(self.grant)});
-        if(!decision.allowed||!decision.consume()||signal?.aborted)throw Error('managed-operation-denied');
-        return executeRepositoryFetch(self.boundary,plan,signal);
-      }});
+    customTools.push(fetchOriginTool(self));
     // With a research helper the web is its work: search results and pages
     // are read on its cheaper model, not in the main agent's context.
     if (!helperRoles(manifest).includes('research')) customTools.push(...self.webTools(self.modelRuntime, 'main'));
-    customTools.push({name:'run_with_network',label:'Run with network',description:'Run one shell command that needs the internet (package install, download, git pull of a public repository), 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.',
-      parameters:{type:'object',properties:{command:{type:'string',minLength:1,maxLength:4000},reason:{type:'string',minLength:1,maxLength:300},timeout:{type:'number',minimum:1,maximum:1800}},required:['command','reason'],additionalProperties:false},
-      execute:async(id,args,signal,onUpdate,ctx)=>{
-        // Bypass runs it without asking, unless it is one the member must confirm.
-        const confirm=await networkConfirmation(self,args.command);
-        const decision=confirm===null?{allowed:true,consume:()=>true}:await (await import('../runtime/inspection/approval-broker.ts')).piApprovalBroker.request({cwd:self.cwd,rawSessionId:self.session.sessionManager.getSessionId(),toolCallId:id,
-          action:{kind:'external-provider-action',preconditionClass:'runtime-only',toolName:'run_with_network',rawAction:{command:args.command},commandPreview:String(args.command),
-            targetPaths:[self.cwd],provider:'network',urlOrigin:null,requestedScope:'network-command-once',reason:(confirm==='ask'?String(args.reason):`Bypass still asks: ${confirm}. ${args.reason}`).slice(0,300),riskClass:'medium',
-            allowConsequence:'Run this exact command once, with internet access; a server it starts accepts connections while it runs.',denyConsequence:'The command does not run; the agent is told you declined.'},
-          terminalConfirm:()=>ctx?.ui?.confirm?.('Chạy lệnh có internet',`${args.command}\n\nLý do: ${args.reason}${confirm==='ask'?'':`\nBypass vẫn hỏi: ${confirm}`}\n\nĐồng ý: 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.\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.`)??Promise.resolve(false),
-          unavailableFallback:'terminal-confirm',recheck:()=>!signal?.aborted&&Boolean(self.grant)});
-        if(!decision.allowed||!decision.consume()||signal?.aborted)throw Error('managed-operation-denied');
-        let ok=false;
-        const before=await self.changedFiles();
-        try { const result=await self.boundary.invoke('bash',{command:args.command,...(args.timeout?{timeout:args.timeout}:{})},signal,onUpdate,ctx?.model,{network:true}); ok=!result?.isError; return result; }
-        finally { await self.claimChanges(before); await self.run?.afterTool('bash',args,ok,()=>self.digest()); await self.refreshReview(); }
-      }});
+    // Commands with network, and with Docker when this machine has an engine.
+    customTools.push(...commandTools(self));
     // Every helper role passes the tool's schema: Pi fixes a tool's schema
     // and description when the conversation opens, so a helper a Harness
     // saved later adds must already pass it. The system prompt, rebuilt each
@@ -160,7 +133,7 @@ export class ManagedSession {
     const agentsFiles = projectInstructions(self.cwd, self.boundary.repositoryTop);
     self.checks = repositoryChecks(agentsFiles, self.cwd, self.boundary.repositoryTop);
     // The Harness workflow (possibly changed on a later enrollment) adds its process to the prompt.
-    const loader = managedResourceLoader(api, { systemPrompt: () => BASE_PROMPT + referencePrompt(self.boundary.userHome) + TEST_PROMPT + webPrompt(helperRoles(manifest)) + helperPrompt(helperRoles(self.manifest)) + workflowPrompt(workflowPolicy(self.manifest), self.checks), agentsFiles,
+    const loader = managedResourceLoader(api, { systemPrompt: () => BASE_PROMPT + referencePrompt(self.boundary.userHome) + TEST_PROMPT + servicesPrompt(self.boundary) + webPrompt(helperRoles(manifest)) + helperPrompt(helperRoles(self.manifest)) + workflowPrompt(workflowPolicy(self.manifest), self.checks), agentsFiles,
       skills: self.resources.skills, prompts: self.resources.prompts, ...await inlineExtensions(api, sdk, self.cwd, terminalExtensions) });
     const settings = api.SettingsManager.inMemory({ retry: { enabled: false, provider: { maxRetries: 0 } }, cacheWarming: 'off', enableInstallTelemetry: false, enableAnalytics: false, enableSkillCommands: true });
     const manager = sessionManager ?? api.SessionManager.inMemory(self.cwd);
@@ -191,6 +164,7 @@ export class ManagedSession {
     self.extensionsResult = result.extensionsResult;
     self.session = result.session;
     self.session.managedExecution = true;
+    self.turnRetry = enableCompanyTurnRetry(self.session, settings);
     // The member's access for this conversation: ask first, or Bypass (permission.mjs).
     self.permission = restorePermission(manager); self.session.managedSetPermission = permissionSetter(self, manager);
     // A helper's receipt (its tokens, the patch it read) is for the member's
@@ -218,9 +192,10 @@ export class ManagedSession {
     };
     self.review = manager.getEntries().filter(e => e.type === 'custom' && e.customType === 'agent-watch-review').at(-1)?.data ?? null;
     const abort = self.session.abort.bind(self.session);
-    self.session.abort = async (...args) => { self.gateAbort?.abort(); return abort(...args); };
-    // One member message is one run, harness rounds included (checks, review,
-    // fixes after the answer): listeners hear "settled" once, when it ends.
+    self.session.abort = async (...args) => { self.gateAbort?.abort(); if (self.activePrompt) self.stopRequested = true; return abort(...args); };
+    // One member message is one turn, harness rounds included (checks, review,
+    // fixes after the answer, rounds that continue an unfinished checklist):
+    // listeners hear "settled" once, when it ends.
     const subscribe = self.session.subscribe.bind(self.session), listeners = self.listeners;
     self.session.subscribe = listener => {
       listeners.add(listener);
@@ -228,14 +203,8 @@ export class ManagedSession {
       return () => { listeners.delete(listener); off(); };
     };
     const prompt = self.session.prompt.bind(self.session);
-    self.session.prompt = async (text, options) => {
-      // An extension command (/bypass, /piagent-update) runs here, never as a turn.
-      if (/^\/\S/.test(text) && self.session.extensionRunner?.getCommand(text.slice(1).split(/\s/)[0])) return prompt(text, options);
-      // /skill:name, /command: the run sees what the member asked for in full.
-      text = self.resources.expand(text);
-      if (self.starting) await self.starting;
-      if (self.activePrompt) return prompt(text, options); // steering/follow-up keep the root
-      await self.refreshReview();
+    // One run: started for the round's request, closed with its report.
+    const runRound = async (text, deliver) => {
       const start = async () => {
         // The Harness (now possibly changed) decides which levels exist; ask
         // for the member's level, or the nearest one it offers.
@@ -281,14 +250,18 @@ export class ManagedSession {
           });
           self.run = new RunProcess(workflowPolicy(self.manifest), { request: text, complex: taskClass(text) === 'complex', checks: self.checks });
           // The files this conversation changed and has not settled: carried
-          // over from a turn that was cut, otherwise none yet.
+          // over from a turn that was cut, otherwise none yet. The code is
+          // compared with the commit the turn started from, so a commit made
+          // during the turn is still its change.
           const pending = pendingBaseline(manager);
           self.ownPaths = new Set(pending !== null ? pendingPaths(manager) : []);
+          self.base = (pending !== null ? pendingHead(manager) : null) ?? await readHead(self.boundary);
           self.run.startDigest = pending ?? await self.digest();
         } catch (error) { self.preflight = describeFailure('main', failureText(error)); }
         self.activePrompt = true;
       })();
       try { await self.starting; } finally { self.starting = null; }
+      const round = { result: undefined, preflight: !!self.preflight, planUpdated: false, changed: false };
       try {
         // The last request of a long conversation was refused as too large:
         // by the model (it no longer fits the window of the model it runs on
@@ -296,13 +269,16 @@ export class ManagedSession {
         // model) or by Studio (a body over 4 MiB, before a 1M-token window is
         // full). The older part is summarised first, so continuing fits.
         if (!self.preflight && self.refusedAsTooLong()) { try { await self.session.compact(); } catch { /* nothing to compact: the request says why */ } }
-        const result = await prompt(text, { ...options, expandPromptTemplates: false });
+        round.result = await deliver();
         if (self.run && !self.preflight) {
           self.gateAbort = new AbortController();
           try { await completionGate(self, self.run, self.gateAbort.signal); } catch { /* the answer stands; the report keeps what is known */ } finally { self.gateAbort = null; }
         }
-        return result;
+        return round;
       } finally {
+        // The round's model work is over: a member message now waits for the next round.
+        self.between = true;
+        Object.assign(round, { planUpdated: !!self.run?.planUpdated, changed: !!self.run?.changed });
         await Promise.allSettled([...self.helpers.values()]);
         // What a command left running in the background ends with the turn.
         try { await self.boundary.stopStrays(); } catch { /* best effort; the boundary stops them on close */ }
@@ -317,12 +293,25 @@ export class ManagedSession {
             catch (error) { if (!process) throw error; await self.broker.request('close'); }
             manager.appendCustomEntry('agent-watch-run', { run_id: self.grant.run_id, state: 'closed' });
           }
-        } finally {
-          self.grant = null; self.run = null; self.activePrompt = false; self.preflight = null;
-          self.notify({ type: 'agent_settled' });
-        }
+        // A run that could not be closed (the network or Agent Watch went away)
+        // ends the turn as failed; the run stays "active" here, so reopening
+        // the conversation recovers or abandons it.
+        } catch (error) { round.closeFailed = failureCode(failureText(error)) || 'close_failed'; }
+        finally { self.grant = null; self.run = null; self.preflight = null; }
       }
     };
+    self.session.prompt = async (text, options) => {
+      // An extension command (/bypass, /piagent-update) runs here, never as a turn.
+      if (/^\/\S/.test(text) && self.session.extensionRunner?.getCommand(text.slice(1).split(/\s/)[0])) return prompt(text, options);
+      // /skill:name, /command: the run sees what the member asked for in full.
+      text = self.resources.expand(text);
+      if (self.starting) await self.starting;
+      // Between two rounds no model runs: the message waits for the next one.
+      if (self.between) return new Promise((resolve, reject) => self.queued.push({ text, options, resolve, reject }));
+      if (self.activePrompt) return prompt(text, options); // steering/follow-up keep the root
+      await self.refreshReview();
+      return memberTurn(self, { manager, prompt, runRound }, text, () => prompt(text, { ...options, expandPromptTemplates: false }));
+    };
     // Native ! commands use the same worker boundary as model bash calls.
     self.session.executeBash = async command => {
       try {
@@ -432,14 +421,14 @@ export class ManagedSession {
   // Whether this conversation changed code, and whether a check ran on it,
   // look only at the files it changed: another conversation (or the member)
   // changing other files in the same folder is not this run's change.
-  async changeDigest() { return readPatchDigest(this.boundary, this.ownPaths); }
+  async changeDigest() { return readPatchDigest(this.boundary, this.ownPaths, this.base); }
   async folderDigest() { try { return await readPatchDigest(this.boundary); } catch { return null; } }
   // What a reviewer reads: this conversation's files; before it changed any,
   // the whole folder (the member's own changes, asked to be reviewed).
   reviewScope() { return this.ownPaths.size ? this.ownPaths : null; }
-  async patchSnapshot() { return readPatchSnapshot(this.boundary, this.reviewScope()); }
-  async patchDigest() { return readPatchDigest(this.boundary, this.reviewScope()); }
-  async changedFiles() { try { return await readChangedFiles(this.boundary); } catch { return null; } }
+  async patchSnapshot() { return readPatchSnapshot(this.boundary, this.reviewScope(), this.base); }
+  async patchDigest() { return readPatchDigest(this.boundary, this.reviewScope(), this.base); }
+  async changedFiles() { try { return await readChangedFiles(this.boundary, this.base); } catch { return null; } }
   // A write or edit names its file; a command, the files it changed.
   claimPath(raw) {
     if (typeof raw !== 'string' || !raw) return;

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

@@ -8,6 +8,7 @@ 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 { containerEngine, engineEnvironment } from './container-engine.mjs';
 import { BWRAP, bubblewrapArgs, credentialFiles, referenceFolders } from './linux-sandbox.mjs';
 import { agentWatchDataDirectory } from './store.mjs';
 
@@ -38,7 +39,7 @@ function referenceRules(home, roots) {
 (deny file-read-data file-read-xattr (require-all (require-any (regex #"^${pattern(home)}/\\.") (subpath ${literal(path.join(home, 'Library'))}))${opened}))`;
 }
 
-export function managedSeatbelt({ cwd, sdkRoot, runtimeRoot, temporary, node, denied = [], readOnly = false, repository = [], gitDirs = [], toolchains = [], developer = [], browsers = [], network = false, references = null, skills = [], caches = [], loopback = true, license = null }) {
+export function managedSeatbelt({ cwd, sdkRoot, runtimeRoot, temporary, node, denied = [], readOnly = false, repository = [], gitDirs = [], toolchains = [], developer = [], browsers = [], network = false, references = null, skills = [], caches = [], loopback = true, license = null, docker = null }) {
   // 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.
@@ -97,7 +98,8 @@ ${network ? `(allow network-outbound (remote ip))
 (allow system-socket)
 (allow mach-lookup (global-name "com.apple.dnssd.service") (global-name "com.apple.trustd.agent") (global-name "com.apple.SystemConfiguration.configd"))
 (allow mach-lookup (global-name "com.apple.SecurityServer") (global-name "com.apple.ocspd"))
-(allow file-read* (subpath "/private/var/db/mds") (literal "/Library/Keychains/System.keychain") (subpath "/Library/Security/Trust Settings"))` : loopback ? '(allow network-outbound (remote ip "localhost:*"))' : ''}
+(allow file-read* (subpath "/private/var/db/mds") (literal "/Library/Keychains/System.keychain") (subpath "/Library/Security/Trust Settings"))${docker ? `
+(allow network-outbound (literal ${literal(docker)}))` : ''}` : loopback ? '(allow network-outbound (remote ip "localhost:*"))' : ''}
 ${denied.map(root => `(deny file-read* file-write* (require-all (subpath ${literal(root)})${skills.filter(dir => inside(dir, root) && dir !== root).map(dir => ` (require-not (subpath ${literal(dir)}))`).join('')}))`).join('\n')}
 (deny file-read* file-read-metadata file-write* (require-all (require-any (regex #"(^|/)(\\.env([./]|$)|credentials([./]|$)|\\.npmrc$|\\.netrc$)") (regex #"/\\.[^/]+/auth\\.json$") ${projectRoots.map(root => `(literal ${literal(path.join(root, 'auth.json'))})`).join(' ')})
   (require-not (regex #"(^|/)\\.env\\.(example|sample|template|dist|defaults)$"))))
@@ -227,6 +229,8 @@ export class ManagedToolBoundary {
     const toolchains = userToolchains(userHome, this.node), developer = developerTools(), browsers = playwrightBrowsers(userHome);
     const languages = languageEnvironment({ userHome, repositoryTop: this.repositoryTop, home: this.home });
     this.packageCache = languages.cache;
+    // The Docker engine, for commands the member approves (run_with_docker).
+    this.engine = readOnly ? null : containerEngine({ userHome });
     // A skill folder opens for reading only inside the agent folders (.claude,
     // .codex, .pi, .agents) or outside the home folder's hidden entries, and
     // never when it holds a closed folder (a link to ~/.ssh, the home folder).
@@ -245,7 +249,7 @@ export class ManagedToolBoundary {
     if (this.linux) {
       const references = referenceFolders(userHome).filter(dir => !narrowed.some(root => inside(dir, root) || inside(root, dir)));
       const empty = path.join(this.temporary, 'empty'); fs.writeFileSync(empty, '', { mode: 0o400 });
-      this.linuxBase = { ...base, toolchains: [...base.toolchains, ...base.browsers], references, empty };
+      this.linuxBase = { ...base, toolchains: [...base.toolchains, ...base.browsers], references, empty, engineRoots: this.engine?.readRoots ?? [] };
       this.referenceCredentials = credentialFiles(references, { limit: 30_000 });
       this.projectCredentials = { at: 0, files: [] };
     } else {
@@ -254,11 +258,14 @@ export class ManagedToolBoundary {
       this.isolatedProfile = managedSeatbelt({ ...base, references: userHome, loopback: false });
       this.proxyPorts = proxyPorts ?? localProxyPorts(); this.proxyCheck = { at: 0, listening: Promise.resolve(false) };
       this.networkProfile = readOnly ? null : managedSeatbelt({ ...base, network: true });
+      // An approved network command that also reaches the Docker engine's socket.
+      this.dockerProfile = this.engine ? managedSeatbelt({ ...base, network: true, docker: this.engine.socket, toolchains: [...base.toolchains, ...this.engine.readRoots] }) : null;
     }
     // 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, browsers, languages,
       identity: identity !== undefined ? identity : gitIdentity(this.git, this.cwd) });
+    if (this.engine) this.environment.docker = { ...this.environment.network, ...engineEnvironment(this.engine, this.home) };
     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'].includes(name) && (name !== 'bash' || commands)) : [...TOOL_NAMES];
@@ -274,7 +281,9 @@ export class ManagedToolBoundary {
       this.#tail = run.catch(() => {}); return run;
     } }));
   }
-  async invoke(name, args, signal, onUpdate, model, { network = false } = {}) {
+  async invoke(name, args, signal, onUpdate, model, { network = false, docker = false } = {}) {
+    if (docker && !this.engine) throw new Error('managed-tool-unavailable');
+    network ||= docker;
     if (this.#closed || !this.allowed.includes(name) || network && (name !== 'bash' || !this.networkAllowed)) 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');
@@ -283,14 +292,14 @@ export class ManagedToolBoundary {
     if (name !== 'bash' && typeof args?.path === 'string' && /^@?~(\/|$)/.test(args.path)) args = { ...args, path: this.userHome + args.path.replace(/^@?~/, '') };
     if (!this.linux && !network && Date.now() - this.proxyCheck.at > 5000) this.proxyCheck = { at: Date.now(), listening: localProxyListening(this.proxyPorts) };
     const isolated = !this.linux && !network && await this.proxyCheck.listening;
-    const message = JSON.stringify({ name, args, ...(network ? { network: true } : {}), ...(isolated ? { isolated: true } : {}), model: model ? { input: model.input, inputLimits: model.inputLimits } : undefined }) + '\n';
+    const message = JSON.stringify({ name, args, ...(network ? { network: true } : {}), ...(isolated ? { isolated: true } : {}), ...(docker ? { docker: true } : this.engine ? { engine: 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 [sandbox, sandboxArgs] = this.linux ? [BWRAP, this.bubblewrap(network)]
-        : ['/usr/bin/sandbox-exec', ['-p', network ? this.networkProfile : isolated ? this.isolatedProfile : this.profile]];
+      const [sandbox, sandboxArgs] = this.linux ? [BWRAP, this.bubblewrap(network, docker)]
+        : ['/usr/bin/sandbox-exec', ['-p', docker ? this.dockerProfile : network ? this.networkProfile : isolated ? this.isolatedProfile : this.profile]];
       const child = spawn(sandbox, [...sandboxArgs, this.node, workerPath, this.sdkPath, this.cwd], {
         cwd: this.cwd, detached: true, stdio: ['pipe', 'pipe', 'pipe'],
-        env: network ? this.environment.network : this.environment.offline,
+        env: docker ? this.environment.docker : network ? this.environment.network : this.environment.offline,
       });
       this.#children.add(child);
       const decoder = new StringDecoder('utf8');
@@ -351,11 +360,13 @@ export class ManagedToolBoundary {
   }
   // bubblewrap arguments for one command: credential files of the project are
   // looked for again every 15 seconds (a file the member just added).
-  bubblewrap(network) {
+  bubblewrap(network, docker = false) {
     if (Date.now() - this.projectCredentials.at > 15_000)
       this.projectCredentials = { at: Date.now(), files: credentialFiles([this.cwd, ...this.linuxBase.repository]) };
     const credentials = [...this.projectCredentials.files, ...(network ? [] : this.referenceCredentials)];
-    return bubblewrapArgs({ ...this.linuxBase, references: network ? [] : this.linuxBase.references, network, credentials });
+    const { engineRoots, ...base } = this.linuxBase;
+    return bubblewrapArgs({ ...base, references: network ? [] : base.references, network, credentials,
+      ...(docker ? { docker: this.engine.socket, toolchains: [...base.toolchains, ...engineRoots] } : {}) });
   }
   // Processes a command left running (`nohup … &`, a detached child) outlive
   // it with the marker in their environment. They are stopped when a turn ends

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

@@ -11,7 +11,7 @@ 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, isolated = false;
+let active = false, controller, network = false, isolated = false, docker = false, engine = false;
 const emit = value => process.stdout.write(JSON.stringify(value) + '\n');
 const input = createInterface({ input: process.stdin });
 input.on('line', async line => {
@@ -19,7 +19,7 @@ input.on('line', async line => {
     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; isolated = message.isolated === true;
+    active = true; controller = new AbortController(); network = message.network === true; isolated = message.isolated === true; docker = message.docker === true; engine = message.engine === 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));
@@ -30,7 +30,7 @@ input.on('line', async line => {
     // 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, isolated }) }); }
+  } 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(); } }
 });
 process.stdin.on('end', () => controller?.abort());

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

@@ -76,24 +76,26 @@ export function isCheckCommand(command, declared = []) {
 // update_plan: the agent's checklist, kept as a session entry so it survives
 // compaction and "continue", and shown to the member beside the conversation.
 export const PLAN_ENTRY = 'agent-watch-plan';
-const STATUS = ['pending', 'in_progress', 'completed'];
+// "deferred": left for later at the member's word, or no longer needed: not
+// done, not open either.
+const STATUS = ['pending', 'in_progress', 'completed', 'deferred'];
 export function normalizePlan(args) {
   const plan = Array.isArray(args?.plan) ? args.plan : [];
   if (plan.length < 1 || plan.length > 30 || plan.some(p => typeof p?.step !== 'string' || !p.step.trim() || p.step.length > 200 || !STATUS.includes(p.status)))
-    throw Error('managed-plan-invalid: send 1 to 30 steps, each {step, status} with status pending, in_progress or completed.');
+    throw Error('managed-plan-invalid: send 1 to 30 steps, each {step, status} with status pending, in_progress, completed or deferred.');
   if (plan.filter(p => p.status === 'in_progress').length > 1) throw Error('managed-plan-invalid: mark at most one step in_progress.');
   return { plan: plan.map(p => ({ step: p.step.trim(), status: p.status })), explanation: typeof args.explanation === 'string' ? args.explanation.slice(0, 300) : '' };
 }
 export function currentPlan(manager) {
   return manager.getEntries().filter(e => e.type === 'custom' && e.customType === PLAN_ENTRY).at(-1)?.data ?? null;
 }
-export const unfinished = plan => !!plan?.plan?.some(p => p.status !== 'completed');
+export const unfinished = plan => !!plan?.plan?.some(p => p.status === 'pending' || p.status === 'in_progress');
 export function planText(plan) {
-  return plan?.plan?.map((p, i) => `${i + 1}. [${p.status === 'completed' ? 'x' : p.status === 'in_progress' ? '>' : ' '}] ${p.step}`).join('\n') ?? '';
+  return plan?.plan?.map((p, i) => `${i + 1}. [${p.status === 'completed' ? 'x' : p.status === 'in_progress' ? '>' : p.status === 'deferred' ? '-' : ' '}] ${p.step}`).join('\n') ?? '';
 }
 export function planTool(run) {
   return { name: 'update_plan', label: 'Plan',
-    description: 'Keep a short checklist for work with several steps. Send the whole list each time; mark the step you work on in_progress and finished steps completed. The member sees the checklist next to the conversation.',
+    description: 'Keep a short checklist for work with several steps. Send the whole list each time; mark the step you work on in_progress and finished steps completed. Mark a step deferred when the member asked to leave it for later or it is no longer needed, and say why in your answer; never mark completed a step you did not do. The member sees the checklist next to the conversation.',
     parameters: { type: 'object', properties: { explanation: { type: 'string', maxLength: 300 }, plan: { type: 'array', minItems: 1, maxItems: 30,
       items: { type: 'object', properties: { step: { type: 'string', minLength: 1, maxLength: 200 }, status: { type: 'string', enum: STATUS } }, required: ['step', 'status'], additionalProperties: false } } },
       required: ['plan'], additionalProperties: false },
@@ -108,7 +110,7 @@ export function planTool(run) {
 // The guidance a policy adds to the main agent's system prompt.
 export function workflowPrompt(policy, checks) {
   const lines = [];
-  if (policy.plan !== 'off') lines.push(`- Plan: for work with several steps keep a checklist with update_plan and update it as you go.${policy.plan === 'require' ? ' For a complex task, file edits are refused until a plan exists, and a checklist left unfinished comes back to you before the turn ends.' : ''}`);
+  if (policy.plan !== 'off') lines.push(`- Plan: for work with several steps keep a checklist with update_plan and update it as you go. When the member asks for several items (plans, files, tickets), put every item in the checklist and work through all of them; do not end your turn to report between items.${policy.plan === 'require' ? ' For a complex task, file edits are refused until a plan exists. A checklist left with pending steps sends you back to the next one until every step is completed or deferred: if you cannot go on without the member, ask with ask_user. Mark a step deferred only when the member asked to leave it for later or it is no longer needed; never mark completed a step you did not do.' : ''}`);
   if (policy.verify !== 'off') {
     const list = checks.commands.length ? `${checks.commands.map(c => '`' + c + '`').join(', ')}${checks.source === 'detected' ? ' (detected; the repository declares none in AGENTS.md "## Checks")' : ''}` : 'none declared: choose the tests, type check or build that cover the change';
     lines.push(`- Verify: after changing code, run the repository checks that cover the change and fix failures before you finish. Repository checks: ${list}.${policy.verify === 'require' ? ' The turn does not end until a check has passed on the final code.' : ''}`);
@@ -182,6 +184,11 @@ export function pendingBaseline(manager) {
   return last && last.settled === false && typeof last.digest === 'string' ? last.digest : null;
 }
 // The files that unsettled turn changed: its digest covers only those.
+// The commit that unsettled turn started from: its digest is taken against it.
+export function pendingHead(manager) {
+  const last = manager.getEntries().filter(e => e.type === 'custom' && e.customType === BASELINE_ENTRY).at(-1)?.data;
+  return last?.settled === false && typeof last.head === 'string' ? last.head : null;
+}
 export function pendingPaths(manager) {
   const last = manager.getEntries().filter(e => e.type === 'custom' && e.customType === BASELINE_ENTRY).at(-1)?.data;
   return last?.settled === false && Array.isArray(last.paths) ? last.paths.filter(p => typeof p === 'string' && p).slice(0, 2000) : [];
@@ -195,7 +202,7 @@ export const PLAN_REFUSALS = 3;
 export class RunProcess {
   constructor(policy, { request, complex, checks }) {
     Object.assign(this, { policy, request: String(request ?? ''), complex, checks, startDigest: null, mutations: 0, lastCheck: null, checksRun: 0, checksFailed: 0,
-      reviews: 0, blocking: 0, blockingOpen: 0, fixLoops: 0, planUpdated: false, planRefusals: new Set(), planSkipped: false, planAsked: false, unplannedChange: false,
+      reviews: 0, blocking: 0, blockingOpen: 0, fixLoops: 0, planUpdated: false, planRefusals: new Set(), planSkipped: false, unplannedChange: false,
       unknownTools: 0, changed: false, verified: false, reviewed: false, reviewUnavailable: false, outcome: null, legacyOutcome: null,
       // Helper objections to a brief, disagreements handed to the member, the
       // claims verify marked failed, and where the harness last sent the
@@ -240,7 +247,8 @@ export class RunProcess {
   // disagreements handed to the member ("disputed"); older versions get the
   // outcome the run would have had without that.
   report(plan, version = 1) {
-    const steps = this.planUpdated || unfinished(plan) ? plan?.plan ?? [] : [];
+    // Steps left for later are not this run's work: Studio reads done/steps.
+    const steps = (this.planUpdated || unfinished(plan) ? plan?.plan ?? [] : []).filter(p => p.status !== 'deferred');
     const fallback = this.changed ? 'interrupted' : 'no_change', count = n => Math.min(n, 1000);
     return { version, policy: { plan: this.policy.plan, verify: this.policy.verify, review: this.policy.review }, changed: this.changed,
       plan_steps: steps.length, plan_done: steps.filter(p => p.status === 'completed').length, checks: count(this.checksRun), checks_failed: count(this.checksFailed),
@@ -346,16 +354,8 @@ export async function completionGate(managed, run, signal) {
       run.claimsDone = true; run.disputes.push({ source: 'verify' });
       await note(`Harness: the main agent and the verify subagent still disagree after two rounds; the member decides.\n${list}`, { phase: 'dispute', role: 'verify', claims });
     }
-    // Plan "require": a checklist written in this turn is brought up to date
-    // once before the turn ends (models often write it and never touch it again).
-    const plan = currentPlan(session.sessionManager);
-    if (run.changed && policy.plan === 'require' && run.planUpdated && !run.planAsked && unfinished(plan)) {
-      run.planAsked = true;
-      const open = plan.plan.filter(p => p.status !== 'completed').length;
-      await send(`Harness process check: your checklist still has ${open} step(s) not marked completed:\n${planText(plan)}\nUpdate it with update_plan so it shows what was done. For a step you did not do, do it or say plainly why it is left.`,
-        { phase: 'plan', planOpen: open });
-      continue;
-    }
+    // Plan "require": a checklist left with open steps is the next round's
+    // (continuation.mjs), after this run's checks and review.
     // An objection no corrected brief followed is answered to the member, once.
     const open = run.objections.filter(o => !o.answered && !o.disputed);
     if (open.length && !run.objectionsAsked) {
@@ -374,10 +374,10 @@ export async function completionGate(managed, run, signal) {
     : policy.verify !== 'off' && !run.verified ? 'unverified' : run.reviewUnavailable ? 'review_unavailable' : policy.review !== 'off' && !run.reviewed ? 'unreviewed' : 'clean';
   run.outcome = run.legacyOutcome !== 'interrupted' && run.disputes.length ? 'disputed' : run.legacyOutcome;
   const settled = run.outcome !== 'interrupted';
-  session.sessionManager.appendCustomEntry(BASELINE_ENTRY, { digest: settled ? digest : run.startDigest, settled, outcome: run.outcome,
+  session.sessionManager.appendCustomEntry(BASELINE_ENTRY, { digest: settled ? digest : run.startDigest, settled, outcome: run.outcome, ...(managed.base ? { head: managed.base } : {}),
     ...(settled ? {} : { paths: [...(managed.ownPaths ?? [])].slice(0, 2000) }) });
   if (!run.changed && !run.disputes.length) return;
-  const finalPlan = currentPlan(session.sessionManager), planOpen = run.planUpdated ? finalPlan?.plan?.filter(p => p.status !== 'completed').length ?? 0 : 0;
+  const finalPlan = currentPlan(session.sessionManager), planOpen = run.planUpdated ? finalPlan?.plan?.filter(p => p.status === 'pending' || p.status === 'in_progress').length ?? 0 : 0;
   const status = { verified: run.verified, reviewed: run.reviewed, blockingOpen: run.blockingOpen, checks: run.checksRun, fixLoops: run.fixLoops,
     ...(planOpen ? { planOpen } : {}), ...(run.planSkipped ? { planSkipped: true } : {}), ...(run.disputes.length ? { disputes: run.disputes.length } : {}), ...(run.changed ? {} : { unchanged: true }) };
   const words = [...(run.changed ? [run.verified ? 'a check passed on the final code' : policy.verify === 'off' ? null : 'no check passed on the final code',

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "type": "module",
   "private": true,
   "license": "MIT",