@procedures/shell 0.0.0-stage → 0.2.0

package/src/command/tree-kill.ts

@@ -0,0 +1,121 @@
+/**
+ * Kill a child process and all the processes that it started (deep dive WRP-10).
+ *
+ * `child.kill()` reaches only the direct child. On Windows it calls `TerminateProcess`, so the
+ * grandchildren keep running (a `pnpm` that starts `node`, a `vite` that starts `esbuild`).
+ * - On Windows, `taskkill /T /F` ends the tree of the process id.
+ * - Elsewhere, the child starts in its own process group (`detached`), and a signal to the
+ *   negative pid reaches every process of the group.
+ *
+ * The module also records each live child. When the host process ends (a normal exit, or
+ * SIGINT, SIGTERM or SIGHUP), it kills each recorded tree, so no child keeps running alone.
+ */
+
+import { execFile, spawnSync, type ChildProcess } from "node:child_process";
+
+const WINDOWS = process.platform === "win32";
+
+/**
+ * True when a child must start with `detached: true`. On POSIX, `detached` puts the child in a
+ * new process group, which `killTree` needs. On Windows, `detached` opens a new console.
+ */
+export const OWN_PROCESS_GROUP: boolean = !WINDOWS;
+
+function running(child: ChildProcess): boolean {
+  return child.pid !== undefined && child.exitCode === null && child.signalCode === null;
+}
+
+/** This function kills the process tree of `child`. It does nothing when the child has ended. */
+export function killTree(child: ChildProcess, signal: NodeJS.Signals = "SIGTERM"): void {
+  if (!running(child)) return;
+  const pid = child.pid!;
+  if (WINDOWS) {
+    execFile("taskkill", ["/T", "/F", "/PID", String(pid)], { windowsHide: true }, (error) => {
+      // taskkill fails when the process ended in the meantime, or when taskkill is missing
+      if (error && running(child)) child.kill(signal);
+    });
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    // The child is not a group leader (it did not start detached): kill only the child
+    child.kill(signal);
+  }
+}
+
+/** The synchronous form, for the exit of the host, when callbacks do not run any more. */
+function killTreeSync(child: ChildProcess): void {
+  if (!running(child)) return;
+  const pid = child.pid!;
+  try {
+    if (WINDOWS) {
+      spawnSync("taskkill", ["/T", "/F", "/PID", String(pid)], { windowsHide: true, stdio: "ignore" });
+    } else {
+      process.kill(-pid, "SIGKILL");
+    }
+  } catch {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // The process ended
+    }
+  }
+}
+
+// =============================================================================
+// The live children, and the hooks that kill them when the host ends
+// =============================================================================
+
+const live = new Set<ChildProcess>();
+const SIGNALS: readonly NodeJS.Signals[] = ["SIGINT", "SIGTERM", "SIGHUP"];
+let hooked = false;
+
+function killAll(): void {
+  for (const child of live) killTreeSync(child);
+  live.clear();
+}
+
+function onExit(): void {
+  killAll();
+}
+
+function onSignal(signal: NodeJS.Signals): void {
+  killAll();
+  // Without this handler, Node ends the process on the signal. When this handler is the only one,
+  // do the same: remove the hooks and send the signal again.
+  if (process.listenerCount(signal) === 1) {
+    unhook();
+    process.kill(process.pid, signal);
+  }
+}
+
+function hook(): void {
+  if (hooked) return;
+  hooked = true;
+  process.on("exit", onExit);
+  for (const signal of SIGNALS) process.on(signal, onSignal);
+}
+
+function unhook(): void {
+  if (!hooked) return;
+  hooked = false;
+  process.off("exit", onExit);
+  for (const signal of SIGNALS) process.off(signal, onSignal);
+}
+
+/**
+ * This function records a child until it ends. While at least one child is recorded, the hooks
+ * kill the recorded trees when the host ends. With no recorded child, the host has no hooks.
+ */
+export function track(child: ChildProcess): void {
+  if (!running(child)) return;
+  live.add(child);
+  hook();
+  const forget = (): void => {
+    live.delete(child);
+    if (live.size === 0) unhook();
+  };
+  child.once("exit", forget);
+  child.once("error", forget);
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @procedures/shell
+ *
+ * Generic shell command execution procedures.
+ *
+ * Provides procedures for running CLI commands:
+ * - shell.run - Run command with args
+ * - shell.exec - Execute command string via shell
+ * - shell.which - Find command path
+ * - shell.stream - Run command with args and stream each output line
+ *
+ * The command helpers (`runCommand`, `streamCommand`, `processes`) are also available without
+ * the registration of the procedures, from `@procedures/shell/command`.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "@procedures/client";
+ *
+ * const result = await client.call(["shell", "run"], {
+ *   command: "git",
+ *   args: ["status"],
+ *   cwd: "/path/to/repo"
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  ShellRunInput,
+  ShellRunOutput,
+  ShellExecInput,
+  ShellExecOutput,
+  ShellWhichInput,
+  ShellWhichOutput,
+  ShellStreamInput,
+  ShellStreamItem,
+} from "./types.js";
+
+export {
+  ShellRunInputSchema,
+  ShellExecInputSchema,
+  ShellWhichInputSchema,
+  ShellStreamInputSchema,
+} from "./types.js";
+
+// Procedures
+export { shellRun, shellExec, shellWhich, shellStream } from "./procedures/shell/index.js";
+
+// Command helpers
+export * from "./command/index.js";
+
+// Registration
+export { registerShellProcedures } from "./module.js";

package/src/module.ts

@@ -0,0 +1,123 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for shell operations
+ */
+
+import { createProcedure, zodAdapter, defineModule, type Effects, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { shellRun } from "./procedures/shell/run.js";
+import { shellExec } from "./procedures/shell/exec.js";
+import { shellWhich } from "./procedures/shell/which.js";
+import { shellStream } from "./procedures/shell/stream.js";
+import {
+  ShellRunInputSchema,
+  ShellExecInputSchema,
+  ShellWhichInputSchema,
+  ShellStreamInputSchema,
+  type ShellRunInput,
+  type ShellRunOutput,
+  type ShellExecInput,
+  type ShellExecOutput,
+  type ShellWhichInput,
+  type ShellWhichOutput,
+  type ShellStreamInput,
+  type ShellStreamItem,
+  ShellRunOutputSchema,
+  ShellExecOutputSchema,
+  ShellWhichOutputSchema,
+  ShellStreamItemSchema,
+} from "./types.js";
+
+/**
+ * The effects of a procedure that runs a program that its caller chooses. The program can read
+ * and change anything, so "process" names both. A caller of these procedures declares what its
+ * program does.
+ */
+const RUNS_PROGRAM: Effects = { reads: ["process"], writes: ["process"] };
+
+// Procedure definitions
+const shellRunProcedure = createProcedure()
+  .path(["shell", "run"])
+  .input(zodAdapter<ShellRunInput>(ShellRunInputSchema))
+  .output(zodAdapter<ShellRunOutput>(ShellRunOutputSchema))
+  .meta({
+    description: "Run a command with arguments",
+    args: ["command"],
+    shorts: { cwd: "C", timeout: "t" },
+    output: "json",
+    effects: RUNS_PROGRAM,
+  })
+  .handler(async (input: ShellRunInput, ctx): Promise<ShellRunOutput> => {
+    return shellRun(input, ctx);
+  })
+  .build();
+
+const shellExecProcedure = createProcedure()
+  .path(["shell", "exec"])
+  .input(zodAdapter<ShellExecInput>(ShellExecInputSchema))
+  .output(zodAdapter<ShellExecOutput>(ShellExecOutputSchema))
+  .meta({
+    description: "Execute command string via shell",
+    args: ["command"],
+    shorts: { cwd: "C", timeout: "t" },
+    output: "json",
+    effects: RUNS_PROGRAM,
+  })
+  .handler(async (input: ShellExecInput, ctx): Promise<ShellExecOutput> => {
+    return shellExec(input, ctx);
+  })
+  .build();
+
+const shellWhichProcedure = createProcedure()
+  .path(["shell", "which"])
+  .input(zodAdapter<ShellWhichInput>(ShellWhichInputSchema))
+  .output(zodAdapter<ShellWhichOutput>(ShellWhichOutputSchema))
+  .meta({
+    description: "Find the path to a command",
+    args: ["command"],
+    shorts: {},
+    output: "json",
+    // A fixed program (`where` or `which`) reads the folders of PATH and changes nothing
+    effects: { reads: ["fs"], writes: [] },
+  })
+  .handler(async (input: ShellWhichInput, ctx): Promise<ShellWhichOutput> => {
+    return shellWhich(input, ctx);
+  })
+  .build();
+
+const shellStreamProcedure = createProcedure()
+  .path(["shell", "stream"])
+  .input(zodAdapter<ShellStreamInput>(ShellStreamInputSchema))
+  .output(zodAdapter<ShellStreamItem>(ShellStreamItemSchema))
+  .meta({
+    description: "Run a command and stream each output line as it arrives",
+    args: ["command"],
+    shorts: { cwd: "C", timeout: "t" },
+    output: "json",
+    streaming: true,
+    effects: RUNS_PROGRAM,
+  })
+  .handler(shellStream)
+  .build();
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const shellModule: ProcedureModule = defineModule("@procedures/shell", [
+    shellRunProcedure,
+    shellExecProcedure,
+    shellWhichProcedure,
+    shellStreamProcedure,
+  ]);
+
+export default shellModule;
+
+/**
+ * This function registers the procedures of @procedures/shell, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerShellProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [shellModule]);
+}

package/src/procedures/shell/exec.ts

@@ -0,0 +1,55 @@
+/**
+ * shell.exec procedure
+ *
+ * Execute a command string via shell.
+ *
+ * This is the one procedure that runs a shell: the command is a shell command line. It is not an
+ * MCP tool, and a data-driven procedure cannot call it (BUGS-2026-07 H18). The shell runs through
+ * the command helpers, so the timeout and `ctx.signal` kill the shell and every program that it
+ * started (deep dive WRP-10), and the `stdin` input reaches the command.
+ */
+
+import { runCommand } from "../../command/run.js";
+import type { ShellExecInput, ShellExecOutput } from "../../types.js";
+
+/** The program and the arguments that run `command` in a shell, as Node's `exec` does. */
+export function shellCommandLine(
+  command: string,
+  shell: boolean | string,
+): { file: string; args: string[]; verbatim: boolean } {
+  if (process.platform === "win32") {
+    const file = typeof shell === "string" ? shell : process.env["ComSpec"] ?? "cmd.exe";
+    if (/(?:^|[\\/])cmd(?:\.exe)?$/i.test(file)) {
+      // cmd.exe reads the rest of its command line as it is, so the arguments get no quotes
+      return { file, args: ["/d", "/s", "/c", `"${command}"`], verbatim: true };
+    }
+    return { file, args: ["-c", command], verbatim: false };
+  }
+  return { file: typeof shell === "string" ? shell : "/bin/sh", args: ["-c", command], verbatim: false };
+}
+
+export async function shellExec(
+  input: ShellExecInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): Promise<ShellExecOutput> {
+  const { file, args, verbatim } = shellCommandLine(input.command, input.shell);
+  const result = await runCommand(file, {
+    args,
+    windowsVerbatimArguments: verbatim,
+    cwd: input.cwd,
+    env: input.env,
+    timeout: input.timeout,
+    signal: ctx?.signal,
+    input: input.stdin,
+    maxOutputBytes: input.maxBuffer,
+  });
+
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    success: result.success,
+    duration: result.duration,
+    signal: result.signal,
+  };
+}

package/src/procedures/shell/index.ts

@@ -0,0 +1,4 @@
+export { shellRun } from "./run.js";
+export { shellExec } from "./exec.js";
+export { shellWhich } from "./which.js";
+export { shellStream } from "./stream.js";

package/src/procedures/shell/run.ts

@@ -0,0 +1,47 @@
+/**
+ * shell.run procedure
+ *
+ * Run a command with arguments and return output.
+ */
+
+import { runCommand } from "../../command/run.js";
+import type { ShellRunInput, ShellRunOutput } from "../../types.js";
+
+/**
+ * Most output kept per stream. Output beyond it is dropped (and reported), so a command
+ * that prints without end cannot exhaust memory. The process is not killed.
+ */
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Run a command with its arguments and no shell. The timeout and `ctx.signal` kill the whole
+ * process tree (deep dive WRP-10).
+ */
+export async function shellRun(
+  input: ShellRunInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): Promise<ShellRunOutput> {
+  const result = await runCommand(input.command, {
+    args: input.args,
+    cwd: input.cwd,
+    env: input.env,
+    timeout: input.timeout,
+    signal: ctx?.signal,
+    maxOutputBytes: MAX_OUTPUT_BYTES,
+    encoding: input.encoding as BufferEncoding,
+  });
+
+  const note = `\n[output truncated at ${MAX_OUTPUT_BYTES} bytes]`;
+  const output: ShellRunOutput = {
+    exitCode: result.exitCode,
+    stdout: result.truncated?.stdout ? result.stdout + note : result.stdout,
+    stderr: result.truncated?.stderr ? result.stderr + note : result.stderr,
+    success: result.success,
+    duration: result.duration,
+  };
+  // A signal means the process was killed (for example by the timeout)
+  if (result.signal) {
+    output.signal = result.signal;
+  }
+  return output;
+}

package/src/procedures/shell/stream.ts

@@ -0,0 +1,43 @@
+/**
+ * shell.stream procedure
+ *
+ * Run a command and stream each output line as it arrives. The procedure is a generator: the
+ * caller reads `{ type: "stdout" | "stderr", line }` items while the command runs, then one
+ * `{ type: "exit" }` item. When the caller stops reading, or its signal aborts, the command and
+ * the programs that it started end.
+ *
+ * The queue to the reader has a limit: when the reader is slow, the command waits in its next
+ * write (deep dive WRP-9). A character whose bytes arrive in two chunks stays whole (deep dive
+ * WRP-2). The work is done by `streamCommand`.
+ */
+
+import { streamCommand } from "../../command/stream.js";
+import type { ShellStreamInput, ShellStreamItem } from "../../types.js";
+
+/**
+ * Run a command and stream each output line as it arrives
+ */
+export async function* shellStream(
+  input: ShellStreamInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): AsyncGenerator<ShellStreamItem, void, undefined> {
+  // No shell: the arguments cannot inject commands
+  for await (const item of streamCommand(input.command, {
+    args: input.args,
+    cwd: input.cwd,
+    env: input.env,
+    timeout: input.timeout,
+    signal: ctx?.signal,
+  })) {
+    if (item.type === "exit") {
+      yield {
+        type: "exit",
+        exitCode: item.exitCode,
+        duration: item.duration,
+        ...(item.signal ? { signal: item.signal } : {}),
+      };
+    } else {
+      yield item;
+    }
+  }
+}

package/src/procedures/shell/which.ts

@@ -0,0 +1,26 @@
+/**
+ * shell.which procedure
+ *
+ * Find the full path to a command.
+ */
+
+import { runCommand } from "../../command/run.js";
+import type { ShellWhichInput, ShellWhichOutput } from "../../types.js";
+
+export async function shellWhich(
+  input: ShellWhichInput,
+  ctx?: { signal?: AbortSignal | undefined }
+): Promise<ShellWhichOutput> {
+  // The name is one argument of where/which, with no shell. (Before, `where ${command}` ran in a
+  // shell, so a name such as `x & calc` ran a second command: deep dive WRP-6.)
+  if (input.command.startsWith("-")) {
+    return { path: null, found: false };
+  }
+  const program = process.platform === "win32" ? "where" : "which";
+  const result = await runCommand(program, { args: [input.command], signal: ctx?.signal, timeout: 30_000 });
+  if (!result.success) {
+    return { path: null, found: false };
+  }
+  const path = result.stdout.trim().split(/\r?\n/)[0]?.trim() ?? "";
+  return path.length > 0 ? { path, found: true } : { path: null, found: false };
+}

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/shell, and of the modules that it
+ * requires, in the global registry: `import "@procedures/shell/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerShellProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerShellProcedures();

package/src/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Shell command types
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// shell.run Types
+// =============================================================================
+
+export const ShellRunInputSchema: z.ZodObject<{
+  command: z.ZodString;
+  args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+  encoding: z.ZodDefault<z.ZodString>;
+}> = z.object({
+  /** Command to run */
+  command: z.string().describe("Command to run"),
+  /** Arguments to pass */
+  args: z.array(z.string()).default([]).describe("Arguments to pass"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Environment variables to set */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables to set"),
+  /** Timeout in milliseconds */
+  timeout: z.number().optional().describe("Timeout in milliseconds"),
+  /** Encoding for output (default: utf8) */
+  encoding: z.string().default("utf8").describe("Encoding for output (default: utf8)"),
+});
+
+export type ShellRunInput = z.infer<typeof ShellRunInputSchema>;
+
+export interface ShellRunOutput {
+  /** Exit code */
+  exitCode: number;
+  /** Standard output */
+  stdout: string;
+  /** Standard error */
+  stderr: string;
+  /** Whether command succeeded (exit code 0) */
+  success: boolean;
+  /** Duration in milliseconds */
+  duration: number;
+  /** The signal that ended the process, if it was killed (for example by the timeout) */
+  signal?: string | undefined;
+}
+
+// =============================================================================
+// shell.exec Types (more options)
+// =============================================================================
+
+export const ShellExecInputSchema: z.ZodObject<{
+  command: z.ZodString;
+  cwd: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+  shell: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+  maxBuffer: z.ZodOptional<z.ZodNumber>;
+  stdin: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** Full command string to execute via shell */
+  command: z.string().describe("Full command string to execute via shell"),
+  /** Working directory */
+  cwd: z.string().optional().describe("Working directory"),
+  /** Environment variables */
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+  /** Timeout in milliseconds. At the timeout, the shell and the programs that it started are killed. */
+  timeout: z.number().optional().describe("Timeout in milliseconds. At the timeout, the shell and the programs that it started are killed."),
+  /** Shell to use: a path, or `true` for the system shell (`cmd.exe` or `/bin/sh`). `false` is the same as `true`. */
+  shell: z.union([z.boolean(), z.string()]).default(true).describe("Shell to use: a path, or `true` for the system shell (`cmd.exe` or `/bin/sh`). `false` is the same as `true`."),
+  /** The most bytes kept of each output stream (default: 64 MiB). The procedure drops the rest. */
+  maxBuffer: z.number().optional().describe("The most bytes kept of each output stream (default: 64 MiB). The procedure drops the rest."),
+  /** Text to write to stdin. Without it, stdin is empty. */
+  stdin: z.string().optional().describe("Text to write to stdin. Without it, stdin is empty."),
+});
+
+export type ShellExecInput = z.infer<typeof ShellExecInputSchema>;
+
+export interface ShellExecOutput {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  success: boolean;
+  duration: number;
+  /** Signal that terminated the process (if any) */
+  signal?: string | undefined;
+}
+
+// =============================================================================
+// shell.which Types
+// =============================================================================
+
+export const ShellWhichInputSchema: z.ZodObject<{
+  command: z.ZodString;
+}> = z.object({
+  /** Command to find */
+  command: z.string().describe("Command to find"),
+});
+
+export type ShellWhichInput = z.infer<typeof ShellWhichInputSchema>;
+
+export interface ShellWhichOutput {
+  /** Full path to command, or null if not found */
+  path: string | null;
+  /** Whether command was found */
+  found: boolean;
+}
+
+// =============================================================================
+// shell.stream Types - Run a command and stream each output line as it arrives
+// =============================================================================
+
+export const ShellStreamInputSchema: z.ZodObject<{
+  command: z.ZodString;
+  args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  timeout: z.ZodOptional<z.ZodNumber>;
+}> = z.object({
+  command: z.string().describe("The program to start (no shell: arguments go in args)"),
+  args: z.array(z.string()).default([]).describe("The arguments of the program"),
+  cwd: z.string().optional().describe("Working directory"),
+  env: z.record(z.string(), z.string()).optional().describe("Environment variables (added to the environment of the host)"),
+  timeout: z.number().optional().describe("Timeout in milliseconds. At the timeout, the program and its children are killed."),
+});
+
+export type ShellStreamInput = z.infer<typeof ShellStreamInputSchema>;
+
+/** One item of shell.stream: an output line, or the exit of the command (the last item). */
+export type ShellStreamItem =
+  | { type: "stdout" | "stderr"; line: string }
+  | { type: "exit"; exitCode: number; duration: number; signal?: string | undefined };
+
+// =============================================================================
+// Output schemas (roadmap 2.1)
+// =============================================================================
+
+// Loose objects: a field that a schema does not name stays in the result (a strict schema would
+// remove it when the output is validated).
+
+const commandResult = {
+  exitCode: z.number().describe("The exit code (0 is success, -1 when a signal ended the program)"),
+  stdout: z.string().describe("The standard output"),
+  stderr: z.string().describe("The standard error"),
+  success: z.boolean().describe("True when the exit code is 0"),
+  duration: z.number().describe("The time of the command, in milliseconds"),
+  signal: z.string().optional().describe("The signal that ended the program (for example at the timeout)"),
+};
+
+export const ShellRunOutputSchema: z.ZodType<ShellRunOutput> = z.looseObject(commandResult);
+
+export const ShellExecOutputSchema: z.ZodType<ShellExecOutput> = z.looseObject(commandResult);
+
+export const ShellWhichOutputSchema: z.ZodType<ShellWhichOutput> = z.looseObject({
+  path: z.string().nullable().describe("The full path of the program, or null when it is not found"),
+  found: z.boolean().describe("True when the program is found"),
+});
+
+export const ShellStreamItemSchema: z.ZodType<ShellStreamItem> = z.union([
+  z.looseObject({
+    type: z.enum(["stdout", "stderr"]).describe("The stream of the line"),
+    line: z.string().describe("One line of output, without its line end"),
+  }),
+  z.looseObject({
+    type: z.literal("exit").describe("The end of the stream (the last item)"),
+    exitCode: z.number().describe("The exit code (-1 when a signal ended the program)"),
+    duration: z.number().describe("The time of the command, in milliseconds"),
+    signal: z.string().optional().describe("The signal that ended the program"),
+  }),
+]);