pi-subagents 0.80.0 → 0.81.0

package/bundle/chunk-CTPAE36Y.js

@@ -0,0 +1,94 @@
+// src/shared/required-child-extensions.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+var ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var MAX_REQUIRED_EXTENSIONS = 32;
+var MAX_PATH_BYTES = 4096;
+var EMPTY_SNAPSHOT = Object.freeze([]);
+function snapshotRequiredChildExtensions(value, label = "Required child extensions", canonicalizeFiles = false) {
+  if (!Array.isArray(value) || value.length > MAX_REQUIRED_EXTENSIONS) throw new Error(`${label} must be an array of at most ${MAX_REQUIRED_EXTENSIONS} entries.`);
+  const ids = /* @__PURE__ */ new Set();
+  const paths = /* @__PURE__ */ new Set();
+  return Object.freeze(value.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry) || Object.keys(entry).some((key) => key !== "id" && key !== "path" && (canonicalizeFiles || key !== "requireForAllRunners"))) throw new Error(`${label} entry ${index} requires only id and path.`);
+    const id = "id" in entry ? entry.id : void 0;
+    const rawPath = "path" in entry ? entry.path : void 0;
+    const requireForAllRunners = "requireForAllRunners" in entry ? entry.requireForAllRunners : void 0;
+    if (typeof id !== "string" || !ID_PATTERN.test(id)) throw new Error(`${label} entry ${index} requires a safe id of at most 128 characters.`);
+    if (ids.has(id)) throw new Error(`${label} id '${id}' is duplicated.`);
+    if (requireForAllRunners !== void 0 && requireForAllRunners !== true) throw new Error(`${label} '${id}' requireForAllRunners must be true when present.`);
+    if (typeof rawPath !== "string" || !rawPath.trim() || rawPath.includes("\0") || Buffer.byteLength(rawPath, "utf8") > MAX_PATH_BYTES || !canonicalizeFiles && !path.isAbsolute(rawPath)) throw new Error(`${label} '${id}' requires ${canonicalizeFiles ? "a" : "an absolute"} non-empty path of at most ${MAX_PATH_BYTES} bytes without NUL.`);
+    let extensionPath = rawPath;
+    if (canonicalizeFiles) {
+      try {
+        extensionPath = fs.realpathSync(path.resolve(rawPath));
+        if (!fs.statSync(extensionPath).isFile()) throw new Error("not a file");
+      } catch (error) {
+        throw new Error(`${label} '${id}' is not an importable file: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    if (paths.has(extensionPath)) throw new Error(`${label} path '${extensionPath}' is duplicated.`);
+    ids.add(id);
+    paths.add(extensionPath);
+    return Object.freeze(requireForAllRunners ? { id, path: extensionPath, requireForAllRunners } : { id, path: extensionPath });
+  }));
+}
+function registry() {
+  const key = /* @__PURE__ */ Symbol.for("pi-subagents.required-child-extensions.v1");
+  const root = globalThis;
+  const existing = root[key];
+  if (existing === void 0) {
+    const created = { version: 1, bySession: /* @__PURE__ */ new Map() };
+    root[key] = created;
+    return created;
+  }
+  if (!existing || typeof existing !== "object" || !("version" in existing) || existing.version !== 1 || !("bySession" in existing) || !(existing.bySession instanceof Map)) throw new Error("Malformed or unsupported required child extension registry.");
+  return { version: 1, bySession: existing.bySession };
+}
+function registerRequiredChildExtensions(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => key !== "sessionId" && key !== "extensions" && key !== "requireForAllRunners")) throw new Error("Required child extension registration accepts only sessionId, extensions, and requireForAllRunners.");
+  if (typeof input.sessionId !== "string" || !input.sessionId || input.sessionId.trim() !== input.sessionId || input.sessionId.length > 256 || input.sessionId.includes("\0")) throw new Error("Required child extension registration requires a non-empty trimmed sessionId of at most 256 characters without NUL.");
+  if (input.requireForAllRunners !== void 0 && typeof input.requireForAllRunners !== "boolean") throw new Error("Required child extension registration requireForAllRunners must be a boolean.");
+  const canonical = snapshotRequiredChildExtensions(input.extensions, "Required child extensions", true);
+  const frozen = input.requireForAllRunners ? Object.freeze(canonical.map((entry) => Object.freeze({ ...entry, requireForAllRunners: true }))) : canonical;
+  const store = registry();
+  if (store.bySession.has(input.sessionId)) throw new Error(`Required child extensions are already registered for session '${input.sessionId}'; dispose them first.`);
+  store.bySession.set(input.sessionId, frozen);
+  return { dispose() {
+    if (store.bySession.get(input.sessionId) === frozen) store.bySession.delete(input.sessionId);
+  } };
+}
+function resolveRequiredChildExtensions(sessionId) {
+  if (!sessionId) return EMPTY_SNAPSHOT;
+  return registry().bySession.get(sessionId) ?? EMPTY_SNAPSHOT;
+}
+function assertRequiredChildExtensionsAdmitted(snapshots, launch) {
+  const ids = [...new Set(snapshots.flatMap((snapshot) => snapshot ?? []).filter((entry) => entry.requireForAllRunners).map((entry) => entry.id))];
+  if (ids.length === 0) return;
+  const route = launch.machine ? `machine '${launch.machine}'` : launch.runnerType !== void 0 && launch.runnerType !== "pi" ? `runner.type='${launch.runnerType}'` : void 0;
+  if (route) throw new Error(`Agent '${launch.agent}' cannot run on ${route}: the host requires child extensions (${ids.join(", ")}) for every runner, and only local native Pi children load them.`);
+}
+function hasMandatoryRequiredChildExtensions(snapshot) {
+  return snapshot?.some((entry) => entry.requireForAllRunners) === true;
+}
+var RETAINED_FILE = "required-child-extensions.json";
+function writeRetainedRequiredChildExtensions(asyncDir, snapshot) {
+  if (!hasMandatoryRequiredChildExtensions(snapshot)) return;
+  fs.writeFileSync(path.join(asyncDir, RETAINED_FILE), `${JSON.stringify(snapshot)}
+`, { mode: 384 });
+}
+function readRetainedRequiredChildExtensions(asyncDir) {
+  const filePath = path.join(asyncDir, RETAINED_FILE);
+  if (!fs.existsSync(filePath)) return void 0;
+  return snapshotRequiredChildExtensions(JSON.parse(fs.readFileSync(filePath, "utf-8")), "Retained required child extensions");
+}
+
+export {
+  snapshotRequiredChildExtensions,
+  registerRequiredChildExtensions,
+  resolveRequiredChildExtensions,
+  assertRequiredChildExtensionsAdmitted,
+  hasMandatoryRequiredChildExtensions,
+  writeRetainedRequiredChildExtensions,
+  readRetainedRequiredChildExtensions
+};

package/bundle/chunk-D4EHT5SJ.js

@@ -0,0 +1,14 @@
+// src/api/delegation.ts
+var SUBAGENT_DELEGATION_REQUEST_EVENT = "prompt-template:subagent:request";
+var SUBAGENT_DELEGATION_STARTED_EVENT = "prompt-template:subagent:started";
+var SUBAGENT_DELEGATION_UPDATE_EVENT = "prompt-template:subagent:update";
+var SUBAGENT_DELEGATION_RESPONSE_EVENT = "prompt-template:subagent:response";
+var SUBAGENT_DELEGATION_CANCEL_EVENT = "prompt-template:subagent:cancel";
+
+export {
+  SUBAGENT_DELEGATION_REQUEST_EVENT,
+  SUBAGENT_DELEGATION_STARTED_EVENT,
+  SUBAGENT_DELEGATION_UPDATE_EVENT,
+  SUBAGENT_DELEGATION_RESPONSE_EVENT,
+  SUBAGENT_DELEGATION_CANCEL_EVENT
+};

package/bundle/chunk-EYNJ6VL6.js

@@ -0,0 +1,526 @@
+import {
+  getProjectSubagentsDir
+} from "./chunk-3DC5KBVP.js";
+import {
+  discoverAgents,
+  formatUnknownAgentError,
+  resolveAgentName,
+  unknownAgentDiagnosticContext
+} from "./chunk-ZBC44JJ3.js";
+
+// src/agents/agent-refinements.ts
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+var REFINEMENT_FORMAT_VERSION = 1;
+var REFINEMENT_DIR = "refinements";
+var CURRENT_FENCE = "pi-subagents-refinement-current";
+var SNAPSHOTS_FENCE = "pi-subagents-refinement-snapshots-json";
+var MAX_EVIDENCE_ITEMS = 8;
+var MAX_AGE_DAYS = 14;
+var MAX_ITEM_BYTES = 2048;
+var MAX_PACKET_BYTES = 16384;
+var PROPOSAL_AGENT = "reviewer";
+function result(text2, isError = false) {
+  return {
+    content: [{ type: "text", text: text2 }],
+    ...isError ? { isError: true } : {},
+    details: { mode: "management", results: [] }
+  };
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function textArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(text).filter((entry) => entry !== null);
+}
+function isoTime(value) {
+  const numberValue = typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  if (numberValue !== void 0) return new Date(numberValue).toISOString();
+  const stringValue = text(value);
+  if (!stringValue) return void 0;
+  const parsed = Date.parse(stringValue);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : void 0;
+}
+function hashPrompt(systemPrompt) {
+  return createHash("sha256").update(systemPrompt).digest("hex");
+}
+function safeAgentFileName(agentName) {
+  const trimmed = agentName.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed) || trimmed.includes("..")) {
+    throw new Error(`Agent name '${agentName}' cannot be used as a refinement file name.`);
+  }
+  return `${trimmed}.md`;
+}
+function getAgentRefinementPath(cwd, agentName) {
+  const refinementRoot = path.join(getProjectSubagentsDir(cwd), REFINEMENT_DIR);
+  const resolvedRoot = path.resolve(refinementRoot);
+  const resolvedPath = path.resolve(refinementRoot, safeAgentFileName(agentName));
+  if (resolvedPath !== path.join(resolvedRoot, path.basename(resolvedPath))) {
+    throw new Error(`Agent name '${agentName}' cannot be used as a refinement file name.`);
+  }
+  return resolvedPath;
+}
+function readExisting(cwd, agentName) {
+  const filePath = getAgentRefinementPath(cwd, agentName);
+  if (!fs.existsSync(filePath)) return { path: filePath };
+  return { path: filePath, parsed: parseRefinementFile(fs.readFileSync(filePath, "utf-8"), filePath) };
+}
+function extractFence(markdown, fence) {
+  const escaped = fence.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = markdown.match(new RegExp("\\n```" + escaped + "\\n([\\s\\S]*?)\\n```", "m"));
+  return match?.[1] ?? null;
+}
+function parseRefinementFile(markdown, label = "refinement file") {
+  const metadataMatch = markdown.match(/^<!-- pi-subagents-refinement:v1\n([\s\S]*?)\n-->\n/);
+  if (!metadataMatch?.[1]) throw new Error(`${label} is missing refinement metadata.`);
+  const metadataValue = JSON.parse(metadataMatch[1]);
+  const metadataRecord = record(metadataValue);
+  if (!metadataRecord) throw new Error(`${label} metadata must be an object.`);
+  const agent = text(metadataRecord.agent);
+  const revision = metadataRecord.revision;
+  const updatedAt = text(metadataRecord.updatedAt);
+  const base = record(metadataRecord.base);
+  const evidence = record(metadataRecord.evidence);
+  if (!agent || typeof revision !== "number" || !Number.isInteger(revision) || !updatedAt || !base || !evidence) {
+    throw new Error(`${label} metadata is invalid.`);
+  }
+  const source = text(base.source);
+  const filePath = text(base.filePath);
+  const systemPromptSha256 = text(base.systemPromptSha256);
+  if (source !== "builtin" && source !== "package" && source !== "user" && source !== "project") throw new Error(`${label} base source is invalid.`);
+  if (!filePath || !systemPromptSha256) throw new Error(`${label} base metadata is invalid.`);
+  const current = extractFence(markdown, CURRENT_FENCE);
+  if (current === null) throw new Error(`${label} is missing current refinement block.`);
+  const snapshotsRaw = extractFence(markdown, SNAPSHOTS_FENCE) ?? "[]";
+  const snapshotsValue = JSON.parse(snapshotsRaw);
+  if (!Array.isArray(snapshotsValue)) throw new Error(`${label} snapshots must be an array.`);
+  const snapshots = snapshotsValue.map((entry, index) => {
+    const item = record(entry);
+    if (!item) throw new Error(`${label} snapshot ${index} must be an object.`);
+    const action = text(item.action);
+    const before = typeof item.before === "string" ? item.before : null;
+    const after = typeof item.after === "string" ? item.after : null;
+    const at = text(item.at);
+    if (typeof item.revision !== "number" || !Number.isInteger(item.revision) || !at || action !== "refine" && action !== "rollback" || before === null || after === null) {
+      throw new Error(`${label} snapshot ${index} is invalid.`);
+    }
+    return {
+      revision: item.revision,
+      at,
+      action,
+      before,
+      after,
+      evidenceIds: textArray(item.evidenceIds),
+      ...text(item.proposalAgent) ? { proposalAgent: text(item.proposalAgent) } : {}
+    };
+  });
+  return {
+    metadata: {
+      agent,
+      revision,
+      updatedAt,
+      base: { source, filePath, systemPromptSha256 },
+      evidence: {
+        maxItems: typeof evidence.maxItems === "number" ? evidence.maxItems : MAX_EVIDENCE_ITEMS,
+        maxAgeDays: typeof evidence.maxAgeDays === "number" ? evidence.maxAgeDays : MAX_AGE_DAYS,
+        itemBytes: typeof evidence.itemBytes === "number" ? evidence.itemBytes : MAX_ITEM_BYTES,
+        totalBytes: typeof evidence.totalBytes === "number" ? evidence.totalBytes : MAX_PACKET_BYTES
+      }
+    },
+    current,
+    snapshots
+  };
+}
+function serializeRefinementFile(parsed) {
+  const metadata = JSON.stringify(parsed.metadata, null, 2);
+  const snapshots = JSON.stringify(parsed.snapshots, null, 2);
+  return [
+    `<!-- pi-subagents-refinement:v${REFINEMENT_FORMAT_VERSION}`,
+    metadata,
+    "-->",
+    "",
+    `# Current refinement for \`${parsed.metadata.agent}\``,
+    "",
+    `\`\`\`${CURRENT_FENCE}`,
+    parsed.current,
+    "```",
+    "",
+    "# Snapshots",
+    "",
+    `\`\`\`${SNAPSHOTS_FENCE}`,
+    snapshots,
+    "```",
+    ""
+  ].join("\n");
+}
+function writeRefinementFile(filePath, parsed) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  fs.writeFileSync(tmp, serializeRefinementFile(parsed), "utf-8");
+  fs.renameSync(tmp, filePath);
+}
+function baseMetadata(agent) {
+  return {
+    source: agent.source,
+    filePath: agent.filePath,
+    systemPromptSha256: hashPrompt(agent.systemPrompt)
+  };
+}
+function metadataFor(agent, revision, now) {
+  return {
+    agent: agent.name,
+    revision,
+    updatedAt: now,
+    base: baseMetadata(agent),
+    evidence: {
+      maxItems: MAX_EVIDENCE_ITEMS,
+      maxAgeDays: MAX_AGE_DAYS,
+      itemBytes: MAX_ITEM_BYTES,
+      totalBytes: MAX_PACKET_BYTES
+    }
+  };
+}
+function withinAge(at, now = Date.now()) {
+  if (!at) return true;
+  const parsed = Date.parse(at);
+  return Number.isFinite(parsed) && now - parsed <= MAX_AGE_DAYS * 24 * 60 * 60 * 1e3;
+}
+function tailBytes(value, maxBytes) {
+  const buffer = Buffer.from(value, "utf-8");
+  if (buffer.byteLength <= maxBytes) return value;
+  return buffer.subarray(buffer.byteLength - maxBytes).toString("utf-8");
+}
+function pushCapped(items, item) {
+  if (items.length >= MAX_EVIDENCE_ITEMS) return;
+  items.push({ ...item, outputTail: item.outputTail ? tailBytes(item.outputTail, MAX_ITEM_BYTES) : void 0 });
+}
+function acceptanceFields(value) {
+  const ledger = record(value);
+  if (!ledger) return {};
+  const childReport = record(ledger.childReport);
+  const reviewResult = record(ledger.reviewResult);
+  const reviewFindings = [
+    ...textArray(childReport?.reviewFindings),
+    ...Array.isArray(reviewResult?.findings) ? reviewResult.findings.map((finding) => text(record(finding)?.issue)).filter((entry) => entry !== null) : []
+  ];
+  const residualRisks = textArray(childReport?.residualRisks);
+  return {
+    ...text(ledger.status) ? { acceptanceStatus: text(ledger.status) } : {},
+    ...reviewFindings.length > 0 ? { reviewFindings } : {},
+    ...residualRisks.length > 0 ? { residualRisks } : {}
+  };
+}
+function controlSignals(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((entry) => {
+    const item = record(entry);
+    if (!item) return null;
+    const message = text(item.message);
+    const reason = text(item.reason);
+    return message ? reason ? `${reason}: ${message}` : message : null;
+  }).filter((entry) => entry !== null);
+}
+function evidencePacket(items) {
+  const packet = [];
+  let bytes = 2;
+  for (const item of items) {
+    const encoded = Buffer.byteLength(JSON.stringify(item), "utf-8") + 1;
+    if (bytes + encoded > MAX_PACKET_BYTES) break;
+    packet.push(item);
+    bytes += encoded;
+  }
+  return packet;
+}
+function collectBoundedRefinementEvidence(cwd, agentName, state) {
+  const items = [];
+  const jobs = [...state.asyncJobs.values()].filter((job) => !job.cwd || path.resolve(job.cwd) === path.resolve(cwd)).filter((job) => job.agents?.includes(agentName) || job.steps?.some((step) => step.agent === agentName)).sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+  for (const job of jobs) {
+    const at = isoTime(job.updatedAt ?? job.startedAt);
+    if (!withinAge(at)) continue;
+    const matchingSteps = job.steps?.filter((step) => step.agent === agentName) ?? [];
+    if (matchingSteps.length === 0) {
+      pushCapped(items, {
+        id: `live:${job.asyncId}`,
+        source: "live-state",
+        runId: job.asyncId,
+        agent: agentName,
+        ...at ? { at } : {},
+        status: job.status,
+        refs: [job.asyncDir]
+      });
+      continue;
+    }
+    for (const [index, step] of matchingSteps.entries()) {
+      const stepRecord = step;
+      pushCapped(items, {
+        id: `live:${job.asyncId}:${index}`,
+        source: "live-state",
+        runId: job.asyncId,
+        agent: agentName,
+        ...at ? { at } : {},
+        status: step.status,
+        ...text(stepRecord.model) ? { model: text(stepRecord.model) } : {},
+        ...text(stepRecord.thinking) ? { thinking: text(stepRecord.thinking) } : {},
+        ...acceptanceFields(stepRecord.acceptance),
+        ...text(step.error) ? { errors: [text(step.error)] } : {},
+        ...text(stepRecord.recentOutput) ? { outputTail: text(stepRecord.recentOutput) } : {},
+        refs: [job.asyncDir]
+      });
+    }
+  }
+  const artifactsDir = path.join(getProjectSubagentsDir(cwd), "artifacts");
+  if (fs.existsSync(artifactsDir)) {
+    const files = fs.readdirSync(artifactsDir).filter((file) => file.endsWith("_meta.json")).map((file) => path.join(artifactsDir, file)).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    for (const file of files) {
+      if (items.length >= MAX_EVIDENCE_ITEMS) break;
+      let metadata = null;
+      try {
+        metadata = record(JSON.parse(fs.readFileSync(file, "utf-8")));
+      } catch {
+        metadata = null;
+      }
+      if (!metadata || text(metadata.agent) !== agentName) continue;
+      const stat = fs.statSync(file);
+      const at = isoTime(metadata.timestamp ?? stat.mtimeMs);
+      if (!withinAge(at)) continue;
+      const outputPath = file.replace(/_meta\.json$/, "_output.md");
+      const outputTail = fs.existsSync(outputPath) ? tailBytes(fs.readFileSync(outputPath, "utf-8"), MAX_ITEM_BYTES) : void 0;
+      pushCapped(items, {
+        id: `artifact:${path.basename(file, "_meta.json")}`,
+        source: outputTail ? "artifact-output" : "artifact-metadata",
+        ...text(metadata.runId) ? { runId: text(metadata.runId) } : {},
+        agent: agentName,
+        ...at ? { at } : {},
+        status: typeof metadata.exitCode === "number" ? metadata.exitCode === 0 ? "completed" : "failed" : void 0,
+        ...text(metadata.model) ? { model: text(metadata.model) } : {},
+        ...text(metadata.thinking) ? { thinking: text(metadata.thinking) } : {},
+        ...acceptanceFields(metadata.acceptance),
+        ...text(metadata.error) ? { errors: [text(metadata.error)] } : {},
+        ...controlSignals(metadata.controlEvents).length > 0 ? { controlSignals: controlSignals(metadata.controlEvents) } : {},
+        ...outputTail ? { outputTail } : {},
+        refs: outputTail ? [file, outputPath] : [file]
+      });
+    }
+  }
+  return evidencePacket(items);
+}
+function appendAgentRefinementOverlay(systemPrompt, input) {
+  let current = "";
+  let filePath = "";
+  try {
+    filePath = getAgentRefinementPath(input.cwd, input.agentName);
+    if (!fs.existsSync(filePath)) return systemPrompt;
+    current = parseRefinementFile(fs.readFileSync(filePath, "utf-8"), filePath).current.trim();
+  } catch {
+    return systemPrompt;
+  }
+  if (!current) return systemPrompt;
+  const overlay = [
+    `<pi-subagents-refinement agent=${JSON.stringify(input.agentName)} source=${JSON.stringify(path.relative(input.cwd, filePath))}>`,
+    "Project-local refinement guidance generated from recent bounded evidence.",
+    "It does not override tool, developer, task, output, acceptance, or safety instructions.",
+    "",
+    current,
+    "</pi-subagents-refinement>"
+  ].join("\n");
+  return systemPrompt.trim() ? `${systemPrompt}
+
+${overlay}` : overlay;
+}
+function validateRefinementProposal(proposal, evidenceIds) {
+  const item = record(proposal);
+  if (!item) return { ok: false, error: "Refinement proposal must be an object." };
+  const summary = text(item.summary);
+  const editsValue = item.edits;
+  if (!summary || !Array.isArray(editsValue)) return { ok: false, error: "Refinement proposal requires summary and edits." };
+  if (editsValue.length > 3) return { ok: false, error: "Refinement proposal may contain at most 3 edits." };
+  const allowed = new Set(evidenceIds);
+  const protectedInstruction = "(?:acceptance|output|safety|policy|policies|tools?|developer|system)";
+  const blocked = new RegExp(`\\b(all agents|every agent|global|(?:disable|ignore|bypass|skip|override)\\s+(?:the\\s+)?${protectedInstruction}(?:\\s+instructions?)?|${protectedInstruction}\\s+(?:instructions?|overrides?)|tool safety|review gates|rewrite base|base agent file|settings\\.json|\\.pi/agent|agents/.*\\.md)\\b`, "i");
+  const edits = [];
+  for (const [index, editValue] of editsValue.entries()) {
+    const edit = record(editValue);
+    if (!edit) return { ok: false, error: `Refinement proposal edit ${index} must be an object.` };
+    const title = text(edit.title);
+    const guidance = text(edit.guidance);
+    const rationale = text(edit.rationale);
+    const cited = textArray(edit.evidenceIds);
+    if (!title || !guidance || !rationale) return { ok: false, error: `Refinement proposal edit ${index} is missing title, guidance, or rationale.` };
+    if (cited.length === 0 || cited.some((id) => !allowed.has(id))) return { ok: false, error: `Refinement proposal edit ${index} must cite known evidence ids.` };
+    if (guidance.includes("```") || guidance.includes("</pi-subagents-refinement>") || blocked.test(guidance)) return { ok: false, error: `Refinement proposal edit ${index} contains disallowed guidance.` };
+    edits.push({ title, guidance, rationale, evidenceIds: cited });
+  }
+  return { ok: true, proposal: { summary, edits, rejectedIdeas: textArray(item.rejectedIdeas), residualRisks: textArray(item.residualRisks) } };
+}
+function proposalSchema() {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["summary", "edits", "residualRisks"],
+    properties: {
+      summary: { type: "string" },
+      edits: {
+        type: "array",
+        maxItems: 3,
+        items: {
+          type: "object",
+          additionalProperties: false,
+          required: ["title", "guidance", "evidenceIds", "rationale"],
+          properties: {
+            title: { type: "string" },
+            guidance: { type: "string" },
+            evidenceIds: { type: "array", items: { type: "string" }, minItems: 1 },
+            rationale: { type: "string" }
+          }
+        }
+      },
+      rejectedIdeas: { type: "array", items: { type: "string" } },
+      residualRisks: { type: "array", items: { type: "string" } }
+    }
+  };
+}
+function proposalFromChild(child) {
+  for (const entry of child.details?.results ?? []) {
+    if (entry.structuredOutput !== void 0) return entry.structuredOutput;
+  }
+  const output = child.details?.results?.map((entry) => entry.finalOutput ?? "").find((entry) => entry.trim().length > 0) ?? child.content?.map((entry) => entry.text ?? "").find((entry) => entry.trim().length > 0) ?? "";
+  const jsonMatch = output.match(/```(?:json)?\n([\s\S]*?)\n```/) ?? output.match(/({[\s\S]*})/);
+  if (!jsonMatch?.[1]) return null;
+  try {
+    return JSON.parse(jsonMatch[1]);
+  } catch {
+    return null;
+  }
+}
+function proposalTask(agent, current, evidence) {
+  return [
+    `You are a fresh read-only proposal child for project-local refinement of one subagent: ${agent.name}.`,
+    "Do not read files. Do not use write, edit, or shell tools. Use only the evidence packet below.",
+    "Propose at most 2-3 minimal overlay guidance edits.",
+    "Each edit must cite one or more evidence ids from the packet.",
+    "Do not propose base agent file, settings, global, automatic, tool, safety, output, acceptance, developer, or system instruction changes.",
+    "Return only structured output that matches the schema.",
+    "",
+    "Agent metadata:",
+    JSON.stringify({ name: agent.name, source: agent.source, filePath: agent.filePath, basePromptSha256: hashPrompt(agent.systemPrompt) }, null, 2),
+    "",
+    "Current overlay:",
+    current.trim() || "(none)",
+    "",
+    "Evidence packet:",
+    JSON.stringify(evidence, null, 2)
+  ].join("\n");
+}
+function guidanceFromProposal(proposal) {
+  return proposal.edits.map((edit) => `- ${edit.guidance.trim()}`).join("\n");
+}
+function resolveOneAgent(cwd, agentName) {
+  const discovered = discoverAgents(cwd, "both");
+  const resolved = resolveAgentName(agentName, discovered.agents);
+  if (resolved.error) return { ok: false, error: resolved.error };
+  if (!resolved.agent) return { ok: false, error: formatUnknownAgentError(agentName, unknownAgentDiagnosticContext(discovered)) };
+  return { ok: true, agent: resolved.agent };
+}
+async function handleRefinementAction(action, params, ctx) {
+  const requestedAgent = params.agent?.trim();
+  if (!requestedAgent) return result(`${action} requires agent. Use /subagents-refine <agent> or subagent({ action: "${action}", agent: "<agent>" }).`, true);
+  let resolved;
+  try {
+    resolved = resolveOneAgent(ctx.cwd, requestedAgent);
+  } catch (error) {
+    return result(error instanceof Error ? error.message : String(error), true);
+  }
+  if (!resolved.ok) return result(resolved.error, true);
+  const agent = resolved.agent;
+  let existing;
+  try {
+    existing = readExisting(ctx.cwd, agent.name);
+  } catch (error) {
+    return result(error instanceof Error ? error.message : String(error), true);
+  }
+  if (action === "refine.show") {
+    if (!existing.parsed) return result(`No refinement overlay exists for '${agent.name}'.`);
+    const currentDigest = hashPrompt(agent.systemPrompt);
+    const drift = existing.parsed.metadata.base.systemPromptSha256 === currentDigest ? "no" : "yes";
+    const history = existing.parsed.snapshots.slice(-5).map((snapshot2) => `- r${snapshot2.revision} ${snapshot2.action} at ${snapshot2.at} (${snapshot2.evidenceIds.length} evidence id${snapshot2.evidenceIds.length === 1 ? "" : "s"})`).join("\n") || "- none";
+    return result([
+      `Refinement overlay for '${agent.name}'`,
+      `Path: ${existing.path}`,
+      `Revision: ${existing.parsed.metadata.revision}`,
+      `Updated: ${existing.parsed.metadata.updatedAt}`,
+      `Base: ${existing.parsed.metadata.base.source} ${existing.parsed.metadata.base.filePath}`,
+      `Base prompt changed since overlay: ${drift}`,
+      "",
+      "Current guidance:",
+      existing.parsed.current.trim() || "(empty)",
+      "",
+      "Recent history:",
+      history
+    ].join("\n"));
+  }
+  if (action === "refine.rollback") {
+    if (!existing.parsed) return result(`No refinement overlay exists for '${agent.name}'.`, true);
+    const latest = existing.parsed.snapshots.at(-1);
+    if (!latest) return result(`No refinement snapshot exists for '${agent.name}'.`, true);
+    const now2 = (/* @__PURE__ */ new Date()).toISOString();
+    const nextRevision2 = existing.parsed.metadata.revision + 1;
+    const next2 = {
+      metadata: metadataFor(agent, nextRevision2, now2),
+      current: latest.before,
+      snapshots: [...existing.parsed.snapshots, { revision: nextRevision2, at: now2, action: "rollback", before: existing.parsed.current, after: latest.before, evidenceIds: latest.evidenceIds }]
+    };
+    try {
+      writeRefinementFile(existing.path, next2);
+    } catch (error) {
+      return result(error instanceof Error ? error.message : String(error), true);
+    }
+    return result(`Rolled back refinement overlay for '${agent.name}' to revision ${nextRevision2}.
+Path: ${existing.path}`);
+  }
+  const evidence = collectBoundedRefinementEvidence(ctx.cwd, agent.name, ctx.state);
+  if (evidence.length === 0) return result(`No bounded recent evidence was found for '${agent.name}'. No proposal child was launched and no overlay was written.`);
+  const current = existing.parsed?.current ?? "";
+  const child = await ctx.launchProposalChild(proposalTask(agent, current, evidence), proposalSchema(), ctx.signal);
+  if (child.isError) return result(`Refinement proposal child failed. No overlay was written.`, true);
+  const validation = validateRefinementProposal(proposalFromChild(child), evidence.map((item) => item.id));
+  if (!validation.ok) return result(`${validation.error} No overlay was written.`, true);
+  if (validation.proposal.edits.length === 0) return result(`The proposal child returned no edits for '${agent.name}'. No overlay was written.`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const nextRevision = (existing.parsed?.metadata.revision ?? 0) + 1;
+  const after = guidanceFromProposal(validation.proposal);
+  const snapshot = {
+    revision: nextRevision,
+    at: now,
+    action: "refine",
+    before: current,
+    after,
+    evidenceIds: [...new Set(validation.proposal.edits.flatMap((edit) => edit.evidenceIds))],
+    proposalAgent: PROPOSAL_AGENT
+  };
+  const next = {
+    metadata: metadataFor(agent, nextRevision, now),
+    current: after,
+    snapshots: [...existing.parsed?.snapshots ?? [], snapshot]
+  };
+  try {
+    writeRefinementFile(existing.path, next);
+  } catch (error) {
+    return result(error instanceof Error ? error.message : String(error), true);
+  }
+  return result([
+    `Wrote refinement overlay for '${agent.name}' at revision ${nextRevision}.`,
+    `Path: ${existing.path}`,
+    `Evidence items: ${evidence.length}`,
+    `Edits: ${validation.proposal.edits.length}`
+  ].join("\n"));
+}
+
+export {
+  appendAgentRefinementOverlay,
+  handleRefinementAction
+};