A local-first multi-agent app development platform, built on PenguinHarness
/**
* exec_command —— local shell executor, a built-in tool implementation (BuiltinTool).
*
* Spawns a process inside the Workspace via `bash -lc <cmd>` and streams content deltas as
* stdout/stderr chunks arrive. Waits up to `yield_time_ms`: if the command finishes in time,
* returns the full output and exit status; if it's still running when the deadline hits,
* returns the output collected so far plus a `process_id` — the process moves to background,
* managed by `CommandSessionManager`, and is interacted with afterward via `input_command`.
* Completion is decided by **the foreground
* process exiting**, not by waiting for EOF on the output stream — background children (e.g.
* `node server.js &`) that inherit the pipes won't hold up the tool.
*
* Division of responsibility with Environment (see environment.ts): this tool only produces
* content deltas; exit code/signal/spawn errors and `process_id` are reported via the return
* value's `note` (appended outside the maxOutputLength truncation, so it survives even when
* long output gets truncated). Whether it ends normally or abnormally, it always finishes via
* the return value, **never throws**; on interruption it only reports `aborted` — the
* interruption note itself is appended by Environment.
* Docs: /docs/tools § "Command sessions".
*/
import path from "node:path";
import { partialToolCallOutput } from "../../omnimessage/index.js";
import type { OmniMessage } from "../../omnimessage/index.js";
import { DETACHED_TOOL_NOTE_PREFIX } from "../../interfaces/index.js";
import type { EnvironmentServices, ToolDefinitionConfig } from "../../interfaces/index.js";
import type { BuiltinTool, ToolExecutionContext, ToolResult } from "./types.js";
import { DEFAULT_EXEC_YIELD_MS, isStopSignal, resultForExit } from "./command/index.js";
import type { ManagedSession } from "./command/index.js";
import { clampYield, collectUntil, reportLabel, tailForReport } from "./background/index.js";
import { describeArgumentError, stringArgument } from "./tool-arguments.js";
/** Tool name constant (used only inside this tool module, not exposed to Environment). */
export const EXEC_COMMAND_NAME = "exec_command";
/**
* The argument names that carry the shell text, in the order the tool reads them: `cmd`, the
* schema's name, then `command`, accepted as an alias. Models trained on harnesses whose
* shell tool takes `command` emit that name even while reading a schema that says `cmd`, and
* a call rejected for it tends to be re-issued unchanged — the model believes it followed
* the schema — so one session can spend most of its calls on the same mistake. The schema
* itself keeps naming `cmd` alone. Every reader of the shell text goes through this list:
* the command policy screens exactly the text the tool runs (internal/command-policy.ts),
* and the Web App's and CLI's previews fall back to the alias the same way.
*/
export const EXEC_COMMAND_TEXT_ARGUMENTS: readonly string[] = ["cmd", "command"];
/** The alias table for argument explanations: `command` is `cmd` under another name, not an unknown argument. */
const EXEC_COMMAND_ALIASES: Readonly<Record<string, readonly string[]>> = {
cmd: EXEC_COMMAND_TEXT_ARGUMENTS.slice(1),
};
/**
* exec_command built-in tool: parses arguments, resolves workdir, and delegates to
* `CommandSessionManager` to spawn the process and collect output.
* `definition` is overridden by Environment at construction time with the matching entry
* from ToolConfig (description/parameters/permission/limits); the runtime tool name and
* self-referential messages follow `definition.name` (the config entry is the single
* source of truth for naming).
* `services.commandSessions` is injected by Environment (shares the same registry with
* input_command).
*/
export function createExecCommandTool(
definition: ToolDefinitionConfig,
services?: EnvironmentServices,
): BuiltinTool {
const manager = services?.commandSessions;
return {
name: definition.name,
definition,
detachable: true,
async *execute(
args: Record<string, unknown>,
ctx: ToolExecutionContext,
): AsyncGenerator<OmniMessage, ToolResult | void> {
const { toolCallId, signal, detachSignal } = ctx;
const delta = (output: string): OmniMessage =>
partialToolCallOutput({ eventType: "delta", output, toolCallId });
if (!manager) {
yield delta(`[${definition.name} unavailable: no command session manager configured]`);
return { stopReason: "fatal" };
}
const text = stringArgument(args, EXEC_COMMAND_TEXT_ARGUMENTS);
if (text === undefined || text.value.length === 0) {
yield delta(
describeArgumentError(
definition,
args,
{ argument: "cmd", kind: "missing" },
{ aliases: EXEC_COMMAND_ALIASES },
),
);
return { stopReason: "fatal" };
}
const cmd = text.value;
// workdir defaults to workspaceDir; relative paths are resolved against workspaceDir.
const rawWorkdir = args["workdir"];
const workdir =
typeof rawWorkdir === "string" && rawWorkdir.length > 0
? path.resolve(ctx.workspaceDir, rawWorkdir)
: ctx.workspaceDir;
const background = args["run_in_background"] === true;
const yieldMs = clampYield(
args["yield_time_ms"],
DEFAULT_EXEC_YIELD_MS,
definition.timeoutMs,
);
// Caller already aborted: finish immediately with aborted.
if (signal?.aborted) return { stopReason: "aborted" };
let session;
try {
session = manager.spawn({ cmd, cwd: workdir });
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
yield delta(`[spawn error: ${message}]`);
return { stopReason: "fatal" };
}
// run_in_background: no collect window at all — register immediately, arm the completion
// report, and hand back the process_id. When the foreground process exits, the report
// reaches the conversation as a harness user message (see armCommandDoneReport); the
// model can still poll/steer it — or terminate it — with input_command meanwhile.
if (background) {
const id = manager.register(session);
armCommandDoneReport(session, id, services);
return {
stopReason: "completed",
note:
`[command running in background with process_id ${id}; its completion will arrive ` +
`as a user message — no need to poll. Use input_command to interact (kill: true stops it)]`,
};
}
// On interruption, kill the whole process group (background children included) to
// avoid orphans; once the process moves to background this listener is removed in finally.
// Deliberately listens to `signal` only: a detach leaves the process running — it is the
// opposite request.
const onAbort = (): void => session.kill();
let registered = false;
signal?.addEventListener("abort", onAbort, { once: true });
try {
// Either an interruption or a detach ends collection; which one fired is read below.
for await (const chunk of session.collect(yieldMs, collectUntil(signal, detachSignal))) {
yield delta(chunk);
}
if (signal?.aborted) return { stopReason: "aborted" };
if (session.running) {
// Still running: register as a background process, returning process_id so
// input_command can continue accessing it. Whatever was collected up to this point
// has already been yielded, so it stays in this call's output.
const id = manager.register(session);
registered = true;
if (detachSignal?.aborted) {
// Detached by the user rather than by the yield deadline: the model never chose
// to poll this one, so arm the completion report the way a run_in_background
// launch does — otherwise the command would finish with nobody told.
armCommandDoneReport(session, id, services);
return {
stopReason: "completed",
note:
`${DETACHED_TOOL_NOTE_PREFIX} with process_id ${id}; leave it running unattended: ` +
`do not poll it or send it input — its completion will arrive on its own as a ` +
`[background_task_done] user message. Move on to other work, or end the turn if ` +
`nothing else is pending; input_command with kill: true still stops it if the user asks]`,
};
}
return {
stopReason: "completed",
note: `[process running with process_id ${id}; use input_command to send input or poll for output]`,
};
}
// Already exited: report exit status; process group cleanup (reaping any leftover
// background children) is handled uniformly in finally.
if (session.error) {
return { stopReason: "fatal", note: `[spawn error: ${session.error.message}]` };
}
return resultForExit(session.exit);
} finally {
signal?.removeEventListener("abort", onAbort);
if (!registered) session.kill();
}
},
};
}
/**
* Arms the completion report of a background-launched command: when the foreground process
* reaches a terminal state, the report (id, exit facts, tail of the yet-undelivered output)
* goes to `services.backgroundDone` — the Session turns it into a harness user message.
* input_command's kill disarms it first (a deliberate kill reports its outcome synchronously), and a
* disposed Environment drops the event (see Environment.emitBackgroundDone).
*
* A stop still reports — the conversation has to learn the dev server it started is down —
* but as `stopped`, not `failed`: the user's stop button, a stop signal from outside (a
* Ctrl-C in the terminal sharing the process group, a `pkill`, a supervisor), the harness's
* own forced stops (a capacity eviction, an idle reap). Worded "failed — terminated by signal
* SIGTERM" they read like a crash, and the model's reasonable response to a crashed dev
* server is to start it again, undoing the stop somebody just asked for. Outcomes nobody
* asked for stay `failed`: a spawn error, a non-zero exit, a hard kill or a fault signal (an
* OOM kill, a segfault).
*/
export function armCommandDoneReport(
session: ManagedSession,
processId: string,
services?: EnvironmentServices,
): void {
const notify = services?.backgroundDone;
if (!notify) return;
session.onceExited(() => {
const exit = session.exit;
const stopped = session.error === null && (session.stopRequested || isStopSignal(exit?.signal));
const failed =
!stopped &&
(session.error !== null || exit?.signal != null || (exit !== null && exit.code !== 0));
const detail = session.error
? `spawn error: ${session.error.message}`
: exit?.signal != null
? `${stopped ? "stopped by" : "terminated by signal"} ${exit.signal}`
: `exit code ${exit?.code ?? "unknown"}`;
notify({
kind: "command",
id: processId,
label: reportLabel(session.cmd),
status: stopped ? "stopped" : failed ? "failed" : "completed",
detail,
output: tailForReport(session.drainPending()),
});
});
}