@rosetears/aili-pi 0.1.9 → 0.1.10

package/src/runtime/persistent-agents/output-delivery.ts

@@ -0,0 +1,356 @@
+import { randomUUID } from "node:crypto";
+import { lstat, open, readFile, realpath, rename, rm } from "node:fs/promises";
+import { relative, resolve, sep, isAbsolute } from "node:path";
+import type { CoordinatorJournal } from "./storage.js";
+import {
+  assertSafeAgentId,
+  ensureSidecarLayout,
+  replayCoordinator,
+  sidecarLayoutForParent,
+  validateExactChildSessionPath,
+} from "./storage.js";
+import type { AgentRecord, SidecarLayout } from "./types.js";
+import type { NormalizedTaskSettlement } from "./task-coordinator.js";
+import { assertNoCredentialMaterial } from "./permission.js";
+
+export const PARENT_PREVIEW_CHAR_LIMIT = 5_000;
+export const BUILTIN_PARENT_DELETE_GAP = "official Pi 0.81.1 built-in Ctrl+D/archive does not cascade AILI sidecars; use confirmed AILI deletion or reconciliation";
+
+function isInside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+async function atomicWrite(path: string, content: string): Promise<void> {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, path);
+}
+
+function ownedAgent(state: ReturnType<CoordinatorJournal["getState"]>, agentId: string): AgentRecord {
+  const agent = state.agents[agentId] ?? state.releasedAgents[agentId];
+  if (!agent) throw new Error(`${agentId}: Agent is not owned by this parent`);
+  return agent;
+}
+
+export function agentOutputPath(layout: SidecarLayout, agentId: string): string {
+  assertSafeAgentId(agentId);
+  const path = resolve(layout.agentsDir, `${agentId}.md`);
+  if (!isInside(resolve(layout.agentsDir), path)) throw new Error(`${agentId}: output path escapes agents directory`);
+  return path;
+}
+
+export async function persistFullAgentOutput(layout: SidecarLayout, agentId: string, fullOutput: string): Promise<string> {
+  await assertNoCredentialMaterial(fullOutput, "Agent output artifact");
+  const outputPath = agentOutputPath(layout, agentId);
+  try {
+    const stat = await lstat(outputPath);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`${agentId}: output target is not a real file`);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await atomicWrite(outputPath, fullOutput);
+  return outputPath;
+}
+
+export interface BoundedTextResult {
+  content: string;
+  offset: number;
+  limit: number;
+  total: number;
+  returned: number;
+  truncated: boolean;
+  source: string;
+  diagnostic?: string;
+}
+
+function boundedLines(lines: string[], offset: number, limit: number, source: string, diagnostic?: string): BoundedTextResult {
+  if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("offset must be a non-negative integer");
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("limit must be a positive integer");
+  const selected = lines.slice(offset, offset + limit);
+  return {
+    content: selected.join("\n"),
+    offset,
+    limit,
+    total: lines.length,
+    returned: selected.length,
+    truncated: offset > 0 || offset + selected.length < lines.length,
+    source,
+    diagnostic,
+  };
+}
+
+export function parseAgentReference(reference: string): { kind: "output" | "history"; agentId: string } {
+  const match = reference.match(/^(agent|history):\/\/([^/?#]+)$/);
+  if (!match) throw new Error(`invalid Agent reference: ${reference}`);
+  const agentId = decodeURIComponent(match[2]!);
+  assertSafeAgentId(agentId);
+  return { kind: match[1] === "agent" ? "output" : "history", agentId };
+}
+
+export async function readAgentOutput(layout: SidecarLayout, journal: CoordinatorJournal, agentId: string, offset = 0, limit = 500): Promise<BoundedTextResult> {
+  ownedAgent(journal.getState(), agentId);
+  const outputPath = agentOutputPath(layout, agentId);
+  const content = await readFile(outputPath, "utf8");
+  await assertNoCredentialMaterial(content, "Agent output read");
+  return boundedLines(content.length === 0 ? [] : content.split("\n"), offset, limit, outputPath);
+}
+
+function entryText(entry: Record<string, unknown>): string {
+  if (entry.type === "session") return `[session] ${String(entry.id ?? "")}`.trim();
+  if (entry.type === "custom_message") return `[custom:${String(entry.customType ?? "unknown")}] ${String(entry.content ?? "")}`.trim();
+  if (entry.type === "message" && entry.message && typeof entry.message === "object") {
+    const message = entry.message as Record<string, unknown>;
+    const role = String(message.role ?? "message");
+    const content = message.content;
+    if (typeof content === "string") return `[${role}] ${content}`;
+    if (Array.isArray(content)) {
+      const parts = content.map((part) => {
+        if (!part || typeof part !== "object") return "";
+        const item = part as Record<string, unknown>;
+        if (typeof item.text === "string") return item.text;
+        if (typeof item.name === "string") return `[tool:${item.name}]`;
+        return `[${String(item.type ?? "content")}]`;
+      }).filter(Boolean);
+      return `[${role}] ${parts.join(" ")}`;
+    }
+    return `[${role}]`;
+  }
+  return `[${String(entry.type ?? "entry")}]`;
+}
+
+export async function readAgentHistory(layout: SidecarLayout, journal: CoordinatorJournal, agentId: string, offset = 0, limit = 500): Promise<BoundedTextResult> {
+  const agent = ownedAgent(journal.getState(), agentId);
+  if (!agent.sessionPath) throw new Error(`${agentId}: no child Session JSONL is registered`);
+  const sessionPath = await validateExactChildSessionPath(layout, agent.sessionPath);
+  const content = await readFile(sessionPath, "utf8");
+  const rawLines = content.split("\n");
+  if (rawLines.at(-1) === "") rawLines.pop();
+  const rendered: string[] = [];
+  let diagnostic: string | undefined;
+  for (let index = 0; index < rawLines.length; index += 1) {
+    const line = rawLines[index]!;
+    try {
+      rendered.push(entryText(JSON.parse(line) as Record<string, unknown>));
+    } catch (error) {
+      if (index === rawLines.length - 1 && !content.endsWith("\n")) {
+        diagnostic = `ignored final partial child JSONL line (${Buffer.byteLength(line)} bytes)`;
+        break;
+      }
+      throw new Error(`${agentId}: child history corruption at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  await assertNoCredentialMaterial(rendered, "Agent history read");
+  return boundedLines(rendered, offset, limit, sessionPath, diagnostic);
+}
+
+export interface ParentResultMessage {
+  customType: "aili.agent-result";
+  content: string;
+  display: true;
+  details: {
+    deliveryId: string;
+    agentId: string;
+    jobId: string;
+    turnId: string;
+    status: string;
+    outputRef: string;
+    historyRef: string;
+    previewTruncated: boolean;
+  };
+}
+
+export interface ParentDeliveryAdapter {
+  scanDeliveryIds(): Promise<Set<string>>;
+  send(message: ParentResultMessage): Promise<"sent" | "unavailable">;
+}
+
+export function scanDeliveryIdsFromParentEntries(entries: unknown[]): Set<string> {
+  const found = new Set<string>();
+  for (const raw of entries) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Record<string, unknown>;
+    const candidates = [entry, entry.message].filter((candidate): candidate is Record<string, unknown> => Boolean(candidate && typeof candidate === "object"));
+    for (const candidate of candidates) {
+      const customType = candidate.customType ?? entry.customType;
+      const details = (candidate.details ?? entry.details) as Record<string, unknown> | undefined;
+      if (customType === "aili.agent-result" && typeof details?.deliveryId === "string") found.add(details.deliveryId);
+    }
+  }
+  return found;
+}
+
+function preview(fullOutput: string): { content: string; truncated: boolean } {
+  if (fullOutput.length <= PARENT_PREVIEW_CHAR_LIMIT) return { content: fullOutput, truncated: false };
+  return { content: fullOutput.slice(-PARENT_PREVIEW_CHAR_LIMIT), truncated: true };
+}
+
+export class AsyncDeliveryService {
+  private readonly deliveryTails = new Map<string, Promise<void>>();
+
+  constructor(
+    private readonly layout: SidecarLayout,
+    private readonly journal: CoordinatorJournal,
+    private readonly parent: ParentDeliveryAdapter,
+  ) {}
+
+  async complete(settlement: NormalizedTaskSettlement, fullOutput: string): Promise<{ deliveryId?: string; status: "skipped-sync" | "pending" | "delivered"; deduplicated?: boolean }> {
+    if (!settlement.deliveryRequired || !settlement.async) return { status: "skipped-sync" };
+    const deliveryId = `delivery-${settlement.jobId}`;
+    return await this.withDeliveryLock(deliveryId, async () => await this.completeLocked(settlement, fullOutput, deliveryId));
+  }
+
+  private async completeLocked(settlement: NormalizedTaskSettlement, fullOutput: string, deliveryId: string): Promise<{ deliveryId: string; status: "pending" | "delivered"; deduplicated?: boolean }> {
+    const state = this.journal.getState();
+    const agent = ownedAgent(state, settlement.agentId);
+    const existing = state.deliveries[deliveryId];
+    if (existing) {
+      if (existing.agentId !== settlement.agentId || existing.jobId !== settlement.jobId) throw new Error(`${deliveryId}: conflicting retry ownership`);
+      if (existing.status === "delivered") return { deliveryId, status: "delivered", deduplicated: true };
+      return await this.deliver(deliveryId);
+    }
+    if (!agent.sessionPath) throw new Error(`${settlement.agentId}: child session path must exist before async delivery`);
+    await persistFullAgentOutput(this.layout, settlement.agentId, fullOutput);
+    await validateExactChildSessionPath(this.layout, agent.sessionPath);
+    const outputPreview = preview(fullOutput);
+    await this.journal.append({
+        kind: "delivery.put",
+        agentId: settlement.agentId,
+        jobId: settlement.jobId,
+        turnId: settlement.turnId,
+        deliveryId,
+        payload: {
+          status: "pending",
+          deliveryId,
+          agentId: settlement.agentId,
+          jobId: settlement.jobId,
+          turnId: settlement.turnId,
+          resultStatus: settlement.status,
+          outputRef: settlement.outputRef,
+          historyRef: settlement.historyRef,
+          preview: outputPreview.content,
+          previewTruncated: outputPreview.truncated,
+        },
+      });
+    return await this.deliver(deliveryId);
+  }
+
+  async recoverPending(): Promise<Array<{ deliveryId: string; status: "pending" | "delivered"; deduplicated?: boolean }>> {
+    const ids = Object.entries(this.journal.getState().deliveries)
+      .filter(([, delivery]) => delivery.status === "pending")
+      .map(([id]) => id);
+    const results = [];
+    for (const id of ids) results.push(await this.withDeliveryLock(id, async () => await this.deliver(id)));
+    return results;
+  }
+
+  private async withDeliveryLock<T>(deliveryId: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.deliveryTails.get(deliveryId) ?? Promise.resolve();
+    const current = previous.then(operation);
+    const tail = current.then(() => undefined, () => undefined);
+    this.deliveryTails.set(deliveryId, tail);
+    try {
+      return await current;
+    } finally {
+      if (this.deliveryTails.get(deliveryId) === tail) this.deliveryTails.delete(deliveryId);
+    }
+  }
+
+  private async deliver(deliveryId: string): Promise<{ deliveryId: string; status: "pending" | "delivered"; deduplicated?: boolean }> {
+    const delivery = this.journal.getState().deliveries[deliveryId];
+    if (!delivery) throw new Error(`${deliveryId}: unknown delivery`);
+    if (delivery.status === "delivered") return { deliveryId, status: "delivered", deduplicated: true };
+    const existing = await this.parent.scanDeliveryIds();
+    if (existing.has(deliveryId)) {
+      await this.ack(deliveryId, delivery);
+      return { deliveryId, status: "delivered", deduplicated: true };
+    }
+    const truncated = delivery.previewTruncated === true;
+    const content = [
+      `Agent ${delivery.agentId} job ${delivery.jobId} ${delivery.resultStatus}.`,
+      truncated ? `[preview truncated to ${PARENT_PREVIEW_CHAR_LIMIT} characters; full output: ${delivery.outputRef}]` : `Full output: ${delivery.outputRef}`,
+      String(delivery.preview ?? ""),
+      `History: ${delivery.historyRef}`,
+    ].join("\n");
+    let sent: "sent" | "unavailable";
+    try {
+      sent = await this.parent.send({
+        customType: "aili.agent-result",
+        content,
+        display: true,
+        details: {
+          deliveryId,
+          agentId: String(delivery.agentId),
+          jobId: String(delivery.jobId),
+          turnId: String(delivery.turnId),
+          status: String(delivery.resultStatus),
+          outputRef: String(delivery.outputRef),
+          historyRef: String(delivery.historyRef),
+          previewTruncated: truncated,
+        },
+      });
+    } catch {
+      return { deliveryId, status: "pending" };
+    }
+    if (sent === "unavailable") return { deliveryId, status: "pending" };
+    await this.ack(deliveryId, delivery);
+    return { deliveryId, status: "delivered" };
+  }
+
+  private async ack(deliveryId: string, delivery: Record<string, unknown>): Promise<void> {
+    await this.journal.append({
+      kind: "delivery.put",
+      agentId: String(delivery.agentId),
+      jobId: String(delivery.jobId),
+      turnId: String(delivery.turnId),
+      deliveryId,
+      payload: { ...delivery, status: "delivered", deliveredAt: new Date().toISOString() },
+    });
+  }
+}
+
+export async function initializeEmptyForkSidecar(parentSessionPath: string, parentId: string): Promise<{ layout: SidecarLayout; diagnostic: string }> {
+  const layout = await ensureSidecarLayout(parentSessionPath);
+  const replay = await replayCoordinator(layout, parentId);
+  if (replay.state.lastSequence !== 0 || Object.keys(replay.state.agents).length > 0 || Object.keys(replay.state.releasedAgents).length > 0) {
+    throw new Error("fork sidecar is not empty; existing child artifacts are never copied, adopted, or reset");
+  }
+  return { layout, diagnostic: "fork registry initialized empty; no child artifacts copied" };
+}
+
+export async function inspectParentSidecar(parentSessionPath: string): Promise<{ status: "attached" | "orphaned" | "missing"; root: string; diagnostic: string }> {
+  const layout = sidecarLayoutForParent(parentSessionPath);
+  let parentExists = true;
+  let rootExists = true;
+  try { await lstat(parentSessionPath); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") parentExists = false; else throw error; }
+  try { await lstat(layout.root); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") rootExists = false; else throw error; }
+  if (!rootExists) return { status: "missing", root: layout.root, diagnostic: BUILTIN_PARENT_DELETE_GAP };
+  return {
+    status: parentExists ? "attached" : "orphaned",
+    root: layout.root,
+    diagnostic: parentExists ? BUILTIN_PARENT_DELETE_GAP : `orphaned sidecar preserved; ${BUILTIN_PARENT_DELETE_GAP}`,
+  };
+}
+
+export async function confirmedDeleteParentAndSidecar(options: {
+  parentSessionPath: string;
+  parentId: string;
+  confirmation: string;
+}): Promise<{ deletedParent: boolean; deletedSidecar: boolean }> {
+  if (options.confirmation !== `DELETE ${options.parentId}`) throw new Error("exact parent deletion confirmation is required");
+  const layout = sidecarLayoutForParent(options.parentSessionPath);
+  const rootStat = await lstat(layout.root);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error("owned sidecar root must be a real directory");
+  const canonicalRoot = await realpath(layout.root);
+  if (canonicalRoot !== resolve(layout.root)) throw new Error("owned sidecar canonical root mismatch");
+  await replayCoordinator(layout, options.parentId);
+  await rm(layout.root, { recursive: true, force: false });
+  await rm(options.parentSessionPath, { force: false });
+  return { deletedParent: true, deletedSidecar: true };
+}

package/src/runtime/persistent-agents/permission.ts

@@ -0,0 +1,223 @@
+import { isOutside } from "pi-permission-modes/src/paths.ts";
+import { analyzeBash } from "pi-permission-modes/src/bash-parse.ts";
+import type { Action, ModeDef, Surface } from "pi-permission-modes/src/schema.ts";
+import { decide, decideBashCommand, mostRestrictive } from "../../vendor/pi-permission-modes/resolve.js";
+import { bashMentionsCredentialPath, isProtectedChildPath } from "../credential-guard.js";
+
+const FILE_SURFACE: Record<string, Surface> = {
+  read: "read",
+  write: "write",
+  edit: "edit",
+  grep: "grep",
+  find: "find",
+  ls: "ls",
+};
+const SECRET_KEY = /^(?:authorization|auth|credential|credentials|token|accessToken|refreshToken|secret|password|passwd|apiKey|api_key|privateKey|private_key)$/i;
+const SECRET_ASSIGNMENT = /\b(?:authorization:\s*bearer|bearer)\s+\S+|\b(?:token|secret|password|passwd|api[_-]?key|private[_-]?key)\s*[=:]\s*\S+/i;
+const PRIVATE_KEY_BLOCK = /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/;
+
+export interface CredentialFinding {
+  path: string;
+  reason: string;
+}
+
+export async function findCredentialMaterial(value: unknown, cwd = process.cwd(), path = "input", seen = new Set<object>()): Promise<CredentialFinding | undefined> {
+  if (typeof value === "string") {
+    if (PRIVATE_KEY_BLOCK.test(value)) return { path, reason: "private-key material" };
+    if (SECRET_ASSIGNMENT.test(value)) return { path, reason: "credential-like assignment" };
+    if (await isProtectedChildPath(cwd, value)) return { path, reason: "protected credential/auth path" };
+    return undefined;
+  }
+  if (!value || typeof value !== "object") return undefined;
+  if (seen.has(value)) return undefined;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const finding = await findCredentialMaterial(value[index], cwd, `${path}[${index}]`, seen);
+      if (finding) return finding;
+    }
+    return undefined;
+  }
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    if (SECRET_KEY.test(key) && item !== undefined && item !== null && item !== "") return { path: `${path}.${key}`, reason: "credential-bearing field" };
+    const finding = await findCredentialMaterial(item, cwd, `${path}.${key}`, seen);
+    if (finding) return finding;
+  }
+  return undefined;
+}
+
+export async function assertNoCredentialMaterial(value: unknown, context: string, cwd = process.cwd()): Promise<void> {
+  const finding = await findCredentialMaterial(value, cwd);
+  if (finding) throw new Error(`${context} denied credential/auth/private-key material at ${finding.path} (${finding.reason})`);
+}
+
+export function redactCredentialText(value: string): string {
+  return value
+    .replace(/-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/g, "<redacted-private-key>")
+    .replace(/\b(authorization:\s*bearer|bearer)\s+\S+/gi, "$1 <redacted>")
+    .replace(/\b(token|secret|password|passwd|api[_-]?key|private[_-]?key)\s*([=:])\s*\S+/gi, "$1$2<redacted>");
+}
+
+export interface ChildPermissionDecision {
+  action: Action;
+  toolName: string;
+  target: string;
+  reason: string;
+  requiresSandbox: boolean;
+  parserFallback?: boolean;
+}
+
+export interface ChildPermissionResolverOptions {
+  mode: ModeDef;
+  cwd: string;
+  sandboxExecutorAvailable: boolean;
+}
+
+export class ChildPermissionResolver {
+  constructor(private readonly options: ChildPermissionResolverOptions) {}
+
+  get modeLabel(): string {
+    return this.options.mode.label;
+  }
+
+  async decide(toolName: string, input: Record<string, unknown>): Promise<ChildPermissionDecision> {
+    const credential = await findCredentialMaterial(input, this.options.cwd);
+    if (credential) {
+      return {
+        action: "deny",
+        toolName,
+        target: credential.path,
+        reason: `credential hard denial: ${credential.reason}`,
+        requiresSandbox: false,
+      };
+    }
+    const surface = FILE_SURFACE[toolName];
+    if (surface) {
+      const target = typeof input.path === "string" ? input.path : "";
+      if (!target) return { action: "deny", toolName, target: "(missing path)", reason: "file tool path is missing", requiresSandbox: false };
+      const action = decide(this.options.mode, surface, target, { isOutside: isOutside(this.options.cwd, target) });
+      return { action, toolName, target, reason: `${this.options.mode.label} ${surface} policy`, requiresSandbox: false };
+    }
+    if (toolName === "bash") {
+      const command = typeof input.command === "string" ? input.command : "";
+      if (!command) return { action: "deny", toolName, target: "(empty command)", reason: "bash command is missing", requiresSandbox: false };
+      if (bashMentionsCredentialPath(command)) return { action: "deny", toolName, target: "protected path", reason: "credential path in bash", requiresSandbox: false };
+      const requiresSandbox = this.options.mode.sandbox.enabled;
+      if (requiresSandbox && !this.options.sandboxExecutorAvailable) {
+        return { action: "deny", toolName, target: command, reason: "mode requires sandboxed bash but no audited child sandbox executor is available", requiresSandbox: true };
+      }
+      if (!requiresSandbox) {
+        const action = decide(this.options.mode, "bash", command);
+        return { action, toolName, target: command, reason: `${this.options.mode.label} bash policy`, requiresSandbox: false };
+      }
+      const analysis = await analyzeBash(command, this.options.cwd);
+      let action: Action;
+      if (analysis.commands.length > 0) {
+        action = analysis.commands
+          .map((commandPart) => decideBashCommand(this.options.mode, commandPart.name, commandPart.args) ?? "allow")
+          .reduce<Action>((left, right) => mostRestrictive(left, right) ?? "allow", "allow");
+      } else {
+        action = decide(this.options.mode, "bash", command);
+      }
+      if (analysis.outsideReason) action = mostRestrictive(action, "ask") ?? "ask";
+      return {
+        action,
+        toolName,
+        target: command,
+        reason: analysis.outsideReason ?? `${this.options.mode.label} bash policy`,
+        requiresSandbox: true,
+        parserFallback: analysis.usedFallback,
+      };
+    }
+    if (toolName === "web_search") {
+      const target = typeof input.query === "string" ? input.query : "(empty)";
+      return { action: decide(this.options.mode, "web_search", target), toolName, target, reason: `${this.options.mode.label} web_search policy`, requiresSandbox: false };
+    }
+    return { action: decide(this.options.mode, "tool", toolName), toolName, target: toolName, reason: `${this.options.mode.label} custom tool policy`, requiresSandbox: false };
+  }
+}
+
+export interface ApprovalPrompt {
+  hasUI: boolean;
+  ask(packet: ApprovalRequestPacket): Promise<"allow" | "deny" | "dismiss">;
+}
+
+export interface ApprovalRequestPacket {
+  requestId: string;
+  agentId: string;
+  jobId: string;
+  toolName: string;
+  summary: string;
+  modeLabel: string;
+}
+
+interface PendingApproval {
+  settle: (decision: "allow" | "deny") => void;
+  jobId: string;
+  signal?: AbortSignal;
+  abortListener?: () => void;
+}
+
+export function brokeredChildPermission(
+  resolver: ChildPermissionResolver,
+  broker: ParentApprovalBroker,
+  context: { agentId: string; jobId: string; signal?: AbortSignal },
+): {
+  decide: (toolName: string, input: Record<string, unknown>) => Promise<Action>;
+  requestApproval: (packet: { toolName: string; summary: string }) => Promise<"allow" | "deny">;
+} {
+  return {
+    decide: async (toolName, input) => (await resolver.decide(toolName, input)).action,
+    requestApproval: async (packet) => await broker.request({
+      agentId: context.agentId,
+      jobId: context.jobId,
+      toolName: packet.toolName,
+      summary: packet.summary,
+      modeLabel: resolver.modeLabel,
+    }, context.signal),
+  };
+}
+
+export class ParentApprovalBroker {
+  private pending = new Map<string, PendingApproval>();
+  private closed = false;
+  private nextId = 0;
+
+  constructor(private readonly prompt: ApprovalPrompt) {}
+
+  pendingCount(jobId?: string): number {
+    if (!jobId) return this.pending.size;
+    return [...this.pending.values()].filter((pending) => pending.jobId === jobId).length;
+  }
+
+  async request(
+    packet: Omit<ApprovalRequestPacket, "requestId">,
+    signal?: AbortSignal,
+  ): Promise<"allow" | "deny"> {
+    if (this.closed || !this.prompt.hasUI || signal?.aborted) return "deny";
+    const requestId = `approval-${++this.nextId}`;
+    const fullPacket: ApprovalRequestPacket = { ...packet, requestId, summary: redactCredentialText(packet.summary).slice(0, 500) };
+    let settleGate!: (decision: "allow" | "deny") => void;
+    const gate = new Promise<"allow" | "deny">((resolve) => { settleGate = resolve; });
+    const pending: PendingApproval = { settle: settleGate, signal, jobId: packet.jobId };
+    if (signal) {
+      pending.abortListener = () => settleGate("deny");
+      signal.addEventListener("abort", pending.abortListener, { once: true });
+    }
+    this.pending.set(requestId, pending);
+    const promptDecision = this.prompt.ask(fullPacket).then(
+      (decision) => decision === "allow" ? "allow" as const : "deny" as const,
+      () => "deny" as const,
+    );
+    const decision = await Promise.race([promptDecision, gate]);
+    this.pending.delete(requestId);
+    if (signal && pending.abortListener) signal.removeEventListener("abort", pending.abortListener);
+    return decision;
+  }
+
+  shutdown(): void {
+    this.closed = true;
+    for (const pending of this.pending.values()) pending.settle("deny");
+    this.pending.clear();
+  }
+}