A local-first multi-agent app development platform, built on PenguinHarness
/**
* Tool call approval: ApproveFn factory + pending
* approval registry.
*
* Approval mode semantics match the CLI (packages/cli/src/approval.ts):
* allow-all auto-approves; deny-all auto-denies; read-only allows read-only tools
* (permission==="r") and routes the rest to manual approval; always-ask routes
* everything to manual approval. Routing to manual approval registers a pending entry
* and pushes an `approval_request` via SSE, suspending until the frontend decides via
* `POST /approvals/:toolCallId`; no timeout — pending approvals are resolved to deny
* when the Task is interrupted (then proceeds through the abort flow).
*
* An unattended Session takes that one route differently: there is no frontend to ask, so
* the call is denied on the spot instead of suspending forever (see `unattended` below).
*
* Every approval decision re-reads the current approval_mode (`getMode` reads the DB),
* so mode changes take effect immediately.
* Docs: /docs/tools § "Approval".
*/
import type { ApprovalMode } from "../api/types.js";
import type { ApprovalDecision, ApproveFn, OmniMessage, ToolCallPayload } from "@adelie/core";
export interface PendingApproval {
toolCall: OmniMessage<ToolCallPayload>;
origin?: string[];
}
interface PendingEntry extends PendingApproval {
resolve: (decision: ApprovalDecision) => void;
}
/** Pending approval registry (key = tool_call_id), one per Session runtime. */
export class ApprovalRegistry {
private readonly pending = new Map<string, PendingEntry>();
/** Inside a multi-entry change (`wait` replacing an entry, `denyAll`, `denyMain`): reported once, at its end. */
private batching = false;
/**
* `onChange` hears every change of `size`, once per call that made it (a `denyAll` over
* three entries is one change) and never for a call that left the count where it was.
*/
constructor(private readonly onChange?: () => void) {}
get size(): number {
return this.pending.size;
}
/** All currently pending approvals (for subscription replay). */
list(): PendingApproval[] {
return [...this.pending.values()].map(({ toolCall, origin }) => ({
toolCall,
...(origin !== undefined ? { origin } : {}),
}));
}
/** Register and wait for a decision. Re-registering the same id (defensive) resolves the old entry as deny. */
wait(toolCall: OmniMessage<ToolCallPayload>): Promise<ApprovalDecision> {
const id = toolCall.payload.tool_call_id;
return this.batch(
() =>
new Promise<ApprovalDecision>((resolve) => {
this.pending.get(id)?.resolve("deny");
const entry: PendingEntry = {
toolCall,
...(toolCall.origin !== undefined ? { origin: toolCall.origin } : {}),
resolve: (decision) => {
if (this.pending.get(id) !== entry) return;
this.pending.delete(id);
this.changed();
resolve(decision);
},
};
this.pending.set(id, entry);
}),
);
}
/** Submit a decision; returns false if not found (already decided/unknown). */
decide(toolCallId: string, decision: ApprovalDecision): boolean {
const entry = this.pending.get(toolCallId);
if (!entry) return false;
entry.resolve(decision);
return true;
}
/** Interruption convergence: resolve all pending approvals as deny. */
denyAll(): void {
this.batch(() => {
for (const entry of [...this.pending.values()]) entry.resolve("deny");
});
}
/**
* Task-boundary convergence: deny only the MAIN session's pending approvals (no origin).
* An origin-tagged approval belongs to a subagent child that outlives the parent's task —
* the child is still blocked on the question, so it stays pending for the user; it is
* denied only with the child itself (kill/dispose paths use denyAll).
*/
denyMain(): void {
this.batch(() => {
for (const entry of [...this.pending.values()]) {
if (entry.origin === undefined || entry.origin.length === 0) entry.resolve("deny");
}
});
}
private changed(): void {
if (!this.batching) this.onChange?.();
}
/** Runs `fn` as one change: `onChange` hears it once, and only when the count moved. */
private batch<T>(fn: () => T): T {
if (this.batching) return fn();
const before = this.pending.size;
this.batching = true;
try {
return fn();
} finally {
this.batching = false;
if (this.pending.size !== before) this.onChange?.();
}
}
}
/**
* Build the approve callback: re-reads the approval mode on every call; when routed to
* manual approval, registers a pending entry and suspends after pushing an
* `approval_request` server event via `publishRequest` — unless the Session is unattended,
* in which case that one route answers deny immediately.
*/
export function makeApprove(args: {
getMode: () => ApprovalMode;
/** A tool's permission level, from the running context's toolset (core Session.toolPermission): strict-tier — a permission edit applies when the next context opens. */
toolPermission: (name: string) => "r" | "rw" | undefined;
registry: ApprovalRegistry;
publishRequest: (pending: PendingApproval) => void;
/**
* Whether nobody is watching this Session — an organization's desk, ticket and spawned
* sessions, the only unattended ones the server drives. Re-read per decision like the
* mode. It changes exactly one route: a call the mode would hand to a person is denied at
* once instead of parking for an answer that is never coming, and no `approval_request`
* is pushed. The automatic answers (allow-all, deny-all, read-only's read tools) and the
* command policy's veto are untouched — they never asked anyone in the first place.
* Absent (development mode) keeps the suspending behaviour.
*/
unattended?: () => boolean;
}): ApproveFn {
const { getMode, toolPermission, registry, publishRequest, unattended } = args;
const manual = (toolCall: OmniMessage<ToolCallPayload>): Promise<ApprovalDecision> => {
if (unattended?.() === true) return Promise.resolve<ApprovalDecision>("deny");
const promise = registry.wait(toolCall);
publishRequest({
toolCall,
...(toolCall.origin !== undefined ? { origin: toolCall.origin } : {}),
});
return promise;
};
return async (toolCall) => {
switch (getMode()) {
case "allow-all":
return "allow";
case "deny-all":
return "deny";
case "read-only":
// Auto-approve read-only tools; route read-write/unknown tools to manual approval (matches CLI semantics).
if (toolPermission(toolCall.payload.name) === "r") return "allow";
return manual(toolCall);
case "always-ask":
default:
return manual(toolCall);
}
};
}