A local-first multi-agent app development platform, built on PenguinHarness
/**
* Behavior tests for background execution: `run_in_background` on exec_command /
* run_subagent, detaching a call that is already executing (the Web App's per-card button),
* the completion-report pipeline (Environment listener → Session notice queue → engine
* boundary delivery), input_command's kill termination, and the `sender` marking on user
* texts.
*/
import { afterEach, describe, expect, it, vi } from "vitest";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { Environment } from "../src/environment/index.js";
import { armCommandDoneReport } from "../src/environment/tools/exec-command.js";
import {
ManagedSession,
DEFAULT_EMPTY_POLL_YIELD_MS,
} from "../src/environment/tools/command/index.js";
import { createSubagentTool } from "../src/environment/tools/run-subagent.js";
import { createInputSubagentTool } from "../src/environment/tools/input-subagent.js";
import { SubagentSessionManager } from "../src/environment/tools/subagent/index.js";
import { ContextEngine } from "../src/engine/context-engine.js";
import {
requestEnd,
assistantText,
buildBackgroundTaskDoneMessage,
emptyTokenCounts,
isSteeredBackgroundNotice,
parseBackgroundTaskDoneMessage,
partialText,
stripLeadingMarkerBlocks,
toolCall,
tokenUsage,
userText,
} from "../src/omnimessage/index.js";
import { Session } from "../src/index.js";
import type {
OmniMessage,
SessionMetaPayload,
TextPayload,
ToolCallPayload,
} from "../src/omnimessage/index.js";
import type {
ApproveFn,
BackgroundTaskDoneEvent,
EnvironmentInterface,
GenerativeModelParameters,
LLMInterface,
LLMOutcome,
SubagentHandle,
SubagentRunner,
ToolConfig,
ToolDefinitionConfig,
ToolDetachResult,
} from "../src/interfaces/index.js";
import { DETACHED_TOOL_NOTE_PREFIX } from "../src/interfaces/index.js";
import type { ToolExecutionContext } from "../src/environment/tools/types.js";
// ---------------------------------------------------------------------------
// Shared helpers
// ---------------------------------------------------------------------------
function toolDef(name: string, extra: Partial<ToolDefinitionConfig> = {}): ToolDefinitionConfig {
return {
name,
description: `${name} test`,
permission: "rw",
maxOutputLength: 16000,
...extra,
};
}
function commandToolConfig(): ToolConfig {
return {
customTools: [toolDef("exec_command"), toolDef("input_command"), toolDef("kill_command")],
mcpServers: [],
};
}
interface FinalOutput {
output: string;
stopReason?: string;
}
async function runTool(
env: Environment,
name: string,
args: Record<string, unknown>,
): Promise<FinalOutput> {
let last: OmniMessage | null = null;
for await (const msg of env.executeTool({
toolCall: toolCall({ name, arguments: JSON.stringify(args), toolCallId: `call_${name}` }),
})) {
if ((msg.payload as { type?: string }).type === "tool_call_output") last = msg;
}
const p = (last?.payload ?? {}) as { output?: string; stop_reason?: string };
return { output: p.output ?? "", stopReason: p.stop_reason };
}
/**
* Runs a tool and detaches the call from outside the moment `when` holds against the output
* seen so far — the Web App's button, fired while the call is still executing.
*/
async function runToolDetachedOn(
env: Environment,
name: string,
args: Record<string, unknown>,
when: (seen: string) => boolean,
): Promise<FinalOutput & { detach: ToolDetachResult | null; completeOutputs: number }> {
const toolCallId = `call_${name}_detach`;
let detach: ToolDetachResult | null = null;
let seen = "";
let completeOutputs = 0;
let last: OmniMessage | null = null;
for await (const msg of env.executeTool({
toolCall: toolCall({ name, arguments: JSON.stringify(args), toolCallId }),
})) {
const p = msg.payload as { type?: string; output?: string };
if (p.type === "tool_call_output") {
completeOutputs += 1;
last = msg;
} else {
seen += p.output ?? "";
}
if (detach === null && when(seen)) detach = env.detachToolCall(toolCallId);
}
const p = (last?.payload ?? {}) as { output?: string; stop_reason?: string };
return { output: p.output ?? "", stopReason: p.stop_reason, detach, completeOutputs };
}
function extractProcessId(output: string): string {
const m = output.match(/process_id (proc-[0-9a-f]+)/);
expect(m, `expected a process_id in: ${JSON.stringify(output)}`).toBeTruthy();
return m![1]!;
}
const cleanups: Array<() => Promise<void> | void> = [];
afterEach(async () => {
while (cleanups.length) await cleanups.pop()!();
});
async function makeEnv(): Promise<{ env: Environment; dir: string }> {
const dir = await mkdtemp(path.join(tmpdir(), "penguin-bg-"));
const env = new Environment({ workspaceDir: dir, toolConfig: commandToolConfig() });
cleanups.push(async () => {
env.dispose();
// Retries: background commands keep this dir as their cwd, and on Windows a just-killed
// process releases that lock asynchronously — an immediate recursive rm hits EBUSY.
await rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
});
return { env, dir };
}
/** Waits until the predicate holds (events arrive from real process exits). */
async function waitFor(pred: () => boolean, timeoutMs = 5000): Promise<void> {
await vi.waitFor(
() => {
if (!pred()) throw new Error("condition not met yet");
},
{ timeout: timeoutMs, interval: 20 },
);
}
// ---------------------------------------------------------------------------
// Marker block and sender field
// ---------------------------------------------------------------------------
describe("[background_task_done] marker and the sender field", () => {
it("build/parse round-trips the completion facts and the body", () => {
const text = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-12ab34cd", status: "failed", detail: "exit code 2" },
"`pnpm test` — exit code 2\n\ntail output",
);
const parsed = parseBackgroundTaskDoneMessage(text);
expect(parsed).not.toBeNull();
expect(parsed!.done).toEqual({
kind: "command",
id: "proc-12ab34cd",
status: "failed",
detail: "exit code 2",
});
expect(parsed!.rest).toBe("`pnpm test` — exit code 2\n\ntail output");
// Detail omitted -> parsed back as empty.
const bare = buildBackgroundTaskDoneMessage(
{ kind: "subagent", id: "subagent-1", status: "completed", detail: "" },
"",
);
expect(parseBackgroundTaskDoneMessage(bare)!.done.detail).toBe("");
});
it("stamps and parses the steering delivery field; unstamped blocks read as task input", () => {
const steered = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-1", status: "completed", detail: "", delivery: "steering" },
"body",
);
expect(parseBackgroundTaskDoneMessage(steered)!.done.delivery).toBe("steering");
expect(isSteeredBackgroundNotice(steered)).toBe(true);
// The unstamped form (idle delivery, and every pre-stamp Trace) has no delivery field.
const plain = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-1", status: "completed", detail: "" },
"body",
);
expect(plain).not.toContain("delivery:");
expect(parseBackgroundTaskDoneMessage(plain)!.done.delivery).toBeUndefined();
expect(isSteeredBackgroundNotice(plain)).toBe(false);
expect(isSteeredBackgroundNotice("plain user text")).toBe(false);
});
it("only parses as a leading block, and the title stripper removes it", () => {
const block = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-1", status: "completed", detail: "" },
"body",
);
expect(parseBackgroundTaskDoneMessage(`hello\n${block}`)).toBeNull();
expect(stripLeadingMarkerBlocks(block)).toBe("body");
});
it("a stopped status reads as a deliberate stop, with the do-not-restart instruction", () => {
const stopped = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-12ab34cd", status: "stopped", detail: "stopped by SIGTERM" },
"`pnpm dev` — stopped by SIGTERM",
);
expect(parseBackgroundTaskDoneMessage(stopped)!.done).toMatchObject({
status: "stopped",
detail: "stopped by SIGTERM",
});
expect(stopped).toContain("Do not restart it unless you are asked to.");
// Everything else keeps the plain "has finished" lead — a real failure still asks to be
// reacted to.
const failed = buildBackgroundTaskDoneMessage(
{ kind: "command", id: "proc-12ab34cd", status: "failed", detail: "exit code 2" },
"",
);
expect(failed).toContain("has finished.");
expect(failed).not.toContain("Do not restart");
});
it("userText marks non-human senders and leaves human input unmarked", () => {
expect((userText("hi").payload as TextPayload).sender).toBeUndefined();
expect((userText("hi", "user").payload as TextPayload).sender).toBeUndefined();
expect((userText("hi", "parent_agent").payload as TextPayload).sender).toBe("parent_agent");
expect((userText("hi", "harness").payload as TextPayload).sender).toBe("harness");
expect((userText("hi", "server").payload as TextPayload).sender).toBe("server");
});
});
// ---------------------------------------------------------------------------
// exec_command run_in_background + kill_command
// ---------------------------------------------------------------------------
describe("exec_command run_in_background", () => {
it("returns a process_id immediately and reports completion with the output tail", async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
const res = await runTool(env, "exec_command", {
cmd: "printf 'bg output'; exit 0",
run_in_background: true,
});
expect(res.stopReason).toBe("completed");
const id = extractProcessId(res.output);
expect(res.output).toContain("will arrive as a user message");
await waitFor(() => events.length === 1);
const e = events[0]!;
expect(e).toMatchObject({ kind: "command", id, status: "completed", detail: "exit code 0" });
expect(e.output).toContain("bg output");
expect(e.label).toContain("printf 'bg output'");
});
it("reports a non-zero exit as failed with the exit code", async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
await runTool(env, "exec_command", { cmd: "exit 3", run_in_background: true });
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ status: "failed", detail: "exit code 3" });
});
it("buffers events fired before the listener attaches", async () => {
const { env } = await makeEnv();
const res = await runTool(env, "exec_command", {
cmd: "printf early; exit 0",
run_in_background: true,
});
extractProcessId(res.output);
// Let the process exit with no listener attached, then attach.
await new Promise((r) => setTimeout(r, 300));
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
await waitFor(() => events.length === 1);
expect(events[0]!.output).toContain("early");
});
it("input_command kill terminates a running background command without a completion report", async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
const res = await runTool(env, "exec_command", {
cmd: "printf 'pre http://localhost:5199/\\n'; sleep 30",
run_in_background: true,
});
const id = extractProcessId(res.output);
// Wait for the pre-kill output to reach the session buffer kill_command drains. A fixed
// sleep raced the pipe on loaded Windows runners, and that buffer is not readable without
// draining it — so wait on the URL scanner instead: ManagedSession pushes each chunk to
// the scanner immediately before appending it to that buffer, so a detected serviceUrl
// proves the line is already buffered.
await waitFor(() => env.listBackgroundCommands().some((p) => p.serviceUrl !== undefined));
const killed = await runTool(env, "input_command", { process_id: id, kill: true });
expect(killed.stopReason).toBe("completed");
expect(killed.output).toContain("pre");
expect(killed.output).toContain(`process ${id} killed`);
// The kill-caused exit must not masquerade as a task completion.
await new Promise((r) => setTimeout(r, 400));
expect(events).toHaveLength(0);
// And the session is gone from the registry.
const again = await runTool(env, "input_command", { process_id: id, kill: true });
expect(again.stopReason).toBe("fatal");
});
it("input_command kill fails on an unknown process_id; the legacy kill_command name is an unknown tool", async () => {
const { env } = await makeEnv();
const res = await runTool(env, "input_command", { process_id: "proc-deadbeef", kill: true });
expect(res.stopReason).toBe("fatal");
expect(res.output).toContain("unknown process_id");
// A stale stored config may still carry the removed tool; the registry no longer
// assembles it, so a model call collapses to the standard unknown-tool failure.
const legacy = await runTool(env, "kill_command", { process_id: "proc-deadbeef" });
expect(legacy.stopReason).toBe("fatal");
expect(legacy.output).toContain("Unknown tool: kill_command");
});
it.skipIf(process.platform === "win32")(
"a stop signal from outside reports stopped, not a signal failure",
async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
const pid = env.listBackgroundCommands()[0]!.pid!;
// Nobody told the harness: a Ctrl-C in a terminal sharing the group, a pkill, a
// supervisor stopping a dev server. Only the signal itself says it was deliberate —
// and read as a crash, the model's next move is to start the thing back up.
process.kill(pid, "SIGTERM");
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ status: "stopped", detail: "stopped by SIGTERM" });
},
);
it("the host's stop button still reports — as stopped, not as a signal failure", async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
const res = await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
const id = extractProcessId(res.output);
// The user's stop from the Web App's process list: the conversation still hears about it
// — the dev server it started is down — it just must not hear "failed".
expect(env.killBackgroundCommand(id)).toBe(true);
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ id, status: "stopped" });
expect(env.killBackgroundCommand(id)).toBe(false);
});
it("a harness-forced stop (capacity eviction, idle reap) reports stopped", async () => {
// Those two paths kill through the registry rather than CommandSessionManager.kill, so
// their report stays armed — and must not blame the process for a stop the harness
// itself asked for, whatever the platform turns that kill into.
const { dir } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
const session = new ManagedSession({ cmd: "sleep 30", cwd: dir, env: process.env });
cleanups.push(() => session.killHard());
armCommandDoneReport(session, "proc-evicted", { backgroundDone: (e) => events.push(e) });
session.kill();
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ id: "proc-evicted", status: "stopped" });
});
it("dispose suppresses pending completion reports", async () => {
const dir = await mkdtemp(path.join(tmpdir(), "penguin-bg-"));
cleanups.push(() => rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 }));
const env = new Environment({ workspaceDir: dir, toolConfig: commandToolConfig() });
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
env.dispose(); // kills the process; its exit must not report
await new Promise((r) => setTimeout(r, 400));
expect(events).toHaveLength(0);
});
});
// ---------------------------------------------------------------------------
// Detaching an executing call (the Web App's per-card button)
// ---------------------------------------------------------------------------
describe("detaching an executing tool call", () => {
it("ends the call as completed with a process_id, kills nothing, and closes out exactly once", async () => {
const { env } = await makeEnv();
const res = await runToolDetachedOn(
env,
"exec_command",
// A yield window far longer than the test: the promotion below can only be the detach.
{ cmd: "printf 'before\\n'; sleep 0.3; printf 'after\\n'; sleep 30", yield_time_ms: 60000 },
(seen) => seen.includes("before"),
);
expect(res.detach).toBe("detached");
// A detach is not an interruption: no aborted stop reason, no interruption marker.
expect(res.stopReason).toBe("completed");
expect(res.output).not.toContain("[interrupted");
expect(res.output).toContain(DETACHED_TOOL_NOTE_PREFIX);
// Exactly one complete tool_call_output, so the engine's loop closes normally.
expect(res.completeOutputs).toBe(1);
// Whatever had been collected stays in this call's output.
expect(res.output).toContain("before");
// The process was NOT killed: it is registered, running, and still producing output that
// a later input_command poll picks up.
const id = extractProcessId(res.output);
expect(env.listBackgroundCommands().find((p) => p.processId === id)?.running).toBe(true);
const polled = await runTool(env, "input_command", { process_id: id, yield_time_ms: 1500 });
expect(polled.output).toContain("after");
});
it("reports the detached command's completion as a background task", async () => {
const { env } = await makeEnv();
const events: BackgroundTaskDoneEvent[] = [];
env.setBackgroundTaskListener((e) => events.push(e));
const res = await runToolDetachedOn(
env,
"exec_command",
{ cmd: "printf 'before\\n'; sleep 0.4; printf 'done\\n'; exit 0", yield_time_ms: 60000 },
(seen) => seen.includes("before"),
);
const id = extractProcessId(res.output);
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ kind: "command", id, status: "completed" });
expect(events[0]!.output).toContain("done");
});
it("answers not_running for an unknown or finished call, and not_detachable for a tool with no background form", async () => {
const { env } = await makeEnv();
expect(env.detachToolCall("call_nobody")).toBe("not_running");
const launched = await runTool(env, "exec_command", {
cmd: "printf 'poll me\\n'; sleep 30",
run_in_background: true,
});
const id = extractProcessId(launched.output);
// input_command only polls a process the registry already holds — there is nothing to
// hand back, so the call is refused rather than silently ending early.
const polled = await runToolDetachedOn(
env,
"input_command",
{ process_id: id, yield_time_ms: 1500 },
(seen) => seen.includes("poll me"),
);
expect(polled.detach).toBe("not_detachable");
expect(polled.stopReason).toBe("completed");
// The call is over: its detach channel is gone with it.
expect(env.detachToolCall("call_input_command_detach")).toBe("not_running");
});
});
describe("background-state listener", () => {
it("pings on a background launch, again when the process exits, and on a kill", async () => {
const { env } = await makeEnv();
let pings = 0;
env.setBackgroundStateListener(() => {
pings += 1;
});
const res = await runTool(env, "exec_command", {
cmd: "printf done; exit 0",
run_in_background: true,
});
extractProcessId(res.output);
// Registration pinged synchronously, inside the launching call.
expect(pings).toBeGreaterThanOrEqual(1);
// The exit pings on its own: the row stays listed (exited) but leaves the running set.
await waitFor(() => env.listBackgroundCommands().every((p) => !p.running));
await waitFor(() => pings >= 2);
const settled = pings;
const long = await runTool(env, "exec_command", { cmd: "sleep 30", run_in_background: true });
const id = extractProcessId(long.output);
expect(pings).toBe(settled + 1);
// A deliberate kill disarms the completion report but not this: the registry removal
// pings synchronously, and the group's later exit adds nothing the host has to act on.
const killed = await runTool(env, "input_command", { process_id: id, kill: true });
expect(killed.stopReason).toBe("completed");
expect(pings).toBeGreaterThan(settled + 1);
expect(env.listBackgroundCommands().find((p) => p.processId === id)).toBeUndefined();
});
it("pings when a subagent is promoted to the background and when its round settles", async () => {
const gates = new Map<string, () => void>();
const runner = runnerOf(async function* ({ prompt }) {
await new Promise<void>((r) => gates.set(prompt, r));
yield withHop(assistantText(`answer to: ${prompt}`));
});
const dir = await mkdtemp(path.join(tmpdir(), "penguin-bg-"));
const env = new Environment({
workspaceDir: dir,
toolConfig: { customTools: [SUB_DEF], mcpServers: [] },
services: { subagentRunner: runner },
});
cleanups.push(async () => {
env.dispose();
await rm(dir, { recursive: true, force: true });
});
let pings = 0;
env.setBackgroundStateListener(() => {
pings += 1;
});
const res = await runTool(env, "run_subagent", { prompt: "bg task", run_in_background: true });
expect(res.stopReason).toBe("completed");
expect(pings).toBeGreaterThanOrEqual(1);
// Promoted (it holds a subagent_id) and mid-round: what a host counts as a background subagent.
expect(env.listBackgroundSubagents()).toMatchObject([{ running: true }]);
expect(env.listBackgroundSubagents()[0]!.subagentId).not.toBeNull();
const launched = pings;
await waitFor(() => gates.has("bg task"));
gates.get("bg task")!();
await waitFor(() => !env.hasRunningBackgroundSubagents());
// The round settling rides the same listener as the registry changes: one subscription
// hears everything that moves the count.
expect(pings).toBeGreaterThan(launched);
expect(env.listBackgroundSubagents()).toMatchObject([{ running: false }]);
// Disposal is silent: the Session has ended, and its registries emptying is not news.
const beforeDispose = pings;
env.dispose();
expect(pings).toBe(beforeDispose);
});
});
describe("input_command defaults", () => {
it("the default empty-poll wait is 110000ms", () => {
expect(DEFAULT_EMPTY_POLL_YIELD_MS).toBe(110_000);
});
});
// ---------------------------------------------------------------------------
// run_subagent run_in_background + kill_subagent (fake runner)
// ---------------------------------------------------------------------------
const SUB_DEF = toolDef("run_subagent");
const SUB_INPUT_DEF = toolDef("input_subagent");
const CTX: ToolExecutionContext = { workspaceDir: "/tmp/ws", toolCallId: "call_1" };
const HOP = "session-child-12ab34cd";
type RunInput = { prompt: string; signal?: AbortSignal; approve?: ApproveFn };
/**
* Test fakes still talk in prompt strings; the contract now takes the OmniMessage list a
* Session's `run` takes, so the adapters below unwrap it once (see SubagentHandle.run).
*/
const promptOf = (messages: OmniMessage[]): string =>
messages.map((m) => (m.payload as { text?: string }).text ?? "").join("");
function runnerOf(run: (input: RunInput) => AsyncGenerator<OmniMessage>): SubagentRunner {
return {
async spawn() {
// Mirrors the composition layer's one-shot meta seam (SubagentHandle.takeMeta).
let metaSent = false;
const handle: SubagentHandle = {
sessionId: HOP,
takeMeta() {
if (metaSent) return null;
metaSent = true;
return withHop({
timestamp: new Date().toISOString(),
type: "session_meta",
payload: { session_id: HOP },
} as unknown as OmniMessage);
},
run: ({ messages, ...rest }) => run({ prompt: promptOf(messages), ...rest }),
dispose() {},
};
return handle;
},
};
}
async function drive(
tool: ReturnType<typeof createSubagentTool>,
args: Record<string, unknown>,
ctx: ToolExecutionContext = CTX,
): Promise<{ output: string; stopReason?: string; note: string; yielded: OmniMessage[] }> {
const gen = tool.execute(args, ctx);
let output = "";
const yielded: OmniMessage[] = [];
for (;;) {
const res = await gen.next();
if (res.done) {
const r = res.value ?? undefined;
return { output, stopReason: r?.stopReason, note: r?.note ?? "", yielded };
}
yielded.push(res.value);
const p = res.value.payload as { type?: string; event_type?: string; output?: string };
if (p.type === "partial_tool_call_output" && p.event_type === "delta" && p.output) {
output += p.output;
}
}
}
function extractSubagentId(text: string): string {
const m = text.match(/subagent_id (subagent-[0-9a-f]+)/);
expect(m, `expected a subagent_id in: ${JSON.stringify(text)}`).toBeTruthy();
return m![1]!;
}
describe("run_subagent run_in_background", () => {
it("returns a subagent_id immediately and reports each round's completion", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
// Each round blocks on its own gate, so the test controls when a round settles.
const gates = new Map<string, () => void>();
const runner = runnerOf(async function* ({ prompt }) {
await new Promise<void>((r) => gates.set(prompt, r));
yield withHop(partialText("delta", `answer to: ${prompt}`));
yield withHop(assistantText(`answer to: ${prompt}`));
});
const events: BackgroundTaskDoneEvent[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
};
const tool = createSubagentTool(SUB_DEF, services);
const res = await drive(tool, {
prompt: "long analysis task",
run_in_background: true,
});
expect(res.stopReason).toBe("completed");
const id = extractSubagentId(res.note);
expect(res.note).toContain("will arrive as a user message");
// The child's session_meta is forwarded at launch (origin-tagged), so the frontend's
// subagents panel and the server's registry learn of it before any poll.
const metas = res.yielded.filter((m) => m.type === "session_meta");
expect(metas).toHaveLength(1);
expect(metas[0]!.origin).toEqual([HOP]);
expect(events).toHaveLength(0); // still running behind the gate
// A mid-round child pins its Session's runtime entry against idle eviction: evicting it
// would strand the completion report and the live message stream.
expect(manager.hasRunning()).toBe(true);
await waitFor(() => gates.has("long analysis task"));
gates.get("long analysis task")!();
await waitFor(() => events.length === 1);
expect(manager.hasRunning()).toBe(false);
expect(events[0]).toMatchObject({ kind: "subagent", id, status: "completed" });
expect(events[0]!.output).toContain("answer to: long analysis task");
expect(events[0]!.label).toBe("long analysis task");
// A follow-up round through input_subagent that outlives the poll window reports again
// on settle, carrying the text the window never delivered.
const input = createInputSubagentTool(SUB_INPUT_DEF, services);
const follow = await drive(input, {
subagent_id: id,
prompt: "second round",
yield_time_ms: 250,
});
expect(follow.stopReason).toBe("completed");
expect(follow.note).toContain("still running");
await waitFor(() => gates.has("second round"));
gates.get("second round")!();
await waitFor(() => events.length === 2);
expect(events[1]!.output).toContain("answer to: second round");
});
it("a HOST-started round stays silent: no completion report for the user's own message", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const gates = new Map<string, () => void>();
const runner = runnerOf(async function* ({ prompt }) {
await new Promise<void>((r) => gates.set(prompt, r));
yield withHop(partialText("delta", `answer to: ${prompt}`));
yield withHop(assistantText(`answer to: ${prompt}`));
});
const events: BackgroundTaskDoneEvent[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
};
const tool = createSubagentTool(SUB_DEF, services);
const res = await drive(tool, { prompt: "dispatched work", run_in_background: true });
const id = extractSubagentId(res.note);
await waitFor(() => gates.has("dispatched work"));
gates.get("dispatched work")!();
await waitFor(() => events.length === 1);
// The user messages the idle child from the panel: their conversation, not dispatched
// work — the parent must not be notified when it settles.
const session = manager.get(id)!;
session.startRun([userText("user says hi")], { suppressDoneReport: true });
await waitFor(() => gates.has("user says hi"));
gates.get("user says hi")!();
await waitFor(() => !session.running);
await new Promise((r) => setTimeout(r, 50));
expect(events).toHaveLength(1);
// The next MODEL-initiated round reports again (the watcher stayed armed).
const input = createInputSubagentTool(SUB_INPUT_DEF, services);
const follow = await drive(input, {
subagent_id: id,
prompt: "model round",
yield_time_ms: 250,
});
expect(follow.stopReason).toBe("completed");
await waitFor(() => gates.has("model round"));
gates.get("model round")!();
await waitFor(() => events.length === 2);
expect(events[1]!.output).toContain("answer to: model round");
});
it("input_subagent abort ends a running background round without a completion report", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const runner = runnerOf(async function* ({ signal }) {
await new Promise<void>((resolve) => {
if (signal?.aborted) return resolve();
signal?.addEventListener("abort", () => resolve(), { once: true });
});
yield withHop(assistantText("late"));
});
const events: BackgroundTaskDoneEvent[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
};
const tool = createSubagentTool(SUB_DEF, services);
const res = await drive(tool, { prompt: "will be aborted", run_in_background: true });
const id = extractSubagentId(res.note);
const input = createInputSubagentTool(SUB_INPUT_DEF, services);
const stopped = await drive(input, { subagent_id: id, abort: true, yield_time_ms: 3000 });
expect(stopped.output).toContain(`aborting subagent ${id}'s current run`);
expect(stopped.note).toContain(`subagent idle with subagent_id ${id}`);
// The session survives — a subagent has no kill notion, only its rounds end.
expect(manager.get(id)).toBeDefined();
// The abort-caused settle must not masquerade as a task completion.
await new Promise((r) => setTimeout(r, 100));
expect(events).toHaveLength(0);
});
it("a failing background subagent still reports (status failed) and taps its messages live", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const runner = runnerOf(async function* () {
// A child-session failure surfaces as its origin-tagged terminal record plus the
// run's return value (Session.run's contract), never a throw.
yield withHop(requestEnd("retryable", { attempt: 6, errorMessage: "socket hang up" }));
return {
kind: "llm_failure" as const,
errorCode: "network" as const,
errorMessage: "socket hang up",
};
});
const events: BackgroundTaskDoneEvent[] = [];
const tapped: OmniMessage[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
backgroundForward: (m: OmniMessage) => tapped.push(m),
};
const tool = createSubagentTool(SUB_DEF, services);
const res = await drive(tool, { prompt: "will fail", run_in_background: true });
extractSubagentId(res.note);
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ kind: "subagent", status: "failed" });
expect(events[0]!.detail).toContain("socket hang up");
// The failure record reached the live tap too (origin-tagged), not a poll buffer.
expect(tapped.some((m) => (m.payload as { type?: string }).type === "request_end")).toBe(true);
});
it("a background child's approvals resolve through the launching call's standing sink", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const decisions: string[] = [];
const runner = runnerOf(async function* ({ approve }) {
const tc = withHop(toolCall({ name: "exec_command", arguments: "{}", toolCallId: "c1" }));
const d = await approve!(tc as OmniMessage<ToolCallPayload>);
decisions.push(d);
yield withHop(partialText("delta", `approved:${d}`));
});
const events: BackgroundTaskDoneEvent[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
};
const tool = createSubagentTool(SUB_DEF, services);
const approveSpy: ApproveFn = async () => "allow";
const res = await drive(
tool,
{ prompt: "needs approval", run_in_background: true },
{ ...CTX, approve: approveSpy },
);
extractSubagentId(res.note);
// Without the standing sink this parks forever: the child's first approval request has
// no collect window to consult through.
await waitFor(() => decisions.length === 1);
expect(decisions[0]).toBe("allow");
await waitFor(() => events.length === 1);
expect(events[0]!.status).toBe("completed");
});
it("a detached child keeps running, inherits the call's approval sink and message tap, and reports on settle", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const decisions: string[] = [];
const gates = new Map<string, () => void>();
const runner = runnerOf(async function* ({ prompt, approve }) {
// Parked until the test releases it, so the detach lands mid-round.
await new Promise<void>((r) => gates.set(prompt, r));
const tc = withHop(toolCall({ name: "exec_command", arguments: "{}", toolCallId: "c1" }));
decisions.push(await approve!(tc as OmniMessage<ToolCallPayload>));
yield withHop(partialText("delta", "child answer"));
yield withHop(assistantText("child answer"));
});
const events: BackgroundTaskDoneEvent[] = [];
const tapped: OmniMessage[] = [];
const services = {
subagentRunner: runner,
subagentSessions: manager,
backgroundDone: (e: BackgroundTaskDoneEvent) => events.push(e),
backgroundForward: (m: OmniMessage) => tapped.push(m),
};
const tool = createSubagentTool(SUB_DEF, services);
const approveSpy: ApproveFn = async () => "allow";
const detach = new AbortController();
const timer = setTimeout(() => detach.abort(), 50);
const res = await drive(
tool,
// A yield window far longer than the test: the promotion can only be the detach.
{ prompt: "long job", yield_time_ms: 60000 },
{ ...CTX, approve: approveSpy, detachSignal: detach.signal },
);
clearTimeout(timer);
// Not an interruption: the call completes with a handle, and the child is still alive.
expect(res.stopReason).toBe("completed");
expect(res.note).toContain(DETACHED_TOOL_NOTE_PREFIX);
const id = extractSubagentId(res.note);
expect(manager.hasRunning()).toBe(true);
await waitFor(() => gates.has("long job"));
gates.get("long job")!();
// Without the standing sink handed over at detach time, this parks forever: no collect
// window will ever attach another one.
await waitFor(() => decisions.length === 1);
expect(decisions[0]).toBe("allow");
await waitFor(() => events.length === 1);
expect(events[0]).toMatchObject({ kind: "subagent", id, status: "completed" });
// And its messages keep streaming to the host past the launching turn's end.
expect(tapped.some((m) => (m.payload as { type?: string }).type === "text")).toBe(true);
});
it("a detached child with a queued approval is not reported as something to poll for", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const decisions: string[] = [];
const runner = runnerOf(async function* ({ approve }) {
const tc = withHop(toolCall({ name: "exec_command", arguments: "{}", toolCallId: "c1" }));
decisions.push(await approve!(tc as OmniMessage<ToolCallPayload>));
yield withHop(assistantText("child answer"));
});
const tool = createSubagentTool(SUB_DEF, {
subagentRunner: runner,
subagentSessions: manager,
});
// The user has not answered yet, so the request is still queued when the detach lands:
// pendingApprovals is 1 at the moment the note is written.
let asked = false;
let held = true;
const approveSpy: ApproveFn = async () => {
asked = true;
await waitFor(() => !held);
return "allow";
};
const detach = new AbortController();
void waitFor(() => asked).then(() => detach.abort());
const res = await drive(
tool,
{ prompt: "long job", yield_time_ms: 60000 },
{ ...CTX, approve: approveSpy, detachSignal: detach.signal },
);
expect(res.note).toContain(DETACHED_TOOL_NOTE_PREFIX);
// The standing sink attached at detach time carries that request to the user itself, so
// the note must not send the model off to poll for it (a run_in_background launch says
// nothing either; only the deadline promotion, which gets no standing sink, does).
expect(res.note).not.toContain("poll to review");
held = false;
await waitFor(() => decisions.length === 1);
expect(decisions[0]).toBe("allow");
});
it("input_subagent fails on an id this conversation never allocated (nothing to resume)", async () => {
const manager = new SubagentSessionManager();
cleanups.push(() => manager.dispose());
const input = createInputSubagentTool(SUB_INPUT_DEF, { subagentSessions: manager });
const res = await drive(input, { subagent_id: "subagent-deadbeef" });
expect(res.stopReason).toBe("fatal");
expect(res.output).toContain("unknown subagent_id");
});
});
/** Tags a message with the child hop, as the SubagentHandle contract requires. */
function withHop<M extends OmniMessage>(msg: M): M {
return { ...msg, origin: [HOP] };
}
// ---------------------------------------------------------------------------
// Engine boundary delivery of queued notices
// ---------------------------------------------------------------------------
/** A fake LLM that always answers with a plain final reply (no tool calls). */
class ReplyLLM implements LLMInterface {
calls = 0;
inputs: OmniMessage[][] = [];
async *streamGenerate(
params: GenerativeModelParameters,
): AsyncGenerator<OmniMessage, LLMOutcome> {
this.calls += 1;
this.inputs.push(params.newMessages);
yield assistantText(`reply ${this.calls}`);
yield tokenUsage(emptyTokenCounts(), { cache_read: 0, cache_write: 0, output: 1, total: 2 });
return { status: "completed" };
}
}
const idleEnvironment: EnvironmentInterface = {
listTools: async () => [],
executeTool: async function* () {
throw new Error("not used");
},
toolPermission: () => undefined,
};
const allow: ApproveFn = async () => "allow";
describe("ContextEngine background-notice delivery", () => {
it("delivers notices queued before the run with the first request input", async () => {
const llm = new ReplyLLM();
const queue: OmniMessage[] = [userText("[notice] task one done", "harness")];
const engine = new ContextEngine({
llm,
environment: idleEnvironment,
backgroundNotices: { drain: () => queue.splice(0), pending: () => queue.length },
});
const streamed: OmniMessage[] = [];
for await (const msg of engine.run([userText("hello")], { approve: allow })) streamed.push(msg);
expect(llm.calls).toBe(1);
const texts = llm.inputs[0]!.map((m) => (m.payload as { text?: string }).text);
expect(texts).toEqual(["hello", "[notice] task one done"]);
// The notice is also yielded to the consumer (mid-run input the render layer never saw).
expect(
streamed.some((m) => (m.payload as { text?: string }).text === "[notice] task one done"),
).toBe(true);
});
it("a notice arriving mid-run extends the task by one turn to react to it", async () => {
const llm = new ReplyLLM();
const queue: OmniMessage[] = [];
const engine = new ContextEngine({
llm,
environment: idleEnvironment,
backgroundNotices: { drain: () => queue.splice(0), pending: () => queue.length },
});
const gen = engine.run([userText("hello")], { approve: allow });
// Push the notice once the first request is in flight: after the first streamed message.
let pushed = false;
for await (const msg of gen) {
void msg;
if (!pushed) {
pushed = true;
queue.push(userText("[notice] finished late", "harness"));
}
}
// Turn 1 answered, then the notice forced turn 2 whose input is exactly the notice.
expect(llm.calls).toBe(2);
const texts = llm.inputs[1]!.map((m) => (m.payload as { text?: string }).text);
expect(texts).toEqual(["[notice] finished late"]);
});
});
// ---------------------------------------------------------------------------
// Session wiring: environment events → notice queue → host signal
// ---------------------------------------------------------------------------
const META: SessionMetaPayload = {
session_id: "session-bg-1",
provider: "custom",
model_id: "m1",
model_context_window: 1000,
system_prompt: "sp",
agent_state: "/tmp/state",
workspace: "/tmp/w",
source: "user",
};
const IMAGES = { imagesDir: "/tmp/scratchpad/session-bg-1", modelHasVision: true } as const;
/** Fake environment that exposes the background listener attach so tests can fire events. */
function listenerEnvironment(): {
environment: EnvironmentInterface;
fire: (e: BackgroundTaskDoneEvent) => void;
} {
let listener: ((e: BackgroundTaskDoneEvent) => void) | null = null;
return {
environment: {
...idleEnvironment,
setBackgroundTaskListener: (cb) => (listener = cb),
},
fire: (e) => listener?.(e),
};
}
const DONE_EVENT: BackgroundTaskDoneEvent = {
kind: "command",
id: "proc-11aa22bb",
status: "completed",
detail: "exit code 0",
label: "sleep 1",
output: "done!",
};
describe("Session background notices", () => {
it("queues an idle-arrival as a harness user message and signals the host", async () => {
const { environment, fire } = listenerEnvironment();
const session = new Session({
meta: META,
...IMAGES,
bootstrap: async () => ({ llm: new ReplyLLM() }),
environment,
});
let signaled = 0;
session.onBackgroundNotice(() => (signaled += 1));
fire(DONE_EVENT);
expect(signaled).toBe(1);
const taken = session.takeBackgroundNotices();
expect(taken).toHaveLength(1);
const p = taken[0]!.payload as TextPayload;
expect(p.role).toBe("user");
expect(p.sender).toBe("harness");
const parsed = parseBackgroundTaskDoneMessage(p.text);
expect(parsed!.done).toMatchObject({ kind: "command", id: "proc-11aa22bb" });
// The host take is the idle path: the notice is the new task's own starting input, so it
// carries no delivery stamp and keeps its independent turn in every render layer.
expect(parsed!.done.delivery).toBeUndefined();
expect(parsed!.rest).toContain("`sleep 1`");
expect(parsed!.rest).toContain("done!");
// Taking empties the queue, and the pending flag (the host's eviction pin) tracks it.
expect(session.hasPendingBackgroundNotices()).toBe(false);
fire(DONE_EVENT);
expect(session.hasPendingBackgroundNotices()).toBe(true);
session.takeBackgroundNotices();
expect(session.takeBackgroundNotices()).toHaveLength(0);
expect(session.hasPendingBackgroundNotices()).toBe(false);
});
it("a stopped command's notice says stopped, not failed", async () => {
const { environment, fire } = listenerEnvironment();
const session = new Session({
meta: META,
...IMAGES,
bootstrap: async () => ({ llm: new ReplyLLM() }),
environment,
});
fire({ ...DONE_EVENT, status: "stopped", detail: "stopped by SIGTERM" });
const text = (session.takeBackgroundNotices()[0]!.payload as TextPayload).text;
// The line the model reads first — "Background command failed … terminated by signal
// SIGTERM" was the whole problem.
expect(text).toContain("Background command stopped: `sleep 1` (process_id proc-11aa22bb)");
expect(text).toContain("stopped by SIGTERM");
expect(text).not.toContain("failed");
});
it("delivers a queued notice on the next run without a host signal for running tasks", async () => {
const { environment, fire } = listenerEnvironment();
const llm = new ReplyLLM();
const session = new Session({
meta: META,
...IMAGES,
bootstrap: async () => ({ llm }),
environment,
});
fire(DONE_EVENT); // no listener registered: stays queued
const streamed: OmniMessage[] = [];
for await (const msg of session.run([userText("hi")])) streamed.push(msg);
expect(llm.calls).toBe(1);
const texts = llm.inputs[0]!.map((m) => (m.payload as { text?: string }).text ?? "");
expect(texts[0]).toBe("hi");
expect(texts[1]).toContain("[background_task_done]");
// Engine drains are the steering delivery path — the notice joined a Task the user's
// prompt started, so it must carry the steering stamp and never open a turn of its own.
expect(isSteeredBackgroundNotice(texts[1]!)).toBe(true);
});
});
// ---------------------------------------------------------------------------
// Sibling background subagents survive a completion notice (issue #581)
// ---------------------------------------------------------------------------
/**
* A runner whose every spawn is a distinct child (its own session id, so the registry and
* the live index tell three children apart) that answers once its gate is released.
*/
function gatedRunner(gates: Map<string, () => void>): SubagentRunner {
let spawned = 0;
return {
async spawn() {
spawned += 1;
const hop = `session-child-${String(spawned).padStart(8, "0")}`;
const tag = <M extends OmniMessage>(msg: M): M => ({ ...msg, origin: [hop] });
let metaSent = false;
const handle: SubagentHandle = {
sessionId: hop,
takeMeta() {
if (metaSent) return null;
metaSent = true;
return tag({
timestamp: new Date().toISOString(),
type: "session_meta",
payload: { session_id: hop },
} as unknown as OmniMessage);
},
// Typed like the contract: a round's return value is its cutoff, and these rounds
// always run to completion.
async *run({ messages }): AsyncGenerator<OmniMessage, null> {
const prompt = promptOf(messages);
await new Promise<void>((resolve) => gates.set(prompt, resolve));
yield tag(assistantText(`answer to: ${prompt}`));
return null;
},
dispose() {},
};
return handle;
},
};
}
describe("sibling background subagents survive a completion notice (issue #581)", () => {
it("settling one child ends no sibling, on the idle path or on the steering path", async () => {
const gates = new Map<string, () => void>();
const dir = await mkdtemp(path.join(tmpdir(), "penguin-bg-"));
const env = new Environment({
workspaceDir: dir,
toolConfig: { customTools: [SUB_DEF], mcpServers: [] },
services: { subagentRunner: gatedRunner(gates) },
});
cleanups.push(async () => {
env.dispose();
await rm(dir, { recursive: true, force: true });
});
const llm = new ReplyLLM();
const session = new Session({
meta: META,
...IMAGES,
bootstrap: async () => ({ llm }),
environment: env,
});
let signaled = 0;
session.onBackgroundNotice(() => {
signaled += 1;
});
const running = () =>
env.listBackgroundSubagents().filter((s) => s.running && s.subagentId !== null);
const statusOf = (msg: OmniMessage): string =>
parseBackgroundTaskDoneMessage((msg.payload as TextPayload).text)!.done.status;
for (const prompt of ["alpha", "beta", "gamma"]) {
const res = await runTool(env, "run_subagent", { prompt, run_in_background: true });
expect(res.stopReason).toBe("completed");
}
await waitFor(() => gates.size === 3);
expect(running()).toHaveLength(3);
// Idle path: alpha settles while no Task runs — the host takes the notice and submits it
// as a Task of its own, the way the server's idle-arrival signal does.
gates.get("alpha")!();
await waitFor(() => signaled === 1);
const notices = session.takeBackgroundNotices();
expect(notices).toHaveLength(1);
expect(statusOf(notices[0]!)).toBe("completed");
for await (const msg of session.run(notices)) void msg;
expect(llm.calls).toBe(1);
expect(running()).toHaveLength(2);
expect(env.hasRunningBackgroundSubagents()).toBe(true);
// Steering path: beta settles while a Task runs — the engine drains the notice into that
// Task at its next boundary, and the host is never signaled.
let released = false;
for await (const msg of session.run([userText("how are they doing?")])) {
void msg;
if (!released) {
released = true;
gates.get("beta")!();
await waitFor(() => session.hasPendingBackgroundNotices());
}
}
expect(llm.calls).toBe(3);
const steered = llm.inputs[2]!.map((m) => (m.payload as { text?: string }).text ?? "");
expect(steered).toHaveLength(1);
expect(isSteeredBackgroundNotice(steered[0]!)).toBe(true);
expect(parseBackgroundTaskDoneMessage(steered[0]!)!.done.status).toBe("completed");
expect(signaled).toBe(1);
expect(running()).toHaveLength(1);
expect(env.hasRunningBackgroundSubagents()).toBe(true);
// The last child still ends on its own terms: completed, neither stopped nor failed.
gates.get("gamma")!();
await waitFor(() => signaled === 2);
const last = session.takeBackgroundNotices();
expect(last).toHaveLength(1);
expect(statusOf(last[0]!)).toBe("completed");
expect(running()).toHaveLength(0);
});
});