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

import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as EffectAcpErrors from "effect-acp/errors";
import type * as EffectAcpSchema from "effect-acp/compat";
import * as NodeBuffer from "node:buffer";

const MAX_LIVE_TERMINALS = 16;
const MAX_UNRELEASED_TERMINALS = 64;
const MAX_RETAINED_TERMINALS = 32;
const MAX_RETAINED_OUTPUT_BYTES = 16 * 1024 * 1024;
const DEFAULT_OUTPUT_BYTE_LIMIT = 4 * 1024 * 1024;
const MAX_OUTPUT_BYTE_LIMIT = 8 * 1024 * 1024;

const terminalRequestError = (message: string, cause?: unknown) =>
  EffectAcpErrors.AcpRequestError.internalError(
    message,
    undefined,
    cause === undefined ? {} : { cause },
  );

interface OutputBufferState {
  chunks: Array<Uint8Array>;
  bytes: number;
  truncated: boolean;
  readonly limit: number;
}

function trimOutputStart(state: OutputBufferState, bytes: number): void {
  let remaining = Math.min(bytes, state.bytes);
  while (remaining > 0) {
    const head = state.chunks[0]!;
    if (head.byteLength <= remaining) {
      state.chunks.shift();
      state.bytes -= head.byteLength;
      remaining -= head.byteLength;
    } else {
      state.chunks[0] = head.subarray(remaining);
      state.bytes -= remaining;
      remaining = 0;
    }
    state.truncated = true;
  }
}

function appendOutput(state: OutputBufferState, chunk: Uint8Array): void {
  state.chunks.push(chunk);
  state.bytes += chunk.byteLength;
  // The spec requires truncation from the beginning of the output.
  if (state.bytes > state.limit) trimOutputStart(state, state.bytes - state.limit);
}

function readOutput(state: OutputBufferState): string {
  let combined: Uint8Array = NodeBuffer.Buffer.concat(state.chunks, state.bytes);
  if (state.truncated) {
    // The spec requires truncation at a UTF-8 character boundary.
    let start = 0;
    while (start < combined.byteLength && (combined[start]! & 0b1100_0000) === 0b1000_0000) {
      start += 1;
    }
    combined = combined.subarray(start);
  }
  return NodeBuffer.Buffer.from(combined).toString("utf8");
}

function terminalExitSignal(error: unknown): string | null {
  const cause = error instanceof Error ? error.cause : undefined;
  const message =
    cause instanceof Error ? cause.message : error instanceof Error ? error.message : "";
  return message.match(/signal: '([^']+)'/u)?.[1] ?? null;
}

export interface AcpTerminalOutputSnapshot {
  readonly output: string;
  readonly truncated: boolean;
  readonly exitStatus: EffectAcpSchema.TerminalExitStatus | undefined;
}

interface ManagedAcpTerminal {
  readonly terminalId: string;
  readonly sessionId: string;
  readonly commandLine: string;
  readonly buffer: OutputBufferState;
  readonly exit: Deferred.Deferred<EffectAcpSchema.WaitForTerminalExitResponse>;
  readonly kill: Effect.Effect<void>;
  readonly dispose: Effect.Effect<void>;
  exitStatus: EffectAcpSchema.TerminalExitStatus | undefined;
  released: boolean;
}

export interface AcpClientTerminals {
  readonly create: (
    request: EffectAcpSchema.CreateTerminalRequest,
  ) => Effect.Effect<EffectAcpSchema.CreateTerminalResponse, EffectAcpErrors.AcpRequestError>;
  readonly output: (
    request: EffectAcpSchema.TerminalOutputRequest,
  ) => Effect.Effect<EffectAcpSchema.TerminalOutputResponse, EffectAcpErrors.AcpRequestError>;
  readonly waitForExit: (
    request: EffectAcpSchema.WaitForTerminalExitRequest,
  ) => Effect.Effect<EffectAcpSchema.WaitForTerminalExitResponse, EffectAcpErrors.AcpRequestError>;
  readonly kill: (
    request: EffectAcpSchema.KillTerminalRequest,
  ) => Effect.Effect<EffectAcpSchema.KillTerminalResponse, EffectAcpErrors.AcpRequestError>;
  readonly release: (
    request: EffectAcpSchema.ReleaseTerminalRequest,
  ) => Effect.Effect<EffectAcpSchema.ReleaseTerminalResponse, EffectAcpErrors.AcpRequestError>;
  /** Buffered output for embedded tool-call content; survives release. */
  readonly readOutputSnapshot: (
    sessionId: string,
    terminalId: string,
  ) => AcpTerminalOutputSnapshot | undefined;
  readonly readCommandLine: (terminalId: string) => string | undefined;
  readonly disposeAll: Effect.Effect<void>;
}

export interface AcpClientTerminalsOptions {
  /** Devin sends shell source in command, rather than an executable plus args. */
  readonly shellCommands?: boolean | undefined;
  readonly defaultCwd: string;
  readonly environment?: NodeJS.ProcessEnv | undefined;
  readonly environmentForSession?:
    | ((sessionId: string) => NodeJS.ProcessEnv | undefined)
    | undefined;
  readonly forceKillAfter?: Duration.Input | undefined;
}

function acpTerminalCommand(input: {
  readonly request: EffectAcpSchema.CreateTerminalRequest;
  readonly shellCommands?: boolean | undefined;
  readonly defaultCwd: string;
  readonly environment?: NodeJS.ProcessEnv | undefined;
  readonly forceKillAfter: Duration.Input;
}) {
  return ChildProcess.make(input.request.command, input.request.args ?? [], {
    cwd: input.request.cwd ?? input.defaultCwd,
    ...(input.environment === undefined ? {} : { env: input.environment }),
    shell: input.shellCommands === true && (input.request.args?.length ?? 0) === 0,
    forceKillAfter: input.forceKillAfter,
  });
}

export const makeAcpClientTerminals = Effect.fn("makeAcpClientTerminals")(function* (
  options: AcpClientTerminalsOptions,
): Effect.fn.Return<AcpClientTerminals, never, ChildProcessSpawner.ChildProcessSpawner> {
  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
  const forceKillAfter = options.forceKillAfter ?? "5 seconds";
  const creationPermit = yield* Semaphore.make(1);
  const terminals = new Map<string, ManagedAcpTerminal>();
  let nextTerminalNumber = 1;

  const enforceTotalOutputLimit = (): void => {
    let excess =
      Array.from(terminals.values()).reduce((total, terminal) => total + terminal.buffer.bytes, 0) -
      MAX_RETAINED_OUTPUT_BYTES;
    if (excess <= 0) return;
    for (const terminal of terminals.values()) {
      const before = terminal.buffer.bytes;
      trimOutputStart(terminal.buffer, excess);
      excess -= before - terminal.buffer.bytes;
      if (excess <= 0) return;
    }
  };

  const pruneReleasedSnapshots = (): void => {
    const released = Array.from(terminals.values()).filter((terminal) => terminal.released);
    let retainedBytes = released.reduce((total, terminal) => total + terminal.buffer.bytes, 0);
    while (released.length > MAX_RETAINED_TERMINALS || retainedBytes > MAX_RETAINED_OUTPUT_BYTES) {
      const terminal = released.shift();
      if (terminal === undefined) break;
      retainedBytes -= terminal.buffer.bytes;
      terminals.delete(terminal.terminalId);
    }
  };

  const requireTerminal = (
    sessionId: string,
    terminalId: string,
    operation: string,
  ): Effect.Effect<ManagedAcpTerminal, EffectAcpErrors.AcpRequestError> => {
    const terminal = terminals.get(terminalId);
    if (terminal === undefined || terminal.sessionId !== sessionId || terminal.released) {
      return Effect.fail(
        terminalRequestError(`ACP ${operation} received an unknown terminal ID '${terminalId}'.`),
      );
    }
    return Effect.succeed(terminal);
  };

  const create: AcpClientTerminals["create"] = (request) =>
    creationPermit.withPermit(
      Effect.uninterruptibleMask((restore) =>
        Effect.gen(function* () {
          const liveCount = Array.from(terminals.values()).filter(
            (terminal) => !terminal.released && terminal.exitStatus === undefined,
          ).length;
          const unreleasedCount = Array.from(terminals.values()).filter(
            (terminal) => !terminal.released,
          ).length;
          if (unreleasedCount >= MAX_UNRELEASED_TERMINALS) {
            return yield* terminalRequestError(
              `ACP terminal/create exceeded the limit of ${MAX_UNRELEASED_TERMINALS} unreleased terminals.`,
            );
          }
          if (liveCount >= MAX_LIVE_TERMINALS) {
            return yield* terminalRequestError(
              `ACP terminal/create exceeded the limit of ${MAX_LIVE_TERMINALS} concurrent terminals.`,
            );
          }
          const requestEnvironment = Object.fromEntries(
            (request.env ?? []).map((variable) => [variable.name, variable.value] as const),
          );
          const sessionEnvironment = options.environmentForSession?.(request.sessionId);
          const environment =
            options.environment === undefined &&
            sessionEnvironment === undefined &&
            (request.env?.length ?? 0) === 0
              ? undefined
              : { ...options.environment, ...sessionEnvironment, ...requestEnvironment };
          const terminalScope = yield* Scope.make();
          const child = yield* restore(
            spawner
              .spawn(
                acpTerminalCommand({
                  request,
                  shellCommands: options.shellCommands,
                  defaultCwd: options.defaultCwd,
                  environment,
                  forceKillAfter,
                }),
              )
              .pipe(
                Effect.provideService(Scope.Scope, terminalScope),
                Effect.mapError((cause) =>
                  terminalRequestError(
                    `Could not start terminal command '${request.command}'.`,
                    cause,
                  ),
                ),
              ),
          ).pipe(
            Effect.onExit((exit) =>
              Exit.isFailure(exit) ? Scope.close(terminalScope, Exit.void) : Effect.void,
            ),
          );

          const terminalId = `t3-term-${nextTerminalNumber}`;
          nextTerminalNumber += 1;
          const record: ManagedAcpTerminal = {
            terminalId,
            sessionId: request.sessionId,
            commandLine: [request.command, ...(request.args ?? [])].join(" "),
            buffer: {
              chunks: [],
              bytes: 0,
              truncated: false,
              limit: Math.min(
                request.outputByteLimit ?? DEFAULT_OUTPUT_BYTE_LIMIT,
                MAX_OUTPUT_BYTE_LIMIT,
              ),
            },
            exit: yield* Deferred.make<EffectAcpSchema.WaitForTerminalExitResponse>(),
            // The spawner only applies the command's forceKillAfter on scope close;
            // an explicit kill must pass it or a SIGTERM-ignoring command never exits.
            kill: child.kill({ forceKillAfter }).pipe(Effect.ignore),
            dispose: Scope.close(terminalScope, Exit.void).pipe(Effect.ignore),
            exitStatus: undefined,
            released: false,
          };
          terminals.set(terminalId, record);

          const pump = (stream: typeof child.stdout) =>
            stream.pipe(
              Stream.runForEach((chunk) =>
                Effect.sync(() => {
                  appendOutput(record.buffer, chunk);
                  enforceTotalOutputLimit();
                }),
              ),
              Effect.ignore,
            );
          const stdoutPump = yield* Effect.forkDetach(pump(child.stdout));
          const stderrPump = yield* Effect.forkDetach(pump(child.stderr));
          yield* Effect.forkDetach(
            child.exitCode.pipe(
              Effect.match({
                onFailure: (error) => ({ exitCode: null, signal: terminalExitSignal(error) }),
                onSuccess: (code) => ({ exitCode: Number(code), signal: null }),
              }),
              Effect.flatMap((status) =>
                Effect.all([Fiber.join(stdoutPump), Fiber.join(stderrPump)], {
                  discard: true,
                }).pipe(
                  Effect.andThen(
                    Effect.sync(() => {
                      record.exitStatus = status;
                    }),
                  ),
                  Effect.andThen(Deferred.succeed(record.exit, status)),
                ),
              ),
            ),
          );
          return { terminalId };
        }),
      ),
    );

  const output: AcpClientTerminals["output"] = (request) =>
    requireTerminal(request.sessionId, request.terminalId, "terminal/output").pipe(
      Effect.map((terminal) => ({
        output: readOutput(terminal.buffer),
        truncated: terminal.buffer.truncated,
        ...(terminal.exitStatus === undefined ? {} : { exitStatus: terminal.exitStatus }),
      })),
    );

  const waitForExit: AcpClientTerminals["waitForExit"] = (request) =>
    requireTerminal(request.sessionId, request.terminalId, "terminal/wait_for_exit").pipe(
      Effect.flatMap((terminal) => Deferred.await(terminal.exit)),
    );

  const kill: AcpClientTerminals["kill"] = (request) =>
    requireTerminal(request.sessionId, request.terminalId, "terminal/kill").pipe(
      Effect.flatMap((terminal) => terminal.kill),
      Effect.as({}),
    );

  const release: AcpClientTerminals["release"] = (request) =>
    Effect.uninterruptible(
      requireTerminal(request.sessionId, request.terminalId, "terminal/release").pipe(
        Effect.flatMap((terminal) =>
          Effect.sync(() => {
            terminal.released = true;
          }).pipe(
            Effect.andThen(terminal.dispose),
            Effect.andThen(Deferred.await(terminal.exit)),
            Effect.andThen(Effect.sync(pruneReleasedSnapshots)),
          ),
        ),
        Effect.as({}),
      ),
    );

  const readOutputSnapshot: AcpClientTerminals["readOutputSnapshot"] = (sessionId, terminalId) => {
    const terminal = terminals.get(terminalId);
    if (terminal === undefined || terminal.sessionId !== sessionId) return undefined;
    return {
      output: readOutput(terminal.buffer),
      truncated: terminal.buffer.truncated,
      exitStatus: terminal.exitStatus,
    };
  };

  const readCommandLine: AcpClientTerminals["readCommandLine"] = (terminalId) =>
    terminals.get(terminalId)?.commandLine;

  const disposeAll: AcpClientTerminals["disposeAll"] = Effect.uninterruptible(
    Effect.suspend(() =>
      Effect.forEach(
        Array.from(terminals.values()),
        (terminal) =>
          Effect.sync(() => {
            terminal.released = true;
          }).pipe(Effect.andThen(terminal.dispose), Effect.andThen(Deferred.await(terminal.exit))),
        { concurrency: "unbounded", discard: true },
      ).pipe(Effect.andThen(Effect.sync(pruneReleasedSnapshots))),
    ),
  );

  const logged =
    <Request, Response>(
      operation: string,
      handler: (request: Request) => Effect.Effect<Response, EffectAcpErrors.AcpRequestError>,
    ) =>
    (request: Request) =>
      handler(request).pipe(
        Effect.tapError((error) =>
          Effect.logWarning("ACP client terminal operation failed", {
            operation,
            detail: error.message,
          }),
        ),
      );

  return {
    create: logged("terminal/create", create),
    output: logged("terminal/output", output),
    waitForExit: logged("terminal/wait_for_exit", waitForExit),
    kill: logged("terminal/kill", kill),
    release: logged("terminal/release", release),
    readOutputSnapshot,
    readCommandLine,
    disposeAll,
  };
});

export function resolveEmbeddedTerminalContent(
  notification: EffectAcpSchema.SessionNotification,
  readOutputSnapshot: AcpClientTerminals["readOutputSnapshot"],
): EffectAcpSchema.SessionNotification {
  const update = notification.update;
  if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
    return notification;
  }
  const content = update.content;
  if (!content || !content.some((entry) => entry.type === "terminal")) {
    return notification;
  }
  const mapped = content.map((entry): EffectAcpSchema.ToolCallContent => {
    if (entry.type !== "terminal") return entry;
    const snapshot = readOutputSnapshot(notification.sessionId, entry.terminalId);
    return {
      type: "content",
      content: {
        type: "text",
        text: snapshot === undefined ? `[terminal ${entry.terminalId}]` : snapshot.output,
      },
    };
  });
  return { ...notification, update: { ...update, content: mapped } };
}