import { pipe } from "effect/Function";
import * as Cause from "effect/Cause";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Sink from "effect/Sink";
import * as Stdio from "effect/Stdio";
import * as Stream from "effect/Stream";
import * as CodexClient from "./client.ts";
import * as CodexError from "./errors.ts";
export const CodexAppServerReplayEntry = Schema.Union([
Schema.Struct({
type: Schema.Literal("expect_outbound"),
label: Schema.optional(Schema.String),
frame: Schema.Unknown,
}),
Schema.Struct({
type: Schema.Literal("emit_inbound"),
label: Schema.optional(Schema.String),
frame: Schema.Unknown,
afterMs: Schema.optional(Schema.Number),
}),
Schema.Struct({
type: Schema.Literal("runtime_exit"),
status: Schema.Literals(["success", "error", "cancelled"]),
error: Schema.optional(Schema.Unknown),
}),
]);
export type CodexAppServerReplayEntry = typeof CodexAppServerReplayEntry.Type;
export const CodexAppServerReplayTranscript = Schema.Struct({
provider: Schema.Literal("codex"),
protocol: Schema.Literal("codex.app-server"),
version: Schema.String,
scenario: Schema.String,
metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
entries: Schema.Array(CodexAppServerReplayEntry),
});
export type CodexAppServerReplayTranscript = typeof CodexAppServerReplayTranscript.Type;
const decodeOutboundJsonFrame = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
export class CodexAppServerReplayJsonParseError extends Schema.TaggedError<CodexAppServerReplayJsonParseError>()(
"CodexAppServerReplayJsonParseError",
{
scenario: Schema.String,
line: Schema.String,
cause: Schema.Defect(),
},
) {
override get message(): string {
return `Failed to parse outbound Codex app-server replay frame for scenario ${this.scenario}.`;
}
}
export class CodexAppServerReplayExhaustedError extends Schema.TaggedError<CodexAppServerReplayExhaustedError>()(
"CodexAppServerReplayExhaustedError",
{
scenario: Schema.String,
cursor: Schema.Number,
actual: Schema.Unknown,
},
) {
override get message(): string {
return `Codex app-server replay transcript exhausted before outbound frame ${this.cursor} in scenario ${this.scenario}.`;
}
}
export class CodexAppServerReplayUnexpectedOutboundError extends Schema.TaggedError<CodexAppServerReplayUnexpectedOutboundError>()(
"CodexAppServerReplayUnexpectedOutboundError",
{
scenario: Schema.String,
cursor: Schema.Number,
expectedType: Schema.String,
actual: Schema.Unknown,
},
) {
override get message(): string {
return `Unexpected outbound Codex app-server frame at replay cursor ${this.cursor} in scenario ${this.scenario}.`;
}
}
export class CodexAppServerReplayFrameMismatchError extends Schema.TaggedError<CodexAppServerReplayFrameMismatchError>()(
"CodexAppServerReplayFrameMismatchError",
{
scenario: Schema.String,
cursor: Schema.Number,
label: Schema.optional(Schema.String),
expected: Schema.Unknown,
actual: Schema.Unknown,
},
) {
override get message(): string {
return `Outbound Codex app-server frame did not match replay cursor ${this.cursor} in scenario ${this.scenario}. Expected ${JSON.stringify(this.expected)}, received ${JSON.stringify(this.actual)}.`;
}
}
export class CodexAppServerReplayRuntimeExitError extends Schema.TaggedError<CodexAppServerReplayRuntimeExitError>()(
"CodexAppServerReplayRuntimeExitError",
{
scenario: Schema.String,
cursor: Schema.Number,
status: Schema.Literals(["error", "cancelled"]),
error: Schema.optional(Schema.Unknown),
},
) {
override get message(): string {
return `Codex app-server replay exited with status ${this.status} at cursor ${this.cursor} in scenario ${this.scenario}.`;
}
}
export const CodexAppServerReplayError = Schema.Union([
CodexAppServerReplayJsonParseError,
CodexAppServerReplayExhaustedError,
CodexAppServerReplayUnexpectedOutboundError,
CodexAppServerReplayFrameMismatchError,
CodexAppServerReplayRuntimeExitError,
]);
export type CodexAppServerReplayError = typeof CodexAppServerReplayError.Type;
export interface CodexAppServerReplayState {
readonly cursor: number;
readonly failure: CodexAppServerReplayError | null;
}
export interface CodexAppServerReplayDriver {
readonly transcript: CodexAppServerReplayTranscript;
readonly state: Ref.Ref<CodexAppServerReplayState>;
readonly beforeEmitInbound?: (
entry: Extract<CodexAppServerReplayEntry, { readonly type: "emit_inbound" }>,
) => Effect.Effect<void>;
}
const encoder = new TextEncoder();
function stableStringify(value: unknown): string {
if (Array.isArray(value)) {
return `[${value.map(stableStringify).join(",")}]`;
}
if (typeof value === "object" && value !== null) {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.toSorted()
.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
.join(",")}}`;
}
return JSON.stringify(value);
}
function normalizeContextHandoffText(value: string): string {
if (!value.startsWith("Context handoff (")) {
return value;
}
const userMessageMarker = "\n\nUser message:\n";
const userMessageIndex = value.indexOf(userMessageMarker);
const headerEndIndex = value.indexOf(":\n");
if (headerEndIndex === -1 || userMessageIndex === -1 || headerEndIndex >= userMessageIndex) {
return value;
}
return `${value.slice(0, headerEndIndex + 2)}<dynamic-summary>${value.slice(userMessageIndex)}`;
}
function normalizeReplayFrame(value: unknown): unknown {
if (typeof value === "string") {
return normalizeContextHandoffText(value);
}
if (typeof value !== "object" || value === null) {
return value;
}
if (Array.isArray(value)) {
return value.map(normalizeReplayFrame);
}
const record = value as Record<string, unknown>;
const normalized = Object.fromEntries(
Object.entries(record).map(([key, entry]) => [key, normalizeReplayFrame(entry)]),
);
if (
normalized.method === "initialize" &&
typeof normalized.params === "object" &&
normalized.params !== null
) {
const params = normalized.params as Record<string, unknown>;
if (typeof params.clientInfo === "object" && params.clientInfo !== null) {
normalized.params = {
...params,
clientInfo: {
...(params.clientInfo as Record<string, unknown>),
version: "<ignored>",
},
};
}
}
if (
normalized.method === "turn/start" &&
typeof normalized.params === "object" &&
normalized.params !== null
) {
const params = { ...(normalized.params as Record<string, unknown>) };
if (params.approvalPolicy === "never") {
delete params.approvalPolicy;
}
if (
typeof params.sandboxPolicy === "object" &&
params.sandboxPolicy !== null &&
(params.sandboxPolicy as Record<string, unknown>).type === "dangerFullAccess"
) {
delete params.sandboxPolicy;
}
if (typeof params.collaborationMode === "object" && params.collaborationMode !== null) {
const collaborationMode = {
...(params.collaborationMode as Record<string, unknown>),
};
if (typeof collaborationMode.settings === "object" && collaborationMode.settings !== null) {
collaborationMode.settings = {
...(collaborationMode.settings as Record<string, unknown>),
developer_instructions: "<ignored>",
};
}
params.collaborationMode = collaborationMode;
}
normalized.params = params;
}
return normalized;
}
function recorderThreadConfigKeys(transcript: CodexAppServerReplayTranscript): ReadonlySet<string> {
const keys = transcript.metadata?.recorderThreadConfigKeys;
return new Set(Array.isArray(keys) ? keys.filter((key) => typeof key === "string") : []);
}
/**
* `cwd`, `model`, host-supplied MCP servers (machine-local URLs, short-lived
* authorization headers) and the T3 thread id vary per machine or run, and
* recorder-only keys are not the client's.
*/
function normalizeThreadRequest(frame: unknown, ignoredConfigKeys: ReadonlySet<string>): unknown {
if (typeof frame !== "object" || frame === null) return frame;
const record = frame as Record<string, unknown>;
if (
(record.method !== "thread/start" &&
record.method !== "thread/resume" &&
record.method !== "thread/fork") ||
typeof record.params !== "object" ||
record.params === null
) {
return frame;
}
const { cwd: _cwd, model: _model, config, ...params } = record.params as Record<string, unknown>;
if (typeof config !== "object" || config === null) return { ...record, params };
const owned = Object.fromEntries(
Object.entries(config as Record<string, unknown>).filter(
([key]) =>
key !== "mcp_servers" &&
!key.startsWith("mcp_servers.") &&
key !== "shell_environment_policy.set.T3CODE_THREAD_ID",
),
);
for (const key of ignoredConfigKeys) delete owned[key];
return { ...record, params: { ...params, config: owned } };
}
function sameFrame(
left: unknown,
right: unknown,
ignoredConfigKeys: ReadonlySet<string> = new Set(),
): boolean {
const normalize = (frame: unknown) =>
pipe(
normalizeReplayFrame(frame),
(request) => normalizeThreadRequest(request, ignoredConfigKeys),
stableStringify,
);
return normalize(left) === normalize(right);
}
function normalizeLegacyInboundFrame(value: unknown): unknown {
if (Array.isArray(value)) {
return value.map(normalizeLegacyInboundFrame);
}
if (typeof value !== "object" || value === null) {
return value;
}
const record = value as Record<string, unknown>;
const normalized = Object.fromEntries(
Object.entries(record).map(([key, entry]) => [key, normalizeLegacyInboundFrame(entry)]),
);
if (
typeof normalized.id === "string" &&
"modelProvider" in normalized &&
"status" in normalized
) {
if (normalized.sessionId === undefined) normalized.sessionId = normalized.id;
if (normalized.projectId === undefined) normalized.projectId = null;
}
if (
(normalized.method === "item/started" || normalized.method === "item/completed") &&
typeof normalized.params === "object" &&
normalized.params !== null
) {
const params = { ...(normalized.params as Record<string, unknown>) };
if (normalized.method === "item/started" && params.startedAtMs === undefined) {
params.startedAtMs = 0;
}
if (normalized.method === "item/completed" && params.completedAtMs === undefined) {
params.completedAtMs = 0;
}
normalized.params = params;
}
if (
typeof normalized.method === "string" &&
normalized.method.endsWith("/requestApproval") &&
typeof normalized.params === "object" &&
normalized.params !== null
) {
const params = { ...(normalized.params as Record<string, unknown>) };
if (params.startedAtMs === undefined) {
params.startedAtMs = 0;
}
normalized.params = params;
}
if (
normalized.method === "item/tool/requestUserInput" &&
typeof normalized.params === "object" &&
normalized.params !== null
) {
const params = { ...(normalized.params as Record<string, unknown>) };
// Codex treats a legacy request without `isBlocking` as blocking.
if (params.isBlocking === undefined) {
params.isBlocking = true;
}
normalized.params = params;
}
return normalized;
}
function encodeInboundFrame(frame: unknown): Uint8Array {
return encoder.encode(`${JSON.stringify(normalizeLegacyInboundFrame(frame))}\n`);
}
function replayTransportError(
error: CodexAppServerReplayError,
): CodexError.CodexAppServerTransportError {
return new CodexError.CodexAppServerTransportError({
operation: "read-input-stream",
cause: error,
});
}
export function layerReplay(
transcript: CodexAppServerReplayTranscript,
): Layer.Layer<CodexClient.CodexAppServerClient, CodexAppServerReplayError> {
return Layer.effect(CodexClient.CodexAppServerClient, makeReplayClient(transcript));
}
export const makeReplayDriver = Effect.fn("effect-codex-app-server/replay.makeReplayDriver")(
function* (
transcript: CodexAppServerReplayTranscript,
options: Pick<CodexAppServerReplayDriver, "beforeEmitInbound"> = {},
) {
return {
transcript,
state: yield* Ref.make<CodexAppServerReplayState>({ cursor: 0, failure: null }),
...options,
} satisfies CodexAppServerReplayDriver;
},
);
export function layerReplayWithDriver(
driver: CodexAppServerReplayDriver,
): Layer.Layer<CodexClient.CodexAppServerClient, CodexAppServerReplayError> {
return Layer.effect(CodexClient.CodexAppServerClient, makeReplayClientWithState(driver));
}
const makeReplayClient = Effect.fn("effect-codex-app-server/replay.makeReplayClient")(function* (
transcript: CodexAppServerReplayTranscript,
options: CodexClient.CodexAppServerClientOptions = {},
) {
const driver = yield* makeReplayDriver(transcript);
return yield* makeReplayClientWithState(driver, options);
});
const makeReplayClientWithState = Effect.fn(
"effect-codex-app-server/replay.makeReplayClientWithState",
)(function* (
driver: CodexAppServerReplayDriver,
options: CodexClient.CodexAppServerClientOptions = {},
) {
const transcript = driver.transcript;
const ignoredThreadConfigKeys = recorderThreadConfigKeys(transcript);
const input = yield* Queue.unbounded<Uint8Array, Cause.Done<void>>();
const state = driver.state;
const outboundRemainder = yield* Ref.make("");
const decoder = new TextDecoder();
const failReplay = (error: CodexAppServerReplayError) =>
Ref.update(state, (current) => ({
...current,
failure: current.failure ?? error,
})).pipe(Effect.andThen(Queue.end(input)));
const drainInbound = Effect.fn("effect-codex-app-server/replay.drainInbound")(function* () {
while (true) {
const current = yield* Ref.get(state);
if (current.failure) {
return;
}
const entry = transcript.entries[current.cursor];
if (!entry) {
return;
}
if (entry.type === "emit_inbound") {
if (driver.beforeEmitInbound !== undefined) {
yield* driver.beforeEmitInbound(entry);
}
if (entry.afterMs !== undefined && entry.afterMs > 0) {
yield* Effect.sleep(Duration.millis(entry.afterMs));
}
yield* Queue.offer(input, encodeInboundFrame(entry.frame));
yield* Ref.update(state, (latest) => ({ ...latest, cursor: latest.cursor + 1 }));
continue;
}
if (entry.type === "runtime_exit") {
yield* Ref.update(state, (latest) => ({ ...latest, cursor: latest.cursor + 1 }));
if (entry.status === "success") {
yield* Queue.end(input);
return;
}
yield* failReplay(
new CodexAppServerReplayRuntimeExitError({
scenario: transcript.scenario,
cursor: current.cursor,
status: entry.status,
...(entry.error === undefined ? {} : { error: entry.error }),
}),
);
return;
}
return;
}
});
const processOutboundFrame = (actual: unknown) =>
drainInbound().pipe(
Effect.andThen(
Effect.gen(function* () {
const current = yield* Ref.get(state);
if (current.failure) {
return;
}
const entry = transcript.entries[current.cursor];
if (!entry) {
yield* failReplay(
new CodexAppServerReplayExhaustedError({
scenario: transcript.scenario,
cursor: current.cursor,
actual,
}),
);
return;
}
if (entry.type !== "expect_outbound") {
yield* failReplay(
new CodexAppServerReplayUnexpectedOutboundError({
scenario: transcript.scenario,
cursor: current.cursor,
expectedType: entry.type,
actual,
}),
);
return;
}
if (!sameFrame(entry.frame, actual, ignoredThreadConfigKeys)) {
yield* failReplay(
new CodexAppServerReplayFrameMismatchError({
scenario: transcript.scenario,
cursor: current.cursor,
...(entry.label === undefined ? {} : { label: entry.label }),
expected: entry.frame,
actual,
}),
);
return;
}
yield* Ref.update(state, (latest) => ({ ...latest, cursor: latest.cursor + 1 }));
yield* drainInbound();
}),
),
);
const processOutboundLine = (line: string) => {
const trimmed = line.trim();
if (trimmed.length === 0) {
return Effect.void;
}
return Effect.try({
try: () => decodeOutboundJsonFrame(trimmed),
catch: (cause) =>
new CodexAppServerReplayJsonParseError({
scenario: transcript.scenario,
line: trimmed,
cause,
}),
}).pipe(
Effect.matchEffect({
onFailure: failReplay,
onSuccess: processOutboundFrame,
}),
);
};
const processOutboundChunk = (chunk: string | Uint8Array) =>
Ref.modify(outboundRemainder, (current) => {
const text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
const combined = current + text;
const lines = combined.split("\n");
const nextRemainder = lines.pop() ?? "";
return [lines.map((line) => line.replace(/\r$/, "")), nextRemainder] as const;
}).pipe(
Effect.flatMap((lines) => Effect.forEach(lines, processOutboundLine, { discard: true })),
);
const terminationError: Effect.Effect<CodexError.CodexAppServerError> = Ref.get(state).pipe(
Effect.map((current) =>
current.failure
? replayTransportError(current.failure)
: new CodexError.CodexAppServerProcessExitedError({ code: 0 }),
),
);
const stdio = Stdio.make({
args: Effect.succeed([]),
stdin: Stream.fromQueue(input),
stdout: () => Sink.forEach(processOutboundChunk),
stderr: () => Sink.drain,
});
yield* drainInbound();
return yield* CodexClient.make(stdio, options, terminationError);
});