sailfork / t3code-github / apps/ server/ src/ orchestration-v2/ Adapters/ MuseAdapterV2.testkit.ts

import * as NodeServices from "@effect/platform-node/NodeServices";
import { Connection, type DuplexTransport } from "@muse-code/sdk";
import {
  ProviderDriverKind,
  ProviderInstanceId,
  ProviderReplayEntry,
  type ProviderReplayEntry as ProviderReplayEntryType,
  type ProviderReplayTranscript,
} from "@t3tools/contracts";
import { MuseSettings } from "@t3tools/provider-muse/settings";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";

import * as TestProviderHost from "@t3tools/provider-testing/TestProviderHost";
import {
  museInitializeParams,
  museServeArgs,
  museWorkspaceRoot,
  type MuseSdkHost,
  type MuseSdkHostOptions,
} from "@t3tools/provider-muse/testing";
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
import * as ProviderAdapterRegistry from "../ProviderAdapterRegistry.ts";
import * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
import type { OrchestratorV2ProviderReplayHarness } from "../testkit/ProviderReplayHarness.ts";
import { materializeReplayTranscriptWorkspace } from "@t3tools/provider-testing/replayTranscript";
import { makeMuseAdapterV2 } from "@t3tools/provider-muse/server";

export const MUSE_PROVIDER_KIND = "muse";
export const MUSE_MSP_REPLAY_PROTOCOL = "muse.msp-jsonl";
const MUSE_REPLAY_ANY = "<any>";

const MuseReplayTranscript = Schema.Struct({
  provider: Schema.Literal(MUSE_PROVIDER_KIND),
  protocol: Schema.Literal(MUSE_MSP_REPLAY_PROTOCOL),
  version: Schema.String,
  scenario: Schema.String,
  metadata: Schema.Struct({
    commandIds: Schema.Array(Schema.Array(Schema.String)),
  }),
  entries: Schema.Array(ProviderReplayEntry),
});
type MuseReplayTranscript = typeof MuseReplayTranscript.Type;
const decodeMuseReplayTranscript = Schema.decodeUnknownEffect(MuseReplayTranscript);

class MuseReplayTranscriptDecodeError extends Schema.TaggedError<MuseReplayTranscriptDecodeError>()(
  "MuseReplayTranscriptDecodeError",
  { scenario: Schema.optional(Schema.String), cause: Schema.Defect() },
) {
  override get message(): string {
    return `Failed to decode Muse MSP replay transcript for scenario ${this.scenario ?? "<unknown>"}.`;
  }
}

class MuseReplayMismatchError extends Schema.TaggedError<MuseReplayMismatchError>()(
  "MuseReplayMismatchError",
  {
    scenario: Schema.String,
    cursor: Schema.Number,
    host: Schema.Number,
    expected: Schema.Unknown,
    actual: Schema.Unknown,
  },
) {
  override get message(): string {
    return `Muse replay frame mismatch at cursor ${this.cursor} from host ${this.host} in scenario ${this.scenario}.`;
  }
}

class MuseReplayIncompleteError extends Schema.TaggedError<MuseReplayIncompleteError>()(
  "MuseReplayIncompleteError",
  {
    scenario: Schema.String,
    cursor: Schema.Number,
    remaining: Schema.Number,
    nextLabel: Schema.optional(Schema.String),
  },
) {
  override get message(): string {
    return `Muse replay ended with ${this.remaining} unconsumed entries at cursor ${this.cursor} (next ${this.nextLabel ?? "<none>"}) in scenario ${this.scenario}.`;
  }
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function replayValueMatches(expected: unknown, actual: unknown): boolean {
  if (expected === MUSE_REPLAY_ANY) return true;
  if (Array.isArray(expected)) {
    return (
      Array.isArray(actual) &&
      expected.length === actual.length &&
      expected.every((entry, index) => replayValueMatches(entry, actual[index]))
    );
  }
  if (isRecord(expected)) {
    if (!isRecord(actual)) return false;
    const keys = new Set([...Object.keys(expected), ...Object.keys(actual)]);
    return [...keys].every((key) => replayValueMatches(expected[key], actual[key]));
  }
  return Object.is(expected, actual);
}

function clientRequestId(frame: unknown): number | undefined {
  return isRecord(frame) && typeof frame.method === "string" && typeof frame.id === "number"
    ? frame.id
    : undefined;
}

function withRequestId(expected: unknown, actual: unknown): unknown {
  const actualId = clientRequestId(actual);
  return isRecord(expected) && clientRequestId(expected) !== undefined && actualId !== undefined
    ? { ...expected, id: actualId }
    : expected;
}

/** A write may not match past one of these: it would be a turn early. */
function startsTurn(entry: ProviderReplayEntryType): boolean {
  if (entry.type !== "expect_outbound" || !isRecord(entry.frame)) return false;
  const method = entry.frame.method ?? entry.frame.type;
  return method === "turn/start" || method === "session/compact" || method === "host_start";
}

function entryHost(entry: ProviderReplayEntryType): number {
  const label = entry.type === "runtime_exit" ? undefined : entry.label;
  const match = label === undefined ? null : /@h(\d+)$/u.exec(label);
  return match === null ? 1 : Number(match[1]);
}

function entryLabel(entry: ProviderReplayEntryType | undefined): string | undefined {
  if (entry === undefined) return undefined;
  return entry.type === "runtime_exit" ? "runtime_exit" : (entry.label ?? entry.type);
}

export function museRecordLabel(
  frame: unknown,
  direction: "expect_outbound" | "emit_inbound",
  requestMethods: ReadonlyMap<unknown, string>,
  host: number,
): string | undefined {
  if (!isRecord(frame)) return undefined;
  const method = typeof frame.method === "string" ? frame.method : undefined;
  const base =
    frame.type === "host_start"
      ? "host_start"
      : method !== undefined
        ? direction === "emit_inbound" && "id" in frame
          ? `request:${method}`
          : method
        : requestMethods.has(frame.id)
          ? `${direction === "emit_inbound" ? "response" : "reply"}:${requestMethods.get(frame.id)}`
          : undefined;
  return base === undefined || host === 1 ? base : `${base}@h${host}`;
}

class LineQueue implements AsyncIterable<string> {
  private readonly lines: Array<string> = [];
  private waiting: ((result: IteratorResult<string>) => void) | undefined;
  private ended = false;

  push(line: string): void {
    if (this.ended) return;
    const waiting = this.waiting;
    if (waiting) {
      this.waiting = undefined;
      waiting({ value: line, done: false });
    } else this.lines.push(line);
  }

  end(): void {
    this.ended = true;
    this.waiting?.({ value: undefined, done: true });
    this.waiting = undefined;
  }

  [Symbol.asyncIterator](): AsyncIterator<string> {
    return {
      next: () => {
        const line = this.lines.shift();
        if (line !== undefined) return Promise.resolve({ value: line, done: false });
        if (this.ended) return Promise.resolve({ value: undefined, done: true });
        return new Promise((resolve) => {
          this.waiting = resolve;
        });
      },
    };
  }
}

interface MuseReplayHost {
  readonly ordinal: number;
  readonly incoming: LineQueue;
  readonly ids: Map<number, number>;
  readonly minted: Array<string>;
  readonly exited: Promise<{ readonly code: number | null; readonly signal: null }>;
  readonly exit: () => void;
  open: boolean;
}

/** Adapter fibers can reorder stdin writes; hold matches within the turn until reached, and fail unmatched writes. */
class MuseReplayController {
  private cursor = 0;
  private failure: unknown = null;
  private readonly consumed = new Set<number>();
  private readonly held: Array<{ readonly host: MuseReplayHost; readonly actual: unknown }> = [];
  private readonly hosts: Array<MuseReplayHost> = [];
  private readonly transcript: MuseReplayTranscript;

  constructor(transcript: MuseReplayTranscript) {
    this.transcript = transcript;
  }

  spawn(args: ReadonlyArray<string>): MuseReplayHost {
    let exit = () => {};
    const exited = new Promise<{ readonly code: number | null; readonly signal: null }>(
      (resolve) => {
        exit = () => resolve({ code: 0, signal: null });
      },
    );
    const host: MuseReplayHost = {
      ordinal: this.hosts.length + 1,
      incoming: new LineQueue(),
      ids: new Map(),
      minted: [...(this.transcript.metadata.commandIds[this.hosts.length] ?? [])],
      exited,
      exit,
      open: true,
    };
    this.hosts.push(host);
    this.receive(host, { type: "host_start", args: [...args] });
    return host;
  }

  mint(host: MuseReplayHost): string {
    const id = host.minted.shift();
    if (id === undefined) {
      throw new Error(`Muse replay host ${host.ordinal} minted more ids than were recorded.`);
    }
    return id;
  }

  receive(host: MuseReplayHost, actual: unknown): void {
    if (this.failure !== null) return;
    const entries = this.transcript.entries;
    let possible = false;
    for (let index = this.cursor; index < entries.length && !possible; index += 1) {
      const entry = entries[index]!;
      const pending = entry.type === "expect_outbound" && !this.consumed.has(index);
      possible =
        pending &&
        entryHost(entry) === host.ordinal &&
        replayValueMatches(withRequestId(entry.frame, actual), actual);
      if (!possible && pending && startsTurn(entry)) break;
    }
    if (!possible) {
      this.fail(
        new MuseReplayMismatchError({
          scenario: this.transcript.scenario,
          cursor: this.cursor,
          host: host.ordinal,
          expected: entries[this.cursor] ?? null,
          actual,
        }),
      );
      return;
    }
    this.held.push({ host, actual });
    this.advance();
  }

  close(host: MuseReplayHost): void {
    host.open = false;
    host.incoming.end();
    host.exit();
  }

  assertComplete(): void {
    if (this.failure !== null) throw this.failure;
    if (this.cursor !== this.transcript.entries.length || this.held.length > 0) {
      const nextLabel = entryLabel(this.transcript.entries[this.cursor]);
      throw new MuseReplayIncompleteError({
        scenario: this.transcript.scenario,
        cursor: this.cursor,
        remaining: this.transcript.entries.length - this.cursor,
        ...(nextLabel === undefined ? {} : { nextLabel }),
      });
    }
  }

  private advance(): void {
    let progressed = true;
    while (progressed && this.failure === null) {
      progressed = this.drainInbound();
      for (const [heldIndex, write] of this.held.entries()) {
        if (this.consumePending(write.host, write.actual)) {
          this.held.splice(heldIndex, 1);
          progressed = true;
          break;
        }
      }
    }
  }

  private consumePending(host: MuseReplayHost, actual: unknown): boolean {
    const entries = this.transcript.entries;
    for (let index = this.cursor; index < entries.length; index += 1) {
      const entry = entries[index]!;
      if (entry.type !== "expect_outbound") return false;
      if (this.consumed.has(index) || entryHost(entry) !== host.ordinal) continue;
      if (!replayValueMatches(withRequestId(entry.frame, actual), actual)) continue;
      const recordedId = clientRequestId(entry.frame);
      const actualId = clientRequestId(actual);
      if (recordedId !== undefined && actualId !== undefined) host.ids.set(recordedId, actualId);
      this.consumed.add(index);
      while (this.consumed.has(this.cursor)) this.cursor += 1;
      return true;
    }
    return false;
  }

  private drainInbound(): boolean {
    let emitted = false;
    while (this.failure === null) {
      const entry = this.transcript.entries[this.cursor];
      if (entry?.type === "runtime_exit") {
        this.cursor += 1;
        emitted = true;
        const host = this.hosts.at(-1);
        if (host !== undefined) this.close(host);
        continue;
      }
      if (entry?.type !== "emit_inbound") return emitted;
      const host = this.hosts[entryHost(entry) - 1];
      if (host === undefined) return emitted;
      this.cursor += 1;
      emitted = true;
      // Output a host wrote after T3 released it was never observed.
      if (!host.open) continue;
      const frame = entry.frame;
      // Responses carry the client's request id; server requests carry their own.
      const reboundId =
        isRecord(frame) && frame.method === undefined && typeof frame.id === "number"
          ? host.ids.get(frame.id)
          : undefined;
      const rebound =
        isRecord(frame) && reboundId !== undefined ? { ...frame, id: reboundId } : frame;
      host.incoming.push(`${JSON.stringify(rebound)}\n`);
    }
    return emitted;
  }

  private fail(cause: unknown): void {
    if (this.failure !== null) return;
    this.failure = cause;
    for (const host of this.hosts) host.incoming.end();
  }
}

export async function connectMuseTransport(input: {
  readonly transport: DuplexTransport;
  readonly readOnly: boolean | undefined;
  readonly mintCommandId?: () => string;
  readonly exited: MuseSdkHost["exited"];
  readonly close: () => Promise<void>;
}): Promise<MuseSdkHost> {
  const connection = new Connection(
    input.transport,
    input.mintCommandId ? { mintCommandId: input.mintCommandId } : {},
  );
  const result = await connection.request("initialize", museInitializeParams(input.readOnly));
  connection.notify("initialized");
  const granted = result.grantedCapabilities;
  return {
    connection,
    initializeResult: {
      grantedCapabilities: Array.isArray(granted)
        ? granted.filter((capability) => typeof capability === "string")
        : [],
    },
    exited: input.exited,
    close: input.close,
  };
}

function makeReplayCreateHost(controller: MuseReplayController) {
  return async (options: MuseSdkHostOptions): Promise<MuseSdkHost> => {
    const host = controller.spawn(museServeArgs(options));
    return connectMuseTransport({
      transport: {
        incoming: host.incoming,
        write: async (line) => {
          for (const part of line.split("\n")) {
            if (part.trim()) controller.receive(host, JSON.parse(part));
          }
        },
        close: () => controller.close(host),
      },
      readOnly: options.readOnly,
      mintCommandId: () => controller.mint(host),
      exited: host.exited,
      close: async () => controller.close(host),
    });
  };
}

const DEFAULT_MUSE_SETTINGS = Schema.decodeSync(MuseSettings)({ enabled: true });

export function layer(input: {
  readonly scenario: string;
  readonly createHost: NonNullable<Parameters<typeof makeMuseAdapterV2>[0]["createHost"]>;
  readonly environment?: NodeJS.ProcessEnv;
}) {
  return ProviderAdapterRegistry.layerFromAdaptersEffect(
    Effect.gen(function* () {
      return [
        yield* makeMuseAdapterV2({
          instanceId: ProviderInstanceId.make(MUSE_PROVIDER_KIND),
          settings: DEFAULT_MUSE_SETTINGS,
          environment: input.environment ?? {},
          createHost: input.createHost,
          continuationRequests: yield* ProviderContinuationRequests.ProviderContinuationRequests,
        }),
      ];
    }),
  ).pipe(
    Layer.provide(
      Layer.mergeAll(
        TestProviderHost.layer().pipe(Layer.provide(NodeServices.layer)),
        NodeServices.layer,
        IdAllocator.layer,
      ),
    ),
  );
}

/** Uses canonical workspace paths, with turn/start in museWorkspaceRoot form (verbatim on Windows). */
export const materializeMuseReplayWorkspace = Effect.fn("materializeMuseReplayWorkspace")(
  function* (transcript: ProviderReplayTranscript, workspace: string) {
    const canonical = yield* FileSystem.FileSystem.pipe(
      Effect.flatMap((fs) => fs.realPath(workspace)),
      Effect.provide(NodeServices.layer),
    );
    const plain = materializeReplayTranscriptWorkspace(transcript, canonical);
    const turnStarts = materializeReplayTranscriptWorkspace(
      transcript,
      yield* museWorkspaceRoot(canonical),
    );
    return {
      ...plain,
      entries: plain.entries.map((entry, index) =>
        entry.type === "expect_outbound" &&
        isRecord(entry.frame) &&
        entry.frame.method === "turn/start"
          ? turnStarts.entries[index]!
          : entry,
      ),
    };
  },
);

export const MuseOrchestratorReplayHarness: OrchestratorV2ProviderReplayHarness<
  MuseReplayTranscript,
  MuseReplayTranscriptDecodeError
> = {
  driver: ProviderDriverKind.make(MUSE_PROVIDER_KIND),
  decodeTranscript: (transcript: ProviderReplayTranscript) =>
    decodeMuseReplayTranscript(transcript).pipe(
      Effect.mapError(
        (cause) => new MuseReplayTranscriptDecodeError({ scenario: transcript.scenario, cause }),
      ),
    ),
  makeProviderAdapterRegistryLayer: (transcript) =>
    Layer.unwrap(
      Effect.gen(function* () {
        const controller = new MuseReplayController(transcript);
        yield* Effect.addFinalizer(() => Effect.sync(() => controller.assertComplete()));
        return layer({
          scenario: transcript.scenario,
          createHost: makeReplayCreateHost(controller),
        });
      }),
    ),
};