sailfork / t3code-github / apps/ server/ src/ orchestration-v2/ CommandOutputHub.ts

import {
  isOrchestrationV2WorkActive,
  OrchestrationV2CommandOutputError,
  type OrchestrationV2CommandOutputFrame,
  type OrchestrationV2SubscribeCommandOutputInput,
  type OrchestrationV2TurnItem,
} from "@t3tools/contracts";
import {
  appendTerminalOutput,
  EMPTY_TERMINAL_OUTPUT,
  normalizeTerminalOutput,
  type TerminalOutputState,
  TERMINAL_OUTPUT_TAIL_CHARS,
  terminalOutputResumeText,
} from "@t3tools/shared/terminalOutput";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";

import * as EventSink from "./EventSink.ts";
import * as ProjectionStore from "./ProjectionStore.ts";

/** Output bypasses orchestration events; expanded rows receive tails, coalesced appends, then persisted output. */

/** Fastest a subscriber receives frames while output flows. */
const COMMAND_OUTPUT_FRAME_INTERVAL_MS = 100;
/** After a subscriber falls behind and is sent the whole tail, it waits this long. */
const COMMAND_OUTPUT_REPLACE_INTERVAL_MS = 500;
/** Raw text a subscriber may accumulate before it is sent the tail instead. */
const COMMAND_OUTPUT_MAX_APPEND_CHARS = 16 * 1024;
/** Evict the least recently written command beyond this limit. */
const MAX_LIVE_COMMANDS = 64;
/** Retain finished tails for settlements that omit output. */
const MAX_FINISHED_COMMANDS = 16;
const MAX_FINAL_SOURCE_CHARS = TERMINAL_OUTPUT_TAIL_CHARS * 4;

interface Subscriber {
  pendingAppend: string;
  needsReplace: boolean;
  /** `needsReplace` was caused by the subscriber falling behind. */
  overflowed: boolean;
  readonly wake: Queue.Queue<void>;
}

export type CommandOutputTarget = OrchestrationV2SubscribeCommandOutputInput;

export interface CommandOutputHubShape {
  readonly append: (input: CommandOutputTarget & { readonly chunk: string }) => Effect.Effect<void>;
  /** Retains the tail briefly for settlements without output; otherwise rows use persisted output. */
  readonly finish: (input: CommandOutputTarget) => Effect.Effect<void>;
  readonly subscribe: (
    input: CommandOutputTarget,
  ) => Stream.Stream<OrchestrationV2CommandOutputFrame, OrchestrationV2CommandOutputError>;
}

export class CommandOutputHub extends Context.Service<CommandOutputHub, CommandOutputHubShape>()(
  "t3/orchestration-v2/CommandOutputHub",
) {}

const isCommandOutputError = Schema.is(OrchestrationV2CommandOutputError);

function commandKey(target: CommandOutputTarget): string {
  return `${target.threadId}\u0000${target.itemId}`;
}

const decodeLegacyClaudeBashResult = Schema.decodeUnknownOption(
  Schema.fromJsonString(
    Schema.Struct({ stdout: Schema.String, stderr: Schema.String, interrupted: Schema.Boolean }),
  ),
);

function legacyClaudeBashOutput(output: string): string {
  if (!output.trimStart().startsWith('{"stdout"')) return output;
  const parsed = decodeLegacyClaudeBashResult(output);
  if (Option.isNone(parsed)) return output;
  const out = parsed.value.stdout.trim().length > 0 ? parsed.value.stdout : "";
  const err = parsed.value.stderr.trim().length > 0 ? parsed.value.stderr : "";
  return out.length > 0 && err.length > 0 && !out.endsWith("\n") ? `${out}\n${err}` : out + err;
}

function persistedCommandOutput(output: string | undefined): {
  readonly text: string;
  readonly truncated: boolean;
} {
  if (output === undefined) return { text: "", truncated: false };
  let source = output;
  if (output.length > MAX_FINAL_SOURCE_CHARS) {
    // Cut at a newline to avoid splitting escape sequences.
    source = output.slice(output.length - MAX_FINAL_SOURCE_CHARS);
    const newline = source.indexOf("\n");
    if (newline !== -1 && newline + 1 < source.length) source = source.slice(newline + 1);
  }
  const normalized = normalizeTerminalOutput(source);
  return {
    text: normalized.text,
    truncated: normalized.truncated || source.length !== output.length,
  };
}

function setBounded<V>(
  map: Map<string, V>,
  key: string,
  value: V,
  max: number,
  onEvict?: (key: string) => void,
): void {
  map.delete(key);
  map.set(key, value);
  if (map.size <= max) return;
  const oldest = map.keys().next().value!;
  map.delete(oldest);
  onEvict?.(oldest);
}

export const make = Effect.gen(function* () {
  const eventSink = yield* EventSink.EventSinkV2;
  const projections = yield* ProjectionStore.ProjectionStoreV2;
  const tails = new Map<string, TerminalOutputState>();
  const finished = new Map<string, TerminalOutputState>();
  const subscribers = new Map<string, Set<Subscriber>>();

  const wakeAll = (key: string, chunk: string) =>
    Effect.forEach(
      subscribers.get(key) ?? [],
      (subscriber) => {
        if (!subscriber.needsReplace) {
          subscriber.pendingAppend += chunk;
          if (subscriber.pendingAppend.length > COMMAND_OUTPUT_MAX_APPEND_CHARS) {
            subscriber.needsReplace = true;
            subscriber.overflowed = true;
            subscriber.pendingAppend = "";
          }
        }
        return Queue.offer(subscriber.wake, undefined);
      },
      { discard: true },
    );

  const append: CommandOutputHubShape["append"] = ({ chunk, ...target }) =>
    Effect.suspend(() => {
      if (chunk.length === 0) return Effect.void;
      const key = commandKey(target);
      const tail = appendTerminalOutput(tails.get(key) ?? EMPTY_TERMINAL_OUTPUT, chunk);
      setBounded(tails, key, tail, MAX_LIVE_COMMANDS, (oldest) => {
        // Eviction invalidates viewers' state; resync on their next frame.
        for (const subscriber of subscribers.get(oldest) ?? []) {
          subscriber.needsReplace = true;
          subscriber.pendingAppend = "";
        }
      });
      return wakeAll(key, chunk);
    });

  const finish: CommandOutputHubShape["finish"] = (target) =>
    Effect.sync(() => {
      const key = commandKey(target);
      const tail = tails.get(key);
      if (tail === undefined) return;
      tails.delete(key);
      setBounded(finished, key, tail, MAX_FINISHED_COMMANDS);
    });

  const subscribe: CommandOutputHubShape["subscribe"] = (target) =>
    Stream.unwrap(
      Effect.gen(function* () {
        const key = commandKey(target);
        const wake = yield* Queue.sliding<void>(1);
        const subscriber: Subscriber = {
          pendingAppend: "",
          needsReplace: true,
          overflowed: false,
          wake,
        };
        // Subscribe before reading to avoid losing intervening chunks.
        const keySubscribers = subscribers.get(key) ?? new Set<Subscriber>();
        keySubscribers.add(subscriber);
        subscribers.set(key, keySubscribers);
        yield* Effect.addFinalizer(() =>
          Effect.sync(() => {
            keySubscribers.delete(subscriber);
            if (keySubscribers.size === 0 && subscribers.get(key) === keySubscribers) {
              subscribers.delete(key);
            }
          }),
        );

        // Persisted items provide settlement and final output; snapshot-only providers (ACP, Pi) also stream here.
        let snapshotOutput: string | undefined;
        let lost: Cause.Cause<unknown> | undefined;
        let settled: Extract<OrchestrationV2TurnItem, { type: "command_execution" }> | undefined;
        const observe = (item: OrchestrationV2TurnItem | undefined) =>
          Effect.suspend(() => {
            if (item === undefined || item.type !== "command_execution") return Effect.void;
            if (!isOrchestrationV2WorkActive(item.status)) {
              settled = item;
            } else if (item.output !== undefined && item.output !== snapshotOutput) {
              snapshotOutput = item.output;
            } else {
              return Effect.void;
            }
            subscriber.needsReplace = true;
            return Queue.offer(wake, undefined);
          });
        const fromSequence = yield* eventSink.latestSequence({ threadId: target.threadId });
        yield* eventSink
          .stream({
            threadId: target.threadId,
            afterSequence: fromSequence,
            eventType: "turn-item.updated",
          })
          .pipe(
            Stream.runForEach((stored) =>
              stored.event.type === "turn-item.updated" && stored.event.payload.id === target.itemId
                ? observe(stored.event.payload)
                : Effect.void,
            ),
            // A lost event stream cannot settle the row; end with an error.
            Effect.catchCause((cause) =>
              Effect.sync(() => {
                lost = cause;
              }).pipe(Effect.andThen(Queue.offer(wake, undefined))),
            ),
            Effect.forkScoped,
          );
        const item = yield* projections.getTurnItem(target);
        // Non-command rows would hold output subscriptions open forever.
        if (item === null || item.type !== "command_execution") {
          return yield* new OrchestrationV2CommandOutputError({
            threadId: target.threadId,
            message: "No such command.",
          });
        }
        yield* observe(item);
        yield* Queue.offer(wake, undefined);

        let lastFrameAt: number | undefined;
        let throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS;
        const nextFrame = Effect.gen(function* (): Effect.fn.Return<
          OrchestrationV2CommandOutputFrame,
          OrchestrationV2CommandOutputError
        > {
          yield* Queue.take(wake);
          if (lost !== undefined) {
            return yield* new OrchestrationV2CommandOutputError({
              threadId: target.threadId,
              message: "Lost the thread's event stream.",
              cause: Cause.squash(lost),
            });
          }
          const now = yield* Clock.currentTimeMillis;
          if (lastFrameAt !== undefined && now - lastFrameAt < throttle) {
            yield* Effect.sleep(throttle - (now - lastFrameAt));
          }
          lastFrameAt = yield* Clock.currentTimeMillis;
          throttle = COMMAND_OUTPUT_FRAME_INTERVAL_MS;
          const tail = tails.get(key) ?? finished.get(key);
          if (settled !== undefined) {
            if (settled.output === undefined && tail !== undefined) {
              return {
                kind: "replace",
                text: tail.text,
                truncated: tail.truncated,
                running: false,
              };
            }
            const output = settled.output && legacyClaudeBashOutput(settled.output);
            return { kind: "replace", ...persistedCommandOutput(output), running: false };
          }
          if (subscriber.needsReplace || tail === undefined) {
            if (subscriber.overflowed) throttle = COMMAND_OUTPUT_REPLACE_INTERVAL_MS;
            subscriber.needsReplace = false;
            subscriber.overflowed = false;
            subscriber.pendingAppend = "";
            if (tail === undefined) {
              return { kind: "replace", ...persistedCommandOutput(snapshotOutput), running: true };
            }
            // Include terminal state so clients interpret later appends identically.
            return {
              kind: "replace",
              text: terminalOutputResumeText(tail),
              truncated: tail.truncated,
              running: true,
            };
          }
          const text = subscriber.pendingAppend;
          subscriber.pendingAppend = "";
          return { kind: "append", text, truncated: tail.truncated, running: true };
        });
        return Stream.fromEffectRepeat(nextFrame).pipe(
          Stream.filter((frame) => frame.kind !== "append" || frame.text.length > 0),
          Stream.takeUntil((frame) => !frame.running),
        );
      }).pipe(
        Effect.mapError((cause) =>
          isCommandOutputError(cause)
            ? cause
            : new OrchestrationV2CommandOutputError({
                threadId: target.threadId,
                message: "Failed to read command output.",
                cause,
              }),
        ),
      ),
    );

  return CommandOutputHub.of({ append, finish, subscribe });
});

export const layer: Layer.Layer<
  CommandOutputHub,
  never,
  EventSink.EventSinkV2 | ProjectionStore.ProjectionStoreV2
> = Layer.effect(CommandOutputHub, make);