@piagent/platform 1.9.2 → 1.10.0

package/packages/piagent-core/managed/member-questions.mjs

@@ -0,0 +1,178 @@
+// Questions the main agent asks the member when the request leaves a decision
+// open: 1–4 questions, each with 2–4 numbered options, and always "Other" in
+// the member's own words. The agent waits for the answer. In the WebUI the
+// question is a card answered there (the Gateway binds a surface for each
+// conversation it runs); in the Terminal it is a selector; with no member at
+// a screen the agent is told to go on with a stated assumption.
+const KEY = Symbol.for('piagent.memberQuestions');
+const REF = /^question\.[0-9a-f-]{36}$/;
+// A waiting question is a step of the running turn: the WebUI's operation
+// watchdog hears from it this often, so a member who answers late still can.
+const WAITING_PULSE_MS = 60_000;
+// What the agent reads when the member stopped the turn (or the screen went
+// away) before answering: the decisions stay theirs.
+const CANCELLED = 'managed-question-cancelled: the member stopped before answering. These decisions are still open: when the member continues, ask again (unless their new message settles them); do not choose for them.';
+const text = (value, max) => typeof value === 'string' ? value.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, ' ').trim().slice(0, max) : '';
+
+// The questions as asked, or null when they do not have the expected shape.
+export function normalizeQuestions(raw) {
+  const list = Array.isArray(raw) ? raw : null;
+  if (!list || list.length < 1 || list.length > 4) return null;
+  const out = [];
+  for (const item of list) {
+    const question = text(item?.question, 400), header = text(item?.header, 24);
+    const options = Array.isArray(item?.options) ? item.options.map(o => ({ label: text(o?.label, 80), description: text(o?.description, 200) })) : [];
+    if (!question || options.length < 2 || options.length > 4 || options.some(o => !o.label) || new Set(options.map(o => o.label.toLowerCase())).size !== options.length) return null;
+    out.push({ header, question, options, multiSelect: item?.multiSelect === true });
+  }
+  return out;
+}
+
+// The member's answer, checked against the questions: one entry per question
+// with the chosen option numbers (0-based) and/or their own words; or skipped
+// (the member leaves the decision to the agent). Null when it does not fit.
+export function normalizeAnswer(questions, raw) {
+  if (raw?.skipped === true) return { skipped: true, answers: [] };
+  const list = Array.isArray(raw?.answers) ? raw.answers : null;
+  if (!list || list.length !== questions.length) return null;
+  const answers = [];
+  for (const [i, item] of list.entries()) {
+    const q = questions[i], other = text(item?.other, 1000) || null;
+    const selected = Array.isArray(item?.selected) ? [...new Set(item.selected)] : [];
+    if (selected.some(n => !Number.isSafeInteger(n) || n < 0 || n >= q.options.length)) return null;
+    if (!q.multiSelect && selected.length + (other ? 1 : 0) > 1) return null;
+    if (!selected.length && !other) return null;
+    answers.push({ selected: selected.sort((a, b) => a - b), other });
+  }
+  return { skipped: false, answers };
+}
+
+// What the agent reads back.
+export function answerText(questions, answer) {
+  if (answer.skipped) return 'The member did not choose and leaves these decisions to you. Make the choice you judge best, say in one line which one and why, and go on.';
+  return ['The member answered:', ...questions.flatMap((q, i) => {
+    const a = answer.answers[i];
+    return [`${i + 1}. ${q.header ? `[${q.header}] ` : ''}${q.question}`,
+      ...a.selected.map(n => `   → ${n + 1}. ${q.options[n].label}`), ...(a.other ? [`   → Other: ${a.other}`] : [])];
+  })].join('\n');
+}
+
+class MemberQuestions {
+  pulseMs = WAITING_PULSE_MS;
+  #surfaces = new Map();
+  #listeners = new Map();
+  #pending = new Map();
+
+  // A screen that can show this conversation's questions (the Gateway, per
+  // conversation it runs). `onEvent` hears each question asked, waiting,
+  // answered or withdrawn.
+  bindSurface(sessionId, onEvent) {
+    const key = String(sessionId);
+    this.#surfaces.set(key, (this.#surfaces.get(key) ?? 0) + 1);
+    const listeners = this.#listeners.get(key) ?? new Set(); listeners.add(onEvent); this.#listeners.set(key, listeners);
+    let bound = true;
+    return () => {
+      if (!bound) return; bound = false;
+      const left = (this.#surfaces.get(key) ?? 1) - 1;
+      if (left > 0) this.#surfaces.set(key, left); else this.#surfaces.delete(key);
+      // No screen is left to answer: a waiting question is withdrawn.
+      if (left <= 0) for (const entry of [...this.#pending.values()]) if (entry.sessionId === key) this.#settle(entry, null, 'surface-closed');
+      listeners.delete(onEvent);
+    };
+  }
+  hasSurface(sessionId) { return (this.#surfaces.get(String(sessionId)) ?? 0) > 0; }
+  #emit(sessionId, event) { for (const listener of [...(this.#listeners.get(sessionId) ?? [])]) { try { listener(event); } catch { /* a listener's failure is its own */ } } }
+
+  // Resolves with the normalized answer; rejects 'managed-question-cancelled'
+  // when the member stops the turn or the screen goes away.
+  ask({ sessionId, toolCallId, questions, signal }) {
+    const key = String(sessionId), ref = `question.${crypto.randomUUID()}`;
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) return reject(Error('managed-question-cancelled'));
+      const entry = { ref, sessionId: key, toolCallId: String(toolCallId ?? ''), questions, askedAt: new Date().toISOString(), resolve, reject, signal };
+      entry.onAbort = () => this.#settle(entry, null, 'stopped');
+      signal?.addEventListener('abort', entry.onAbort, { once: true });
+      entry.pulse = setInterval(() => this.#emit(key, { type: 'waiting', ref }), this.pulseMs);
+      this.#pending.set(ref, entry);
+      this.#emit(key, { type: 'asked', ref });
+    });
+  }
+  #settle(entry, answer, reason) {
+    if (!this.#pending.delete(entry.ref)) return;
+    clearInterval(entry.pulse); entry.signal?.removeEventListener('abort', entry.onAbort);
+    this.#emit(entry.sessionId, { type: answer ? 'answered' : 'withdrawn', ref: entry.ref, reason });
+    if (answer) entry.resolve(answer); else entry.reject(Error('managed-question-cancelled'));
+  }
+
+  // The questions waiting for this conversation's member, oldest first.
+  pending(sessionId) {
+    const key = String(sessionId);
+    return [...this.#pending.values()].filter(e => e.sessionId === key)
+      .map(e => ({ questionRef: e.ref, askedAt: e.askedAt, questions: structuredClone(e.questions) }));
+  }
+  answer(sessionId, questionRef, raw) {
+    const entry = REF.test(String(questionRef)) ? this.#pending.get(questionRef) : null;
+    if (!entry || entry.sessionId !== String(sessionId)) throw Error('question-not-pending');
+    const answer = normalizeAnswer(entry.questions, raw);
+    if (!answer) throw Error('question-answer-invalid');
+    this.#settle(entry, answer, 'answered');
+    return { questionRef, state: 'answered' };
+  }
+}
+export const memberQuestions = globalThis[KEY] ??= new MemberQuestions();
+
+// In the Terminal: each question as a selector of its numbered options, then
+// "Other" (typed) and "Let the agent decide". Esc leaves it to the agent.
+async function askInTerminal(ui, questions, signal) {
+  const answers = [];
+  for (const [i, q] of questions.entries()) {
+    const title = `${questions.length > 1 ? `(${i + 1}/${questions.length}) ` : ''}${q.header ? `${q.header}: ` : ''}${q.question}`;
+    const items = q.options.map((o, n) => `${n + 1}. ${o.label}${o.description ? ` — ${o.description}` : ''}`);
+    const other = `${q.options.length + 1}. Khác (tự nhập)`, skip = 'Để agent tự quyết', done = 'Xong';
+    const selected = [];
+    for (;;) {
+      const choices = q.multiSelect ? [...items.filter((_, n) => !selected.includes(n)), other, ...(selected.length ? [done] : [skip])] : [...items, other, skip];
+      const picked = await ui.select(q.multiSelect && selected.length ? `${title}\nĐã chọn: ${selected.map(n => n + 1).join(', ')}` : title, choices, { signal });
+      if (signal?.aborted) throw Error('managed-question-cancelled');
+      if (picked === undefined || picked === skip) return { skipped: true, answers: [] };
+      if (picked === done) { answers.push({ selected, other: null }); break; }
+      if (picked === other) {
+        const typed = await ui.input(title, 'Câu trả lời của bạn', { signal });
+        if (signal?.aborted) throw Error('managed-question-cancelled');
+        if (typed?.trim()) { answers.push({ selected, other: typed.trim() }); break; }
+        continue;
+      }
+      const n = items.indexOf(picked);
+      if (!q.multiSelect) { answers.push({ selected: [n], other: null }); break; }
+      selected.push(n);
+    }
+  }
+  return normalizeAnswer(questions, { answers }) ?? { skipped: true, answers: [] };
+}
+
+const QUESTION_SCHEMA = { type: 'object', properties: {
+  header: { type: 'string', maxLength: 24, description: 'A short label for the question, 1–3 words (e.g. "Phạm vi", "Dữ liệu").' },
+  question: { type: 'string', minLength: 1, maxLength: 400, description: 'One clear question in the member\'s language, ending with a question mark.' },
+  options: { type: 'array', minItems: 2, maxItems: 4, description: 'The real choices, most likely first. "Other" (the member\'s own words) is always added for the member: never add an "Other" option yourself.',
+    items: { type: 'object', properties: { label: { type: 'string', minLength: 1, maxLength: 80 }, description: { type: 'string', maxLength: 200, description: 'What choosing it means for the work.' } }, required: ['label'], additionalProperties: false } },
+  multiSelect: { type: 'boolean', description: 'True when several options may be chosen together.' } },
+  required: ['question', 'options'], additionalProperties: false };
+
+// The tool of the main agent. `managed` is the ManagedSession.
+export function askTool(managed) {
+  return { name: 'ask_user', label: 'Hỏi thành viên',
+    description: 'Ask the member 1–4 questions and wait for the answers, when the request leaves a decision open that changes the result and the code, the docs or a subagent cannot settle it: scope, expected behaviour, data shape, a trade-off, a name the member will see. Ask before acting on a guess, all questions in one call, each with 2–4 concrete numbered options (most likely first); the member can always answer in their own words or leave the choice to you. Do not ask what you can find out yourself, to confirm what the member already said, or for permission to do what was asked.',
+    parameters: { type: 'object', properties: { questions: { type: 'array', minItems: 1, maxItems: 4, items: QUESTION_SCHEMA } }, required: ['questions'], additionalProperties: false },
+    execute: async (toolCallId, args, signal, _onUpdate, ctx) => {
+      const questions = normalizeQuestions(args?.questions);
+      if (!questions) throw Error('managed-question-invalid: give 1–4 questions, each with a question and 2–4 options with distinct labels.');
+      const sessionId = managed.session?.sessionManager?.getSessionId?.();
+      let answer;
+      const cancelled = (error) => { throw error?.message === 'managed-question-cancelled' ? Error(CANCELLED) : error; };
+      if (sessionId && memberQuestions.hasSurface(sessionId)) answer = await memberQuestions.ask({ sessionId, toolCallId, questions, signal }).catch(cancelled);
+      else if (ctx?.hasUI && ctx.ui?.select && !ctx.ui[Symbol.for('piagent.webui.gateway-runtime-ui.v1')]) answer = await askInTerminal(ctx.ui, questions, signal).catch(cancelled);
+      else return { content: [{ type: 'text', text: 'No member can answer right now (this conversation has no screen to ask on). Go on with the most reasonable choice for each question, state the assumption plainly in your answer, and keep it easy to change.' }],
+        details: { questions, answer: null, surface: 'none' } };
+      return { content: [{ type: 'text', text: answerText(questions, answer) }], details: { questions, answer } };
+    } };
+}

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

@@ -0,0 +1,73 @@
+import { briefIssues, currentPlan, planText, verifyVerdicts } from './workflow.mjs';
+
+// A helper may object to the brief it was given, with evidence. It never
+// decides and never does other work instead: the main agent decides and has
+// to answer the objection (a corrected brief, another approach, or why the
+// objection does not hold). The same helper objecting a second time in a run
+// stops the exchange, and the member decides.
+
+// The member's own words for a helper: the current message and, while a
+// message only continues earlier work ("tiếp tục", a short follow-up), the
+// ones before it, back to one that states a task. Newer words are kept first.
+export const FOLLOW_UP_CHARS = 160;
+const REQUEST_CHARS = 6000;
+export function memberRequest(texts) {
+  const words = texts.map(text => String(text ?? '').trim()).filter(Boolean), picked = words.length ? [words.at(-1)] : [];
+  for (let i = words.length - 2; i >= 0 && picked.length < 5 && picked[0].length < FOLLOW_UP_CHARS; i -= 1) picked.unshift(words[i]);
+  const kept = [];
+  let room = REQUEST_CHARS;
+  for (const text of picked.reverse()) { if (room <= 0) break; kept.unshift(text.slice(0, room)); room -= text.length; }
+  return kept;
+}
+const userText = message => typeof message.content === 'string' ? message.content : (message.content ?? []).filter(p => p?.type === 'text').map(p => p.text).join('\n');
+export const memberMessages = manager => manager.getEntries().filter(e => e.type === 'message' && e.message?.role === 'user').map(e => userText(e.message));
+
+// What a helper reads before its brief: the member's request verbatim and the
+// plan, so a brief that drifted from the request can be seen to drift.
+export function anchorText(manager, harness) {
+  const texts = memberRequest(memberMessages(manager)), plan = planText(currentPlan(manager));
+  if (!texts.length) return '';
+  const words = texts.length === 1 ? texts[0] : texts.map((text, i) => `${i === texts.length - 1 ? 'Current message' : 'Earlier message'}:\n${text}`).join('\n\n');
+  const from = harness ? 'the harness' : 'the main agent';
+  return `The member's request, verbatim (${from} wrote the brief below from it):\n<<<\n${words}\n>>>\n${plan ? `\nCurrent plan:\n${plan}\n` : ''}\nBrief from ${from}:\n`;
+}
+
+// Before a helper starts: once a helper objected twice in a run the member
+// decides, so the main agent cannot send it another brief before then. A
+// new brief to a helper that objected answers that objection.
+export function beforeDelegate(run, role, harness) {
+  if (!run || harness) return;
+  if (run.disputes.some(d => d.source === role && d.brief)) throw Error(`managed-helper-disputed: the ${role} subagent objected to your briefs twice for this message, so the member decides. Tell them what it objects to and what you decided; do not delegate to it again before their next message.`);
+  for (const objection of run.objections) if (objection.role === role) objection.answered = true;
+}
+
+const issueText = (issue, i) => `${i + 1}. [${issue.kind}] ${issue.detail}${issue.evidence ? ` (evidence: ${issue.evidence})` : ''}`;
+// After a helper answered: an objection to the main agent's brief is
+// recorded, shown to the member and handed to the main agent with the answer.
+// Returns the note the main agent reads under the helper's answer ('' when
+// there is none). The harness's own briefs (its review, its re-check) are
+// fixed text: an objection to one only restates the member's request, so
+// it is not relayed.
+export async function relayObjection(managed, role, reply, harness) {
+  const run = managed.run, issues = harness ? null : briefIssues(reply);
+  if (!run || !issues?.length) return '';
+  const second = run.objections.some(o => o.role === role), list = issues.map(issueText).join('\n');
+  run.objections.push({ role, issues, answered: false, disputed: second });
+  if (second) run.disputes.push({ source: role, brief: true });
+  await managed.session.sendCustomMessage({ customType: 'agent-watch-process', display: true,
+    content: second ? `Harness: the ${role} subagent objected to a brief a second time for this message; the exchange stops and the member decides.\n${list}`
+      : `Harness: the ${role} subagent objected to the brief the main agent gave it:\n${list}`,
+    details: { phase: second ? 'dispute' : 'objection', role, by: 'main', issues: issues.map(({ kind, detail }) => ({ kind, detail })) } }, { triggerTurn: false });
+  return second ? `\n\n[Harness] The ${role} subagent objected to your brief again. This is its second objection for this message, so the harness ends the exchange: do not delegate to it again before the member's next message. Tell the member plainly what it objects to and what you decided, and let them decide.`
+    : `\n\n[Harness] The ${role} subagent objected to your brief (see brief_issues above). You decide, but answer the objection before you act on this answer: send it a corrected brief, change your approach, or tell the member why the objection does not hold. A second objection from it for this message goes to the member.`;
+}
+
+// Verify's verdicts, counted for the receipt. Under a required verify the
+// failed claims are the run's to settle; once the agent has been sent back
+// with them, only the harness's own re-check replaces them.
+export function recordVerdicts(run, reply, harness, details) {
+  const found = verifyVerdicts(reply);
+  details.verdicts = found ? Object.fromEntries(['pass', 'fail', 'unverifiable'].map(s => [s, found.filter(v => v.status === s).length])) : null;
+  if (run && found && (harness || !run.claimsAsked)) run.verifyFails = found.filter(v => v.status === 'fail');
+  return found ? ' · ' + Object.entries(details.verdicts).filter(([, n]) => n).map(([s, n]) => `${n} ${s}`).join(', ') : '';
+}

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

@@ -1,32 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
 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') ?? '';
+const WORKER = fileURLToPath(new URL('./review-snapshot-worker.mjs', import.meta.url));
+const MAX_SNAPSHOT = 16 * 1024 * 1024;
 
-// 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.
+// The worker runs inside the tool boundary; what it prints is one short line.
+async function worker(boundary, mode) {
+  const result = await boundary.invoke('bash', { command: `${quote(process.execPath)} ${quote(WORKER)} ${mode}`, timeout: 60 });
+  const text = textContent(result).trim();
+  if (result.details?.truncation?.truncated || text.includes('\n')) throw Error(/review-(patch|file|untracked)-limit/.exec(text)?.[0] ?? 'managed-review-patch-unreadable');
+  const [digest, bytes, name] = text.split(' ');
+  if (!/^[a-f0-9]{64}$/.test(digest ?? '') || !(Number(bytes) > 0 && Number(bytes) <= MAX_SNAPSHOT)) throw Error(/review-(patch|file|untracked)-limit/.exec(text)?.[0] ?? 'managed-review-patch-unreadable');
+  return { digest, bytes: Number(bytes), name };
+}
+
+// The digest of the patch a reviewer would see (diff against HEAD plus
+// untracked files): whether a review is still current. Nothing else moves.
+export async function readPatchDigest(boundary) { return (await worker(boundary, 'digest')).digest; }
+
+// The patch a reviewer sees, read inside the tool boundary. The worker writes
+// it to the boundary's temporary directory and names it, with its digest, on
+// its output; the file is read once, must match that digest (a file changed
+// meanwhile never passes) and is removed.
 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 };
+  const { digest, bytes, name } = await worker(boundary, 'file');
+  if (!/^review-[0-9a-f-]{36}\.json$/.test(name ?? '')) throw Error('managed-review-patch-unreadable');
+  const file = path.join(boundary.temporary, name);
+  let data;
+  try {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+      if (!fs.fstatSync(fd).isFile() || fs.fstatSync(fd).size !== bytes) throw Error('managed-review-patch-changed');
+      data = Buffer.alloc(bytes);
+      for (let at = 0; at < bytes;) { const n = fs.readSync(fd, data, at, bytes - at, at); if (!n) throw Error('managed-review-patch-changed'); at += n; }
+    } finally { fs.closeSync(fd); }
+  } finally { fs.rmSync(file, { force: true }); }
+  if (createHash('sha256').update(data).digest('hex') !== digest) throw Error('managed-review-patch-changed');
+  return { patch: data.toString('utf8'), digest };
 }
 
 // Why a required review could not run, in one word for the member.
@@ -43,6 +57,78 @@ 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.mode === 'directory' ? `=== new folder ${f.path} (a repository of its own, not reviewed)`
+    : f.encoding === 'omitted' ? `=== new file ${f.path} (${f.bytes} bytes, too large to review)`
     : 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')}` : ''}`;
 }
+
+// A patch larger than one reviewer reads at once (REVIEW_PART_BYTES, about
+// 30k tokens with room to read the code around it) is reviewed in parts of
+// whole files under the review helper's grant, and the findings are merged.
+// The parts run one after another (REVIEW_PARALLEL): Studio admits one
+// request of a run role at a time, so parts side by side only wait in its
+// line (measured 2026-10-05: 4 parts, each started as the previous ended). One file's diff larger than READ_SECTION is not
+// read (a lockfile, generated output): every part and the merged answer name
+// it. More than REVIEW_PARTS_MAX parts: the review cannot run (too_large).
+export const REVIEW_PART_BYTES = 120_000, REVIEW_PARALLEL = 1, REVIEW_PARTS_MAX = 96;
+const READ_SECTION = 400_000;
+const SEVERITY = { blocking: 0, major: 1, minor: 2 };
+
+export function reviewParts(snapshot, size = REVIEW_PART_BYTES) {
+  const whole = reviewText(snapshot);
+  let value;
+  try { value = JSON.parse(snapshot.patch); } catch { value = null; }
+  const omitted = (value?.untracked ?? []).filter(f => f.encoding === 'omitted').map(f => ({ path: f.path, bytes: f.bytes, ...(f.mode === 'directory' ? { repository: true } : {}) }));
+  if (!value || Buffer.byteLength(whole) <= size && !omitted.length) return { parts: [{ files: null, text: whole }], omitted: [] };
+  const sections = [];
+  for (const text of String(value.patch ?? '').split(/(?=^diff --git )/m).filter(Boolean)) {
+    const file = /^diff --git (?:"?a\/(.+?)"? )"?b\/(.+?)"?$/m.exec(text)?.[2] ?? text.slice(0, 200).split('\n')[0];
+    sections.push({ file, kind: 'diff', text, bytes: Buffer.byteLength(text) });
+  }
+  for (const f of value.untracked ?? []) {
+    if (f.encoding === 'omitted') continue;
+    const text = 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)`;
+    sections.push({ file: f.path, kind: 'new', text, bytes: Buffer.byteLength(text) });
+  }
+  const groups = [];
+  for (const section of sections) {
+    if (section.bytes > READ_SECTION) { omitted.push({ path: section.file, bytes: section.bytes }); continue; }
+    const last = groups.at(-1);
+    if (last && last.bytes + section.bytes <= size) { last.sections.push(section); last.bytes += section.bytes; }
+    else groups.push({ sections: [section], bytes: section.bytes });
+  }
+  if (groups.length > REVIEW_PARTS_MAX) throw Error('managed-review-patch-too-large');
+  const skipped = omitted.length ? `\nNot read: ${omitted.map(o => o.repository ? `${o.path} (a repository of its own)` : `${o.path} (${o.bytes} bytes, too large to review)`).join(', ')}.` : '';
+  const parts = groups.map((group, i) => {
+    const files = group.sections.map(s => s.file), diff = group.sections.filter(s => s.kind === 'diff').map(s => s.text).join(''), news = group.sections.filter(s => s.kind === 'new').map(s => s.text);
+    const head = groups.length === 1 ? `Patch snapshot ${snapshot.digest}.` : `Patch snapshot ${snapshot.digest}, part ${i + 1} of ${groups.length}. This part's files: ${files.join(', ')}. The other parts are reviewed separately: judge this part, and read other files only for context.`;
+    return { files, text: `${head}${skipped}\n--- diff against HEAD ---\n${diff || '(no changes to tracked files in this part)'}\n${news.length ? `--- new files ---\n${news.join('\n\n')}` : ''}` };
+  });
+  return { parts: parts.length ? parts : [{ files: [], text: `Patch snapshot ${snapshot.digest}: every changed file is too large to review.${skipped}` }], omitted };
+}
+
+// One answer from the review of every part: each part's summary, then the
+// findings of all parts (most severe first) and their objections to the brief
+// in one JSON block. `parsed`: every part gave its JSON.
+export function mergeReviews(review, answers, { findingsOf, issuesOf }) {
+  const n = answers.length, all = [], issues = [], lines = [];
+  let parsed = true;
+  answers.forEach((answer, i) => {
+    const findings = findingsOf(answer.reply);
+    if (!findings) parsed = false;
+    all.push(...(findings ?? []));
+    issues.push(...(issuesOf(answer.reply) ?? []));
+    let summary = null;
+    for (const raw of [...String(answer.reply).matchAll(/```json\s*([\s\S]*?)```/g)].map(m => m[1]).reverse()) { try { summary = JSON.parse(raw)?.summary ?? null; if (summary) break; } catch { /* not this block */ } }
+    const files = review.parts[i].files ?? [];
+    lines.push(`Part ${i + 1}/${n} (${files.length} file${files.length === 1 ? '' : 's'}: ${files.slice(0, 6).join(', ')}${files.length > 6 ? ', …' : ''}): ${findings ? `${findings.length} finding(s). ${typeof summary === 'string' ? summary.slice(0, 300) : ''}` : `no JSON findings; its answer began: ${String(answer.reply).slice(0, 400)}`}`);
+  });
+  all.sort((a, b) => SEVERITY[a.severity] - SEVERITY[b.severity]);
+  const count = severity => all.filter(f => f.severity === severity).length;
+  const summary = `${n} parts reviewed: ${count('blocking')} blocking, ${count('major')} major, ${count('minor')} minor${parsed ? '' : '; a part gave no JSON findings'}${review.omitted.length ? `; ${review.omitted.length} file(s) too large to review` : ''}.`;
+  const json = JSON.stringify({ findings: all.slice(0, 40), brief_issues: issues.slice(0, 5), summary });
+  const head = `Review of the patch in ${n} parts.${review.omitted.length ? ` Not read, too large: ${review.omitted.map(o => o.path).join(', ')}.` : ''}\n`;
+  const body = lines.join('\n').slice(0, Math.max(0, 16000 - json.length - head.length - 20));
+  return { reply: `${head}${body}\n\`\`\`json\n${json}\n\`\`\``, usage: answers.reduce((total, a) => total + a.usage, 0), findings: all, parsed, blocking: count('blocking') };
+}

package/packages/piagent-core/managed/request-stream.mjs

@@ -8,9 +8,13 @@ import { randomUUID } from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { describeFailure, failureCode, failureIsAdmissionRefusal, failureIsBriefRefusal, failureReason, unnamedFailureText } from '../runtime/managed-failure.mjs';
 import { CLIENT_AGENT } from './client-agent.mjs';
+import { shareGrant, releaseGrant } from './grant-share.mjs';
 
 // How long one request waits in line for a free company model account.
 const CAPACITY_WAIT_MS = 20 * 60_000;
+// How long a helper's request waits before the helper moves to another model.
+export const HELPER_SWITCH_MS = 60_000;
+const HELPER_SWITCH_CODES = new Set(['session_account_not_ready_retry_later', 'account_capacity_unavailable']);
 // A brief refusal (see failureIsBriefRefusal) is asked again up to three times,
 // 3, 6 and 9 s apart.
 const BRIEF_ASKS = 3, BRIEF_PAUSE_MS = 3_000;
@@ -23,7 +27,8 @@ export function wrapRoleStreams(owner, runtime, role, { provider, verifyGrant })
       if (role === 'main') owner.mainAnswers = (owner.mainAnswers ?? 0) + 1;
       const out = owner.ai.createAssistantMessageEventStream(), signal = options?.signal;
       void (async () => {
-        let wait = null, noted = false, brief = 0, refused = null;
+        let wait = null, noted = false, brief = 0, refused = null, rebinds = 0, share = null;
+        const letGo = () => { if (share) { releaseGrant(owner, role, share); share = null; } };
         // The error event and the final message carry the same failure: kept once.
         const unnamed = raw => { noted ||= keepUnnamed(owner, role, raw); return raw; };
         try {
@@ -39,14 +44,22 @@ export function wrapRoleStreams(owner, runtime, role, { provider, verifyGrant })
           for (;;) {
             // Asked again after a refusal and the grant cannot be renewed (the
             // run was closed): the refusal says why, not the renewal.
-            const grant = await owner.broker.request('renew', { role }).catch((error) => { throw refused ? Error(refused) : error; });
+            // Requests of one role running side by side (a review in parts, a
+            // helper's search beside its call) share one renew: each renew
+            // replaces the role's token and would void a sibling's before
+            // Studio admits it. The share is let go once Studio has answered.
+            share = shareGrant(owner, role);
+            const grant = await share.grant.catch((error) => { throw refused ? Error(refused) : error; });
             verifyGrant(grant, owner.manifest, role);
             if (role === 'main') owner.grant = grant;
             const route = owner.routes.get(runtime);
             if (!route || grant.provider_model_id !== route.native || grant.provider !== route.provider || grant.model_id !== route.model_id || model.id !== 'agent-watch-auto') throw Error('managed-route-changed');
             const asked = Date.now();
-            const stream = original({ ...model, id: route.native }, context, { ...options, apiKey: grant.token, sessionId: grant.role_id, maxRetries: 0,
-              headers: { ...options?.headers, 'User-Agent': CLIENT_AGENT, 'X-Session-Id': grant.role_id } });
+            // The main agent names its conversation, so every turn reaches the
+            // same company account and prompt cache; a helper names its role.
+            const conversation = role === 'main' ? conversationSession(owner) : null;
+            const stream = original({ ...model, id: route.native }, context, { ...options, apiKey: grant.token, sessionId: conversation ?? grant.role_id, maxRetries: 0,
+              headers: { ...options?.headers, 'User-Agent': CLIENT_AGENT, 'X-Session-Id': grant.role_id, ...(conversation ? { 'X-Claude-Code-Session-Id': conversation } : {}) } });
             // Whether Studio admitted the request is known at its first event
             // after "start": until then nothing is passed on, so a refused
             // request leaves no trace in the conversation.
@@ -54,12 +67,27 @@ export function wrapRoleStreams(owner, runtime, role, { provider, verifyGrant })
             for await (const event of stream) {
               if (opening && event.type === 'start') { opening.push(event); continue; }
               const code = event.type === 'error' ? failureCode(event.error?.errorMessage) : null;
-              if (opening && code && !signal?.aborted && (failureIsAdmissionRefusal(code) || failureIsBriefRefusal(code) && brief < BRIEF_ASKS)) { refusal = event.error; break; }
-              if (opening) { for (const held of opening) out.push(held); opening = null; wait = capacityWaitEnded(owner, wait, 'admitted'); }
+              if (opening && code && !signal?.aborted && (failureIsAdmissionRefusal(code) || failureIsBriefRefusal(code) && brief < BRIEF_ASKS
+                || role === 'main' && code === ACCOUNT_GONE && rebinds < MAX_REBINDS)) { refusal = event.error; break; }
+              if (opening) { for (const held of opening) out.push(held); opening = null; wait = capacityWaitEnded(owner, wait, 'admitted'); letGo(); }
               out.push(event.type === 'error' ? { ...event, ...(signal?.aborted ? { reason: 'aborted' } : {}), error: told(event.error) } : event);
             }
             if (!refusal) { for (const held of opening ?? []) out.push(held); out.end(told(await stream.result())); return; }
             refused = String(refusal.errorMessage ?? '');
+            // A lapsed or replaced grant: the next ask renews it, not this share.
+            const stale = share; letGo();
+            if (failureIsBriefRefusal(failureCode(refusal.errorMessage)) && owner.sharedGrants?.get(role) === stale) owner.sharedGrants.delete(role);
+            // The conversation's account is gone (signed out, removed) or has
+            // rested past SESSION_REBIND_MS (a spent quota window): a new
+            // generation lets Studio bind the conversation to another account.
+            // Its prompt cache starts over there once.
+            const refusedCode = failureCode(refusal.errorMessage);
+            if (role === 'main' && rebinds < MAX_REBINDS && (refusedCode === ACCOUNT_GONE
+              || refusedCode === ACCOUNT_RESTING && wait && Date.now() - wait.since >= (owner.sessionRebindMs ?? SESSION_REBIND_MS))) {
+              owner.conversationGeneration = (owner.conversationGeneration ?? 0) + 1; rebinds += 1;
+              wait = capacityWaitEnded(owner, wait, 'rebound');
+              continue;
+            }
             // A brief refusal is asked again after a short pause, without a wait step.
             if (failureIsBriefRefusal(failureCode(refusal.errorMessage))) { brief += 1; await sleep((owner.briefPauseMs ?? BRIEF_PAUSE_MS) * brief, undefined, { signal }); continue; }
             wait = await waitForCapacity(owner, wait, role, failureCode(refusal.errorMessage), signal, Date.now() - asked);
@@ -72,13 +100,28 @@ export function wrapRoleStreams(owner, runtime, role, { provider, verifyGrant })
           out.push({ type: 'error', reason: aborted ? 'aborted' : 'error', error: { role: 'assistant', content: [], api: model.api, provider: provider, model: model.id,
             stopReason: aborted ? 'aborted' : 'error', errorMessage: aborted ? 'Request was aborted' : describeFailure(role, unnamed(error?.message)), timestamp: Date.now(),
             usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } } });
-        } finally { capacityWaitEnded(owner, wait, signal?.aborted ? 'stopped' : 'ended'); }
+        } finally { letGo(); capacityWaitEnded(owner, wait, signal?.aborted ? 'stopped' : 'ended'); }
       })();
       return out;
     };
   }
 }
 
+// Studio binds a conversation to one company account (session_bindings): the
+// provider's prompt cache lives on that account (Claude) and follows
+// prompt_cache_key (Codex). The main agent therefore names its conversation
+// (the Pi session id), not the turn's run role; measured 2026-10-04, a run
+// role per turn left Codex 10% cached on each turn's first request.
+const ACCOUNT_GONE = 'session_account_unavailable_start_new_session';
+const ACCOUNT_RESTING = 'session_account_not_ready_retry_later';
+export const SESSION_REBIND_MS = 90_000;
+const MAX_REBINDS = 2;
+export function conversationSession(owner) {
+  const id = owner.session?.sessionManager?.getSessionId?.();
+  if (typeof id !== 'string' || !/^[\w-]{8,128}$/.test(id)) return null;
+  return owner.conversationGeneration ? `${id}-${owner.conversationGeneration}` : id;
+}
+
 // A failure no code names is shown as "could not be sent"; its own words are
 // kept, redacted, in the conversation file (never shown) so it can be told
 // apart later. True when it was kept.
@@ -105,6 +148,10 @@ export function capacityDelayMs(asks, heldMs, random = Math.random()) {
 // CAPACITY_WAIT_MS it fails with Studio's reason. Null: stop waiting.
 async function waitForCapacity(owner, wait, role, code, signal, heldMs = 0) {
   if (wait && Date.now() - wait.since >= (owner.capacityWaitMs ?? CAPACITY_WAIT_MS)) { capacityWaitEnded(owner, wait, 'gave-up'); return null; }
+  // A helper whose model has no account free for a while (resting after a
+  // refusal, out of usage) stops waiting: it starts once more, and Studio
+  // gives the new helper the next model of its role that serves.
+  if (wait && role !== 'main' && HELPER_SWITCH_CODES.has(code) && Date.now() - wait.since >= (owner.helperSwitchMs ?? HELPER_SWITCH_MS)) { capacityWaitEnded(owner, wait, 'switched'); return null; }
   wait ??= { id: randomUUID(), role, since: Date.now(), asks: 0, open: true };
   wait.asks += 1; wait.code = code;
   owner.capacityWaits.add(wait);

package/packages/piagent-core/managed/review-snapshot-worker.mjs

@@ -1,27 +1,45 @@
 import fs from 'node:fs';
-import { createHash } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { managedGit } from './toolchain.mjs';
 // Executed only through the tool Seatbelt boundary; repo-local Git config cannot
 // grant a hook, textconv or credential helper access to the trusted runtime.
-const git = args => execFileSync(managedGit(), ['--no-pager', ...args], { encoding: 'utf8', maxBuffer: 160000, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' } });
+// The snapshot holds the whole patch (its digest decides whether a review is
+// stale); a reviewer reads it in parts (patch-snapshot.mjs). A new file too
+// large to read is held by its hash: a change to it still changes the digest.
+const MAX_SNAPSHOT = 16 * 1024 * 1024, MAX_UNTRACKED = 2000, READ_FILE = 400_000, BINARY_INLINE = 120_000, HASHED_FILE = 256 * 1024 * 1024;
+const git = args => execFileSync(managedGit(), ['--no-pager', ...args], { encoding: 'utf8', maxBuffer: MAX_SNAPSHOT + 1, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_NOSYSTEM: '1' } });
+const sha256 = data => createHash('sha256').update(data).digest('hex');
 const patch = git(['diff', '--binary', '--no-ext-diff', '--no-textconv', 'HEAD', '--', '.']);
 const paths = git(['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean).sort();
-if (paths.length > 100) throw Error('review-untracked-limit');
+if (paths.length > MAX_UNTRACKED) throw Error('review-untracked-limit');
 const untracked = paths.map(name => {
   const stat = fs.lstatSync(name);
   if (stat.isSymbolicLink()) return { path: name, mode: 'symlink', target: fs.readlinkSync(name) };
-  if (!stat.isFile() || stat.size > 120000) throw Error('review-file-limit');
+  // A folder Git lists as one entry is a repository of its own (a clone
+  // inside the project): named, not read, and its entries keep the digest.
+  if (stat.isDirectory()) return { path: name, mode: 'directory', encoding: 'omitted', bytes: 0, sha256: sha256(fs.readdirSync(name).sort().join('\0')) };
+  if (!stat.isFile() || stat.size > HASHED_FILE) throw Error('review-file-limit');
+  const data = fs.readFileSync(name), mode = stat.mode & 0o777;
+  if (stat.size > READ_FILE) return { path: name, mode, encoding: 'omitted', bytes: stat.size, sha256: sha256(data) };
   // Text goes as text, so the reviewer can read new files; binary as base64.
-  const data = fs.readFileSync(name);
   let text = null;
   if (!data.includes(0)) { try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(data); } catch { text = null; } }
-  return text === null ? { path: name, mode: stat.mode & 0o777, contents: data.toString('base64'), encoding: 'base64' } : { path: name, mode: stat.mode & 0o777, contents: text, encoding: 'utf8' };
+  if (text !== null) return { path: name, mode, contents: text, encoding: 'utf8' };
+  return stat.size > BINARY_INLINE ? { path: name, mode, encoding: 'omitted', bytes: stat.size, sha256: sha256(data) } : { path: name, mode, contents: data.toString('base64'), encoding: 'base64' };
 });
-const snapshot = JSON.stringify({ patch, untracked });
-if (Buffer.byteLength(snapshot) > 120000) throw Error('review-patch-limit');
-// With a part number the snapshot is sent in base64 parts small enough for the
-// shell tool's output limit, each headed by the whole snapshot's digest.
-const part = process.argv[2], bytes = Buffer.from(snapshot), SIZE = 30000;
-if (part === undefined) process.stdout.write(snapshot);
-else process.stdout.write(`${createHash('sha256').update(bytes).digest('hex')} ${Math.max(1, Math.ceil(bytes.length / SIZE))}\n${bytes.subarray(Number(part) * SIZE, (Number(part) + 1) * SIZE).toString('base64')}`);
+const snapshot = Buffer.from(JSON.stringify({ patch, untracked }));
+if (snapshot.length > MAX_SNAPSHOT) throw Error('review-patch-limit');
+// "digest": the digest and size only (is a review still current?). "file":
+// the snapshot goes to a new file in this boundary's temporary directory,
+// named on stdout with its digest; the runtime reads it once, checks the
+// digest and removes it. No argument: the snapshot itself.
+const mode = process.argv[2];
+if (mode === 'digest') process.stdout.write(`${sha256(snapshot)} ${snapshot.length}`);
+else if (mode === 'file') {
+  const name = `review-${randomUUID()}.json`;
+  fs.writeFileSync(path.join(os.tmpdir(), name), snapshot, { mode: 0o600, flag: 'wx' });
+  process.stdout.write(`${sha256(snapshot)} ${snapshot.length} ${name}`);
+} else process.stdout.write(snapshot);