@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/{evaluate-skill/scripts/lib/pi.mjs → evaluate-behavior/scripts/lib/subject.mjs}

@@ -1,23 +1,15 @@
+// One subject: the host-neutral part of running an arm's agent. It materializes the declared environment, fixture,
+// runtime and Freeflow settings, asks the arm's host adapter (hosts/) to launch the agent, and turns what the host
+// observed into the arm's run record. Everything that depends on the host program lives in its adapter.
+
 import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
-import { once } from "node:events";
-import { createWriteStream } from "node:fs";
 import { mkdir, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
-import {
-  mergeUsage,
-  messageText,
-  NO_PROGRESS_MS,
-  pipeStream,
-  processGroupExists,
-  signalProcessTree,
-  TERMINATION_GRACE_MS,
-  waitForForcedKill,
-  writeStream,
-} from "./process.mjs";
-import { runRpcBodySession, runRpcDescriptionSession } from "./rpc.mjs";
+import { baseProcessEnvironment } from "./process.mjs";
+import { writeFreeflowSettings } from "./freeflow.mjs";
+import { runMetrics } from "./hooks.mjs";
+import { hostAdapter } from "./hosts/index.mjs";
 import {
   fingerprintDirectory,
   materializeEnvironment,
@@ -26,29 +18,17 @@ import {
   snapshotWorkspace,
   verifyEnvironment,
   verifyRuntime,
+  WORKSPACE,
   workspaceChanges,
 } from "./sandbox.mjs";
 
-const guardExtension = fileURLToPath(new URL("../pi-guard.mjs", import.meta.url));
-const observerExtension = fileURLToPath(new URL("../pi-observer.mjs", import.meta.url));
-const HOST_COMMANDS = { pi: "pi", piflow: "piflow" };
-const BASE_PROCESS_ENVIRONMENT_KEYS = [
-  "PATH",
-  "HOME",
-  "TMPDIR",
-  "TMP",
-  "TEMP",
-  "LANG",
-  "LC_ALL",
-  "XDG_CONFIG_HOME",
-  "XDG_DATA_HOME",
-  "XDG_CACHE_HOME",
-  "PIFLOW_CODING_AGENT_DIR",
-  "PIFLOW_CODING_AGENT_SESSION_DIR",
-  "PI_PACKAGE_DIR",
-  "PI_OFFLINE",
-];
 const TURN_WORKSPACE_KINDS = new Set(["path", "changed-paths", "file-text", "json"]);
+// Tools whose commands run in the subject's container when it has one: bash, and Freeflow's background commands.
+const CONTAINER_SHELL_TOOLS = new Set(["bash", "bash_background", "monitor"]);
+// Freeflow's background commands save their output under the subject's temp directory and name that file to the
+// model, which reads it with read or from bash; with them declared, that directory is readable (and, in a container,
+// mounted read-only at its own path).
+const BACKGROUND_TOOLS = new Set(["bash_background", "monitor"]);
 
 export class VariantSetupError extends Error {
   constructor(message) {
@@ -57,39 +37,91 @@ export class VariantSetupError extends Error {
   }
 }
 
-export async function runDescription({ group, variant, root, variantDirectory, fixture, runtime, signal }) {
-  if (group.input.turns !== undefined) {
-    return runPersistentDescription({ group, variant, root, variantDirectory, fixture, runtime, signal });
-  }
-  return runOneShotDescription({ group, variant, root, variantDirectory, fixture, runtime, signal });
+export async function runDescription({
+  group,
+  variant,
+  root,
+  variantDirectory,
+  fixture,
+  runtime,
+  freeflow,
+  hostExtensions,
+  signal,
+  extendEnvironment = null,
+}) {
+  const options = { group, variant, root, variantDirectory, fixture, runtime, freeflow, hostExtensions, signal };
+  options.extendEnvironment = extendEnvironment;
+  if (group.input.turns !== undefined) return runPersistentDescription(options);
+  return runOneShotDescription(options);
 }
 
-export async function runBody({ group, variant, root, variantDirectory, fixture, runtime, signal }) {
-  const options = { group, variant, root, variantDirectory, fixture, runtime, signal };
+export async function runBody({
+  group,
+  variant,
+  root,
+  variantDirectory,
+  fixture,
+  runtime,
+  freeflow,
+  hostExtensions,
+  signal,
+  extendEnvironment = null,
+  nextPrompt = null,
+}) {
+  const options = { group, variant, root, variantDirectory, fixture, runtime, freeflow, hostExtensions, signal };
+  options.extendEnvironment = extendEnvironment;
   const subject = await prepareSubject(options, "rpc");
-  const before = await fingerprintDirectory(subject.workspace);
+  const before = await fingerprintDirectory(subject.workspace, WORKSPACE);
   const declaredPrompts = group.input.prompt === undefined ? [...group.input.turns] : [group.input.prompt];
-  const observation = await runRpcBodySession({
-    command: subject.host.command,
-    args: subject.args,
-    cwd: subject.workspace,
-    eventsFile: subject.eventsFile,
-    stderrFile: subject.stderrFile,
-    signal,
-    prompts: declaredPrompts,
-    targetPath: subject.environment.targetPath,
-    environment: subject.processEnvironment,
-    afterTurn: needsTurnWorkspaceEvidence(group)
-      ? (turn) => snapshotWorkspace({ workspace: subject.workspace, variantDirectory, turn, before })
-      : null,
-  });
+  // A container environment runs the subject's bash and declared commands in a container of its own, removed even
+  // when the run is cancelled. A group with neither needs no subject container; its graders still run in the image.
+  const usesContainer =
+    group.tools.some((tool) => CONTAINER_SHELL_TOOLS.has(tool)) || (group.commands?.length ?? 0) > 0;
+  const declaredContainer = usesContainer ? group.variants[variant].shell?.container : undefined;
+  let container = null;
+  if (declaredContainer !== undefined) {
+    const { containerTarget, startContainer } = await import("./container.mjs");
+    // The subject's declared resources are mounted read-only at the paths it was given, so its bash can run a
+    // skill's scripts; the workspace is the only writable mount.
+    container = await startContainer({
+      container: declaredContainer,
+      workspace: subject.workspace,
+      resources: subject.resourceRoots,
+    });
+    subject.processEnvironment.SKILL_EVAL_CONTAINER = containerTarget(container);
+  }
+  let observation;
+  try {
+    observation = await subject.adapter.runSession({
+      subject,
+      command: subject.host.command,
+      settings: subject.isolation.settings,
+      args: subject.args,
+      cwd: subject.workspace,
+      eventsFile: subject.eventsFile,
+      stderrFile: subject.stderrFile,
+      signal,
+      prompts: declaredPrompts,
+      resumeBefore: group.input.resume_before ?? [],
+      targetPath: subject.environment.targetPath,
+      environment: subject.processEnvironment,
+      nextPrompt,
+      afterTurn: needsTurnWorkspaceEvidence(group)
+        ? (turn) => snapshotWorkspace({ workspace: subject.workspace, variantDirectory, turn, before })
+        : null,
+    });
+  } finally {
+    await container?.remove();
+  }
   const contextObservation = await readContextObservations(
     subject.contextObservationPath,
     subject.requiresContextObservation,
   );
   observation.contextObservationArtifact = contextObservation.artifact;
+  if (contextObservation.error) (observation.protocolErrors ??= []).push(contextObservation.error);
   await verifySubjectResources(subject, observation);
-  const after = await fingerprintDirectory(subject.workspace);
+  // Links the subject made are recorded with their targets, never followed, so an installer's link cannot lose the run.
+  const after = await fingerprintDirectory(subject.workspace, WORKSPACE);
 
   const turns = [];
   for (const [index, turn] of observation.turns.entries()) {
@@ -106,6 +138,9 @@ export async function runBody({ group, variant, root, variantDirectory, fixture,
       assistantError: turn.assistantError,
       settled: turn.settled,
       workspace: turn.workspace ?? null,
+      ...(turn.resumed ? { resumed: turn.resumed } : {}),
+      // Runs Pi started on its own after this turn's prompt (an extension's notice), whose activity is part of it.
+      ...(turn.unpromptedRuns ? { unpromptedRuns: turn.unpromptedRuns } : {}),
     });
   }
 
@@ -142,7 +177,7 @@ function bodyRun(options, subject, observation, input, effects) {
 }
 
 function subjectRun({ group, variant }, subject, observation) {
-  return {
+  const run = {
     schema_version: 1,
     variant,
     state: subjectRunState(observation),
@@ -150,8 +185,9 @@ function subjectRun({ group, variant }, subject, observation) {
     completedAt: new Date().toISOString(),
     workspace: subject.workspace,
     tools: [...group.tools],
+    commands: group.commands ?? [],
     model: {
-      declared: group.model ?? null,
+      declared: group.variants[variant].model ?? null,
       observed: observation.model,
     },
     resources: {
@@ -160,9 +196,14 @@ function subjectRun({ group, variant }, subject, observation) {
       skills: subject.environment.skills,
       context: subject.environment.context,
       runtime: subject.runtime,
+      freeflow: subject.freeflow,
+      hostExtensions: subject.hostExtensions,
       contextDelivery: subject.environment.contextDelivery,
       targetPath: subject.environment.targetPath,
+      // Everything the subject's tools could read: the workspace first, then its declared resources.
+      readableRoots: [subject.workspaceRoot, ...subject.resourceRoots],
     },
+    isolation: subject.isolation,
     contextObservationArtifact: observation.contextObservationArtifact ?? null,
     response: observation.response,
     transcript: observation.transcript,
@@ -181,17 +222,24 @@ function subjectRun({ group, variant }, subject, observation) {
       stderr: subject.stderrFile,
     },
   };
+  // Run-metrics hooks derive their fields from what this run already recorded.
+  const metrics = runMetrics({ group, arm: variant, subject, observation, run });
+  if (metrics !== null) run.metrics = metrics;
+  return run;
 }
 
 async function runOneShotDescription(options) {
   const subject = await prepareSubject(options, "json");
-  const observation = await runPiProcess({
+  const observation = await subject.adapter.runOneShot({
+    subject,
     command: subject.host.command,
     args: subject.args,
     cwd: subject.workspace,
     eventsFile: subject.eventsFile,
     stderrFile: subject.stderrFile,
     signal: options.signal,
+    // Pi takes the prompt as its last argument (`args`); a host that reads prompts from stdin takes it here.
+    prompts: [options.group.input.prompt],
     environment: subject.processEnvironment,
   });
   const contextObservation = await readContextObservations(
@@ -199,12 +247,14 @@ async function runOneShotDescription(options) {
     subject.requiresContextObservation,
   );
   observation.contextObservationArtifact = contextObservation.artifact;
+  if (contextObservation.error) (observation.protocolErrors ??= []).push(contextObservation.error);
   await verifySubjectResources(subject, observation);
   const successfulReadPaths = await canonicalReadPaths(observation.successfulReads, subject.workspace);
   const targetRead =
     subject.environment.targetPath !== null && successfulReadPaths.includes(subject.environment.targetPath);
   return descriptionRun(options, subject, observation, {
     input: { prompt: options.group.input.prompt },
+    toolActivity: observation.toolActivity ?? [],
     activation: {
       targetRead,
       firstReadTurn: targetRead ? 1 : null,
@@ -216,8 +266,10 @@ async function runOneShotDescription(options) {
 
 async function runPersistentDescription(options) {
   const subject = await prepareSubject(options, "rpc");
-  const observation = await runRpcDescriptionSession({
+  const observation = await subject.adapter.runSession({
+    subject,
     command: subject.host.command,
+    settings: subject.isolation.settings,
     args: subject.args,
     cwd: subject.workspace,
     eventsFile: subject.eventsFile,
@@ -231,6 +283,7 @@ async function runPersistentDescription(options) {
     subject.requiresContextObservation,
   );
   observation.contextObservationArtifact = contextObservation.artifact;
+  if (contextObservation.error) (observation.protocolErrors ??= []).push(contextObservation.error);
   await verifySubjectResources(subject, observation);
 
   const turns = [];
@@ -264,59 +317,139 @@ async function runPersistentDescription(options) {
   });
 }
 
-async function prepareSubject({ group, variant, root, variantDirectory, fixture: fixtureSnapshot, runtime }, mode) {
+async function prepareSubject(
+  {
+    group,
+    variant,
+    root,
+    variantDirectory,
+    fixture: fixtureSnapshot,
+    runtime,
+    freeflow = null,
+    hostExtensions = [],
+    extendEnvironment = null,
+  },
+  mode,
+) {
   const workspace = path.join(variantDirectory, "workspace");
 
   let environment;
   let fixture;
   let materializedRuntime;
+  let adapter;
+  let isolation;
   try {
     environment = await materializeEnvironment({
       environment: group.variants[variant],
       root,
       variantDirectory,
     });
+    // A pipeline stage adds what it declares it sees from earlier stages as further declared context.
+    if (extendEnvironment !== null) await extendEnvironment(environment, variantDirectory);
     materializedRuntime = await materializeRuntime({ runtime, variantDirectory });
+    // Runtime environment literals may differ between arms (definitions.mjs); each subject gets its arm's own.
+    const literal = group.variants[variant].runtimeLiteral;
+    if (literal !== undefined) materializedRuntime.environment = { ...materializedRuntime.environment, literal };
     fixture = await materializeFixture({ fixture: fixtureSnapshot, workspace });
+    // Written before the workspace's starting state is taken, so they never count as the subject's changes.
+    if (freeflow !== null) await writeFreeflowSettings(workspace, freeflow);
+    adapter = hostAdapter(materializedRuntime.host);
+    isolation = await adapter.prepareIsolation(variantDirectory, group.variants[variant].model?.model ?? null, {
+      settings: adapter.effectiveSettings(group.variants[variant].hostSettings ?? {}),
+    });
   } catch (error) {
     if (error instanceof VariantSetupError) throw error;
     throw new VariantSetupError(error instanceof Error ? error.message : String(error));
   }
 
-  const host = { name: materializedRuntime.host, command: HOST_COMMANDS[materializedRuntime.host] };
+  const host = { name: materializedRuntime.host, command: adapter.command };
   const contextObservationPath = path.join(variantDirectory, "context-observations.jsonl");
   const requiresContextObservation = group.expectations.some((expectation) => expectation.kind === "context-text");
   const sessionDirectory = path.join(variantDirectory, "session");
   if (materializedRuntime.session) await mkdir(sessionDirectory, { recursive: true });
-  const args = piArguments(group, environment, materializedRuntime, mode, requiresContextObservation, sessionDirectory);
   const allowedRoots = [
     await realpath(workspace),
     ...environment.skills.map((skill) => skill.path),
     ...environment.context.map((entry) => entry.path),
     ...materializedRuntime.extensions.flatMap((bundle) => bundle.resources.map((resource) => resource.path)),
+    // Freeflow points the subject at its own skills and references inside the package.
+    ...(freeflow === null ? [] : [freeflow.packageRoot]),
+    ...(group.tools.some((tool) => BACKGROUND_TOOLS.has(tool)) && isolation.environment.TMPDIR
+      ? [isolation.environment.TMPDIR]
+      : []),
   ];
+  let launch;
+  try {
+    launch = await adapter.prepareLaunch({
+      group,
+      variant,
+      environment,
+      runtime: materializedRuntime,
+      mode,
+      observeContext: requiresContextObservation,
+      contextObservationPath,
+      sessionDirectory,
+      model: group.variants[variant].model,
+      freeflowEntry: freeflow?.entry ?? null,
+      hostExtensions,
+      workspace,
+      variantDirectory,
+      allowedRoots,
+      isolation: isolation.evidence,
+    });
+  } catch (error) {
+    if (error instanceof VariantSetupError) throw error;
+    throw new VariantSetupError(error instanceof Error ? error.message : String(error));
+  }
   return {
-    args,
+    adapter,
+    args: launch.args,
     environment,
+    hostExtensions,
+    freeflow:
+      freeflow === null
+        ? null
+        : {
+            ref: freeflow.ref,
+            commit: freeflow.commit,
+            package: freeflow.package,
+            tarballSha256: freeflow.tarballSha256,
+            metadata: freeflow.metadata,
+            repository: freeflow.repository,
+            personal: freeflow.personal,
+          },
+    // Where the built Freeflow package lies, so metrics can tell its skill reads apart; not recorded in run.json.
+    freeflowRoot: freeflow?.packageRoot ?? null,
     runtime: materializedRuntime,
     host,
     fixture,
     workspace,
+    workspaceRoot: allowedRoots[0],
+    // Every readable root but the workspace: the declared skills, context, runtime resources and Freeflow's package.
+    resourceRoots: allowedRoots.slice(1),
     contextObservationPath,
     requiresContextObservation,
     sessionDirectory,
     eventsFile: path.join(variantDirectory, "events.jsonl"),
     stderrFile: path.join(variantDirectory, "stderr.log"),
     startedAt: new Date().toISOString(),
-    processEnvironment: createProcessEnvironment({
-      runtime: materializedRuntime,
-      group,
-      workspace,
-      allowedRoots,
-      contextManifestPath: environment.contextDelivery.manifestPath,
-      contextObservationPath,
-      requiresContextObservation,
-    }),
+    isolation: isolation.evidence,
+    processEnvironment: {
+      ...createProcessEnvironment({
+        runtime: materializedRuntime,
+        group,
+        workspace,
+        allowedRoots,
+        contextManifestPath: environment.contextDelivery.manifestPath,
+        contextObservationPath,
+        requiresContextObservation,
+        hostEnvironment: launch.environment,
+      }),
+      // A declared shell lets the guard allow bash; its isolation extension runs it.
+      ...(group.variants[variant].shell ? { SKILL_EVAL_SHELL: JSON.stringify(group.variants[variant].shell) } : {}),
+      // Last, so nothing inherited or declared can point the subject back at the parent's home or Pi settings.
+      ...isolation.environment,
+    },
   };
 }
 
@@ -328,21 +461,22 @@ function createProcessEnvironment({
   contextManifestPath,
   contextObservationPath,
   requiresContextObservation,
+  hostEnvironment,
 }) {
-  const processEnvironment = Object.fromEntries(
-    BASE_PROCESS_ENVIRONMENT_KEYS.flatMap((key) => (process.env[key] === undefined ? [] : [[key, process.env[key]]])),
-  );
+  const processEnvironment = baseProcessEnvironment();
   Object.assign(processEnvironment, {
     PWD: workspace,
     ...runtime.environment.literal,
-    PI_SKIP_VERSION_CHECK: "1",
-    PI_TELEMETRY: "0",
+    // The host's own variables, such as Pi's version check and telemetry switches, after declared literals.
+    ...hostEnvironment,
     SKILL_EVAL_ALLOWED_ROOTS: JSON.stringify(allowedRoots),
     SKILL_EVAL_WRITABLE_ROOT: workspace,
     SKILL_EVAL_ALLOWED_TOOLS: JSON.stringify(group.tools),
     SKILL_EVAL_CONTEXT_MANIFEST: contextManifestPath ?? "",
     SKILL_EVAL_HOST: runtime.host,
+    SKILL_EVAL_PROMPT_MODE: runtime.prompt,
   });
+  if (group.commands !== undefined) processEnvironment.SKILL_EVAL_COMMANDS = JSON.stringify(group.commands);
   for (const key of runtime.environment.inherit) {
     if (process.env[key] === undefined) {
       throw new VariantSetupError(`inherited runtime environment variable is unavailable: ${key}`);
@@ -353,24 +487,39 @@ function createProcessEnvironment({
   return processEnvironment;
 }
 
+// A missing or malformed observation fails the subject but keeps everything the process already reported:
+// transcript, response, usage, and process evidence stay in run.json.
 async function readContextObservations(file, required) {
-  const contents = await readFile(file, "utf8").catch((error) => {
-    if (error?.code === "ENOENT") {
-      if (required) throw new Error("context observer produced no evidence");
-      return "";
-    }
-    throw error;
-  });
+  let contents;
+  try {
+    contents = await readFile(file, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    if (!required) return { observations: [], artifact: null, error: null };
+    return {
+      observations: [],
+      artifact: null,
+      error: { reason: "context-observer-missing", message: "context observer produced no evidence" },
+    };
+  }
   const observations = [];
   for (const line of contents.split("\n").filter(Boolean)) {
     try {
       observations.push(JSON.parse(line));
     } catch (error) {
-      throw new Error(`context observation is malformed: ${error instanceof Error ? error.message : String(error)}`);
+      return {
+        observations: [],
+        artifact: null,
+        error: {
+          reason: "context-observation-malformed",
+          message: `context observation is malformed: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      };
     }
   }
   return {
     observations,
+    error: null,
     artifact:
       contents === ""
         ? null
@@ -397,11 +546,12 @@ async function verifySubjectResources(subject, observation) {
   }
 }
 
-function descriptionRun(options, subject, observation, { input, activation }) {
+function descriptionRun(options, subject, observation, { input, activation, toolActivity }) {
   return {
     ...subjectRun(options, subject, observation),
     evaluationType: "description",
     ...input,
+    ...(toolActivity === undefined ? {} : { toolActivity }),
     activation,
   };
 }
@@ -420,179 +570,6 @@ function subjectRunState(observation) {
   return "infrastructure-failed";
 }
 
-function piArguments(group, environment, runtime, mode, observeContext, sessionDirectory) {
-  const args = ["--mode", mode];
-  if (mode === "json") args.push("-p");
-  if (runtime.session) args.push("--session-dir", sessionDirectory);
-  else args.push("--no-session");
-  args.push("--no-extensions", "--extension", guardExtension);
-  for (const bundle of runtime.extensions) args.push("--extension", bundle.entry);
-  if (observeContext) args.push("--extension", observerExtension);
-  args.push("--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "--no-approve");
-  if (group.tools.length === 0) args.push("--no-tools");
-  else args.push("--tools", group.tools.join(","));
-  for (const skill of environment.skills) args.push("--skill", skill.path);
-  if (group.model?.model) args.push("--model", group.model.model);
-  if (group.model?.thinking) args.push("--thinking", group.model.thinking);
-  if (mode === "json") args.push(group.input.prompt);
-  return args;
-}
-
-async function runPiProcess({ command, args, cwd, eventsFile, stderrFile, signal, environment }) {
-  const child = spawn(command, args, {
-    cwd,
-    detached: process.platform !== "win32",
-    env: environment,
-    shell: false,
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  const events = createWriteStream(eventsFile, { encoding: "utf8" });
-  const stderr = createWriteStream(stderrFile, { encoding: "utf8" });
-  const transcript = [];
-  const calls = new Map();
-  const successfulReads = [];
-  const parseErrors = [];
-  const protocolErrors = [];
-  let settled = false;
-  let response = "";
-  let usage = null;
-  let assistantError = null;
-  let observedModel = null;
-  let buffer = "";
-  let eventLine = 0;
-  const processGroupId = child.pid;
-  let watchdog;
-  let forcedKill;
-  /** @type {Promise<void> | null} */
-  let forcedKillPromise = null;
-  let terminationReason = null;
-
-  const resetWatchdog = () => {
-    clearTimeout(watchdog);
-    watchdog = setTimeout(() => requestTermination("no-progress-watchdog"), NO_PROGRESS_MS);
-    watchdog.unref();
-  };
-  const requestTermination = (reason) => {
-    if (terminationReason !== null) return;
-    terminationReason = reason;
-    signalProcessTree(processGroupId, child, "SIGTERM");
-    if (process.platform !== "win32") {
-      forcedKillPromise = new Promise((resolve) => {
-        forcedKill = setTimeout(() => {
-          signalProcessTree(processGroupId, child, "SIGKILL");
-          resolve();
-        }, TERMINATION_GRACE_MS);
-      });
-    }
-  };
-  const onAbort = () => requestTermination("cancelled");
-  if (signal?.aborted) onAbort();
-  else signal?.addEventListener("abort", onAbort, { once: true });
-  resetWatchdog();
-
-  const stderrTask = pipeStream(child.stderr, stderr, resetWatchdog);
-  const stdoutTask = (async () => {
-    for await (const chunk of child.stdout) {
-      resetWatchdog();
-      buffer += chunk.toString("utf8");
-      while (true) {
-        const newline = buffer.indexOf("\n");
-        if (newline === -1) break;
-        const line = buffer.slice(0, newline);
-        buffer = buffer.slice(newline + 1);
-        await writeStream(events, `${line}\n`);
-        observeLine(line.endsWith("\r") ? line.slice(0, -1) : line);
-      }
-    }
-    if (buffer.length > 0) {
-      await writeStream(events, buffer);
-      observeLine(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
-    }
-    events.end();
-    await once(events, "finish");
-  })();
-
-  function observeLine(line) {
-    eventLine += 1;
-    if (line.trim() === "") return;
-    let event;
-    try {
-      event = JSON.parse(line);
-    } catch {
-      parseErrors.push({ line: eventLine, reason: "invalid-json" });
-      return;
-    }
-    if (event.type === "extension_error") {
-      protocolErrors.push({
-        reason: "extension-error",
-        extensionPath: event.extensionPath ?? null,
-        event: event.event ?? null,
-        error: event.error ?? null,
-      });
-      requestTermination("protocol-error");
-    }
-    if (event.type === "agent_settled") settled = true;
-    if (event.type === "tool_execution_start") {
-      calls.set(event.toolCallId, { toolName: event.toolName, args: event.args });
-    }
-    if (event.type === "tool_execution_end" && !event.isError) {
-      const call = calls.get(event.toolCallId);
-      if (call?.toolName === "read" && typeof call.args?.path === "string") {
-        successfulReads.push(call.args.path);
-      }
-    }
-    if (event.type === "message_end" && event.message) {
-      transcript.push(event.message);
-      if (event.message.role === "assistant") {
-        response = messageText(event.message);
-        usage = mergeUsage(usage, event.message.usage);
-        observedModel = {
-          provider: event.message.provider ?? null,
-          model: event.message.model ?? null,
-        };
-        assistantError =
-          event.message.stopReason === "error" || event.message.stopReason === "aborted"
-            ? (event.message.errorMessage ?? `assistant stopped with ${event.message.stopReason}`)
-            : null;
-      }
-    }
-  }
-
-  let exitCode = null;
-  let exitSignal = null;
-  try {
-    const [code, closedSignal] = await once(child, "close");
-    exitCode = code;
-    exitSignal = closedSignal;
-    await Promise.all([stdoutTask, stderrTask]);
-  } catch (error) {
-    requestTermination("process-error");
-    throw error;
-  } finally {
-    clearTimeout(watchdog);
-    if (forcedKillPromise !== null) {
-      if (processGroupExists(processGroupId)) await waitForForcedKill(forcedKillPromise);
-      else clearTimeout(forcedKill);
-    }
-    signal?.removeEventListener("abort", onAbort);
-  }
-
-  return {
-    exitCode,
-    signal: exitSignal,
-    settled,
-    assistantError,
-    model: observedModel,
-    terminationReason,
-    parseErrors,
-    protocolErrors,
-    successfulReads,
-    transcript,
-    response,
-    usage,
-  };
-}
-
 async function canonicalReadPaths(paths, cwd) {
   const canonical = [];
   for (const rawPath of paths) {