A local-first multi-agent app development platform, built on PenguinHarness
/**
* ManagedSubagentSession — a subagent session capable of running in the background.
*
* Holds a `SubagentHandle` and drives its `run` (pump): the same child Session may run across
* multiple rounds (the first round is initiated by `run_subagent`, later rounds append a Prompt
* via `input_subagent`). Structurally mirrors a command session (ManagedSession): the parent tool
* call collects output live within the yield window; output produced outside the window (while
* running in the background) goes into a buffer, delivered all at once on the next access.
*
* Three kinds of output, each with its own destination:
* - **Message buffer**: all of the child session's OmniMessage (already tagged with origin), for
* the parent tool call to forward to the frontend for rendering; capped in count, overflow
* drops the oldest (only affects frontend replay — the child Session's own Trace loses no
* data);
* - **Text buffer**: assistant text deltas from the direct child layer (origin one hop), fed back
* as the parent tool's own output to the LLM; capped in capacity (prevents memory bloat),
* overflow drops the oldest with a marker;
* - **Approval queue**: the child session's tool approval requests. While running in the
* background, the parent session may have no active tool call to forward approval through, so
* the request is queued and the child session blocks waiting; the parent tool call
* (run_subagent / input_subagent) attaches an approval sink (`attachApprovalSink`) within its
* window to consult Human one request at a time — if detached mid-consultation (window ends),
* the request stays queued, and a late-arriving decision still takes effect (settled guard,
* first to arrive wins).
*
* Mid-run control: `steer` queues a message on the child Session's own steering queue (the
* mechanism a user steers the main session with), and `abortRun` aborts only the current
* round via a per-run AbortController — the session survives both for follow-up prompts.
* The model (input_subagent) and the host (subagents panel) converge on these same methods.
*
* Cleanup: `kill()` aborts the current run via AbortSignal, denies all pending approvals, and
* releases child Session resources; idempotent. The child Session runs in-process, so there's no
* need for a separate synchronous hard-kill path (its command sessions are reaped by their own
* exit fallback); `killHard` is equivalent to `kill`.
*/
import type { OmniMessage, ApprovalDecision, ToolCallPayload } from "../../../omnimessage/index.js";
import type {
ApproveFn,
RunCutoff,
SubagentHandle,
ThinkingLevelName,
} from "../../../interfaces/index.js";
import type { ToolResult } from "../types.js";
import { CappedTextBuffer, WakeSignal } from "../background/index.js";
/** Message buffer count cap: overflow drops the oldest (only frontend replay is affected — the child Session has its own Trace). */
const MESSAGE_BUFFER_CAP = 4096;
/** Text buffer capacity cap (characters): prevents a chatty child Agent from blowing up memory. */
const OUTPUT_BUFFER_CAP = 1024 * 1024; // 1 MiB
/** Terminal state of one run. */
export interface SubagentExit {
status: "completed" | "failed";
note?: string;
}
/** A pending approval request: the settled guard makes the decision first-to-arrive-wins (late/duplicate decisions are ignored). */
interface PendingApproval {
toolCall: OmniMessage<ToolCallPayload>;
settled: boolean;
resolve: (decision: ApprovalDecision) => void;
}
export class ManagedSubagentSession {
/** Timestamp of the last access (used for the eviction policy). */
lastUsed: number = Date.now();
private readonly handle: SubagentHandle;
private readonly abortCtrl = new AbortController();
/**
* Abort scope of the CURRENT run only: `abortRun` (input_subagent's `abort`, the panel's
* stop button) fires this one, ending the round the way a user's stop ends a main-session
* Task — the session itself survives for steering and follow-up runs, unlike `kill`.
*/
private runCtrl: AbortController | null = null;
private messages: OmniMessage[] = [];
private readonly textBuffer = new CappedTextBuffer(OUTPUT_BUFFER_CAP, "earlier subagent output");
private isRunning = false;
private exitInfo: SubagentExit | null = null;
private killed = false;
private readonly approvals: PendingApproval[] = [];
private sink: { approve: ApproveFn; detached: Promise<void> } | null = null;
private sinkEpoch = 0;
private pumpingApprovals = false;
/**
* Standing approval sink for background-launched sessions (`run_in_background`): the
* launching call's own `ctx.approve`, consulted whenever no window sink is attached. A
* background child has no parent tool call waiting on it, so without this its first
* read-write tool parks at the approval queue forever — the "background subagent's
* commands never run" failure. Window sinks (an active run_subagent/input_subagent
* call) still take precedence while attached.
*/
private persistentApprove: ApproveFn | null = null;
/**
* Live forwarding tap for background-launched sessions: child messages go here the moment
* the pump produces them instead of waiting in the message buffer for the next poll. Set
* once at launch; anything already buffered flushes through it first (order preserved).
*/
private forwardTap: ((msg: OmniMessage) => void) | null = null;
// Single wake point: new message / run finished / new approval request all wake a waiting waitWake through it.
private readonly wakeSignal = new WakeSignal();
constructor(handle: SubagentHandle, opts?: { resumeAgentId?: string }) {
this.handle = handle;
this.resumeAgentId = opts?.resumeAgentId;
}
/**
* The owning Agent recorded at spawn/resume for the revival path (undefined = the parent
* Agent's own, i.e. a self-spawn): a released session's registry tombstone carries it so a
* later input_subagent on the same id can resume the child (see SubagentSessionManager).
*/
readonly resumeAgentId: string | undefined;
/** Child Session id (one hop of a message's origin); `subagent_id` is derived from its tail so the frontend can correlate it. */
get sessionId(): string {
return this.handle.sessionId;
}
/** One-shot take of the child's origin-tagged session_meta (see SubagentHandle.takeMeta); null when the handle predates the seam or the meta already went out. */
takeMeta(): OmniMessage | null {
return this.handle.takeMeta?.() ?? null;
}
/** Whether a round of the task is currently running. */
get running(): boolean {
return this.isRunning;
}
/** Terminal state of the most recent run; null if no round has ever completed. */
get exit(): SubagentExit | null {
return this.exitInfo;
}
/** Number of pending approval requests (the parent tool uses this to hint the model to poll again). */
get pendingApprovals(): number {
return this.approvals.length;
}
/** Whether there's unread output (buffered messages or text); used to re-check the predicate before waiting (see collect.ts). */
get hasPending(): boolean {
return this.messages.length > 0 || !this.textBuffer.isEmpty;
}
/** Whether the session has been killed/disposed (used by the manager's live index to drop dead entries lazily). */
get disposed(): boolean {
return this.killed;
}
/**
* Starts a new round of the task on the child Session (async pump, doesn't block the caller).
* `messages` is the round's input in the same OmniMessage shape `steer` takes — the caller
* owns their `sender`, so a model dispatch and a human's panel message stay distinguishable
* in the child's Trace. `opts.suppressDoneReport` keeps the settle watcher quiet for this round — a HOST-initiated
* round is the user's own conversation with the child, not work the model dispatched, so the
* parent must not receive a completion notice for it. Throws if already disposed or still
* running (converted to an explanatory output by the caller).
*/
startRun(messages: OmniMessage[], opts?: { suppressDoneReport?: boolean }): void {
if (this.killed) throw new Error("subagent session disposed");
if (this.isRunning) throw new Error("subagent is still running");
this.isRunning = true;
this.exitInfo = null;
this.reportCurrentRun = opts?.suppressDoneReport !== true;
this.runCtrl = new AbortController();
this.notifyState();
void this.pump(messages, this.runCtrl);
}
/**
* Queues a steering message for the current run (the same channel a user steers the main
* session with — see SubagentHandle.steer). False when idle, killed, or the handle predates
* steering: the caller then falls back to a follow-up run or reports "not running".
*/
steer(messages: OmniMessage[]): boolean {
if (this.killed || !this.isRunning) return false;
return this.handle.steer?.(messages) ?? false;
}
/**
* Aborts the CURRENT run only (see runCtrl); the session stays alive for steering and
* follow-up prompts. False when no run is in flight. The exit lands asynchronously through
* the pump (status failed with an aborted note), so callers observe settlement via
* waitWake/running like any other run end.
*/
abortRun(): boolean {
if (this.killed || !this.isRunning) return false;
// An abort is always an explicit actor's gesture whose outcome that actor sees directly
// (the input_subagent call's own result, or the panel the user pressed stop on): the
// settling round must not additionally fire a completion report at the parent.
this.reportCurrentRun = false;
this.runCtrl?.abort();
return true;
}
/** Pins the child's thinking level (see SubagentHandle.setThinkingLevel); false when the session is dead or the handle predates the pin. */
setThinkingLevel(level: ThinkingLevelName): boolean {
if (this.killed || !this.handle.setThinkingLevel) return false;
this.handle.setThinkingLevel(level);
return true;
}
// Run-state observer (host liveness): fired on every isRunning flip — startRun and the
// pump's settle. The event carries no payload; observers re-read `running`.
private stateListener: (() => void) | null = null;
/** Attaches the single run-state listener (the manager's aggregate notifier). */
onStateChange(cb: () => void): void {
this.stateListener = cb;
}
private notifyState(): void {
this.stateListener?.();
}
/** Takes the buffered child-session messages (already tagged with origin, for the parent tool to forward). */
drainMessages(): OmniMessage[] {
if (this.messages.length === 0) return [];
const out = this.messages;
this.messages = [];
return out;
}
/** Takes the currently unread child Agent text (including the drop marker); clears the buffer. */
drainText(): string {
return this.textBuffer.drain();
}
/** The child's most recent complete assistant text, across every round; null before it says anything (see the pump). */
private lastAnswer: string | null = null;
/** What the child last said — the idempotent snapshot input_subagent returns and a completion report carries. */
get lastAssistantText(): string | null {
return this.lastAnswer;
}
/** External wakeup (e.g. the parent tool call was aborted): makes a waiting `waitWake` return immediately. */
wakeup(): void {
this.wakeSignal.notify();
}
// Settle watcher (run_in_background completion reports): fires at the end of EVERY round of a
// background-launched session (later input_subagent rounds included), until disarmed. A kill
// by an explicit per-run abort stays silent — the aborter reads the outcome directly.
private settleWatcher: (() => void) | null = null;
/** Arms the completion-report watcher (replacing any previous one); fires immediately (microtask) when the session is already idle with a terminal state. */
onSettled(cb: () => void): void {
this.settleWatcher = cb;
if (!this.isRunning && this.exitInfo !== null) queueMicrotask(() => this.fireSettleWatcher());
}
/** Disarms the completion-report watcher (deliberate kill / dispose). */
clearSettleWatcher(): void {
this.settleWatcher = null;
}
/** Attaches the standing approval sink of a background launch (see persistentApprove) and drains anything already queued. */
setPersistentApprovalSink(approve: ApproveFn): void {
this.persistentApprove = approve;
void this.pumpApprovals();
}
/**
* Host-provided session-lifetime fallback approval sink (see
* EnvironmentInterface.setSubagentApprovalFallback): consulted when neither a window sink
* nor a background launch's standing sink exists, so a child's approval escalates to the
* user instead of parking until the model's next poll. Lowest precedence of the three.
*/
private fallbackApprove: ApproveFn | null = null;
/** Attaches the host fallback approval sink (see fallbackApprove) and drains anything already queued. */
setFallbackApprovalSink(approve: ApproveFn): void {
this.fallbackApprove = approve;
void this.pumpApprovals();
}
/** The active standing sink: a background launch's own, else the host fallback; null without either. */
private standingApprove(): ApproveFn | null {
return this.persistentApprove ?? this.fallbackApprove;
}
/** Whether a live forwarding tap is attached (host paths attach one on first touch; see setMessageTap). */
get hasMessageTap(): boolean {
return this.forwardTap !== null;
}
/** Attaches the live forwarding tap of a background launch (see forwardTap), flushing the buffered backlog through it in order. */
setMessageTap(tap: (msg: OmniMessage) => void): void {
const backlog = this.messages;
this.messages = [];
this.forwardTap = tap;
for (const msg of backlog) tap(msg);
}
/** Whether the round in flight (or the last one) should fire the settle watcher: false for host-initiated rounds (see startRun). */
private reportCurrentRun = true;
private fireSettleWatcher(): void {
const cb = this.settleWatcher;
if (cb && !this.killed && this.reportCurrentRun) cb();
}
/** Waits for "woken up" or `ms` to expire, whichever comes first. */
async waitWake(ms: number): Promise<void> {
await this.wakeSignal.wait(ms);
}
/**
* Attaches an approval sink: the parent tool call active within the window hands in its own
* `ctx.approve`, and queued approval requests are consulted with Human through it one at a
* time. Returns a detach function (called when the window ends); a later attach replaces the
* former one.
*/
attachApprovalSink(approve: ApproveFn): () => void {
const epoch = ++this.sinkEpoch;
let onDetach!: () => void;
const detached = new Promise<void>((resolve) => {
onDetach = resolve;
});
this.sink = { approve, detached };
void this.pumpApprovals();
return () => {
if (this.sinkEpoch === epoch) this.sink = null;
onDetach();
};
}
/** Cleanup: aborts the current run, denies pending approvals, releases child Session resources; idempotent. */
kill(): void {
if (this.killed) return;
this.killed = true;
this.abortCtrl.abort();
for (const req of [...this.approvals]) this.settle(req, "deny");
// If running, released by pump's finally after it finishes; otherwise released immediately.
if (!this.isRunning) this.handle.dispose();
this.wakeSignal.notify();
}
/** Synchronous hard-kill path: the child Session runs in-process with no separate OS resources, so this is equivalent to `kill`. */
killHard(): void {
this.kill();
}
// -------------------------------------------------------------------------
// Internal: pump and buffering
// -------------------------------------------------------------------------
/** Drives one round of `handle.run`: buffers messages and text, settling the terminal state when it ends. */
private async pump(messages: OmniMessage[], runCtrl: AbortController): Promise<void> {
let wroteAny = false;
// Whether the round was cut off early (a user abort, a terminal LLM failure, a
// mid-task compaction failure): read from the run generator's return value — the
// child engine states it directly; a cut-off round is reported failed, not completed.
let cut: RunCutoff | null = null;
try {
// Either scope ends the round: the session-lifetime kill, or this run's own abort.
// Manual iteration (not for-await) so the handle's return value — whether the round
// was cut off — is read; a child session failure doesn't throw.
const it = this.handle.run({
messages,
signal: AbortSignal.any([this.abortCtrl.signal, runCtrl.signal]),
approve: this.childApprove,
});
for (;;) {
const res = await it.next();
if (res.done) {
// Older embedders' handles may return nothing: that counts as ran-to-completion.
cut = res.value ?? null;
break;
}
const msg = res.value;
this.bufferMessage(msg);
if ((msg.origin?.length ?? 0) === 1) {
const p = msg.payload as {
type?: string;
event_type?: string;
text?: string;
};
if (
p.type === "partial_text" &&
p.event_type === "delta" &&
typeof p.text === "string" &&
p.text
) {
wroteAny = true;
this.appendText(p.text);
} else if (
p.type === "text" &&
(p as { role?: string }).role === "assistant" &&
typeof p.text === "string" &&
p.text
) {
// The child's most recent COMPLETE utterance: what input_subagent hands the model
// and what a completion report carries — an idempotent "what it last said"
// snapshot rather than an incremental delta drain.
wroteAny = true;
this.lastAnswer = p.text;
}
}
this.wakeSignal.notify();
}
if (cut !== null) {
// The note reaches the parent model: the cause code plus the raw detail.
const detail = cut.errorMessage;
const cause = cut.errorCode ?? (cut.kind === "abort" ? "aborted" : cut.kind);
this.exitInfo = {
status: "failed",
note: `[subagent ${cut.kind === "abort" ? "aborted" : "failed"}: ${cause}${detail ? ` — ${detail}` : ""}]`,
};
} else if (!wroteAny) {
this.exitInfo = {
status: "completed",
note: "[subagent finished without a text answer]",
};
} else {
this.exitInfo = { status: "completed" };
}
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
this.exitInfo = { status: "failed", note: `[subagent error: ${message}]` };
} finally {
this.isRunning = false;
if (this.killed) this.handle.dispose();
this.wakeSignal.notify();
this.notifyState();
this.fireSettleWatcher();
}
}
private bufferMessage(msg: OmniMessage): void {
// A live tap (background launch) replaces buffering outright: the frontend receives the
// message immediately, and a later poll must not deliver a second copy.
if (this.forwardTap) {
this.forwardTap(msg);
return;
}
this.messages.push(msg);
// Overflow drops the oldest: only affects frontend replay — the child Session's Trace and text buffer are unaffected.
if (this.messages.length > MESSAGE_BUFFER_CAP) this.messages.shift();
}
private appendText(text: string): void {
this.textBuffer.append(text);
}
// -------------------------------------------------------------------------
// Internal: approval queue
// -------------------------------------------------------------------------
/** Approval callback handed to the child Session: the request is queued and waits for some parent tool call to consult Human and give a decision. */
private readonly childApprove: ApproveFn = (toolCall) => {
if (this.killed) return Promise.resolve("deny");
return new Promise<ApprovalDecision>((resolve) => {
this.approvals.push({ toolCall, settled: false, resolve });
this.wakeSignal.notify(); // Wake the parent tool call waiting within the window, so it can consult as soon as possible
void this.pumpApprovals();
});
};
/** Settles an approval decision: first to arrive wins, late/duplicate decisions are ignored. */
private settle(req: PendingApproval, decision: ApprovalDecision): void {
if (req.settled) return;
req.settled = true;
const idx = this.approvals.indexOf(req);
if (idx >= 0) this.approvals.splice(idx, 1);
req.resolve(decision);
this.wakeSignal.notify();
}
/**
* Hands the request at the head of the queue to an approval sink, one at a time: the
* window sink of an active run_subagent/input_subagent call when attached, else the
* standing sink of a background launch (persistentApprove). A window consultation stops
* when the window ends (the sink is detached) — unresolved requests stay queued for the
* next sink; a standing consultation simply awaits the decision (there is no window to
* end). If a consultation already in flight resolves late, the decision still takes
* effect via settle.
*/
private async pumpApprovals(): Promise<void> {
if (this.pumpingApprovals) return;
this.pumpingApprovals = true;
try {
while ((this.sink !== null || this.standingApprove() !== null) && this.approvals.length > 0) {
const req = this.approvals[0]!;
const sink = this.sink;
if (sink === null) {
await this.standingApprove()!(req.toolCall).then(
(d) => this.settle(req, d),
() => this.settle(req, "deny"), // An approval sink error is treated as a denial (avoids leaving the child session stuck forever)
);
continue;
}
const answer = sink.approve(req.toolCall).then(
(d) => this.settle(req, d),
() => this.settle(req, "deny"),
);
await Promise.race([answer, sink.detached]);
if (req.settled) continue;
if (this.sink && this.sink !== sink) continue; // The sink was replaced by a new call: retry with the new sink
if (this.standingApprove() !== null) continue; // Window gone but a standing sink exists: fall through to it next round
break; // The sink was detached and still unresolved: stay queued for the next sink
}
} finally {
this.pumpingApprovals = false;
}
}
}
/** Converts a run's terminal state into a tool result (note is appended outside the truncation, so it isn't lost with long output). A failed child run is fatal for this call — nothing retries a tool. */
export function resultForSubagentExit(exit: SubagentExit | null): ToolResult {
if (!exit) return { stopReason: "completed" };
return {
stopReason: exit.status === "failed" ? "fatal" : exit.status,
...(exit.note !== undefined ? { note: exit.note } : {}),
};
}