// @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, {