@piagent/platform 1.8.0 → 1.9.1

package/packages/piagent-core/extensions/policy-core.js

@@ -1199,7 +1199,7 @@ export function evaluateExecPolicyCore(command, options) {
     for (const pattern of policy.blockedCommandPatterns ?? []) {
       if (!legacyPatternMatchesSegment(pattern, words)) continue;
       matches.push(`forbid:legacy:${pattern}`);
-      reasons.push(`Blocked by legacy policy pattern: ${pattern}`);
+      reasons.push(`Blocked: the command runs ${pattern}, which the project policy forbids`);
     }
 
     const nested = extractNestedCommands(braceText, words);
@@ -1242,7 +1242,7 @@ export function evaluateExecPolicyCore(command, options) {
   };
   for (const pattern of policy.requireConfirmationPatterns ?? []) {
     if (segments.some((entry) => confirmationPatternMatches(pattern, entry.words))) {
-      reasons.push(`Confirmation required by legacy policy pattern: ${pattern}`);
+      reasons.push(`Confirmation required: the command runs ${pattern}`);
       break;
     }
   }

package/packages/piagent-core/extensions/source-checkout-paths.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { extractShellPathCandidates, normalizePathCandidate } from "./policy-core.js";
+import { normalizeRelative } from "./shell-reach.ts";
+
+// Where a path lands relative to the external source checkouts granted to this
+// session (read-only roots under the shared cache).
+
+function inside(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+export function grantedSourceCheckoutRootForPath(cwd: string, candidate: string, roots: string[]): string | undefined {
+  if (roots.length === 0) return undefined;
+  const absolute = path.resolve(cwd, normalizePathCandidate(candidate));
+  let canonical: string;
+  try {
+    canonical = fs.realpathSync.native(absolute);
+  } catch {
+    return undefined;
+  }
+  return roots.find((root) => inside(root, canonical));
+}
+
+// A shell command can name a file it is about to create. realpath fails for that
+// file, so resolve its nearest existing parent instead; otherwise a new file in
+// the cache, spelled through an alias such as /var for /private/var, escapes
+// both the text match and the realpath match.
+function shellTargetInsideGrantedSourceCheckout(cwd: string, candidate: string, roots: string[]): boolean {
+  if (grantedSourceCheckoutRootForPath(cwd, candidate, roots)) return true;
+  let parent = path.resolve(cwd, normalizePathCandidate(candidate));
+  const rest: string[] = [];
+  while (path.dirname(parent) !== parent) {
+    rest.unshift(path.basename(parent));
+    parent = path.dirname(parent);
+    let canonical: string;
+    try { canonical = fs.realpathSync.native(parent); } catch { continue; }
+    const target = path.join(canonical, ...rest);
+    return roots.some((root) => inside(root, target));
+  }
+  return false;
+}
+
+export function shellTouchesGrantedSourceCheckout(cwd: string, command: string, roots: string[]): boolean {
+  if (roots.length === 0) return false;
+  for (const root of roots) {
+    const relative = path.relative(cwd, root).split(path.sep).join("/");
+    if (command.includes(root) || (relative && command.includes(relative))) return true;
+  }
+  return extractShellPathCandidates(command)
+    .some((candidate) => shellTargetInsideGrantedSourceCheckout(cwd, normalizeRelative(cwd, candidate) ?? candidate, roots));
+}

package/packages/piagent-core/managed/broker-client.mjs

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class ManagedBrokerClient {
+  #child; #pending = new Map(); #tail = Promise.resolve(); #closed = false;
+  constructor({ executable, profileID }) {
+    if (!path.isAbsolute(executable) || fs.realpathSync(executable) !== executable || !/^[a-f0-9]{64}$/.test(profileID)) throw Error('managed-broker-binding-invalid');
+    this.#child = spawn(executable, ['managed-broker', '--profile', profileID], {
+      stdio: ['pipe', 'pipe', 'pipe'], env: { PATH: '/usr/bin:/bin', LANG: 'en_US.UTF-8' },
+    });
+    let pending = ''; const decoder = new StringDecoder('utf8');
+    const fail = () => { this.#closed = true; for (const item of this.#pending.values()) { clearTimeout(item.timer); item.reject(Error('managed-broker-disconnected')); } this.#pending.clear(); };
+    this.#child.stdin.on('error', fail); this.#child.on('error', fail); this.#child.on('close', fail);
+    this.#child.stderr.on('data', () => {});
+    this.#child.stdout.on('data', chunk => {
+      pending += decoder.write(chunk);
+      if (Buffer.byteLength(pending) > 2 * 1024 * 1024) { this.#child.kill(); fail(); return; }
+      for (;;) {
+        const end = pending.indexOf('\n'); if (end < 0) break;
+        const line = pending.slice(0, end); pending = pending.slice(end + 1);
+        try {
+          const result = JSON.parse(line), item = this.#pending.get(result.id);
+          if (!item) throw Error('unexpected-broker-response');
+          clearTimeout(item.timer); this.#pending.delete(result.id);
+          if (result.error) item.reject(Error(`managed-broker:${String(result.error).replace(/[^a-zA-Z_]/g, '').slice(0, 80)}`));
+          else item.resolve(result.result);
+        } catch { this.#child.kill(); fail(); }
+      }
+    });
+  }
+  request(action, args = {}) {
+    const next = this.#tail.then(() => new Promise((resolve, reject) => {
+      if (this.#closed) { reject(Error('managed-broker-disconnected')); return; }
+      const id = randomUUID();
+      const timer = setTimeout(() => { this.#child.kill(); reject(Error('managed-broker-timeout')); }, 25000);
+      this.#pending.set(id, { resolve, reject, timer });
+      this.#child.stdin.write(JSON.stringify({ ...args, id, action }) + '\n');
+    }));
+    this.#tail = next.catch(() => {}); return next;
+  }
+  async dispose() {
+    if (this.#closed) return;
+    try { await this.request('close'); } catch {}
+    this.#child.stdin.end(); this.#child.kill(); this.#closed = true;
+  }
+}

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

@@ -0,0 +1,28 @@
+import { nativeManagedModel, piProvider } from './native-catalog.mjs';
+export const THINKING = ['off','minimal','low','medium','high','xhigh','max'];
+export function nativeThinkingLevels(model) {
+  if (!model?.reasoning) return ['off'];
+  const mapping=model.thinkingLevelMap??{};
+  return THINKING.filter(level=>mapping[level]!==null && (!['xhigh','max'].includes(level)||mapping[level]!==undefined));
+}
+// A selected level must work for the current main route and at least one
+// permitted candidate for every enabled helper. Studio rechecks availability
+// and policy on run creation; this is capability UI, not an admission promise.
+export function managedThinkingLevels(manifest, runtime, main) {
+  // A role whose level the Harness fixes does not narrow the member's choice.
+  const roles=Object.entries(manifest.harness.configuration).filter(([name,r])=>r&&Array.isArray(r.model_ids)&&(name==='main'||r.effort==null)).map(([,r])=>r);
+  return nativeThinkingLevels(main).filter(level=>(!Array.isArray(manifest.thinking_levels)||manifest.thinking_levels.includes(level)) && roles.every(role=>role.model_ids.some(id=>{
+    const item=manifest.models.find(m=>m.id===id);
+    if(!item)return false;
+    const native=nativeManagedModel(runtime,piProvider(item.owned_by),item.provider_model_id);
+    return native && nativeThinkingLevels(native).includes(level);
+  })));
+}
+
+// Pi's rule for a level a model lacks: the next deeper one it has, else the
+// next shallower one. Without a list every level stands.
+export function nearestLevel(level, allowed) {
+  if (!Array.isArray(allowed) || allowed.length === 0 || allowed.includes(level)) return level;
+  const order = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'], at = Math.max(0, order.indexOf(level));
+  return order.slice(at).find(l => allowed.includes(l)) ?? order.slice(0, at).reverse().find(l => allowed.includes(l)) ?? allowed[0];
+}

package/packages/piagent-core/managed/client-agent.mjs

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+
+// How Piagent names itself to Studio on every company request, so Studio's
+// reports show the tool and its version ("piagent/1.9.1").
+const version = JSON.parse(fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version;
+export const CLIENT_AGENT = `piagent/${version}`;

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

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { failureCode } from '../runtime/managed-failure.mjs';
+import { currentPlan, unfinished, planText } from './workflow.mjs';
+
+// One message longer than a summary part (a pasted log) keeps its start and
+// end for the summary; the transcript itself is unchanged.
+function clip(message, tokens) {
+  const keep = tokens * 2, cut = text => text.length <= 2 * keep ? text : `${text.slice(0, keep)}\n[… ${text.length - 2 * keep} characters left out of this summary …]\n${text.slice(-keep)}`;
+  if (typeof message.content === 'string') return { ...message, content: cut(message.content) };
+  if (!Array.isArray(message.content)) return message;
+  return { ...message, content: message.content.map(part => part.type === 'text' ? { ...part, text: cut(part.text) } : part.type === 'thinking' ? { ...part, thinking: cut(part.thinking ?? '') } : part) };
+}
+function addUsage(a, b) {
+  const sum = (x, y) => (x ?? 0) + (y ?? 0);
+  return { ...a, input: sum(a.input, b.input), output: sum(a.output, b.output), cacheRead: sum(a.cacheRead, b.cacheRead), cacheWrite: sum(a.cacheWrite, b.cacheWrite),
+    totalTokens: sum(a.totalTokens, b.totalTokens), cost: Object.fromEntries(Object.keys(a.cost ?? {}).map(k => [k, sum(a.cost[k], b.cost?.[k])])) };
+}
+
+// Pi summarises everything older than the kept tail in one request. A
+// conversation can be longer than the window of the model a run uses now
+// (the harness moved from a 1M-token model to a 272k one, or Auto fell
+// back), and that request is then refused, so the conversation could never
+// shrink again. Such a history is summarised in parts that fit, each part
+// updating the summary of the parts before.
+export async function stageCompaction(session, api, sdk) {
+  const whole = session._runDefaultCompaction?.bind(session);
+  if (!whole || !session._summarizationRetryCallbacks) throw Error('managed-sdk-version-unqualified');
+  const { computeFileLists, formatFileOperations } = await import(pathToFileURL(path.join(sdk, 'dist/core/compaction/utils.js')));
+  // An unfinished plan is kept word for word: the summary would lose its steps.
+  const withPlan = result => {
+    const plan = currentPlan(session.sessionManager);
+    return unfinished(plan) ? { ...result, summary: `${result.summary}\n\nCurrent plan (kept verbatim; keep it up to date with update_plan):\n${planText(plan)}` } : result;
+  };
+  session._runDefaultCompaction = async (preparation, model, apiKey, headers, instructions, signal, env, reason) => {
+    const { settings, previousSummary } = preparation, room = model.contextWindow - settings.reserveTokens;
+    const history = [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages];
+    const size = history.reduce((n, m) => n + api.estimateTokens(m), 0) + Math.ceil((previousSummary?.length ?? 0) / 4);
+    if (size + 4096 <= room) {
+      try { return withPlan(await whole(preparation, model, apiKey, headers, instructions, signal, env, reason)); }
+      // Token estimates are rough, and Studio takes at most 4 MiB per body:
+      // a single request refused as too large is retried in parts.
+      catch (error) { if (signal?.aborted || !['upstream_request_rejected', 'request_too_large'].includes(failureCode(error?.message))) throw error; }
+    }
+    // Half the window per part leaves room for dense text (Vietnamese, code),
+    // the previous summary and the answer.
+    const budget = Math.max(8192, Math.floor(room / 2) - settings.reserveTokens), parts = [];
+    for (const message of history) {
+      const fitted = clip(message, budget), tokens = api.estimateTokens(fitted), part = parts.at(-1);
+      if (part && part.tokens + tokens <= budget) { part.messages.push(fitted); part.tokens += tokens; }
+      else parts.push({ messages: [fitted], tokens });
+    }
+    let summary = previousSummary, usage;
+    for (const part of parts) {
+      const result = await api.generateSummaryWithUsage(part.messages, model, settings.reserveTokens, apiKey, headers, signal, instructions, summary,
+        session.thinkingLevel, session.agent.streamFunction, env, session.settingsManager.getRetrySettings(), session._summarizationRetryCallbacks({ source: 'compaction', reason }), undefined);
+      summary = result.text; usage = usage ? addUsage(usage, result.usage) : result.usage;
+    }
+    const { readFiles, modifiedFiles } = computeFileLists(preparation.fileOps);
+    return withPlan({ summary: summary + formatFileOperations(readFiles, modifiedFiles), firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore, usage, details: { readFiles, modifiedFiles } });
+  };
+}

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

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ManagedToolBoundary } from './tool-boundary.mjs';
+import { ensureSearchTools } from './toolchain.mjs';
+import { nativeManagedModel, piProvider } from './native-catalog.mjs';
+import { fetchPublicPage } from './web-fetch.mjs';
+
+// `piagent studio --doctor`: what a company session needs on THIS machine,
+// checked with the real sandbox and the real Agent Watch broker, without
+// sending any model request. Run after installing on a new machine, or when
+// tools misbehave. Required checks decide the exit code; optional ones only
+// report what daily coding may miss (a compiler, Python, git identity).
+const text = result => (result?.content ?? []).filter(part => part.type === 'text').map(part => part.text).join('\n').trim();
+const first = value => String(value ?? '').split('\n')[0].slice(0, 160);
+
+export async function runDoctor({ sdkRoot, origin, broker, network = true }) {
+  const results = [];
+  const check = async (label, required, run) => {
+    try { results.push({ label, required, ok: true, detail: first(await run()) }); }
+    catch (error) { results.push({ label, required, ok: false, detail: first(error?.message ?? error) }); }
+  };
+  const sdk = fs.realpathSync(sdkRoot);
+  await check('Pi host 0.87.1', true, () => {
+    const version = JSON.parse(fs.readFileSync(path.join(sdk, 'package.json'), 'utf8')).version;
+    if (version !== '0.87.1') throw Error(`found ${version}; company sessions need 0.87.1`);
+    return sdk;
+  });
+  await check('search tools (ripgrep, fd)', true, async () => { await ensureSearchTools(sdk); return 'ready'; });
+  const project = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'piagent-doctor-')));
+  let boundary;
+  try {
+    boundary = new ManagedToolBoundary({ cwd: project, sdkRoot: sdk, protectedRoots: [] });
+    const bash = async (command, options) => text(await boundary.invoke('bash', { command, timeout: 60 }, undefined, undefined, undefined, options));
+    await check('sandbox starts and runs a command', true, async () => { if (await bash('echo doctor-ok') !== 'doctor-ok') throw Error('unexpected output'); return 'bash'; });
+    await check('write, read, edit, list, find, search a file', true, async () => {
+      await boundary.invoke('write', { path: 'src/note.txt', content: 'alpha\nbeta\n' });
+      await boundary.invoke('edit', { path: 'src/note.txt', edits: [{ oldText: 'beta', newText: 'gamma' }] });
+      if (!/gamma/.test(text(await boundary.invoke('read', { path: 'src/note.txt' })))) throw Error('edit not applied');
+      if (!/note\.txt/.test(text(await boundary.invoke('ls', { path: 'src' })))) throw Error('ls did not list the file');
+      if (!/note\.txt/.test(text(await boundary.invoke('find', { pattern: '*.txt' })))) throw Error('find did not find the file');
+      if (!/note\.txt/.test(text(await boundary.invoke('grep', { pattern: 'gamma' })))) throw Error('grep did not find the text');
+      return '6 tools';
+    });
+    await check('project folder names with spaces and Vietnamese', true, async () => {
+      await boundary.invoke('write', { path: 'Dự án mới/ghi chú.md', content: 'ổn\n' });
+      if (await bash("cat 'Dự án mới/ghi chú.md'") !== 'ổn') throw Error('content changed'); return 'ok';
+    });
+    await check('files outside the project stay out of reach', true, async () => {
+      let refused = false; try { await boundary.invoke('write', { path: '../piagent-doctor-outside.txt', content: 'x' }); } catch { refused = true; }
+      if (!refused) { fs.rmSync(path.join(path.dirname(project), 'piagent-doctor-outside.txt'), { force: true }); throw Error('a write outside the project was allowed'); }
+      return 'refused';
+    });
+    await check('commands have no network unless approved', true, async () => {
+      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';
+    });
+    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');
+      try { return await bash('git commit -qm doctor && git log -1 --format="%an <%ae>"'); }
+      catch (error) { throw Error(/tell me who you are|user\.(name|email)/i.test(String(error?.message)) ? 'no git identity: run git config --global user.name and user.email' : error?.message); }
+    });
+    await check('node', true, () => bash('node --version'));
+    await check('npm', false, () => bash('npm --version'));
+    await check('python3', false, () => bash('python3 --version'));
+    await check('C compiler (native npm modules, Rust, cgo)', false, async () => {
+      await boundary.invoke('write', { path: 'main.c', content: 'int main(void){return 0;}\n' });
+      await bash('cc main.c -o main && ./main'); return first(await bash('cc --version'));
+    });
+    await check('make', false, () => bash('make --version'));
+    if (network) await check('web_fetch reads a public page', false, async () => `status ${(await fetchPublicPage('https://example.com/', { maxChars: 1000 })).status}`);
+  } finally { await boundary?.dispose(); fs.rmSync(project, { recursive: true, force: true }); }
+  if (broker) {
+    let manifest = null;
+    await check('Agent Watch answers with the company key', true, async () => {
+      manifest = await broker.request('config');
+      if (manifest?.schema_version !== 2 || !manifest.harness) throw Error('the key has no harness');
+      return `key "${manifest.key_label ?? manifest.key_id}"`;
+    });
+    if (manifest) await check('this Piagent knows every harness model', true, async () => {
+      const api = await import(pathToFileURL(path.join(sdk, 'dist/index.js'))), ai = await import(pathToFileURL(path.join(sdk, 'node_modules/@earendil-works/pi-ai/dist/index.js')));
+      const runtime = await api.ModelRuntime.create({ credentials: new ai.InMemoryCredentialStore(), modelsPath: null, allowModelNetwork: false, refreshOnCreate: false });
+      const roles = Object.entries(manifest.harness.configuration ?? {}).filter(([, role]) => role?.model_ids?.length);
+      for (const [role, value] of roles) for (const id of value.model_ids) {
+        const model = (manifest.models ?? []).find(entry => entry.id === id);
+        if (!model) throw Error(`${role}: the key is not granted a harness model; ask an administrator to save the harness again`);
+        if (!nativeManagedModel(runtime, piProvider(model.owned_by), model.provider_model_id)) throw Error(`${role}: unknown to this Piagent; update Piagent`);
+      }
+      return `${roles.map(([role]) => role).join(', ')}; thinking ${(manifest.thinking_levels ?? []).join('/') || 'off only'}`;
+    });
+    if (network) await check('Studio is reachable', true, async () => {
+      // Any HTTP answer proves the route; an unauthenticated one is refused.
+      const response = await fetch(new URL('/v1/models', origin), { signal: AbortSignal.timeout(8000) });
+      return `HTTP ${response.status}`;
+    });
+  }
+  return results;
+}
+
+export function doctorReport(results) {
+  const failed = results.filter(result => !result.ok && result.required), missing = results.filter(result => !result.ok && !result.required);
+  const lines = results.map(result => `${result.ok ? ' ok  ' : result.required ? ' FAIL' : ' miss'} ${result.label}${result.detail ? ` — ${result.detail}` : ''}`);
+  lines.push(failed.length ? `Not ready: ${failed.length} required check(s) failed.` : `Ready for company sessions${missing.length ? `; ${missing.length} optional item(s) missing` : ''}. No model request was sent.`);
+  return { text: lines.join('\n'), ok: failed.length === 0 };
+}

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

@@ -0,0 +1,57 @@
+import { REVIEW_PROMPT, VERIFY_PROMPT, isCheckCommand } from './workflow.mjs';
+
+// Each helper role runs at most this often per user message (Studio's MaxHelperCalls).
+export const HELPER_CALLS = 8;
+
+// The helpers a main agent may delegate to, in the Harness's order. Each is
+// optional: only those the company Harness enables (and Agent Watch passes
+// on) are offered. Scout reads the code, research also reads the web, verify
+// re-checks a result with the repository's checks and primary sources,
+// review judges the patch. None of them changes files.
+export const HELPER_ROLES = Object.freeze(['scout', 'research', 'verify', 'review']);
+export const helperRoles = manifest => HELPER_ROLES.filter(role => manifest?.harness?.configuration?.[role]);
+const WIDE_READING = 'when understanding the task needs more reading than a few batches of files, such as a flow across many modules of an unfamiliar codebase';
+export function helperPrompt(roles) {
+  const lines = [];
+  if (roles.includes('scout')) lines.push(`Use the scout helper (delegate role "scout") ${WIDE_READING}, and work from its file:line findings; do small lookups yourself.`);
+  if (roles.includes('research')) lines.push(roles.includes('scout') ? 'Use the research helper (delegate role "research") for questions that need external documentation or current information (library and API docs, releases, error messages) together with the code.'
+    : `Use the research helper (delegate role "research") ${WIDE_READING} or external documentation, and work from its findings; do small lookups yourself.`);
+  if (roles.includes('verify')) lines.push('Before you report a non-trivial result as done, you may have the verify helper (delegate role "verify") confirm it independently: it runs the repository checks on the current code and checks claims against the code and primary sources, answering pass, fail or unverifiable with evidence.');
+  return lines.length ? ' ' + lines.join(' ') : '';
+}
+const HELPER_USES = {
+  scout: () => 'scout: 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). It reads only the project, no web, and answers with file:line facts; your own context stays free for the change.',
+  research: roles => roles.includes('scout') ? 'research: questions that need the web as well as the code: library or API documentation, releases, error messages, current information.'
+    : 'research: 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), or to read external documentation; your own context stays free for the change. It also searches the web.',
+  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.',
+};
+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.`;
+}
+const RESEARCH_PROMPT = 'Research the assigned question. Read only the needed source; use web_search or web_fetch for external documentation. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and what you checked and found nothing in. You cannot change files or delegate.';
+const SCOUT_PROMPT = 'Scout the codebase for the assigned question. Search first (grep, find), then read only the parts that matter. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and where you looked and found nothing. You have no web access: when the answer needs external documentation, say so. You cannot change files or delegate.';
+export const READ_TOOLS = ['read', 'grep', 'find', 'ls'];
+// What each helper may use. Every helper's project is read-only; verify also
+// runs commands there (offline, writes only to its temporary directory).
+export const HELPER_SETUP = {
+  scout: { web: false, commands: false, prompt: SCOUT_PROMPT, label: 'Scout' },
+  research: { web: true, commands: false, prompt: RESEARCH_PROMPT, label: 'Research' },
+  verify: { web: true, commands: true, prompt: VERIFY_PROMPT, label: 'Verify' },
+  review: { web: false, commands: false, prompt: REVIEW_PROMPT, label: 'Review' },
+};
+// A repository check a helper ran counts for the run like one the main
+// agent ran, when the code was the same before and after it: the helper
+// cannot write, but the main agent may edit beside it in the same answer.
+export function countedCheck(managed, tool) {
+  if (tool.name !== 'bash') return tool;
+  return { ...tool, execute: async (...args) => {
+    const counted = managed.run && isCheckCommand(args[1]?.command, managed.checks.commands), before = counted ? await managed.digest() : null;
+    let ok = false;
+    try { const result = await tool.execute(...args); ok = true; return result; }
+    finally {
+      const after = counted && before !== null ? await managed.digest() : null;
+      if (after !== null && after === before) await managed.run.afterTool('bash', args[1], ok, async () => after);
+    }
+  } };
+}

package/packages/piagent-core/managed/native-catalog.mjs

@@ -0,0 +1,42 @@
+// Reviewed gaps in Pi 0.87.1's bundled catalog. Never infer context/output
+// limits for an unknown future model.
+// Claude Sonnet 5.5, checked 2026-09-30:
+// https://platform.claude.com/docs/en/models/overview
+// https://platform.claude.com/docs/en/build-with-claude/effort
+const sonnet55 = {
+  id: 'claude-sonnet-5-5', provider: 'anthropic', api: 'anthropic-messages',
+  name: 'Claude Sonnet 5.5', reasoning: true, input: ['text', 'image'],
+  contextWindow: 1000000, maxTokens: 128000,
+  cost: { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+  thinkingLevelMap: { off: null, minimal: null, low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max' },
+  compat: { forceAdaptiveThinking: true, supportsTemperature: false, supportsStrictTools: true, supportsMidConvoEffort: true },
+  promptCache: { short: 300, long: 3600 },
+};
+// GPT-6.1 Sol through Codex, checked 2026-10-01: Codex keeps the 272k window
+// of its pricing tier (the API model has 1.05M); 128k output; efforts low to
+// max, no none/minimal; $2/$10 per 1M, cached $0.10, doubled above 272k.
+// https://developers.openai.com/api/docs/models/gpt-6.1-sol
+// https://learn.chatgpt.com/docs/models
+// https://pi.dev/models/openai-codex/gpt-6-1-sol
+const sol61 = {
+  id: 'gpt-6.1-sol', provider: 'openai-codex', api: 'openai-codex-responses', baseUrl: 'https://chatgpt.com/backend-api',
+  name: 'GPT-6.1 Sol', reasoning: true, input: ['text', 'image'],
+  contextWindow: 272000, maxTokens: 128000,
+  cost: { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5, tiers: [{ inputTokensAbove: 272000, input: 4, output: 15, cacheRead: 0.2, cacheWrite: 5 }] },
+  thinkingLevelMap: { off: null, minimal: 'low', low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'max' },
+  compat: { supportsOpenAIGrammarTools: true, supportsAdditionalTools: true, supportsToolSearch: true, supportsMidConvoSystemMessages: true },
+  inputLimits: { images: { resize: { maxWidth: 2000, maxHeight: 2000, maxBytes: 4718592, jpegQuality: 80 } } },
+};
+const GAPS = { anthropic: [sonnet55], 'openai-codex': [sol61] };
+// Studio's providers: the Claude and Codex subscriptions, or an API-key
+// vendor (DeepSeek, Kimi, GLM, MiMo, Qwen, OpenCode, Grok) whose id is Pi's
+// own provider id; Studio runs vendors as OpenAI Chat Completions.
+const VENDOR = /^[a-z][a-z0-9-]{1,39}$/;
+export const isVendor = provider => typeof provider === 'string' && provider !== 'claude' && provider !== 'codex' && VENDOR.test(provider);
+export function piProvider(provider) { return provider === 'claude' ? 'anthropic' : provider === 'codex' ? 'openai-codex' : provider; }
+export function studioAPI(provider) { return provider === 'claude' ? 'anthropic-messages' : provider === 'codex' ? 'openai-responses' : 'openai-completions'; }
+export function studioPath(provider) { return provider === 'claude' ? '/claude' : provider === 'codex' ? '/v1' : '/openai/v1'; }
+export function nativeManagedModel(runtime, provider, id) {
+  const gap = GAPS[provider]?.find(model => model.id === id);
+  return runtime.getModel(provider, id) ?? (gap ? structuredClone(gap) : undefined);
+}

package/packages/piagent-core/managed/patch-snapshot.mjs

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const quote = value => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
+
+// The patch a reviewer sees (diff against HEAD plus untracked files), read
+// inside the tool boundary. It comes in parts: the shell tool truncates its
+// output well below the 120 KB a review may cover. Every part names the
+// snapshot's digest, so parts of a patch that changed meanwhile never mix.
+export async function readPatchSnapshot(boundary) {
+  const worker = fileURLToPath(new URL('./review-snapshot-worker.mjs', import.meta.url));
+  const read = async part => {
+    const result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(worker)} ${part}`, timeout: 20 });
+    if (result.details?.truncation?.truncated) throw Error('managed-review-patch-too-large');
+    const text = textContent(result).trim(), newline = text.indexOf('\n');
+    const [digest, parts] = (newline < 0 ? text : text.slice(0, newline)).split(' ');
+    if (!/^[a-f0-9]{64}$/.test(digest ?? '') || !(Number(parts) >= 1 && Number(parts) <= 8)) throw Error('managed-review-patch-unreadable');
+    return { digest, parts: Number(parts), bytes: Buffer.from(newline < 0 ? '' : text.slice(newline + 1), 'base64') };
+  };
+  const first = await read(0), chunks = [first.bytes];
+  for (let part = 1; part < first.parts; part += 1) {
+    const next = await read(part);
+    if (next.digest !== first.digest) throw Error('managed-review-patch-changed');
+    chunks.push(next.bytes);
+  }
+  const patch = Buffer.concat(chunks).toString('utf8');
+  if (createHash('sha256').update(patch).digest('hex') !== first.digest) throw Error('managed-review-patch-changed');
+  return { patch, digest: first.digest };
+}
+
+// Why a required review could not run, in one word for the member.
+export function reviewUnavailableReason(message) {
+  const text = String(message ?? '');
+  if (/review-(patch|file|untracked)-limit|managed-review-patch-too-large/.test(text)) return 'too_large';
+  if (/not a git repository|Could not access 'HEAD'|managed-review-patch-unreadable/i.test(text)) return 'not_git';
+  if (/managed-helper-limit|helper_run_limit_reached/.test(text)) return 'limit';
+  return 'failed';
+}
+
+// The patch as a reviewer reads it: the diff, then each new file in full.
+export function reviewText(snapshot) {
+  let value;
+  try { value = JSON.parse(snapshot.patch); } catch { return `Patch snapshot ${snapshot.digest}:\n${snapshot.patch}`; }
+  const files = (value.untracked ?? []).map(f => f.mode === 'symlink' ? `=== new symlink ${f.path} -> ${f.target}`
+    : f.encoding === 'utf8' ? `=== new file ${f.path}\n${f.contents}` : `=== new binary file ${f.path} (${Math.round(f.contents.length * 0.75)} bytes)`);
+  return `Patch snapshot ${snapshot.digest}:\n--- diff against HEAD ---\n${value.patch || '(no changes to tracked files)'}\n${files.length ? `--- new files ---\n${files.join('\n\n')}` : ''}`;
+}

package/packages/piagent-core/managed/repository-operation.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {managedGit} from './toolchain.mjs';
+
+const quote = value => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+const text = result => result.content.filter(p=>p.type==='text').map(p=>p.text).join('\n').trim();
+const hash = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+export function githubRemote(value) {
+  // No arbitrary protocol helper, userinfo, port, query, refspec or SSH command.
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)([A-Za-z0-9][A-Za-z0-9_.-]{0,99})\/([A-Za-z0-9][A-Za-z0-9_.-]{0,99}?)(?:\.git)?$/.exec(value);
+  if (!match || match.slice(1).some(x=>x==='.'||x==='..')) throw Error('managed-repository-origin-unsupported');
+  return {repository:`${match[1]}/${match[2]}`,url:`https://github.com/${match[1]}/${match[2]}.git`};
+}
+
+export async function repositoryFetchPlan(boundary) {
+  const result=await boundary.invoke('bash',{command:'git config --local --get remote.origin.url',timeout:5});
+  const remote=githubRemote(text(result));
+  return Object.freeze({...remote,cwd:boundary.cwd});
+}
+
+function command(binary,args,{cwd,env,signal,secret='',limit=1024*1024}={}) {
+  return new Promise((resolve,reject)=>{
+    if(signal?.aborted) return reject(Error('managed-operation-cancelled'));
+    const child=spawn(binary,args,{cwd,env,stdio:['ignore','pipe','pipe']});let output='',size=0,failed=false;
+    const abort=()=>{failed=true;child.kill('SIGKILL')};signal?.addEventListener('abort',abort,{once:true});
+    const timer=setTimeout(abort,60000);timer.unref();
+    child.stdout.on('data',chunk=>{size+=chunk.length;if(size>limit)abort();else output+=chunk});
+    // Credential helpers and Git diagnostics are never relayed to model context.
+    child.stderr.on('data',()=>{});child.on('error',()=>{failed=true});
+    child.on('close',code=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);
+      if(failed||code!==0) reject(Error(signal?.aborted?'managed-operation-cancelled':'managed-repository-fetch-failed'));
+      else resolve(secret?output.replaceAll(secret,'[REDACTED]'):output);
+    });
+  });
+}
+
+export async function fetchRepositoryBundle(plan, destination, signal) {
+  // This private process sees only fixed arguments and an empty bare repo. It
+  // never executes a command, hook, helper, filter or config from the project.
+  const git=managedGit(), gitHash=hash(git);
+  const temporary=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'managed-fetch-')));
+  fs.chmodSync(temporary,0o700);
+  const env={PATH:'/usr/bin:/bin',HOME:temporary,LANG:'en_US.UTF-8',GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_TERMINAL_PROMPT:'0',GIT_ASKPASS:'/usr/bin/false'};
+  let token='';
+  try {
+    // gh reads the logged-in user's own GitHub credential, never a Studio key.
+    // A public repository works without gh. Private access remains unavailable
+    // until that user signs in; no personal credential is put in agent env.
+    for(const candidate of ['/opt/homebrew/bin/gh','/usr/local/bin/gh']) {
+      if(!fs.existsSync(candidate))continue;
+      const gh=fs.realpathSync(candidate);
+      try {token=(await command(gh,['auth','token','--hostname','github.com'],{cwd:temporary,env:{PATH:'/usr/bin:/bin',HOME:os.homedir(),LANG:'en_US.UTF-8'},signal,limit:4096})).trim();} catch {}
+      break;
+    }
+    if(token && !/^[A-Za-z0-9_]{10,2048}$/.test(token)) throw Error('managed-github-credential-invalid');
+    await command(git,['init','--bare','--quiet',temporary],{cwd:temporary,env,signal});
+    if(hash(git)!==gitHash)throw Error('managed-runtime-changed');
+    const authentication=token?{GIT_CONFIG_COUNT:'1',GIT_CONFIG_KEY_0:'http.https://github.com/.extraheader',GIT_CONFIG_VALUE_0:'Authorization: Basic '+Buffer.from('x-access-token:'+token).toString('base64')}:{};
+    await command(git,['-c','credential.helper=','-c','core.hooksPath=/dev/null','-c','http.followRedirects=false','-c','protocol.allow=never','-c','protocol.https.allow=always','fetch','--quiet','--no-tags','--no-recurse-submodules','--depth=100',plan.url,'+refs/heads/*:refs/heads/*'],{cwd:temporary,env:{...env,...authentication},signal,secret:token});
+    // A self-contained bundle cannot be shallow. Do not silently fetch an
+    // unbounded history; export fetched objects as a local bare repository.
+    fs.cpSync(temporary,destination,{recursive:true,errorOnExist:true,force:false});
+    // Remote URL/config is not needed by the untrusted offline import.
+    fs.writeFileSync(path.join(destination,'config'),'[core]\n\tbare = true\n');
+  } finally {token='';fs.rmSync(temporary,{recursive:true,force:true});}
+}
+
+export async function executeRepositoryFetch(boundary,plan,signal,{transport=fetchRepositoryBundle}={}) {
+  const current=await repositoryFetchPlan(boundary);
+  if(current.url!==plan.url||current.cwd!==plan.cwd)throw Error('managed-operation-scope-changed');
+  const staging=path.join(boundary.temporary,'approved-origin-'+Date.now());
+  try {
+    await transport(plan,staging,signal);
+    const rechecked=await repositoryFetchPlan(boundary);
+    if(rechecked.url!==plan.url)throw Error('managed-operation-scope-changed');
+    // Import is sandboxed. Malicious repo hooks/config cannot reach credentials.
+    await boundary.invoke('bash',{command:`git -c core.hooksPath=/dev/null -c protocol.allow=never -c protocol.file.allow=always fetch --no-tags --no-recurse-submodules --no-write-fetch-head --update-shallow ${quote(staging)} '+refs/heads/*:refs/remotes/origin/*'`,timeout:30},signal);
+    return {content:[{type:'text',text:`Fetched origin branches for ${plan.repository}. Working files and current branch were not changed.`}],details:{operation:'git.fetch',repository:plan.repository}};
+  } finally {fs.rmSync(staging,{recursive:true,force:true});}
+}