sailfork / t3code-github / packages/ provider-acp/ src/ server/ AcpSessionRuntime.ts

// @effect-diagnostics nodeBuiltinImport:off
import * as NodeCrypto from "node:crypto";
import * as NodeFS from "node:fs";
import * as NodePath from "node:path";

import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Result from "effect/Result";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import * as SubscriptionRef from "effect/SubscriptionRef";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as EffectAcpClient from "effect-acp/client";
import * as EffectAcpErrors from "effect-acp/errors";
import type * as EffectAcpSchema from "effect-acp/compat";
import type * as EffectAcpProtocol from "effect-acp/protocol";
import { resolveSpawnCommand } from "@t3tools/shared/shell";
import { AgentScope, AgentScopeThreadId, RAISE_OOM_SCORE_LINE } from "@t3tools/shared/AgentScope";
import * as HostProcess from "@t3tools/shared/HostProcess";

import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
import { appendAcpStderrTail, sanitizeAcpStderrExcerpt } from "./stderr.ts";
import {
  collectSessionConfigOptionValues,
  decideToolCallUpdateEmission,
  extractModelConfigId,
  findModelConfigOption,
  findSessionConfigOption,
  mergeToolCallState,
  toolCallProgressLength,
  parseSessionModeState,
  parseSessionUpdateEvent,
  sessionUpdateCountsAsLoadReplayActivity,
  sessionUpdateIsReplay,
  waitForSessionLoadReplayIdle,
  type SessionLoadGate,
  type AcpParsedSessionEvent,
  type AcpSessionModeState,
  type AcpToolCallState,
} from "./runtimeModel.ts";

const MAX_SHOWN_TOOL_CALL_IDS = 256;

interface AcpToolCallTrackedState {
  readonly state: AcpToolCallState;
  readonly lastEmittedDetailLength: number | undefined;
  readonly skippedSinceEmit: number;
}

function formatConfigOptionValue(value: string | boolean): string {
  return JSON.stringify(value);
}

export interface AcpSessionEventStreamBarrier {
  readonly _tag: "EventStreamBarrier";
  readonly acknowledge: Deferred.Deferred<void>;
}

export type AcpSessionRuntimeEvent =
  | AcpParsedSessionEvent
  | AcpSessionEventStreamBarrier
  | {
      readonly _tag: "ConnectionTerminated";
      readonly error: EffectAcpErrors.AcpError;
    };

const defaultSessionLoadTimeout = Duration.seconds(90);
const defaultSessionLoadReplayIdleGap = Duration.seconds(2);
const defaultCancelTimeout = Duration.seconds(15);
const maxStartupMetadataUpdates = 32;
// Antigravity can emit an accepted 16 KiB Google authorization URL on stderr.
const maxStderrChunkLength = 32_768;

export interface AcpSpawnInput {
  readonly command: string;
  readonly args: ReadonlyArray<string>;
  readonly cwd?: string;
  readonly env?: NodeJS.ProcessEnv;
  readonly extendEnv?: boolean;
  readonly shell?: false;
}

export interface AcpSessionRuntimeOptions {
  readonly spawn: AcpSpawnInput;
  readonly cwd: string;
  readonly resumeSessionId?: string;
  readonly resumeMethod?: "load" | "resume";
  readonly sessionLoadTimeout?: Duration.Input;
  readonly sessionLoadReplayIdleGap?: Duration.Input;
  readonly interruptPromptOnCancel?: boolean;
  readonly cancelMeta?: EffectAcpSchema.CancelNotification["_meta"];
  readonly initializeMeta?: EffectAcpSchema.InitializeRequest["_meta"];
  readonly ownDetachedProcessGroup?: boolean;
  readonly ownDescendantProcessGroups?: boolean;
  readonly processGroupPlatform?: NodeJS.Platform;
  readonly processGroupTerminationGrace?: Duration.Input;
  readonly windowsProcessTreeTerminator?: (
    pid: number,
  ) => Effect.Effect<void, AcpProcessGroupTerminationError>;
  readonly posixProcessTreeController?: AcpPosixProcessTreeController;
  readonly linuxCgroupController?: AcpLinuxCgroupController | null;
  readonly cancelBehavior?: "interrupt" | "wait-for-prompt";
  readonly cancelTimeout?: Duration.Input;
  readonly clientCapabilities?: EffectAcpSchema.InitializeRequest["clientCapabilities"];
  readonly clientInfo: {
    readonly name: string;
    readonly title?: string;
    readonly version: string;
  };
  readonly authMethodId?: string;
  /** Authenticate before opening: Antigravity selects its credential source from the method. */
  readonly authenticateEagerly?: boolean;
  readonly mcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
  /** Sent on every session/new, load, resume and fork; omitting them clears an agent's stored roots. */
  readonly additionalDirectories?: ReadonlyArray<string>;
  /** Session `_meta`, chosen from the negotiated agent before each session setup or activation. */
  readonly sessionMeta?: (
    initializeResult: EffectAcpSchema.InitializeResponse,
  ) => EffectAcpSchema.NewSessionRequest["_meta"] | undefined;
  readonly transformStdout?: EffectAcpClient.AcpClientOptions["transformStdout"];
  readonly transformSessionUpdate?: (
    notification: EffectAcpSchema.SessionNotification,
  ) => EffectAcpSchema.SessionNotification;
  /** Redact secrets before logging. Failure closes the runtime. */
  readonly onStderr?: (text: string) => Effect.Effect<void, EffectAcpErrors.AcpError>;
  /** Disable only for non-interactive discovery that must surface auth-required immediately. */
  readonly authenticateOnAuthRequired?: boolean;
  readonly onInitialized?: (
    result: EffectAcpSchema.InitializeResponse,
  ) => Effect.Effect<void, never>;
  readonly acpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
  readonly httpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
  readonly requestLogger?: (event: AcpSessionRequestLogEvent) => Effect.Effect<void, never>;
  readonly protocolLogging?: {
    readonly logIncoming?: boolean;
    readonly logOutgoing?: boolean;
    readonly logger?: (event: EffectAcpProtocol.AcpProtocolLogEvent) => Effect.Effect<void, never>;
  };
  readonly onIncomingRequest?: EffectAcpClient.AcpClientOptions["onIncomingRequest"];
  readonly onTermination?: (error: EffectAcpErrors.AcpError) => Effect.Effect<void>;
  readonly onOutgoingResponseFailure?: EffectAcpClient.AcpClientOptions["onOutgoingResponseFailure"];
  readonly onOutgoingResponse?: EffectAcpClient.AcpClientOptions["onOutgoingResponse"];
  /** Unadvertised model IDs accepted by the config option; the agent validates them. */
  readonly customModels?: ReadonlyArray<string>;
}

export interface AcpSessionRequestLogEvent {
  readonly method: string;
  readonly payload: unknown;
  readonly status: "started" | "succeeded" | "failed";
  readonly result?: unknown;
  readonly cause?: Cause.Cause<EffectAcpErrors.AcpError>;
}

export class AcpProcessGroupTerminationError extends Schema.TaggedError<AcpProcessGroupTerminationError>()(
  "AcpProcessGroupTerminationError",
  {
    detail: Schema.String,
    pid: Schema.optionalKey(Schema.Int),
    exitCode: Schema.optionalKey(Schema.Number),
    cause: Schema.optional(Schema.Defect()),
  },
) {
  override get message(): string {
    return this.detail;
  }
}

const isAcpProcessGroupTerminationError = Schema.is(AcpProcessGroupTerminationError);

export interface AcpPosixProcessIdentity {
  readonly executable: string | undefined;
  readonly pgid: number;
  readonly pid: number;
  readonly ppid: number;
  readonly sid: number;
  readonly state?: string;
  readonly startTime: string;
}

export interface AcpPosixProcessTreeController {
  readonly childPidsOf: (pid: number) => ReadonlyArray<number>;
  readonly childrenOf: (pid: number) => ReadonlyArray<AcpPosixProcessIdentity>;
  readonly identity: (pid: number) => AcpPosixProcessIdentity | undefined;
  readonly snapshot: () => ReadonlyArray<AcpPosixProcessIdentity>;
  readonly signalProcess: (pid: number, signal: NodeJS.Signals) => void;
}

export interface AcpLinuxCgroupLease {
  readonly contains: (pid: number) => boolean;
  readonly exists: () => boolean;
  readonly path: string;
  readonly relativePath: string;
  readonly kill: () => void;
  readonly populated: () => boolean;
  readonly remove: () => void;
}

export interface AcpLinuxCgroupController {
  readonly create: () => AcpLinuxCgroupLease | undefined;
}

export interface AcpPosixOwnershipRoot {
  captureAttempted?: boolean;
  value: AcpOwnedPosixProcess | undefined;
}

function decodeMountInfoPath(value: string): string {
  return value.replace(/\\([0-7]{3})/g, (_match, octal: string) =>
    String.fromCharCode(Number.parseInt(octal, 8)),
  );
}

export function parseUnifiedCgroupPath(contents: string): string | undefined {
  const matches = [...contents.matchAll(/^0::(\/.*)$/gm)];
  return matches.length === 1 ? matches[0]![1] : undefined;
}

export function isSafeCgroupPath(value: string): boolean {
  return (
    value.startsWith("/") &&
    !value.includes("(deleted)") &&
    NodePath.posix.normalize(value) === value
  );
}

export function parseCgroup2Mounts(
  contents: string,
): ReadonlyArray<{ readonly mountPoint: string; readonly root: string }> {
  const mounts: Array<{ readonly mountPoint: string; readonly root: string }> = [];
  for (const line of contents.split("\n")) {
    const [mount, filesystem] = line.split(" - ");
    if (mount === undefined || filesystem?.split(" ")[0] !== "cgroup2") continue;
    const fields = mount.split(" ");
    if (fields.length < 5) continue;
    mounts.push({
      mountPoint: decodeMountInfoPath(fields[4]!),
      root: decodeMountInfoPath(fields[3]!),
    });
  }
  return mounts;
}

export function wrapCommandForLinuxCgroup(
  lease: AcpLinuxCgroupLease,
  command: string,
  args: ReadonlyArray<string>,
): { readonly command: string; readonly args: ReadonlyArray<string> } {
  return {
    command: "/bin/sh",
    args: [
      "-c",
      [
        "lease_path=$1; expected=$2; shift 2",
        RAISE_OOM_SCORE_LINE,
        'printf "%s\\n" "$" > "$lease_path/cgroup.procs" || exit 125',
        "actual=",
        "while IFS= read -r line; do",
        '  case "$line" in 0::*) [ -z "$actual" ] || exit 126; actual=${line#0::};; esac',
        "done < /proc/self/cgroup || exit 125",
        '[ "$actual" = "$expected" ] || exit 126',
        "unset ELECTRON_RUN_AS_NODE T3_ACP_CGROUP_WRAPPER",
        "trap 'exit 125' 0",
        // Bash can skip EXIT traps on failed exec; reject invalid targets with path and exit 125.
        '[ -f "$1" ] && [ -x "$1" ] || { printf "%s: %s: not an executable file\\n" "$0" "$1" >&2; exit 125; }',
        'exec "$@"',
      ].join("\n"),
      "t3-acp-cgroup-wrapper",
      lease.path,
      lease.relativePath,
      command,
      ...args,
    ],
  };
}

export function resolveLinuxCgroupTargetCommand(
  command: string,
  cwd: string,
  environment: NodeJS.ProcessEnv,
): string | undefined {
  // Match Node spawn: only undefined PATH gets a fallback; empty PATH searches cwd.
  const pathEnv = environment.PATH === undefined ? "/usr/bin:/bin" : environment.PATH;
  const candidates = command.includes(NodePath.sep)
    ? [NodePath.resolve(cwd, command)]
    : pathEnv
        .split(NodePath.delimiter)
        .map((entry) =>
          NodePath.join(
            entry.length === 0
              ? cwd
              : NodePath.isAbsolute(entry)
                ? entry
                : NodePath.resolve(cwd, entry),
            command,
          ),
        );
  for (const candidate of candidates) {
    try {
      if (!NodeFS.statSync(candidate).isFile()) continue;
      NodeFS.accessSync(candidate, NodeFS.constants.X_OK);
      return candidate;
    } catch {}
  }
  return undefined;
}

const STALE_ACP_CGROUP_SIBLING = /^t3-acp-(\d+)-/;

export interface SweepStaleLinuxCgroupSiblingsOptions {
  readonly currentPid?: number;
  readonly isProcessAlive?: (pid: number) => boolean;
  readonly readPopulated?: (siblingPath: string) => "0" | "1" | undefined;
  readonly remove?: (siblingPath: string) => void;
}

function defaultCgroupOwnerIsAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch (cause) {
    return (cause as NodeJS.ErrnoException | undefined)?.code !== "ESRCH";
  }
}

function defaultReadCgroupPopulated(siblingPath: string): "0" | "1" | undefined {
  const state = /(?:^|\n)populated ([01])(?:\n|$)/.exec(
    NodeFS.readFileSync(NodePath.join(siblingPath, "cgroup.events"), "utf8"),
  )?.[1];
  return state === "0" || state === "1" ? state : undefined;
}

export function sweepStaleLinuxCgroupSiblings(
  parentPath: string,
  options: SweepStaleLinuxCgroupSiblingsOptions = {},
): void {
  const currentPid = options.currentPid ?? process.pid;
  const isProcessAlive = options.isProcessAlive ?? defaultCgroupOwnerIsAlive;
  const readPopulated = options.readPopulated ?? defaultReadCgroupPopulated;
  const remove = options.remove ?? ((siblingPath: string) => NodeFS.rmdirSync(siblingPath));
  try {
    for (const entry of NodeFS.readdirSync(parentPath, { withFileTypes: true })) {
      try {
        if (!entry.isDirectory()) continue;
        const match = STALE_ACP_CGROUP_SIBLING.exec(entry.name);
        if (match === null) continue;
        const ownerPid = Number(match[1]);
        if (!Number.isSafeInteger(ownerPid) || ownerPid <= 1 || ownerPid === currentPid) continue;
        if (isProcessAlive(ownerPid)) continue;
        const siblingPath = NodePath.join(parentPath, entry.name);
        if (NodePath.dirname(siblingPath) !== parentPath) continue;
        if (readPopulated(siblingPath) !== "0") continue;
        remove(siblingPath);
      } catch {}
    }
  } catch {}
}

function tryCreateLinuxCgroupLease(
  currentRelative: string,
  mount: { readonly mountPoint: string; readonly root: string },
): AcpLinuxCgroupLease | undefined {
  if (
    !isSafeCgroupPath(mount.root) ||
    !isSafeCgroupPath(mount.mountPoint) ||
    !(
      mount.root === "/" ||
      currentRelative === mount.root ||
      currentRelative.startsWith(`${mount.root}/`)
    )
  ) {
    return undefined;
  }
  const mountRelative =
    mount.root === "/" ? currentRelative : currentRelative.slice(mount.root.length);
  const currentPath = NodePath.resolve(mount.mountPoint, `.${mountRelative}`);
  const resolvedMount = NodePath.resolve(mount.mountPoint);
  if (currentPath !== resolvedMount && !currentPath.startsWith(`${resolvedMount}${NodePath.sep}`)) {
    return undefined;
  }
  sweepStaleLinuxCgroupSiblings(currentPath);
  const childName = `t3-acp-${process.pid}-${NodeCrypto.randomUUID().replaceAll("-", "")}`;
  const childPath = NodePath.join(currentPath, childName);
  const childRelative = NodePath.posix.join(currentRelative, childName);
  if (NodePath.dirname(childPath) !== currentPath) return undefined;
  try {
    NodeFS.mkdirSync(childPath, { mode: 0o700 });
    NodeFS.accessSync(NodePath.join(childPath, "cgroup.procs"), NodeFS.constants.W_OK);
    NodeFS.accessSync(NodePath.join(childPath, "cgroup.kill"), NodeFS.constants.W_OK);
    NodeFS.accessSync(NodePath.join(childPath, "cgroup.events"), NodeFS.constants.R_OK);
    if (NodeFS.readFileSync(NodePath.join(childPath, "cgroup.type"), "utf8").trim() !== "domain") {
      throw new Error("ACP cgroup is not a domain cgroup");
    }
    if (typeof process.execve !== "function") throw new Error("process.execve is unavailable");
  } catch {
    try {
      NodeFS.rmdirSync(childPath);
    } catch {}
    return undefined;
  }
  return {
    contains: (pid) =>
      parseUnifiedCgroupPath(NodeFS.readFileSync(`/proc/${pid}/cgroup`, "utf8")) === childRelative,
    exists: () => NodeFS.existsSync(childPath),
    path: childPath,
    relativePath: childRelative,
    kill: () => NodeFS.writeFileSync(NodePath.join(childPath, "cgroup.kill"), "1\n"),
    populated: () => {
      const state = /(?:^|\n)populated ([01])(?:\n|$)/.exec(
        NodeFS.readFileSync(NodePath.join(childPath, "cgroup.events"), "utf8"),
      )?.[1];
      if (state === undefined) throw new Error("ACP cgroup.events has no populated state");
      return state === "1";
    },
    remove: () => {
      const directories = (path: string): ReadonlyArray<string> =>
        NodeFS.readdirSync(path, { withFileTypes: true }).flatMap((entry) =>
          entry.isDirectory()
            ? [...directories(NodePath.join(path, entry.name)), NodePath.join(path, entry.name)]
            : [],
        );
      for (const directory of directories(childPath)) NodeFS.rmdirSync(directory);
      NodeFS.rmdirSync(childPath);
    },
  };
}

export function makeLinuxCgroupController(): AcpLinuxCgroupController {
  return {
    create: () => {
      let currentRelative: string | undefined;
      let mounts: ReadonlyArray<{ readonly mountPoint: string; readonly root: string }> = [];
      try {
        currentRelative = parseUnifiedCgroupPath(NodeFS.readFileSync("/proc/self/cgroup", "utf8"));
        mounts = parseCgroup2Mounts(NodeFS.readFileSync("/proc/self/mountinfo", "utf8"));
      } catch {
        return undefined;
      }
      if (
        currentRelative === undefined ||
        !currentRelative.startsWith("/") ||
        mounts.length === 0
      ) {
        return undefined;
      }
      if (!isSafeCgroupPath(currentRelative)) return undefined;
      // Multi-mount hosts often list a read-only view before the delegated one.
      for (const mount of mounts) {
        const lease = tryCreateLinuxCgroupLease(currentRelative, mount);
        if (lease !== undefined) return lease;
      }
      return undefined;
    },
  };
}

// OS-state polls need wall time; TestClock sleep requires explicit advancement.
const wallClock = Clock.Clock.defaultValue();
const withWallClock = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
  Effect.provideService(effect, Clock.Clock, wallClock);

export function terminateLinuxCgroupLease(
  lease: AcpLinuxCgroupLease,
): Effect.Effect<void, AcpProcessGroupTerminationError> {
  const failure = (name: string, cause: unknown) =>
    new AcpProcessGroupTerminationError({
      cause,
      detail: `Failed to ${name} ACP cgroup ${lease.path}`,
    });
  return Effect.gen(function* () {
    let lastRemovalFailure: { readonly cause: unknown } | null = null;
    for (let attempt = 0; attempt < 200; attempt += 1) {
      if (!lease.exists()) return;
      const killed = Result.try(() => lease.kill());
      if (Result.isFailure(killed)) {
        const cause = killed.failure;
        const code = (cause as NodeJS.ErrnoException | undefined)?.code;
        if (code !== "ENOENT") return yield* failure("kill", cause);
        if (!lease.exists()) return;
        yield* Effect.sleep("10 millis");
        continue;
      }
      const populated = Result.try(() => lease.populated());
      if (Result.isFailure(populated)) {
        const cause = populated.failure;
        const code = (cause as NodeJS.ErrnoException | undefined)?.code;
        if (code === "ENOENT" && !lease.exists()) return;
        if (code === "ENOENT") {
          yield* Effect.sleep("10 millis");
          continue;
        }
        return yield* failure("read state for", cause);
      }
      if (populated.success) {
        lastRemovalFailure = null;
        yield* Effect.sleep("10 millis");
        continue;
      }
      const removed = Result.try(() => lease.remove());
      if (Result.isFailure(removed)) {
        const cause = removed.failure;
        const code = (cause as NodeJS.ErrnoException | undefined)?.code;
        if (code === "ENOENT" && !lease.exists()) return;
        if (code !== "EBUSY" && code !== "ENOTEMPTY" && code !== "ENOENT") {
          return yield* failure("remove", cause);
        }
        lastRemovalFailure = { cause };
      } else {
        lastRemovalFailure = null;
      }
      if (!lease.exists()) return;
      yield* Effect.sleep("10 millis");
    }
    if (lastRemovalFailure !== null) {
      return yield* failure("remove", lastRemovalFailure.cause);
    }
    return yield* new AcpProcessGroupTerminationError({
      detail: `ACP cgroup ${lease.path} remained present after cgroup cleanup`,
    });
  }).pipe(withWallClock);
}

export function signalLinuxCgroupRootTerm(input: {
  readonly controller: AcpPosixProcessTreeController;
  readonly lease: AcpLinuxCgroupLease;
  readonly root: AcpPosixOwnershipRoot;
}): void {
  const root = input.root.value;
  if (root === undefined) return;
  try {
    const observed = input.controller.identity(root.pid);
    if (!samePosixProcessIdentity(root, observed) || !input.lease.contains(root.pid)) return;
    input.controller.signalProcess(root.pid, "SIGTERM");
  } catch {}
}

function readLinuxProcessIdentity(pid: number): AcpPosixProcessIdentity | undefined {
  try {
    const stat = NodeFS.readFileSync(`/proc/${pid}/stat`, "utf8");
    const commandEnd = stat.lastIndexOf(")");
    if (commandEnd < 0) return undefined;
    const fields = stat
      .slice(commandEnd + 2)
      .trim()
      .split(/\s+/);
    // After comm: state, ppid, pgrp, session, … starttime (field 22 / index 19).
    const state = fields[0];
    const ppid = Number(fields[1]);
    const pgid = Number(fields[2]);
    const sid = Number(fields[3]);
    const startTime = fields[19];
    if (
      state === undefined ||
      !Number.isSafeInteger(ppid) ||
      !Number.isSafeInteger(pgid) ||
      !Number.isSafeInteger(sid) ||
      startTime === undefined
    ) {
      return undefined;
    }
    let executable: string | undefined;
    try {
      executable = NodeFS.readlinkSync(`/proc/${pid}/exe`);
    } catch {
      executable = undefined;
    }
    return { executable, pgid, pid, ppid, sid, startTime, state };
  } catch {
    return undefined;
  }
}

/** Linux zombies keep pid/starttime until reaped; they are not live survivors. */
export function posixProcessIsZombie(process: AcpPosixProcessIdentity): boolean {
  return process.state === "Z";
}

function readLinuxChildPids(pid: number): ReadonlyArray<number> {
  const childPids = new Set<number>();
  let taskIds: ReadonlyArray<string> = [];
  try {
    taskIds = NodeFS.readdirSync(`/proc/${pid}/task`).filter((entry) =>
      /^[1-9][0-9]*$/.test(entry),
    );
  } catch {
    return [];
  }
  for (const taskId of taskIds) {
    try {
      for (const childPid of NodeFS.readFileSync(`/proc/${pid}/task/${taskId}/children`, "utf8")
        .trim()
        .split(/\s+/)
        .filter(Boolean)
        .map(Number)) {
        childPids.add(childPid);
      }
    } catch {}
  }
  return [...childPids];
}

function makeLinuxProcessTreeController(): AcpPosixProcessTreeController {
  return {
    childPidsOf: readLinuxChildPids,
    childrenOf: (pid) =>
      readLinuxChildPids(pid).flatMap((childPid) => {
        const identity = readLinuxProcessIdentity(childPid);
        return identity === undefined ? [] : [identity];
      }),
    identity: readLinuxProcessIdentity,
    snapshot: () =>
      NodeFS.readdirSync("/proc", { withFileTypes: true }).flatMap((entry) => {
        if (!entry.isDirectory() || !/^[1-9][0-9]*$/.test(entry.name)) return [];
        const identity = readLinuxProcessIdentity(Number(entry.name));
        return identity === undefined ? [] : [identity];
      }),
    signalProcess: (pid, signal) => process.kill(pid, signal),
  };
}

export function observePosixOwnershipLedger(input: {
  readonly childQueues: Map<number, Array<number>>;
  readonly controller: AcpPosixProcessTreeController;
  readonly frontier: Map<number, AcpOwnedPosixProcess>;
  readonly ledger: Map<string, AcpOwnedPosixProcess>;
  readonly maxProcesses?: number;
  readonly root: AcpPosixOwnershipRoot;
  readonly rootPid: number;
}): void {
  let rootIdentity: AcpPosixProcessIdentity | undefined = input.root.value;
  if (rootIdentity === undefined) {
    if (input.root.captureAttempted === true) {
      throw new AcpProcessGroupTerminationError({
        detail: `ACP process ${input.rootPid} exited before its ownership ledger was captured`,
      });
    }
    input.root.captureAttempted = true;
    rootIdentity = input.controller.identity(input.rootPid);
    if (rootIdentity === undefined) {
      throw new AcpProcessGroupTerminationError({
        detail: `ACP process ${input.rootPid} exited before its ownership ledger was captured`,
      });
    }
    const parent = input.controller.identity(rootIdentity.ppid);
    const ownedRoot = {
      ...rootIdentity,
      parentExecutable: parent?.executable,
      parentStartTime: parent?.startTime ?? "",
    };
    input.ledger.set(processIdentityKey(rootIdentity), ownedRoot);
    input.frontier.set(rootIdentity.pid, ownedRoot);
    input.root.value = ownedRoot;
  }
  const maxProcesses = Math.max(1, input.maxProcesses ?? Number.POSITIVE_INFINITY);
  let remainingBudget = maxProcesses;
  const pending = [...input.frontier.entries()];
  const visited = new Set<number>();
  while (pending.length > 0 && remainingBudget > 0) {
    const entry = pending.shift();
    if (entry === undefined) continue;
    const [parentPid, parent] = entry;
    input.frontier.delete(parentPid);
    if (visited.has(parent.pid)) continue;
    visited.add(parent.pid);
    remainingBudget -= 1;
    const observedParent = input.controller.identity(parent.pid);
    if (!samePosixProcessIdentity(parent, observedParent)) {
      input.childQueues.delete(parent.pid);
      continue;
    }
    const refreshedParent = { ...parent, ...observedParent };
    input.ledger.set(processIdentityKey(refreshedParent), refreshedParent);
    input.frontier.set(refreshedParent.pid, refreshedParent);
    let queuedChildren = input.childQueues.get(refreshedParent.pid);
    if (queuedChildren === undefined) {
      if (remainingBudget === 0) continue;
      remainingBudget -= 1;
      queuedChildren = [...input.controller.childPidsOf(refreshedParent.pid)];
    }
    while (queuedChildren.length > 0 && remainingBudget > 0) {
      const childPid = queuedChildren.shift();
      if (childPid === undefined) continue;
      remainingBudget -= 1;
      const child = input.controller.identity(childPid);
      if (child === undefined) continue;
      if (child.ppid !== parent.pid) continue;
      let reservedPid = input.frontier.get(child.pid);
      if (reservedPid !== undefined && !samePosixProcessIdentity(reservedPid, child)) {
        input.frontier.delete(child.pid);
        for (const [key, owned] of input.ledger.entries()) {
          if (owned.pid === child.pid) input.ledger.delete(key);
        }
        reservedPid = undefined;
      }
      const childKey = processIdentityKey(child);
      const owned =
        reservedPid === undefined
          ? {
              ...child,
              parentExecutable: refreshedParent.executable,
              parentStartTime: refreshedParent.startTime,
            }
          : { ...reservedPid, ...child };
      input.ledger.set(childKey, owned);
      input.frontier.set(child.pid, owned);
    }
    if (queuedChildren.length === 0) input.childQueues.delete(refreshedParent.pid);
    else input.childQueues.set(refreshedParent.pid, queuedChildren);
  }
}

function observePosixOwnershipLedgerContinuously(input: {
  readonly childQueues: Map<number, Array<number>>;
  readonly controller: AcpPosixProcessTreeController;
  readonly frontier: Map<number, AcpOwnedPosixProcess>;
  readonly ledger: Map<string, AcpOwnedPosixProcess>;
  readonly root: AcpPosixOwnershipRoot;
  readonly rootPid: number;
}): Effect.Effect<never> {
  return Effect.forever(
    Effect.gen(function* () {
      const startedAt = yield* Clock.currentTimeMillis;
      yield* Effect.sync(() => observePosixOwnershipLedger({ ...input, maxProcesses: 64 })).pipe(
        Effect.exit,
      );
      const targetInterval = input.frontier.size <= 32 ? 25 : input.frontier.size <= 128 ? 50 : 100;
      const completedAt = yield* Clock.currentTimeMillis;
      yield* Effect.sleep(`${Math.max(5, targetInterval - (completedAt - startedAt))} millis`);
    }),
  ).pipe(withWallClock);
}

export function makePosixProcessTreeController(
  platform: NodeJS.Platform,
): AcpPosixProcessTreeController {
  if (platform === "linux") return makeLinuxProcessTreeController();
  throw new AcpProcessGroupTerminationError({
    detail: `Detached ACP descendant ownership is unsupported on ${platform}`,
  });
}

function samePosixProcessIdentity(
  expected: AcpPosixProcessIdentity,
  observed: AcpPosixProcessIdentity | undefined,
): boolean {
  return (
    observed !== undefined &&
    observed.pid === expected.pid &&
    observed.startTime === expected.startTime
  );
}

export interface AcpOwnedPosixProcess extends AcpPosixProcessIdentity {
  readonly parentExecutable: string | undefined;
  readonly parentStartTime: string;
}

function processIdentityKey(process: AcpPosixProcessIdentity): string {
  return `${process.pid}:${process.startTime}`;
}

function processDepth(
  process: AcpPosixProcessIdentity,
  ledgerByPid: ReadonlyMap<number, AcpOwnedPosixProcess>,
): number {
  let depth = 0;
  let current = process;
  const seen = new Set<number>();
  while (!seen.has(current.pid)) {
    seen.add(current.pid);
    const parent = ledgerByPid.get(current.ppid);
    if (parent === undefined) break;
    depth += 1;
    current = parent;
  }
  return depth;
}

export function capturePosixOwnershipLedger(input: {
  readonly controller: AcpPosixProcessTreeController;
  readonly ledger: Map<string, AcpOwnedPosixProcess>;
  readonly root?: AcpPosixOwnershipRoot;
  readonly rootPid: number;
  readonly table?: ReadonlyArray<AcpPosixProcessIdentity>;
}): ReadonlyArray<AcpPosixProcessIdentity> {
  let table: ReadonlyArray<AcpPosixProcessIdentity>;
  if (input.table === undefined) {
    try {
      table = input.controller.snapshot();
    } catch (cause) {
      throw new AcpProcessGroupTerminationError({
        cause,
        detail: `Failed to snapshot ACP process tree ${input.rootPid}`,
      });
    }
  } else {
    table = input.table;
  }
  const byPid = new Map(table.map((process) => [process.pid, process]));
  let rootIdentity: AcpPosixProcessIdentity | undefined =
    input.root?.value ??
    [...input.ledger.values()].find((process) => process.pid === input.rootPid);
  if (rootIdentity === undefined) {
    rootIdentity = byPid.get(input.rootPid);
    if (rootIdentity === undefined) {
      throw new AcpProcessGroupTerminationError({
        detail: `ACP process ${input.rootPid} exited before its ownership ledger was captured`,
      });
    }
    const ownedRoot = {
      ...rootIdentity,
      parentExecutable: byPid.get(rootIdentity.ppid)?.executable,
      parentStartTime: byPid.get(rootIdentity.ppid)?.startTime ?? "",
    };
    input.ledger.set(processIdentityKey(rootIdentity), ownedRoot);
    if (input.root !== undefined) input.root.value = ownedRoot;
  }
  // Expire stale identities to allow PID reuse; retain the root reservation for finalizer retries.
  for (const [key, owned] of input.ledger.entries()) {
    if (owned.pid === input.rootPid) continue;
    const live = byPid.get(owned.pid);
    if (live === undefined || !samePosixProcessIdentity(owned, live)) {
      input.ledger.delete(key);
    }
  }
  const children = new Map<number, Array<AcpPosixProcessIdentity>>();
  const retainedByPid = new Map(
    [...input.ledger.values()]
      .filter((owned) => samePosixProcessIdentity(owned, byPid.get(owned.pid)))
      .map((owned) => [owned.pid, owned]),
  );
  for (const process of table) {
    const siblings = children.get(process.ppid) ?? [];
    siblings.push(process);
    children.set(process.ppid, siblings);
  }
  const pending = [...input.ledger.values()].filter((owned) =>
    samePosixProcessIdentity(owned, byPid.get(owned.pid)),
  );
  const visited = new Set<number>();
  while (pending.length > 0) {
    const parent = pending.shift();
    if (parent === undefined || visited.has(parent.pid)) continue;
    visited.add(parent.pid);
    const observedParent = byPid.get(parent.pid);
    if (!samePosixProcessIdentity(parent, observedParent)) continue;
    const refreshedParent = { ...parent, ...observedParent };
    input.ledger.set(processIdentityKey(parent), refreshedParent);
    for (const process of children.get(refreshedParent.pid) ?? []) {
      const reservedPid = retainedByPid.get(process.pid);
      if (reservedPid !== undefined && !samePosixProcessIdentity(reservedPid, process)) continue;
      const owned =
        reservedPid === undefined
          ? {
              ...process,
              parentExecutable: refreshedParent.executable,
              parentStartTime: refreshedParent.startTime,
            }
          : { ...reservedPid, ...process };
      input.ledger.set(processIdentityKey(process), owned);
      retainedByPid.set(process.pid, owned);
      pending.push(owned);
    }
  }
  return table;
}

export function terminatePosixOwnedProcessTree(input: {
  readonly controller: AcpPosixProcessTreeController;
  readonly discoveryPasses?: number;
  readonly grace?: Duration.Input;
  readonly ledger?: Map<string, AcpOwnedPosixProcess>;
  readonly root?: AcpPosixOwnershipRoot;
  readonly rootPid: number;
}): Effect.Effect<void, AcpProcessGroupTerminationError> {
  // Parent-chain discovery misses early double-forks; only pre-exec cgroups guarantee ownership.
  const ledger = input.ledger ?? new Map<string, AcpOwnedPosixProcess>();

  const fail = (detail: string, cause?: unknown) =>
    new AcpProcessGroupTerminationError({ detail, ...(cause === undefined ? {} : { cause }) });
  const snapshot = () => {
    try {
      return input.controller.snapshot();
    } catch (cause) {
      throw fail(`Failed to snapshot ACP process tree ${input.rootPid}`, cause);
    }
  };
  const discover = (table: ReadonlyArray<AcpPosixProcessIdentity>) =>
    capturePosixOwnershipLedger({
      controller: input.controller,
      ledger,
      ...(input.root === undefined ? {} : { root: input.root }),
      rootPid: input.rootPid,
      table,
    });
  const signalPhase = (signal: NodeJS.Signals, includeRoot: boolean) => {
    const table = snapshot();
    discover(table);
    const byPid = new Map(table.map((entry) => [entry.pid, entry]));
    const current = input.controller.identity(process.pid);
    if (current === undefined) throw fail("Cannot identify the current T3 process group");
    const ledgerByPid = new Map(
      [...ledger.values()].map((process) => [process.pid, process] as const),
    );
    const pending = [...ledger.values()].filter(
      (candidate) =>
        (includeRoot || candidate.pid !== input.rootPid) &&
        samePosixProcessIdentity(candidate, byPid.get(candidate.pid)),
    );
    const retainedByPid = new Map(
      [...ledger.values()]
        .filter((owned) => samePosixProcessIdentity(owned, byPid.get(owned.pid)))
        .map((owned) => [owned.pid, owned]),
    );
    const signalled = new Set<number>();
    while (pending.length > 0) {
      pending.sort(
        (left, right) => processDepth(right, ledgerByPid) - processDepth(left, ledgerByPid),
      );
      const candidate = pending.shift();
      if (candidate === undefined || signalled.has(candidate.pid)) continue;
      const observed = input.controller.identity(candidate.pid);
      if (
        candidate.pid <= 1 ||
        candidate.pid === process.pid ||
        observed === undefined ||
        observed.pgid === current.pgid ||
        observed.sid === current.sid ||
        !samePosixProcessIdentity(candidate, observed)
      ) {
        continue;
      }
      for (const child of input.controller.childrenOf(candidate.pid)) {
        if (child.ppid !== candidate.pid) continue;
        const reservedPid = retainedByPid.get(child.pid);
        if (reservedPid !== undefined && !samePosixProcessIdentity(reservedPid, child)) continue;
        const owned =
          reservedPid === undefined
            ? {
                ...child,
                parentExecutable: observed.executable,
                parentStartTime: observed.startTime,
              }
            : { ...reservedPid, ...child };
        ledger.set(processIdentityKey(child), owned);
        ledgerByPid.set(child.pid, owned);
        retainedByPid.set(child.pid, owned);
        // Signal newly discovered children in this same pass (fork-during-kill).
        if (
          (includeRoot || child.pid !== input.rootPid) &&
          !signalled.has(child.pid) &&
          samePosixProcessIdentity(owned, input.controller.identity(child.pid))
        ) {
          pending.push(owned);
        }
      }
      try {
        // Node lacks pidfd_send_signal, so starttime checks still leave a read-to-kill race.
        input.controller.signalProcess(candidate.pid, signal);
        signalled.add(candidate.pid);
      } catch (cause) {
        if (samePosixProcessIdentity(candidate, input.controller.identity(candidate.pid))) {
          throw fail(`Failed to signal ACP process ${candidate.pid}`, cause);
        }
      }
    }
  };

  return Effect.gen(function* () {
    const passes = Math.max(2, Math.min(input.discoveryPasses ?? 4, 8));
    for (let pass = 0; pass < passes; pass += 1) {
      yield* Effect.try({
        try: () => signalPhase("SIGTERM", false),
        catch: (cause) => cause as AcpProcessGroupTerminationError,
      });
      yield* Effect.sleep("10 millis");
    }
    yield* Effect.try({
      try: () => signalPhase("SIGTERM", true),
      catch: (cause) => cause as AcpProcessGroupTerminationError,
    });
    const grace = input.grace ?? "1 second";
    if (grace !== 0) yield* Effect.sleep(grace);
    for (let pass = 0; pass < passes; pass += 1) {
      yield* Effect.try({
        try: () => signalPhase("SIGKILL", true),
        catch: (cause) => cause as AcpProcessGroupTerminationError,
      });
      yield* Effect.sleep("10 millis");
    }
    const finalTable = snapshot();
    discover(finalTable);
    const survivors = new Map(finalTable.map((entry) => [entry.pid, entry]));
    const residual = [...ledger.values()].filter((owned) => {
      const observed = survivors.get(owned.pid);
      if (!samePosixProcessIdentity(owned, observed) || observed === undefined) {
        return false;
      }
      return !posixProcessIsZombie(observed);
    });
    if (residual.length > 0) {
      return yield* fail(
        `ACP process tree ${input.rootPid} retained owned processes: ${residual.map((entry) => entry.pid).join(", ")}`,
      );
    }
  }).pipe(withWallClock);
}

function windowsTaskkillResultIsSuccess(exitCode: number, _output?: string): boolean {
  return exitCode === 0;
}

const terminateWindowsProcessTreeWithTaskkill = (
  pid: number,
): Effect.Effect<void, AcpProcessGroupTerminationError, ChildProcessSpawner.ChildProcessSpawner> =>
  Effect.scoped(
    Effect.gen(function* () {
      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
      const taskkill = yield* spawner.spawn(
        ChildProcess.make("taskkill", ["/PID", String(pid), "/T", "/F"]),
      );
      const outputFiber = yield* Stream.decodeText(taskkill.all).pipe(
        Stream.mkString,
        Effect.forkScoped,
      );
      const exitCode = Number(yield* taskkill.exitCode);
      const output = yield* Fiber.join(outputFiber);
      // A missing leader cannot prove that inherited descendants exited.
      if (windowsTaskkillResultIsSuccess(exitCode, output)) return;
      const trimmedOutput = output.trim();
      return yield* new AcpProcessGroupTerminationError({
        detail: `taskkill exited ${exitCode} for ACP process tree ${pid}`,
        pid,
        exitCode,
        ...(trimmedOutput.length === 0
          ? {}
          : { cause: trimmedOutput.length > 500 ? trimmedOutput.slice(0, 500) : trimmedOutput }),
      });
    }),
  ).pipe(
    Effect.mapError((cause) =>
      isAcpProcessGroupTerminationError(cause)
        ? cause
        : new AcpProcessGroupTerminationError({
            cause,
            detail: `Failed to run taskkill for ACP process tree ${pid}`,
            pid,
          }),
    ),
  );

export function selectAcpAgentAuthMethod(
  authMethods: ReadonlyArray<EffectAcpSchema.AuthMethod> | undefined,
  preferredMethodId?: string,
): EffectAcpSchema.AuthMethod | undefined {
  const preferred = preferredMethodId?.trim();
  if (preferred) {
    return authMethods?.find((method) => method.id === preferred);
  }
  return authMethods?.find((method) => method.type === undefined || method.type === "agent");
}

function isAcpAuthenticationRequired(error: EffectAcpErrors.AcpError): boolean {
  return error._tag === "AcpRequestError" && error.code === -32000;
}

export interface AcpSessionRuntimeStartResult {
  readonly sessionId: string;
  readonly initializeResult: EffectAcpSchema.InitializeResponse;
  readonly sessionSetupResult:
    | EffectAcpSchema.ForkSessionResponse
    | EffectAcpSchema.LoadSessionResponse
    | EffectAcpSchema.NewSessionResponse
    | EffectAcpSchema.ResumeSessionResponse;
  readonly modelConfigId: string | undefined;
}

export interface AcpSessionActivationOptions {
  readonly mcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
  readonly acpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
  readonly httpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
}

export class AcpSessionRuntime extends Context.Service<
  AcpSessionRuntime,
  {
    readonly handleRequestPermission: EffectAcpClient.AcpClient["Service"]["handleRequestPermission"];
    readonly handleElicitation: EffectAcpClient.AcpClient["Service"]["handleElicitation"];
    readonly handleMcpConnect: EffectAcpClient.AcpClient["Service"]["handleMcpConnect"];
    readonly handleMcpMessage: EffectAcpClient.AcpClient["Service"]["handleMcpMessage"];
    readonly handleMcpDisconnect: EffectAcpClient.AcpClient["Service"]["handleMcpDisconnect"];
    readonly handleMcpNotification: EffectAcpClient.AcpClient["Service"]["handleMcpNotification"];
    readonly handleReadTextFile: EffectAcpClient.AcpClient["Service"]["handleReadTextFile"];
    readonly handleWriteTextFile: EffectAcpClient.AcpClient["Service"]["handleWriteTextFile"];
    readonly handleCreateTerminal: EffectAcpClient.AcpClient["Service"]["handleCreateTerminal"];
    readonly handleTerminalOutput: EffectAcpClient.AcpClient["Service"]["handleTerminalOutput"];
    readonly handleTerminalWaitForExit: EffectAcpClient.AcpClient["Service"]["handleTerminalWaitForExit"];
    readonly handleTerminalKill: EffectAcpClient.AcpClient["Service"]["handleTerminalKill"];
    readonly handleTerminalRelease: EffectAcpClient.AcpClient["Service"]["handleTerminalRelease"];
    readonly handleSessionUpdate: EffectAcpClient.AcpClient["Service"]["handleSessionUpdate"];
    readonly handleElicitationComplete: EffectAcpClient.AcpClient["Service"]["handleElicitationComplete"];
    readonly handleUnknownExtRequest: EffectAcpClient.AcpClient["Service"]["handleUnknownExtRequest"];
    readonly handleUnknownExtNotification: EffectAcpClient.AcpClient["Service"]["handleUnknownExtNotification"];
    readonly handleExtRequest: EffectAcpClient.AcpClient["Service"]["handleExtRequest"];
    readonly handleExtNotification: EffectAcpClient.AcpClient["Service"]["handleExtNotification"];
    /** Reads capabilities without authentication, session creation, or MCP startup. */
    readonly initialize: () => Effect.Effect<
      EffectAcpSchema.InitializeResponse,
      EffectAcpErrors.AcpError
    >;
    readonly authenticate?: (methodId: string) => Effect.Effect<void, EffectAcpErrors.AcpError>;
    readonly start: () => Effect.Effect<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
    readonly getEvents: () => Stream.Stream<AcpSessionRuntimeEvent, never>;
    readonly drainEvents: Effect.Effect<void>;
    readonly getModeState: Effect.Effect<AcpSessionModeState | undefined>;
    readonly getConfigOptions: Effect.Effect<ReadonlyArray<EffectAcpSchema.SessionConfigOption>>;
    /** The current configuration options, then each later change. */
    readonly configOptionChanges: Stream.Stream<ReadonlyArray<EffectAcpSchema.SessionConfigOption>>;
    readonly loadSession: (
      sessionId: string,
      options?: AcpSessionActivationOptions,
    ) => Effect.Effect<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
    readonly resumeSession: (
      sessionId: string,
      options?: AcpSessionActivationOptions,
    ) => Effect.Effect<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
    readonly forkSession: (
      sessionId: string,
      options?: AcpSessionActivationOptions,
      meta?: NonNullable<EffectAcpSchema.ForkSessionRequest["_meta"]>,
    ) => Effect.Effect<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
    readonly listSessions: (
      cursor?: string,
    ) => Effect.Effect<EffectAcpSchema.ListSessionsResponse, EffectAcpErrors.AcpError>;
    readonly closeSession: (
      sessionId?: string,
    ) => Effect.Effect<EffectAcpSchema.CloseSessionResponse, EffectAcpErrors.AcpError>;
    readonly deleteSession: (
      sessionId: string,
    ) => Effect.Effect<EffectAcpSchema.DeleteSessionResponse, EffectAcpErrors.AcpError>;
    readonly listProviders: Effect.Effect<
      EffectAcpSchema.ListProvidersResponse,
      EffectAcpErrors.AcpError
    >;
    readonly setProvider: (
      provider: EffectAcpSchema.SetProviderRequest,
    ) => Effect.Effect<EffectAcpSchema.SetProviderResponse, EffectAcpErrors.AcpError>;
    readonly disableProvider: (
      providerId: string,
    ) => Effect.Effect<EffectAcpSchema.DisableProviderResponse, EffectAcpErrors.AcpError>;
    readonly logout: Effect.Effect<EffectAcpSchema.LogoutResponse, EffectAcpErrors.AcpError>;
    /** options.dispatched settles when cancel can target this prompt. */
    readonly prompt: (
      payload: Omit<EffectAcpSchema.PromptRequest, "sessionId">,
      options?: { readonly dispatched?: Deferred.Deferred<void> },
    ) => Effect.Effect<EffectAcpSchema.PromptResponse, EffectAcpErrors.AcpError>;
    readonly cancel: Effect.Effect<void, EffectAcpErrors.AcpError>;
    readonly terminateProcessGroup?: Effect.Effect<void, AcpProcessGroupTerminationError>;
    readonly setMode: (
      modeId: string,
    ) => Effect.Effect<EffectAcpSchema.SetSessionModeResponse, EffectAcpErrors.AcpError>;
    readonly setSessionModel: (
      modelId: string,
      meta?: EffectAcpSchema.SetSessionModelRequest["_meta"],
    ) => Effect.Effect<EffectAcpSchema.SetSessionModelResponse, EffectAcpErrors.AcpError>;
    /**
     * Writes a session configuration option. A select value the option does
     * not list is refused unless `allowUnlistedValue` is set, for agents that
     * take any value and judge it themselves (a custom model id the agent
     * does not list).
     */
    readonly setConfigOption: (
      configId: string,
      value: string | boolean,
      options?: { readonly allowUnlistedValue?: boolean },
    ) => Effect.Effect<EffectAcpSchema.SetSessionConfigOptionResponse, EffectAcpErrors.AcpError>;
    readonly setModel: (model: string) => Effect.Effect<void, EffectAcpErrors.AcpError>;
    readonly request: (
      method: string,
      payload: unknown,
    ) => Effect.Effect<unknown, EffectAcpErrors.AcpError>;
    readonly notify: (
      method: string,
      payload: unknown,
    ) => Effect.Effect<void, EffectAcpErrors.AcpError>;
  }
>()("@t3tools/provider-acp/server/AcpSessionRuntime") {}

interface AcpStartedState extends AcpSessionRuntimeStartResult {}

type AcpStartState =
  | { readonly _tag: "NotStarted" }
  | {
      readonly _tag: "Starting";
      readonly deferred: Deferred.Deferred<AcpSessionRuntimeStartResult, EffectAcpErrors.AcpError>;
    }
  | { readonly _tag: "Started"; readonly result: AcpStartedState };

type AcpInitializeState =
  | { readonly _tag: "NotStarted" }
  | {
      readonly _tag: "Starting";
      readonly deferred: Deferred.Deferred<
        EffectAcpSchema.InitializeResponse,
        EffectAcpErrors.AcpError
      >;
    }
  | { readonly _tag: "Started"; readonly result: EffectAcpSchema.InitializeResponse };

interface AcpAssistantSegmentState {
  readonly nextSegmentIndex: number;
  readonly activeItemId?: string;
}

interface EnsureActiveAssistantSegmentResult {
  readonly itemId: string;
  readonly startedEvent?: Extract<AcpParsedSessionEvent, { readonly _tag: "AssistantItemStarted" }>;
}

interface AcpActivePrompt {
  readonly fiber: Fiber.Fiber<EffectAcpSchema.PromptResponse, EffectAcpErrors.AcpError>;
  readonly completed: Deferred.Deferred<void>;
}

export const make = Effect.fn("AcpSessionRuntime.make")(function* (
  options: AcpSessionRuntimeOptions,
): Effect.fn.Return<
  AcpSessionRuntime["Service"],
  EffectAcpErrors.AcpError,
  ChildProcessSpawner.ChildProcessSpawner | SecureRandom.SecureRandom | Scope.Scope
> {
  const random = yield* SecureRandom.SecureRandom;
  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
  const runtimeScope = yield* Scope.fork(yield* Scope.Scope);
  const eventQueue = yield* Queue.unbounded<AcpSessionRuntimeEvent>();
  const modeStateRef = yield* Ref.make<AcpSessionModeState | undefined>(undefined);
  const toolCallsRef = yield* Ref.make(new Map<string, AcpToolCallTrackedState>());
  const shownToolCallIds = new Set<string>();
  const assistantItemRuntimeId = yield* random.uuidV4().pipe(
    Effect.mapError(
      (cause) =>
        new EffectAcpErrors.AcpTransportError({
          detail: "Failed to generate an ACP assistant item runtime identifier.",
          cause,
        }),
    ),
  );
  const assistantSegmentRef = yield* Ref.make<AcpAssistantSegmentState>({ nextSegmentIndex: 0 });
  const configOptionsRef = yield* SubscriptionRef.make(sessionConfigOptionsFromSetup(undefined));
  const initializeStateRef = yield* Ref.make<AcpInitializeState>({ _tag: "NotStarted" });
  const startStateRef = yield* Ref.make<AcpStartState>({ _tag: "NotStarted" });
  const startupMetadataRef = yield* Ref.make<ReadonlyArray<EffectAcpSchema.SessionNotification>>(
    [],
  );
  const notificationSemaphore = yield* Semaphore.make(1);
  const terminationErrorRef = yield* Ref.make<Option.Option<EffectAcpErrors.AcpError>>(
    Option.none(),
  );
  const stoppingRef = yield* Ref.make(false);
  const stderrFailure = yield* Deferred.make<never, EffectAcpErrors.AcpError>();
  const stderrTailRef = yield* Ref.make("");
  const homeDirectory = yield* HostProcess.HomeDirectory;
  const stderrDrained = yield* Deferred.make<void>();
  const runtimeClosed = yield* Deferred.make<void>();
  const promptSerializationSemaphore = yield* Semaphore.make(1);
  const sessionLoadSemaphore = yield* Semaphore.make(1);
  const promptDispatchSemaphore = yield* Semaphore.make(1);
  const activePromptRef = yield* Ref.make<Option.Option<AcpActivePrompt>>(Option.none());
  const assistantUpdatesOpenRef = yield* Ref.make(true);
  const sessionLoadGateRef = yield* Ref.make<Option.Option<SessionLoadGate>>(Option.none());

  const ensureConnected = Effect.gen(function* () {
    const error = yield* Ref.get(terminationErrorRef);
    if (Option.isSome(error)) {
      return yield* error.value;
    }
    if (yield* Ref.get(stoppingRef)) {
      return yield* new EffectAcpErrors.AcpTransportError({
        detail: "The ACP session runtime is closed.",
        cause: undefined,
      });
    }
  });

  const enrichProcessExitWithStderr = (
    error: EffectAcpErrors.AcpError,
  ): Effect.Effect<EffectAcpErrors.AcpError> =>
    error._tag !== "AcpProcessExitedError" || (error.stderr?.trim().length ?? 0) > 0
      ? Effect.succeed(error)
      : Deferred.await(stderrDrained).pipe(
          Effect.timeout("250 millis"),
          Effect.ignore,
          Effect.andThen(Ref.get(stderrTailRef)),
          Effect.map((tail) => {
            const stderr = sanitizeAcpStderrExcerpt(tail, homeDirectory);
            return stderr.length === 0
              ? error
              : new EffectAcpErrors.AcpProcessExitedError({
                  ...(error.code !== undefined ? { code: error.code } : {}),
                  ...(error.signal !== undefined ? { signal: error.signal } : {}),
                  ...(error.pid !== undefined ? { pid: error.pid } : {}),
                  stderr,
                  ...(error.cause !== undefined ? { cause: error.cause } : {}),
                });
          }),
        );

  const recordTermination = Effect.fn("AcpSessionRuntime.recordTermination")(function* (
    error: EffectAcpErrors.AcpError,
  ) {
    if (yield* Ref.get(stoppingRef)) {
      return;
    }
    const enriched = yield* enrichProcessExitWithStderr(error);
    const firstTermination = yield* Ref.modify(terminationErrorRef, (current) =>
      Option.isSome(current)
        ? ([false, current] as const)
        : ([true, Option.some(enriched)] as const),
    );
    if (!firstTermination) {
      return;
    }
    yield* closeActiveAssistantSegment({ queue: eventQueue, assistantSegmentRef });
    yield* Queue.offer(eventQueue, { _tag: "ConnectionTerminated", error: enriched });
  });

  const logRequest = (event: AcpSessionRequestLogEvent) =>
    options.requestLogger ? options.requestLogger(event) : Effect.void;

  const runLoggedRequest = <A>(
    method: string,
    payload: unknown,
    effect: Effect.Effect<A, EffectAcpErrors.AcpError>,
  ): Effect.Effect<A, EffectAcpErrors.AcpError> =>
    logRequest({ method, payload, status: "started" }).pipe(
      Effect.flatMap(() =>
        (options.onStderr ? Effect.raceFirst(effect, Deferred.await(stderrFailure)) : effect).pipe(
          Effect.catch((error) =>
            enrichProcessExitWithStderr(error).pipe(Effect.flatMap(Effect.fail)),
          ),
          Effect.tap((result) =>
            logRequest({
              method,
              payload,
              status: "succeeded",
              result,
            }),
          ),
          Effect.onError((cause) =>
            logRequest({
              method,
              payload,
              status: "failed",
              cause,
            }),
          ),
        ),
      ),
    );

  const spawnCommand =
    options.spawn.shell === false
      ? { command: options.spawn.command, args: options.spawn.args, shell: false }
      : yield* resolveSpawnCommand(options.spawn.command, options.spawn.args, {
          ...(options.spawn.env ? { env: options.spawn.env } : {}),
          extendEnv: options.spawn.extendEnv ?? true,
        });
  const linuxCgroupLease =
    options.ownDescendantProcessGroups === true && options.processGroupPlatform === "linux"
      ? yield* Effect.sync(() => {
          try {
            if (options.linuxCgroupController === null) return undefined;
            return (options.linuxCgroupController ?? makeLinuxCgroupController()).create();
          } catch {
            return undefined;
          }
        })
      : undefined;
  // This is lifecycle containment for inherited provider work. It is not a
  // security boundary against a provider that can modify its delegated cgroup.
  if (linuxCgroupLease !== undefined) {
    yield* Scope.addFinalizer(
      runtimeScope,
      Effect.uninterruptible(terminateLinuxCgroupLease(linuxCgroupLease)).pipe(
        Effect.ignoreCause({ log: true }),
      ),
    );
  }
  const containedTargetCommand =
    linuxCgroupLease === undefined || NodePath.isAbsolute(spawnCommand.command)
      ? spawnCommand.command
      : yield* Effect.gen(function* () {
          const resolved = resolveLinuxCgroupTargetCommand(
            spawnCommand.command,
            options.spawn.cwd ?? options.cwd,
            { ...process.env, ...options.spawn.env },
          );
          if (resolved !== undefined) return resolved;
          return yield* new EffectAcpErrors.AcpSpawnError({
            command: options.spawn.command,
            cause: new Error("Contained ACP command was not found on PATH"),
          });
        });
  const agentScope = yield* AgentScope;
  const scopedLaunch =
    linuxCgroupLease !== undefined || spawnCommand.shell
      ? undefined
      : yield* agentScope.wrap({
          command: spawnCommand.command,
          args: spawnCommand.args,
          name: "acp",
          threadId: yield* AgentScopeThreadId,
          env: { ...process.env, ...options.spawn.env },
        });
  const scopedSpawnCommand =
    scopedLaunch === undefined ? spawnCommand : { ...scopedLaunch, shell: false };
  // Finalizers run in reverse order: reap detached work after terminating the agent.
  const scopeUnit = scopedLaunch?.unit;
  const stopScope =
    scopeUnit === undefined ? Effect.void : yield* Effect.cached(agentScope.stop(scopeUnit));
  yield* Scope.addFinalizer(runtimeScope, stopScope);
  const containedSpawnCommand =
    linuxCgroupLease === undefined
      ? scopedSpawnCommand
      : {
          ...wrapCommandForLinuxCgroup(linuxCgroupLease, containedTargetCommand, spawnCommand.args),
          shell: false,
        };
  const spawnEnvironment =
    linuxCgroupLease === undefined
      ? options.spawn.env
      : {
          ...options.spawn.env,
          ELECTRON_RUN_AS_NODE: "1",
          T3_ACP_CGROUP_WRAPPER: "1",
        };
  const child = yield* spawner
    .spawn(
      ChildProcess.make(containedSpawnCommand.command, containedSpawnCommand.args, {
        ...(options.spawn.cwd ? { cwd: options.spawn.cwd } : {}),
        ...(spawnEnvironment ? { env: spawnEnvironment } : {}),
        extendEnv: options.spawn.extendEnv ?? true,
        ...(options.ownDetachedProcessGroup === undefined
          ? {}
          : { detached: options.ownDetachedProcessGroup }),
        shell: containedSpawnCommand.shell,
      }),
    )
    .pipe(
      Effect.provideService(Scope.Scope, runtimeScope),
      Effect.mapError(
        (cause) =>
          new EffectAcpErrors.AcpSpawnError({
            command: options.spawn.command,
            cause,
          }),
      ),
    );

  // Detached children can keep stdout open, delaying protocol termination.
  if (scopeUnit !== undefined) {
    yield* child.exitCode.pipe(
      Effect.matchEffect({ onFailure: () => stopScope, onSuccess: () => stopScope }),
      Effect.forkIn(runtimeScope),
    );
  }

  const posixOwnershipLedger = new Map<string, AcpOwnedPosixProcess>();
  const posixOwnershipFrontier = new Map<number, AcpOwnedPosixProcess>();
  const posixOwnershipChildQueues = new Map<number, Array<number>>();
  const posixOwnershipRoot: AcpPosixOwnershipRoot = { value: undefined };
  const posixController =
    options.ownDescendantProcessGroups === true
      ? yield* Effect.try({
          try: () => {
            if (options.posixProcessTreeController !== undefined) {
              return options.posixProcessTreeController;
            }
            if (options.processGroupPlatform === undefined) {
              throw new AcpProcessGroupTerminationError({
                detail: "POSIX ACP descendant ownership requires a supported host platform",
              });
            }
            return makePosixProcessTreeController(options.processGroupPlatform);
          },
          catch: (cause) =>
            new EffectAcpErrors.AcpSpawnError({ command: options.spawn.command, cause }),
        })
      : undefined;
  if (posixController !== undefined) {
    const observeOwnership = () =>
      observePosixOwnershipLedger({
        childQueues: posixOwnershipChildQueues,
        controller: posixController,
        frontier: posixOwnershipFrontier,
        ledger: posixOwnershipLedger,
        root: posixOwnershipRoot,
        rootPid: Number(child.pid),
      });
    yield* Effect.try({
      try: observeOwnership,
      catch: (cause) =>
        new EffectAcpErrors.AcpSpawnError({ command: options.spawn.command, cause }),
    });
    // Cgroup teardown needs only the root identity captured above.
    if (linuxCgroupLease === undefined) {
      yield* observePosixOwnershipLedgerContinuously({
        childQueues: posixOwnershipChildQueues,
        controller: posixController,
        frontier: posixOwnershipFrontier,
        ledger: posixOwnershipLedger,
        root: posixOwnershipRoot,
        rootPid: Number(child.pid),
      }).pipe(Effect.forkIn(runtimeScope));
    }
  }

  const signalOwnedProcessGroup = (signal: NodeJS.Signals) =>
    Effect.try({
      try: () => {
        signalProcessGroup(Number(child.pid), signal);
        return true;
      },
      catch: (cause) =>
        new AcpProcessGroupTerminationError({
          cause,
          detail: `Failed to signal ACP process group ${child.pid} with ${signal}`,
        }),
    }).pipe(
      Effect.catch((error) => {
        const cause = error.cause as NodeJS.ErrnoException | undefined;
        return cause?.code === "ESRCH" ? Effect.succeed(false) : Effect.fail(error);
      }),
    );
  const terminateWindowsProcessTree =
    options.windowsProcessTreeTerminator ??
    ((pid: number) =>
      terminateWindowsProcessTreeWithTaskkill(pid).pipe(
        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
      ));
  const terminatePosixProcessTree = Effect.fn("AcpSessionRuntime.terminatePosixProcessTree")(
    function* (grace: Duration.Input, platformOverride?: NodeJS.Platform) {
      const platform = platformOverride ?? options.processGroupPlatform;
      if (platform === undefined || platform === "win32") {
        return yield* new AcpProcessGroupTerminationError({
          detail: "POSIX ACP descendant ownership requires a supported host platform",
        });
      }
      const controller = yield* Effect.try({
        try: () => posixController ?? makePosixProcessTreeController(platform),
        catch: (cause) =>
          isAcpProcessGroupTerminationError(cause)
            ? cause
            : new AcpProcessGroupTerminationError({
                cause,
                detail: `Failed to initialize ACP descendant ownership on ${platform}`,
              }),
      });
      yield* terminatePosixOwnedProcessTree({
        controller,
        grace,
        ledger: posixOwnershipLedger,
        root: posixOwnershipRoot,
        rootPid: Number(child.pid),
      });
    },
  );
  const terminateOwnedProcessGroupImpl = Effect.gen(function* () {
    if (options.ownDetachedProcessGroup !== true) return;
    if (options.processGroupPlatform === undefined) {
      return yield* new AcpProcessGroupTerminationError({
        detail: "Detached ACP process-group ownership requires a host platform",
      });
    }
    if (options.processGroupPlatform === "win32") {
      return yield* terminateWindowsProcessTree(Number(child.pid));
    }
    if (linuxCgroupLease !== undefined) {
      if (posixController !== undefined) {
        yield* Effect.sync(() =>
          signalLinuxCgroupRootTerm({
            controller: posixController,
            lease: linuxCgroupLease,
            root: posixOwnershipRoot,
          }),
        );
      }
      const grace = options.processGroupTerminationGrace ?? "1 second";
      if (grace !== 0) yield* Effect.sleep(grace);
      return yield* terminateLinuxCgroupLease(linuxCgroupLease);
    }
    if (options.ownDescendantProcessGroups === true) {
      return yield* terminatePosixProcessTree(options.processGroupTerminationGrace ?? "1 second");
    }
    const groupExisted = yield* signalOwnedProcessGroup("SIGTERM");
    if (!groupExisted) return;
    const grace = options.processGroupTerminationGrace ?? "1 second";
    if (grace !== 0) {
      yield* Effect.sleep(grace);
    }
    yield* signalOwnedProcessGroup("SIGKILL");
  }).pipe(withWallClock);
  const terminateProcessGroup = yield* Effect.cached(
    Effect.uninterruptible(terminateOwnedProcessGroupImpl),
  );
  if (options.ownDetachedProcessGroup === true) {
    const hostPlatform = yield* HostProcess.Platform;
    const forceTerminateOwnedProcessGroup =
      hostPlatform === "win32"
        ? terminateWindowsProcessTreeWithTaskkill(Number(child.pid)).pipe(
            Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
          )
        : linuxCgroupLease !== undefined
          ? terminateLinuxCgroupLease(linuxCgroupLease)
          : options.ownDescendantProcessGroups === true
            ? terminatePosixProcessTree(0, hostPlatform)
            : signalOwnedProcessGroup("SIGKILL").pipe(Effect.asVoid);
    yield* Scope.addFinalizer(
      runtimeScope,
      Effect.uninterruptible(forceTerminateOwnedProcessGroup).pipe(
        Effect.ignoreCause({ log: true }),
      ),
    );
  }
  yield* child.stderr.pipe(
    Stream.decodeText(),
    Stream.runForEach((chunk) =>
      Ref.update(stderrTailRef, (current) => appendAcpStderrTail(current, chunk)).pipe(
        Effect.andThen(
          options.onStderr ? options.onStderr(chunk.slice(-maxStderrChunkLength)) : Effect.void,
        ),
        Effect.catch((error) =>
          Effect.gen(function* () {
            yield* Deferred.fail(stderrFailure, error);
            yield* recordTermination(error);
            yield* child.kill({ forceKillAfter: "1 second" }).pipe(Effect.ignore);
          }),
        ),
      ),
    ),
    Effect.ensuring(Deferred.succeed(stderrDrained, undefined)),
    Effect.ignore,
    Effect.forkIn(runtimeScope),
  );

  const acpContext = yield* Layer.build(
    EffectAcpClient.layerChildProcess(child, {